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: G. Branden Robinson
Subject: Re: Bug#1018737: /usr/bin/rst2man: rst2man: .TH 5th field shouldn't be empty
Date: Tue, 6 Sep 2022 14:13:20 -0500

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, and also might wonder if the
missing center header on the rendered page constitutes a bug in the
formatter or macro package.  That could lead to spurious defect reports,
which I definitely don't like with my groff developer's hat on.

I agree that "Miscellaneous Information Manual" doesn't say much.  A
little, yes--but it is chagrining that it's the longest section title by
a significant margin, to utter such paucity.

I'm open to suggestions for new text.  Something shorter would be good,
to reduce the probability of man page title shortening due to collision,
a new groff 1.23 man(7) feature.

https://savannah.gnu.org/bugs/index.php?43532

I don't, however, want to muck with the contents of these string
definitions  before 1.23 final because they would need their
translations updated (cs, fr, de, it, sv).

At 2022-09-06T19:00:40+0200, Alejandro Colomar wrote:
> Agree, the section number already provides a good default information
> (and for more details, consult man(1)).  The text is mostly useless.
> 
> BTW, I just noticed that if you write a mdoc(7) page, the defaults are
> worse than uninformative; they are misinformation:

[groff mdoc(7) slaps "BSD" in front of all the section titles]

> Where did that BSD come from?

It was apparently a Christmas present from Werner to all Linux haters.
;-)

https://git.savannah.gnu.org/cgit/groff.git/commit/?id=71c06e4dd7b2a901e4cf7fc1624098f890f7821f

> That seems like a bug to me.

Yes--I want to kill this `doc-volume-operating-system` string.
Similarly, no one has been willing to proclaim that having
`doc-default-operating-system` be "BSD" makes any sense for the groff
project.  Ingo and I discussed this in July.  It is one of my release
goals for groff 1.23.

https://lists.gnu.org/archive/html/groff/2022-07/msg00280.html

I admit that I don't know off the top of my head how an mdoc page author
is supposed to override the manual section title, or if that is even
admitted by the macro language.  (You _can_ go behind its back and
redefine *roff strings in an implementation-dependent way, but this has
obvious portability problems.)

Regards,
Branden

Attachment: signature.asc
Description: PGP signature


reply via email to

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