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

[Seth McDonald <sethmcmail@pm.me>]

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

Hi Alex,

On Tue, 27 Jan 2026 at 14:47:40 +0100, Alejandro Colomar wrote:
> [CC += Doug, Branden, наб]
> 
> Hi Seth!
> 
> On 2026-01-27T09:20:26+0000, Seth McDonald wrote:
> > G'day,
> > 
> > When parsing man pages, I've noticed I'm often only interested in a
> > particular set of sections within the page (e.g. SYNOPSIS, HISTORY).
> > And since skimming through the page to get to these sections can get
> > monotonous, I wrote up a small bash script to automate the process.
> 
> Agree.  I wrote mansect(1) for the same exact reason.
> 
> > 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.

[...]
> >  So I've improved the script somewhat and written a brief
> > man page for it, as included in this patch set.
> 
> That covers the main use case of mansect(1), so I think this specialized
> wrapper could be useful.

Agreed.  Less typing = better, after all (afaiu).  And it can certainly
be more appropriately written as an explict wrapper over mansect(1),
rather than its own self-contained script.

[...]
> Back then I also opted for the simplicity of allowing users to decide
> the formatter with which to format the manual page, which BTW is useful
> to test different ones (mandoc(1), groff(1)).  However, having a wrapper
> that calls man(1) seems useful.

That makes sense, and I agree with this reasoning for mansect(1).
Though I do think a simple wrapper with a reasonable default can be good
for when you're not interested in the difference.

> > 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.

> 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.

[...]
> Then, about the implementation, it checks the existence of commands,
> which is unnecessary: the shell will complain for us if they don't
> exist.
> 
> 	$ foo
> 	bash: foo: command not found
> 
> Keep it simple.
> 
> Then you export a few things:
> 
> +[[ $MAN_KEEP_FORMATTING ]] && export MAN_KEEP_FORMATTING=1
> +[[ $MANWIDTH ]] && export MANWIDTH
> 
> That seems redundant.  If it is already exported, the childs will
> inherit that.

These are both just things I sometimes add in my local scripts for
easier debugging.  Probably should have removed them for the patch.

> 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.

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.

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.

(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. :) )

-- 
Take care,
	Seth McDonald.

On-list:  2336 E8D2 FEB1 5300 692C  62A9 5839 6AD8 9243 D369
Off-list: 82B9 620E 53D0 A1AE 2D69  6111 C267 B002 0A90 0289

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 322 bytes --]