Re: [RFC PATCH v1 0/2] New sman(1) script

[Alejandro Colomar <alx@kernel.org>]

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

Hi Seth,

On 2026-01-28T04:44:53+0000, Seth McDonald wrote:

[...]
> > > As far as I can tell, no program in src/bin/ can currently do this.  The
> > > closest is mansect(1), but that outputs the source code rather than the
> > > rendered page.
> > 
> > You could use mansect(1) for that, and pipe it to man(1) (or groff(1)).
> 
> I honestly have no idea how that never crossed my mind.  Seems so
> obvious in retrospect lol.

:-)

[...]
> > > As an example, the script currently re-renders the whole man page for
> > > each section in a for loop, rather than printing each section from the
> > > same rendered page, which would likely be more performant.
> > 
> > I honestly can't read that script.  My ability to read other people's
> > bash(1) scripts is quite limited.  :)
> 
> Very fair.  There's just something about shell scripts that make them
> particularly difficult to parse imo.

I think tend to have more issues reading scripts that use shell features
other than pipes.  Scripts that do 'foo|bar|baz|asd|fgh' tend to be
quite readable.

> > About the interface, I think I like more the interface of mansect(1),
> > which is
> > 
> > 	mansect section [file ...]
> > 
> > I think that's ideal.  We don't need an argument like man(1)'s -s,
> > because that would be more easily specified as
> > 
> > 	mansectf LIBRARY printf.3;
> > 
> > The .3 disambiguates without needing a separate argument.  However,
> > I don't think we want to do librarian work here, and think we should
> > entirely refrain from accepting manual page names like man(1).  I think
> > we should only accept file names.
> 
> I modelled the interface after man(1) because I assumed that would be
> more familiar.  But I'd certainly be down for an interface like
> mansect(1)'s if that's preferable.

A benefit of mansect(1)'s interface is that it can be used on a
directory:

	mansect HISTORY man2/

And it works on all files under that directory.  I've found that to be
quite useful.

[...]
> > And then about the main work, it can be done by calling mansect(1) in
> > a pipeline.
> > 
> > With that in mind, I've written my own approach, which I've called
> > mansectf.
> > 
> > 	$ 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;
> > 
> > Does this work for you?  I look at it and wonder if it's worth
> > a separate script, but then it might be useful for people who are less
> > experienced with man(1).  To be fair, few people know that man(1) can
> > accept stdin, and even if they know, sometimes convenience wrappers
> > improve readability: for example, printf(1) is unnecessary given that
> > fprintf(3) exists, yet it's thoroughly used and I find it essential.
> > 
> > 	printf("foo");
> > 	fprintf(stdout, "foo");
> > 
> > So, I think such a thin wrapper can have its place, as it's the main use
> > case of mansect(1).
> 
> This would be perfectly suitable, at least for my use cases.  I also
> think mansectf is a *much* more apt name.

Nice!

> All in all, I also think the best option here is a thin wrapper over
> mansect(1).  The main benefit being that it would simplify many use
> cases of mansect(1) without adding an unreasonable amount of complexity.

Yup.

> Also, if we were to add mansectf, I would probably opt for adding it to
> mansect(1)'s man page, rather than giving it its own page.

I think I'll write a separate manual page.  I tend to dislike pages that
document more than one API, with few exceptions.  Exceptions are for
example modf/modff/modfl, where the only difference is the type.

> (P.S. While I'm nowhere near an expert on Unix shells, I honestly feel
> like I've learnt more about their use from these email exchanges than
> most other sources.  So thanks for that. :) )

You're welcome!  :-)

(FWIW, I also learnt to write good shell scripts in this mailing list;
 especially, preparing scripts for applying global changes to the manual
 pages, and for finding inconsistencies in manual pages.)


Have a lovely day!
Alex

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

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