Hi Alex,
At 2023-08-14T16:06:16+0200, Alejandro Colomar wrote:
> One of the questions I have at the moment is how should we call the
> pages, and what should we write in the TH and NAME. Branden, do you
> have any comments on that? I used underscores for the page title and
> file name,
I think it's generally a good practice to have the page topic (the first
argument to `TH`) match the "basename" of the man page document's file
name. That rules out slashes there.
> but for the NAME I used slashes (so the actual name of the interface).
This seems like a good idea to me. Neither the man(7) package nor the
formatter care what is in that section.
Consider:
$ cat slashy.man
.TH slashy 1 2023-08-15 "groff test suite"
.SH Name
.IR /etc/slashy/ n
\- configuration of Roguelike game,
version
.I n
.SH Description
Eat and chop.
`nroff -man` and `mandoc | ul` both render this correctly.
> I didn't do any italics in the name, though, so /pid/ is no special in
> the name.
As shown above, I would go ahead and mark it up The Right Way™.
Except...
Unfortunately, lexgrog(1) failed. CCing man-db maintainer Colin Watson.
slashy.man: parse failed
For the time being, therefore, I would back things down to the
following, which _does_ work.
.TH less\-slashy 1 2023-08-15 "groff test suite"
.SH Name
.I /etc/slashy/n
\- configuration of Roguelike game,
version
.I n
.SH Description
Eat and chop.
$ lexgrog less-slashy.man
less-slashy.man: "/etc/slashy/n - configuration of Roguelike game, version n"
...so you can still do quite a bit, just not change fonts _within_ the
page "name" (which can be a comma-separated list of names).[1]
Interestingly, the following _doesn't_ bomb:
$ cat moderately-slashy.man
.TH moderately\-slashy 1 2023-08-15 "groff test suite"
.SH Name
.IR /etc/slashy/n
\- configuration of Roguelike game,
version
.I n
.SH Description
Eat and chop.
Observe the missing second argument to `IR`. `nroff -rCHECKSTYLE=1
-man` would holler about this, but lexgrog chokes only if there's an
argument there.
$ lexgrog moderately-slashy.man
moderately-slashy.man: "/etc/slashy/n - configuration of Roguelike game, version n"
Maybe this is easy to fix, but even if so you'll probably want to wait
until the fixed version has percolated in to distributions of interest,
or your man page won't be indexed, and not show up in apropos(1) or `man
-k` searches.
What if it's not easy to fix? We could of course just give up on some
man(7) features.
Or...we could make lexgrog(1) unnecessary (more likely, a wrapper).
I've had an idea for a while: what if the man(7) package paid attention
to the arguments to `SH` macro calls?
And what if man(7) supported a string that could hold the name of a
section heading of interest?
Consider the difference.
$ nroff -man moderately-slashy.man
moderately-slashy(1) General Commands Manual moderately-slashy(1)
Name
/etc/slashy/n - configuration of Roguelike game, version n
Description
Eat and chop.
groff test suite 2023‐08‐15 moderately-slashy(1)
$ nroff -man -dEXTRACT=Name moderately-slashy.man
/etc/slashy/n - configuration of Roguelike game, version n
$ echo "sweet as"
This would be _really easy_ to do. (Famous last words, I know, but
groff mdoc(7) already does a similar thing, for different reasons.[2])
lexgrog(1) could then become a wrapper around `nroff -man -dEXTRACT=Name
-P -cbou`. It would be easy to chop off the trailing blank line. You
wouldn't need to chop off the leading spaces, thanks to a groff-next
feature that's already landed.
$ ./build/test-groff -rBP=0 -man -T utf8 -P -cbou \
moderately-slashy.man | grep Rogue
/etc/slashy/n - configuration of Roguelike game, version n
(`BP` is the new "base paragraph indentation" register. The "-P -cbou"
options strip all formatting, leaving you a pure character stream in the
output--no escape sequences, no overstriking. See grotty(1).)
Colin, how do you feel about this idea? I aim to do it anyway, but if
it doesn't excite you as a means of making lexgrog's job simpler--at
least on systems that run a sufficiently new version of groff--I may
kick it down the road until after we solve the automatic tagging
problem. I want to be able to type something like this:
nroff -man -dEXTRACT=Options/-e
...and have it do exactly what you think it would do. That future
doesn't seem very far away given what we're having to implement for PDF
bookmarks.[3] At least at present, before difficult obstacles arise...
Regards,
Branden
[1] Further experimentation reveals that lexgrog seems to be tripping
_only_ on second arguments to font style alternation macros.
.I /etc/slashy/\fRn
\- configuration of Roguelike game,
version
.I n
is accepted (but don't do it--`\f` is hateful).
.I /etc/slashy/n
\- configuration of Roguelike game,
version
.IB n "oh yeah"
...doesn't break lexgrog but doesn't store quite the right data, either.
broadly-slashy.man: "/etc/slashy/n - configuration of Roguelike game, version n "oh yeah""
Maybe this means a fix to lexgrog on its own terms will be easy. No
idea. I seem to remember Colin mentioning before that it is dismaying
how much *roff syntax a makewhatis(1) or lexgrog(1) or similar program
has to understand to do its job. I have no idea why brighter minds than
mine didn't think up a solution like my "EXTRACT" string above decades
ago. Maybe they did, and I'm about to find out what's wrong with it...
[2] https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/mdoc/doc-common?h=1.23.0#n1414
[3] https://lore.kernel.org/linux-man/20230815005022.47vpqsjoczn4vyii@illithid/
Attachment:
signature.asc
Description: PGP signature
