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
