Re: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty

[Alejandro Colomar]

Hi Branden,

On 9/6/22 22:42, G. Branden Robinson wrote:
> Hi Alex,
>
> At 2022-09-06T21:43:28+0200, Alejandro Colomar wrote:
> > On 9/6/22 21:35, Alejandro Colomar wrote:
> > >     Most if not all readers of manual pages will know the meaning of
> > >   those little numbers.  The few that don't, are probably using
> > >   man(1) for the first time in their lives, and it will kindly hint
> > >   that they should read man(1),
> >
> > Of course, I referred to:
> >
> > $ man
> > What manual page do you want?
> > For example, try 'man man'.
>
> This is more a suggestion for Colin Watson, but pointing the n00b toward
> the intro(1) page might be an even better idea.  man-db's man(1) page is
> fairly intimidating thanks to all of the features users have come to
> demand of it.
>
> On the other hand, such a shift might not be worthwhile until someone
> champions the inclusion of James K. Lowden's intro(1) rewrite, or
> something like it, into the Linux man-pages.

If someone wants to send it as a patch, I'm open to discussing it.
I remember having some concerns when I read the page, but I don't 
remember now about them.  I'd be happy to discuss it with a patch sent 
to linux-man@.

> > > which also documents that as one of the first things.  And for those
> > > that are reading the pages as a book, the intro page will introduce the
> > > chapter to the reader, so, again, the number will be
> >
> > This has bugged me for a long time:
> >
> > Things like 1-9 are manual sections.
>
> More precisely, they are sections of a volume of the manual.  Proper
> Unix Programmer's Manuals came in two volumes, albeit as far as I know
> this only happened twice: for 7th edition and 10th edition Research.
>
> > But things like NAME, SYNOPSIS, ...  are also called manual page
> > sections (with the little difference of "page").
>
> It's a solecism.  Strictly, they are _section headings_.  But it is
> awkward to use the word "heading" in cross-references.

I disagree (but probably you understood something different from what I 
meant; continue reading).  The 'section headings' are the headings for 
the page sections.  The 'sections' are the contents themselves 
(including the heading).  Of course, when I referred to SYNOPSIS, I 
really meant the contents of that section, and not to the heading 
itself; that was obvious in my head, but might not be so obvious now 
that I think.

>  In my groff work
> I say
>
>    section \[lq]$section_heading_text\[rq] {above, below}
>
>    subsection \[lq]$subsection_heading_text\[rq] {above, below}
>
>    section \[lq]$section_heading_text\[rq] of
>    .MR foo 1
>
>    subsection \[lq]$subsection_heading_text\[rq]
>    .MR foo 1
>
> as appropriate.  _In context_, this usage is unambiguous, which is why I
> adopted it.
>
> > Why, why?  Why didn't history refer to them as different things?
>
> Because people like you and me don't have time machines to go back to
> Room 1127 and wail at people with.  Compounded by uncritical reverence
> for every decision anyone involved with the Bell Labs CSRC and, later,
> Berkeley CSRG made, not to mention the utility that confusing points of
> terminology possessed for the gatekeeping practices of an earlier
> generation of brogrammers.
>
> You know how it is, Deckard.  If you're not Core Team, you're little
> people.
>
> In any case, if I had such a time machine, I'd have a higher
> priority--kidnapping Dana Carvey from 1986 and pulling him, in character
> as the Saturday Night Live "Church Lady", to 1970s Murray Hill to run
> the word "special" so far into the ground that the CSRC people never
> used it in terminology again.

You would have to let me the machine to go tell K&R some things about 
promoting everything to int.  That, and that fixed width types should be 
the fundamental ones, and the convenient ones should be just typedefs. 
Lucky those who didn't know what an ABI would be.

> In the historical Unix literature I've read, and that's a fair piece,
> though surely not enough--the word "special" is only ever applied in
> nomenclature as an admission of defeat.  Or, perhaps, as a signpost that
> conceptual boundaries in the area under discussion had not been as
> carefully considered as one would like.  (These days, such things often
> get the overused metaphor "leaky abstraction" pinned on them.[1])
>
> If the latter, I wish the practice had been more frankly acknowledged.
>
> > I've seen sporadically references to the numbers as chapters, probably
> > from when the manual was a proper book, but that term seems to have
> > fallen in use.
>
> I don't recall seeing this.  While not my preference, I would regard it
> as an excusable innovation in response to an unhelpful overlap in prior
> usage.

I don't remember where I've seen this.  I seem to recall it, but maybe 
it's just a glitch in my memory.  It would certainly simplify 
nomenclature.  If we come up with a good term for subsections such as 
3head, I might start using the term colloquially.  Does subchapter sound 
good to you?

> > > enough to tell that you're still reading section 3.
> >
> > BTW, I had been thinking about this recently: I need to write intro(*)
> > pages for all the new subsections I created.  And system_data_types(7)
> > will probably be a link page to into(3type).
> >
> > Gimme some time for that.  I need inspiration.  Suggestions welcome.
> > :)
>
> I suggest only that you take that opportunity to tell authors of non-C
> library man pages _not_ to use these specialized sections.

Yup, I could add something about that.

>  They exist
> only to impose some ordering on the Amazing Technicolor Dreamcoat of the
> excessively ramified standard C library.

Actually, I think it's the lack of ramification the thing that's so 
problematic.  If it had something like hundreds of small headers, each 
with its small subset of functions and types, then documenting a header 
per manual page would be easy.

> Regards,
> Branden
>
> [1] This past weekend I was reading _Numerical Recipes_ and noticed to
>      my horror the application of the term "abstract data type" to
>      bog-standard _aggregate_ data types (C: structs).  Apparently these
>      were thought by Metcalf to be insufficiently excitingly to Fortran
>      77 programmers on their own merits, such that when Fortran 90
>      finally got a record type, they needed this sexed-up, and
>      inappropriate, term applied to them.
>
>      Yeah, boy--let's get a case of IPA delivered and bro down with some
>      ASTs.  <fist bump>[2]
>
>      "Those types are not 'abstract'--they are as real as int and float."
>      -- guess who?[3]
>
> [2] Of course I'm being unfair.  The bros I've met seem to prefer stouts
>      that are hopped to the moon.
>
> [3] Z. Qbhtynf ZpVyebl [ROT-13]

:p  By the way, an actual link to the context of the quote would be 
nice.  I've only found copies of the quote without context.  Where did 
that appear?

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

OpenPGP_signature
Description: OpenPGP digital signature