[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Subsections are not recognized

From: Alejandro Colomar
Subject: Re: Subsections are not recognized
Date: Thu, 10 Nov 2022 11:28:31 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.4.1

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

$ 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
found style problems; aborting
make: *** [lib/
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

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 

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 *-)




Attachment: OpenPGP_signature
Description: OpenPGP digital signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]