Re: Subsections are not recognized

[Alejandro Colomar]

Hi Branden!

On 11/10/22 10:31, G. Branden Robinson wrote:
> Hi Alex,
>
> At 2022-11-09T23:46:43+0100, Alejandro Colomar wrote:
> > I remember having reported this, but can't seem to find the report.
> > Just to make sure it's not forgotten before 1.23.0, I'll remind about
> > it:
> >
> > $ make lint-man V=1
> > LINT (groff)    tmp/lint/man2type/open_how.2type.lint-man.groff.touch
> > tbl man2type/open_how.2type \
> > | eqn -Tutf8  \
> > | troff -man -t -M ./etc/groff/tmac -m checkstyle -rCHECKSTYLE=3 -ww -Tutf8
> > -rLL=78n  \
> > | grotty -c  \
> > | col -b -p -x  \
> > | (! grep -n '.\{80\}.' >&2)
> > an.tmac:man2type/open_how.2type:6: style: .TH missing fifth argument and
> > second argument '2type' not a recognized manual section; specify volume
> > title
> > found style problems; aborting
> > make: *** [lib/lint-man.mk:77:
> > tmp/lint/man2type/open_how.2type.lint-man.groff.touch] Error 1
> >
> > Subsections should be recognized and treated as the section to which
> > they belong.
>
> I regret to say I _don't_ remember agreeing to change groff man(7) in
> this way.

I don't intend man(7) to change to have new default texts for subsections, if 
that's what you understood.

I just would like that if there's no 5th argument, it defaults to the default 
text of the _main_ section to which the subsection belongs.  That is, if I don't 
write a text for the 2type subsection, man(7) defaults to "System Calls Manual" 
as it would for section 2.  Does that sound good to you?

I also didn't mean that we had agreed about it, but rather that I'd like to get 
some consensus about it before the release, whether it is changing man(7) or the 
man-pages.

>  If you will recall, I was dubious about your introduction of
> these suffixes in the first place.

I remember.

> I suggested grouping them by C
> header file name, but you rightly pointed out that even in standard C
> that doesn't unambiguously locate a single definition for a symbol.
>
> I therefore now see some sense in your suffixing approach; I simply
> would urge you to discourage writers of third-party C libraries from
> copying it.  The OS layer is messy because history is messy (and
> complicated).

I'm thinking about it.  I'm also considering Ingo's proposition about 
configuring man(1) with a configuration file (or maybe a new directory with 
symlinks[1]), and then adding a flag -M to refer to the manual being consulted.

> If you want to introduce bespoke subcomponents of the manual section
> number, I do in fact think you should take on the added responsibility
> of supplying a fifth argument to `TH` to explain what that subcomponent
> is about.

Yeah, I might do that, if using the text of the main section of the manual is 
not clear enough; isn't it?

> I suppose in this case it might be something like the following.
>
> .TH open_how 2type ... ... "System Call Data Types"

open_how(2type)        System Calls Manual       open_how(2type)

I think the above header could make sense.  It would be simpler, IMO.  What are 
your thoughts?

> I see multiple advantages in delegating this responsibility to the man
> page author.
>
> 1.  You maintain control of the subsections and their meanings.

I prefer a (yet unwritten) info(2type) page, but keeping the main section's 
title.

> 2.  You can change your mind again, and reform is only a "sed -i" away.
> 3.  While you exercise your freedoms under points 1 and 2, there is no
>      desynchronization with the man(7) implementation.
> 4.  We avoid cramming the man(7) implementation full of giant lists of
>      symbols that stultify readers and learners, and of which any given
>      page will use a tiny fraction.  mdoc(7)'s body hangs on the wire as
>      a baleful warning to us on this very point.[1][2]

No, I don't intend to add new texts in man(7).

In fact, I'd go as far as killing all those strings in there (your 1 and 2 
notes), and recommend instead using the in-page LIBRARY section for that.

"Library Functions Manual" should be good for the ncurses manual pages in 
section 3 (or any subsection therein), IMO.  The LIBRARY in-page section should 
clarify that it's about ncurses, libc, or whatever.

IMO, the whole 5th argument could even be killed in man(7)...

> (There is indeed value in having correct and consistent nomenclature,
> which I must assume was the purpose of these string definitions, but I
> think a better way to solve these problems would be to (1) document
> them, perhaps in a section 7 man page, and (2) encourage the development
> of linter tools to detect common mistakes.  One might claim that
> mdoc(7)'s approach is more reliable, but I observe that the ignorant
> user can get around its curated lexicon in most or all cases by simply
> typing a phrase in prose.  Observe how `Dt` and `Os` simply use
> unrecognized arguments verbatim.  I therefore do not find mdoc(7)'s
> string dictionary approach a sound design choice.[3])
>
> In the example above, I left out the word "Manual", as Doug McIlroy
> correctly pointed out that the word, suffixing every single one of our
> predefined manual section names, explains (nearly) nothing.  I wouldn't
> mind removing it from groff's man(7) and mdoc(7) implementations, but
> that's another reform I am not anxious to pursue before 1.23 is out.

I agree with Doug.  Just kill it.  :)
Waiting for after 1.23 makes sense, though.

> What do you think?

All of the above *-)


Cheers,

Alex

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

OpenPGP_signature
Description: OpenPGP digital signature