groff
[Top][All Lists]
Advanced

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

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


From: Alejandro Colomar
Subject: Re: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty
Date: Wed, 7 Sep 2022 00:13:18 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.2.1

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

Attachment: OpenPGP_signature
Description: OpenPGP digital signature


reply via email to

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