Hi Branden,
On 2023-08-15 17:36, G. Branden Robinson wrote:
> 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.
I'm worried that mandoc(1) may have even more tight assumptions. I even
warns you if the Name and TH don't match, AFAIR.
Considering that I can't have the right formatting, I prefer to leave it
with no formatting at all; otherwise, it could be confusing. Having no
formatting leaves a clue that it doesn't have it because it's not
possible.
>
> 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"
That reminds me of man_section(), which is quite useful for reviewing
global changes to man pages.
I can, after a global fix to the SYNOPSIS, render all synopses, and
grep there if there's any inconsistency.
It's in ./scripts/bash_aliases:
man_section()
{
if [ $# -lt 2 ]; then
>&2 echo "Usage: ${FUNCNAME[0]} <dir> <section>...";
return $EX_USAGE;
fi
local page="$1";
shift;
local sect="$*";
find "$page" -type f \
|xargs wc -l \
|grep -v -e '\b1 ' -e '\btotal\b' \
|awk '{ print $2 }' \
|sort \
|while read -r manpage; do
(sed -n '/^\.TH/,/^\.SH/{/^\.SH/!p}' <"$manpage";
for s in $sect; do
<"$manpage" \
sed -n \
-e "/^\.SH $s/p" \
-e "/^\.SH $s/,/^\.SH/{/^\.SH/!p}";
done;) \
|mandoc -Tutf8 2>/dev/null \
|col -pbx;
done;
}
Cheers,
Alex
--
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
