[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: groff features for hyperlinked man pages (was: No 6.05/.01 pdf book
From: |
Alejandro Colomar |
Subject: |
Re: groff features for hyperlinked man pages (was: No 6.05/.01 pdf book available) |
Date: |
Fri, 18 Aug 2023 15:50:21 +0200 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.13.1 |
Hi Branden, Deri,
On 2023-08-15 02:50, G. Branden Robinson wrote:
[...]
>
>>> I just re-read this, and am confused. '\-' is an ASCII character,
>>> isn't it? In fact, all of the Linux man-pages pathnames are
>>> composed exclusively of ASCII characters, aren't they?
>
> You're thinking about this at the wrong level, Alex. `\-` is a *roff
> special character. Unless converted to something else by character
> translation or character definition,[7] it goes to the
> device-independent page description language as a special character too.
[...]
> It is up to the output device to decide what to do with that. groff's
> "ascii" and "latin1" output devices put out a U+002D character; its
> "utf8" device puts out a minus sign, U+2212. Now, before anyone
> defecates a brick about the U+2212 not being easily greppable, nor
> useful for copying and pasting to a shell prompt, the man(7) and mdoc(7)
> macro packages override that.
So, \- is kept as a special character, even in man(7), until output
drivers translate it to ASCII -? Or which program does the translation?
If it's gropdf(1) that makes the translation, I guess it will also be
able to perform the same translation for MR. If the translation has
already been made by troff(1), then gropdf(1) shouldn't care. In any
case, I still don't see the problem.
[...]
>> .BR persistent\-keyring (7) ,
> [...]
>> Which when converted to .MR calls looks like:-
> [...]
>> .MR "persistent\-keyring" "7" "," "persistent-keyring"
>
> Urp. No, it doesn't. Not unless you changed `MR` in deri-gropdf-ng.
>
> .BR persistent\-keyring (7) ,
>
> when converted to an `MR` call, looks like this.
>
> .MR persistent\-keyring 7 ,
>
> I expect man page authors would violently protest if they were told they
> had to type all those quotes and, worse, repeat the name of the page.
Indeed. I won't violently protest to Deri's experiments, as I do worse
aberrations while experimenting, but I would if this went into groff(1). :)
>
> One of the selling points of `MR` is less typing (no parentheses).
I woudn't really buy it just for that. ;)
In fact, not having a RM variant, it's more typing when (foo(1)).
But yep, not being DRY would be a trigger for burning the streets of Paris.
> It
> is hard enough to sell that macro on the linux-man list without
> inaccurate claims entering the fray.
>
> Now, if I understand correctly, is quite possible that something you're
> doing in your branch is having `MR` call another macro internally to
> prepare a hyperlink with some "anchor"--I won't say "node" because
> collides with GNU troff internal jargon--information. (This is
> suggested by the heavy quoting you showed, since when macros call each
> other with arbitrary numbers of arguments, and those arguments need to
> be kept separate in the callee, the caller should use the `\$@` escape
> sequence, which is analogous to the POSIX shell's `$@`.)
I'd expect that the hyperlinking ability should be modifyable with
groff(1) --I don't care at what level of the pipeline--, similar to how
it was modifiable with man2html(1). But the source code shouldn't know
about it.
[...]
> I don't think it's naughty; I think that by and large, man page authors
> don't care to give "anchor names" to elements of their document. They
> want the macro package to figure it out.
Indeed. I'd like groff(1) to figure out some name that resembles the
text used as man page reference, or as section heading; I don't want to
specify it.
> I think one reason--maybe the
> only reason--people are getting a glimpse inside the sausage factory of
> GNU troff internals is because we haven't had a defined mechanism for
> getting character data to an output device that is neither (1) intended
> for formatting (writing visible glyphs) nor (2) in the printable ASCII
> (Unicode Basic Latin) character set. That's the aforementioned Savannah
> #63074.[3]
>
> Looking farther ahead, I think a further step is required if we're going
> to have intra-page links; we're going to have to have a way to
> disambiguate duplicates. In practice there's not much risk from having
> duplicate section titles in man pages, but I reckon a big, complex page
> could duplicate subsection titles. And if we automatically generate
> hyperlink tags for paragraph tags, those would likely need it as well.
> Maybe representing such internal anchors hierarchically will be enough:
> "section_subsection_tag" or something like that.
Yep. I'd expect something like that. You could also include the page
name in a book, which would involve the changes suggested by Deri of not
having the page title hardcoded as the first level, right?
Cheers,
Alex
--
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
OpenPGP_signature
Description: OpenPGP digital signature