Re: [RFC PATCH v1 1/2] src/bin/sman: Add script

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 2934 bytes --]

Hi наб,

On 2026-01-28T17:52:15+0100, наб wrote:
> You wrote it confusingly (if I wrote it like that it'd be on purpose;
>  I doubt that was your intent but that's how it reads),
> so I isomorphised your program into third normal form:
> -- >8 --
> #!/bin/sh
> #
> # Copyright, the authors of the Linux man-pages project
> # SPDX-License-Identifier: GPL-3.0-or-later
> 
> name="${0##*/}"

I find basename(1) much more readable.  Also, it's easier to find
documentation about it.

> 
> # fail [error message]
> fail() {
> 	[ $# -gt 1 ] && echo "$name: $1"

I agree [(1) is more readable than '[[...]]'.  I prefer test(1), though.

[...]
> -- >8 --
> 
> Then I made it behave acceptably thusly:
> -- >8 --
[...]
> -- >8 --

[...]
> If you were shipping this you'd want to do the filtering in one pass
> because the UX of the sections being out of order is IMO suboptimal.
> And also processing and fully-bufferring the /whole/ rendered output,
> for big pages, is so slow
> (I tested on voreutils ls(1) ‒ <https://ro.ws.co.ls/man1/ls.1.pdf>
>  time man ls > /dev/null takes 0m0.513s wall clock;
>  multiply this for each section, and you see how this is suboptimal;
>  similarly, voreutils stty(1) measures 0m1.620s;
>  this is especially suboptimal since big complex pages are exactly the
>  ones you'd want to filter;
>  also, I think this wants a negative section filter as well
>  (to remove HISTORY or STANDARDS which may be less relevant))

In mansect(1) (see below), you can do negative filtering if you want,
by writing a complex-enough PCRE2 pattern that rejects some name(s).

> you can work around this a little by sticking a load of stdbuf -oL
> on the pipeline, but, again, I think the final for loop should be
> representable as a one-shot AWK program.

It is, and indeed, that's how I implemented mansect(1).  Well, I used
pcre2grep(1) instead of awk(1), but it is a one-shot program.

	alx@devuan:~/src/linux/man-pages/man-pages/master$ cat src/bin/mansect 
	#!/bin/bash
	#
	# Copyright, the authors of the Linux man-pages project
	# SPDX-License-Identifier: GPL-3.0-or-later

	set -Eefuo pipefail;


	if test $# -lt 1; then
		>&2 printf '%s\n' "$(basename "$0"): error: Too few arguments."
		exit 1;
	fi;

	s="$1";
	shift;

	if test $# -lt 1; then
		preconv;
	else
		find -H "$@" -not -type d \
		| xargs preconv;
	fi \
	| pcre2grep -M \
		-e '^\.lf 1 ' \
		-e '^\.TH ' \
		-e '(?s)^\.SH ('"$s"')$(?:(?!^\.(lf 1|TH|SH) ).)*';

And as I suggested in the other sub-thread, we can just pipe this to
a formatter to get the intended behavior:

	$ cat src/bin/mansectf 
	#!/bin/bash
	#
	# Copyright, the authors of the Linux man-pages project
	# SPDX-License-Identifier: GPL-3.0-or-later

	set -Eefuo pipefail;

	mansect "$@" \
	| man /dev/stdin;


Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]