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

[G. Branden Robinson]

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.

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

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.

> > 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.  They exist
only to impose some ordering on the Amazing Technicolor Dreamcoat of the
excessively ramified standard C library.

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]

signature.asc
Description: PGP signature