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

[Alejandro Colomar]

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\"
>
> https://git.savannah.gnu.org/cgit/groff.git/tree/tmac/an.tmac#n181
>
> 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.

Cheers,

Alex

--
<http://www.alejandro-colomar.es/>

OpenPGP_signature
Description: OpenPGP digital signature