[Top][All Lists]

[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: Tue, 6 Sep 2022 21:35:55 +0200
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.2.0

Hi Branden,

On 9/6/22 21:13, G. Branden Robinson wrote:
Hi Doug & Alex,

At 2022-08-30T17:14:31-0400, Douglas McIlroy wrote:
An empty field conveys as much information as the uninformative
default, "Miscellaneous Information Manual", with less clutter. I
recommend abolishing the default.

I'm reluctant to do this because it breaks the orthogonality of the
current arrangement.

.\" Localize manual section titles for English.
.de an*localize-strings
.  ds an*section1 General Commands Manual\"
.  ds an*section2 System Calls Manual\"
.  ds an*section3 Library Functions Manual\"
.  ds an*section4 Kernel Interfaces Manual\"
.  ds an*section5 File Formats Manual\"
.  ds an*section6 Games Manual\"
.  ds an*section7 Miscellaneous Information Manual\"
.  ds an*section8 System Manager's Manual\"
.  ds an*section9 Kernel Developer's Manual\"

A man page author at anything less than master level might wonder, when
composing and test-rendering a section 7 page, why they have to supply
text in this case but not any other,

Oh, I was suggesting to drop the defaults for *all* sections, not 7. I.e., do not have a default header-middle.

I guess it comes from when man pages were designed to be printed as an actual book, and books sometimes have this little thing in the header of every page, or sometimes every other page, that tells you in which section of the book you are.

Well, there are various arguments against that that occur to me:

- Manual pages are not edited as books nowadays. Still, I have the intention of creating a single PDF for the Linux man-pages, as I think you already do with groff's, so okay, this is admittedly not a strong argument.

- The number between parentheses reminds you of the section anyway:

  $ man NULL | head -n1
  NULL(3const)                                        NULL(3const)
  $ man fopen | head -n1
  FOPEN(3)            Library Functions Manual            FOPEN(3)

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), 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 enough to tell that you're still reading section 3.

I don't know if doug also meant this.  I understood it that way.




Attachment: OpenPGP_signature
Description: OpenPGP digital signature

reply via email to

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