linux-kernel - Re: [PATCH v2 1/3] proc_pid_fdinfo.5: Reduce indent for most of the page

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives
Hash Suite: Windows password security audit tool. GUI, reports in PDF.
[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <20241102213620.kfccilxvhihwmnld@devuan>
Date: Sat, 2 Nov 2024 22:36:20 +0100
From: Alejandro Colomar <alx@...nel.org>
To: "G. Branden Robinson" <g.branden.robinson@...il.com>,
	cjwatson@...ian.org
Cc: Ian Rogers <irogers@...gle.com>, David Airlie <airlied@...il.com>,
	Simona Vetter <simona@...ll.ch>,
	Maarten Lankhorst <maarten.lankhorst@...ux.intel.com>,
	Maxime Ripard <mripard@...nel.org>,
	Thomas Zimmermann <tzimmermann@...e.de>,
	Jonathan Corbet <corbet@....net>, dri-devel@...ts.freedesktop.org,
	linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org,
	linux-man@...r.kernel.org, cjwatson@...ian.org, groff@....org
Subject: Re: [PATCH v2 1/3] proc_pid_fdinfo.5: Reduce indent for most of the
 page

Hi Branden, Colin,

On Sat, Nov 02, 2024 at 11:40:13AM +0100, Alejandro Colomar wrote:
> > I also of course have ideas for generalizing the feature, so that you
> > can request any (sub)section by name, and, with a bit more ambition,[4]
> > paragraph tags (`TP`) too.
> > 
> > So you could do things like:
> > 
> > nroff -man -d EXTRACT="RETURN VALUE" man3/bsearch.3
> 
> I certainly use this.
> 
> 	#  man_section()  prints specific manual page sections (DESCRIPTION, SYNOPSIS,
> 	# ...) of all manual pages in a directory (or in a single manual page file).
> 	# Usage example:  .../man-pages$ man_section man2 SYNOPSIS 'SEE ALSO';
> 
> 	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;
> 	}

On the other hand, you may want to just package this small shell script
(or rather a part of it) as a program.

How about this?

	$ cat /usr/local/bin/mansect
	#!/bin/sh

	if [ $# -lt 1 ]; then
		>&2 echo "Usage: $0 SECTION [FILE ...]";
		return 1;
	fi

	s="$1";
	shift;


	if test -z "$*"; then
		sed -n \
			-e '/^\.TH/,/^\.SH/{/^\.SH/!p}' \
			-e '/^\.SH '"$s"'$/p' \
			-e '/^\.SH '"$s"'$/,/^\.SH/{/^\.SH/!p}' \
			;
	else
		find "$@" -not -type d \
		| xargs wc -l \
		| sed '${/ total$/d}' \
		| grep -v '\b1 ' \
		| awk '{ print $2 }' \
		| xargs -L1 sed -n \
			-e '/^\.TH/,/^\.SH/{/^\.SH/!p}' \
			-e '/^\.SH '"$s"'$/p' \
			-e '/^\.SH '"$s"'$/,/^\.SH/{/^\.SH/!p}' \
			;
	fi;

This only filters the source of the page, producing output that's
suitable for the groff pipeline.

	alx@...uan:~$ man -w proc | xargs cat | mansect NAME
	.TH proc 5 2024-06-15 "Linux man-pages 6.9.1-158-g2ac94c631"
	.SH NAME
	proc \- process information, system information, and sysctl pseudo-filesystem
	alx@...uan:~$ man -w strtol strtoul | xargs mansect 'NAME'
	.TH strtol 3 2024-07-23 "Linux man-pages 6.9.1-158-g2ac94c631"
	.SH NAME
	strtol, strtoll, strtoq \- convert a string to a long integer
	.TH strtoul 3 2024-07-23 "Linux man-pages 6.9.1-158-g2ac94c631"
	.SH NAME
	strtoul, strtoull, strtouq \- convert a string to an unsigned long integer

You can request several sections with a regex:

	$ man -w strtol strtoul | xargs mansect '\(NAME\|SEE ALSO\)'
	.TH strtol 3 2024-07-23 "Linux man-pages 6.9.1-158-g2ac94c631"
	.SH NAME
	strtol, strtoll, strtoq \- convert a string to a long integer
	.SH SEE ALSO
	.BR atof (3),
	.BR atoi (3),
	.BR atol (3),
	.BR strtod (3),
	.BR strtoimax (3),
	.BR strtoul (3)
	.TH strtoul 3 2024-07-23 "Linux man-pages 6.9.1-158-g2ac94c631"
	.SH NAME
	strtoul, strtoull, strtouq \- convert a string to an unsigned long integer
	.SH SEE ALSO
	.BR a64l (3),
	.BR atof (3),
	.BR atoi (3),
	.BR atol (3),
	.BR strtod (3),
	.BR strtol (3),
	.BR strtoumax (3)

And it can then be piped to groff(1) to format the entire set of pages:

	$ man -w strtol strtoul | xargs mansect '\(NAME\|SEE ALSO\)' | groff -man -Tutf8
	strtol(3)                  Library Functions Manual                  strtol(3)

	NAME
	     strtol, strtoll, strtoq - convert a string to a long integer

	SEE ALSO
	     atof(3), atoi(3), atol(3), strtod(3), strtoimax(3), strtoul(3)

	Linux man‐pages 6.9.1‐158‐g2ac... 2024‐07‐23                         strtol(3)
	───────────────────────────────────────────────────────────────────────────────
	strtoul(3)                 Library Functions Manual                 strtoul(3)

	NAME
	     strtoul, strtoull, strtouq - convert a string to an unsigned long integer

	SEE ALSO
	     a64l(3), atof(3), atoi(3), atol(3), strtod(3), strtol(3), strtoumax(3)

	Linux man‐pages 6.9.1‐158‐g2ac... 2024‐07‐23                        strtoul(3)


This is quite naive, and will not work with pages that define their own
stuff, since this script is not groff(1).  But it should be as fast as
is possible, which is what Colin wants, is as simple as it can be (and
thus relatively safe), and should work with most pages (as far as
indexing is concerned, probably all?).


Have a lovely night!
Alex

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

Download attachment "signature.asc" of type "application/pgp-signature" (834 bytes)