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