Re: proc(5)'s sashimi

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1.1: Type: text/plain, Size: 4908 bytes --]

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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]