[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
Re: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty
Tue, 6 Sep 2022 21:35:55 +0200
Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101 Thunderbird/102.2.0
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
.\" Localize manual section titles for English.
. 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
- The number between parentheses reminds you of the section anyway:
$ man NULL | head -n1
$ 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.
Description: OpenPGP digital signature