Re: Subsections are not recognized

[G. Branden Robinson]

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.  If you will recall, I was dubious about your introduction of
these suffixes in the first place.  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).

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.

I suppose in this case it might be something like the following.

.TH open_how 2type ... ... "System Call Data Types"

I see multiple advantages in delegating this responsibility to the man
page author.

1.  You maintain control of the subsections and their meanings.
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]

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

What do you think?

Regards,
Branden

[1] 
https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/mdoc/doc-syms?id=7e5d433ba5ddc2389986a5c02f91eb57fc1de47d#n190
    
https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/mdoc/doc-syms?id=7e5d433ba5ddc2389986a5c02f91eb57fc1de47d#n614
    
https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/mdoc/doc-syms?id=7e5d433ba5ddc2389986a5c02f91eb57fc1de47d#n788
[2] 
https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/mdoc/doc-common?id=7e5d433ba5ddc2389986a5c02f91eb57fc1de47d#n344
    
https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/mdoc/doc-common?id=7e5d433ba5ddc2389986a5c02f91eb57fc1de47d#n512

[3] I'm getting more familiar with mdoc(7) at long last because I have
    begun heavily revising its man page in the course of addressing two
    release-goal Savannah bugs.  It can boast of some nice features but
    it also has significant drawbacks and difficulties, some of which
    are above and some of which I am chronicling in my commit messages.

signature.asc
Description: PGP signature