man page style conventions

man page style conventions

[Keith Marshall]

Hello,

In the man-pages(7) document, as rendered at:
http://www.alejandro-colomar.es/share/dist/man-pages/git/HEAD/man-pages-HEAD.pdf#man-pages.7

under the section heading "FORMATTING AND WORDING CONVENTIONS", and
subsection "Formatting conventions (general)", close to the bottom of
page 9, I see:

> Any reference to another man page should be written with the name in
> bold, always followed by the section number, formatted in Roman
> (normal) font, without any separating spaces (e.g., intro(2)). The
> preferred way to write this in the source file is:
> 
>    .BR intro (2)

I have noticed that, as of groff-1.23, both groff_man(7), and the macro
package which it documents, flagrantly ignore, and indeed violate this
convention.  I further notice that man-pages(7) document, from which I
have quoted, above, appears to have been formatted using that very
version of groff_man(7), perhaps with the intro(2) reference, within the
quoted paragraph, having been formatted using:

   .MR intro 2

rather than the recommended:

   .BR intro (2)

This leads to a glaring anomaly, within the quoted paragraph; rather
than the topic name "intro" being set in bold, as the convention
demands, it is set in (non-bold) italics!

In my personal opinion, FWIW, the use of italics in this context is just
plain ugly.  Opinion aside, it does not conform to the convention, as it
is stated in man-pages(7) -- either the convention needs to be changed,
by common consent, or groff_man(7) needs to be brought to heel.

-- 
Regards,
Keith.

Re: man page style conventions

[G. Branden Robinson]

[-- Attachment #1: Type: text/plain, Size: 5656 bytes --]

At 2024-04-13T13:22:01+0100, Keith Marshall wrote:
> In the man-pages(7) document, as rendered at:
> http://www.alejandro-colomar.es/share/dist/man-pages/git/HEAD/man-pages-HEAD.pdf#man-pages.7
> 
> under the section heading "FORMATTING AND WORDING CONVENTIONS", and
> subsection "Formatting conventions (general)", close to the bottom of
> page 9, I see:
> 
> > Any reference to another man page should be written with the name in
> > bold, always followed by the section number, formatted in Roman
> > (normal) font, without any separating spaces (e.g., intro(2)). The
> > preferred way to write this in the source file is:
> > 
> >    .BR intro (2)
> 
> I have noticed that, as of groff-1.23, both groff_man(7), and the
> macro package which it documents, flagrantly ignore, and indeed
> violate this convention.  I further notice that man-pages(7) document,
> from which I have quoted, above, appears to have been formatted using
> that very version of groff_man(7), perhaps with the intro(2)
> reference, within the quoted paragraph, having been formatted using:
> 
>    .MR intro 2
> 
> rather than the recommended:
> 
>    .BR intro (2)

This is a deliberate change and was mooted on the groff mailing list for
literally years before landing.  For so long that plan9port's man(7)
started doing it first, in fact.

> This leads to a glaring anomaly, within the quoted paragraph; rather
> than the topic name "intro" being set in bold, as the convention
> demands, it is set in (non-bold) italics!
> 
> In my personal opinion, FWIW, the use of italics in this context is
> just plain ugly.  Opinion aside, it does not conform to the
> convention, as it is stated in man-pages(7) -- either the convention
> needs to be changed, by common consent, or groff_man(7) needs to be
> brought to heel.

When Bell Labs promulgated man(7) in 1979, their convention was
italic-on-roman, and they practiced it with high reliability, except in
the "SEE ALSO" section itself, where they used roman-on-roman.  Doug
McIlroy (the person responsible for man(7), for those who don't know)
characterized the latter as not a deliberate choice.

There hasn't been a single reliable convention for the styling of man
page cross references since at least 1988, with SunOS 4.0, when Sun
transitioned from `IR` to `BR` to cases like the above.  (I don't have
records of what System V Unices were doing in this period, but Sun
retained the change when converting their OS to a System V foundation
for SunOS 5/Solaris 2.)  This shift dovetailed with the limitations of
PC video text mode, which did not have an attribute bit for underlining
or italics, but did support bold and colors.  When BSD adopted mdoc(7)
to replace then-still-encumbered man(7)--at about the same time groff
was developing a free one anyway[1]--they fragmented the convention
further by adopting a practice of roman-on-roman.[2]

So we had 3 choices of face for the topic part of the cross reference
and all got used.

Because proponents of any one convention are prone to leap into combat
with the others to, uh, bring them to heel, I figured the best thing to
do was let the distributor/user decide on the typeface.  Besides which,
marking a man page cross reference as such, semantically, makes it
possible to automatically hyperlink them.  That started to pay off in
groff 1.23 and will do so even more in 1.24.

Reading the groff_man(7) page might be helpful to you.  Here is the
relevant material from Git HEAD.  groff 1.23.0's is similar.

     .MR topic [manual‐section [trailing‐text]]
            (since groff 1.23) Set a man page cross reference as
            “topic(manual‐section)”.  If trailing‐text (typically
            punctuation) is specified, it follows the closing
            parenthesis without intervening space.  Hyphenation is
            disabled while the cross reference is set.  topic is set in
            the font specified by the MF string.  If manual‐section is
            present, the cross reference hyperlinks to a URI of the form
            “man:topic(manual‐section)”.

     -dMF=man‐page‐topic‐font
              Select the font used for man page identifiers in .TH calls
              and topics named in .MR calls; the default is “I” (italic
              style of the default family).  Any valid argument to
              groff’s “.ft” request may be used.  If the MF string ends
              in “I”, it is assumed to be an oblique typeface, and
              italic corrections are applied before and after man page
              topics and identifiers.

     /etc/groff/man.local
            Put site‐local changes and customizations into this file.

(The path in the last item is configured at build time and differs from
place to place; the foregoing is Debian's practice.)

Regards,
Branden

[1] Someone on the TUHS mailing list shared a recollection that some
    people in the Berkeley CSRG wanted to give up AT&T troff
    compatibility in favor of groff.  Apparently, the kibosh was put on
    this by more senior figure(s).  My inference is that this decision
    was made by those intending to incorporate BSDI; to implicitly
    condone copylefted software, let along to ship it, was intolerable
    to those who had visions of extracting fat economic rents from a
    captive market of Unix sites that had committed themselves to
    "Opposing Sun Forever".[3]

[2] https://lists.gnu.org/archive/html/groff/2023-08/msg00005.html

[3] https://en.wikipedia.org/wiki/Open_Software_Foundation

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: man page style conventions

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 3127 bytes --]

On Sat, Apr 13, 2024 at 01:22:01PM +0100, Keith Marshall wrote:
> Hello,

Hi Keith! (and Branden!)

> In the man-pages(7) document, as rendered at:
> http://www.alejandro-colomar.es/share/dist/man-pages/git/HEAD/man-pages-HEAD.pdf#man-pages.7
> 
> under the section heading "FORMATTING AND WORDING CONVENTIONS", and
> subsection "Formatting conventions (general)", close to the bottom of
> page 9, I see:

Page numbers broke at some point.  I noticed recently, but didn't know
when it started happening.  It might have been some of the refactors I
applied to the script.  If anyone contributes a fix to the script
without making it less readable, please.
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/share/mk/build/pdf/book/prepare.pl>

> 
> > Any reference to another man page should be written with the name in
> > bold, always followed by the section number, formatted in Roman
> > (normal) font, without any separating spaces (e.g., intro(2)). The
> > preferred way to write this in the source file is:
> > 
> >    .BR intro (2)

Yep.  We still follow that convention in the source code (you can check
yourself at any page's SEE ALSO for example).

> I have noticed that, as of groff-1.23, both groff_man(7), and the macro
> package which it documents, flagrantly ignore, and indeed violate this
> convention.  I further notice that man-pages(7) document, from which I
> have quoted, above, appears to have been formatted using that very
> version of groff_man(7), perhaps with the intro(2) reference, within the
> quoted paragraph, having been formatted using:
> 
>    .MR intro 2

It is written in the source code with BR:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/man7/man-pages.7#n754>

However, the magic script that prepares the PDF book does some
transformations to MR.  I think it's this line:
<https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/share/mk/build/pdf/book/prepare.pl#n140>

I would love to see that perl(1) script transformed into a bash(1)
script, so I can put my hands on it comfortably.  If anyone offers for
such task, such anyone is more than welcome.

> rather than the recommended:
> 
>    .BR intro (2)
> 
> This leads to a glaring anomaly, within the quoted paragraph; rather
> than the topic name "intro" being set in bold, as the convention
> demands, it is set in (non-bold) italics!

If you see the manual page in the terminal, you'll still see it in bold.
> 
> In my personal opinion, FWIW, the use of italics in this context is just
> plain ugly.  Opinion aside, it does not conform to the convention, as it
> is stated in man-pages(7) -- either the convention needs to be changed,
> by common consent, or groff_man(7) needs to be brought to heel.

Yep.  I'm waiting for Branden to send MR.sed, aka, the biggest
single-commit change ever to this repo (AFAIR).  When he sends that
patch, I'll change this page to recommend the use of MR.  (Or he could.)

Have a lovely day!
Alex

> 
> -- 
> Regards,
> Keith.

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: man page style conventions

[Lennart Jablonka]

Quoth Keith Marshall:
>In my personal opinion, FWIW, the use of italics in this context is just
>plain ugly.  Opinion aside, it does not conform to the convention, as it
>is stated in man-pages(7) -- either the convention needs to be changed,
>by common consent, or groff_man(7) needs to be brought to heel.

In addition to what Alex and Branden said, I will note that 
man-pages(7) contains this at the very beginning:

>This page describes the conventions that should be employed when 
>writing man pages for the Linux man-pages project, which 
>documents the user-space API provided by the Linux kernel and the 
>GNU C library.  The project thus provides most of the pages in 
>Section 2, many of the pages that appear in Sections 3, 4, and 7, 
>and a few of the pages that appear in Sections 1, 5, and 8 of the 
>man pages on a Linux system.  The conventions described on this 
>page may also be useful for authors writing man pages for other 
>projects.

man-pages(7) is pretty much prescriptive for the linux-man-pages 
project.  It is also something likely to be seen by someone 
wanting to learn how to write a man page, but it still is 
independent of what Groff does.  There exist different conventions 
for how to write man pages.  The <opinion>obviously traditionally 
correct</opinion> way of referring to other man pages is with 
explicit italics; the new Groff way is to use .MR; the 
linux-man-pages way is to embolden the title.

groff_man(7) conforms to the conventions—to /its/ conventions.  
The discrepancy between man-pages(7) and groff_man(7) does not 
imply that either has to change.

But yes, in my opinion, man-pages(7) should change.  I think it 
should probably go away, or stay inside the linux-man-pages 
repository, not getting installed.  It is, after all, 
linux-man-pages-specific and groff_man_style(7) exists.

Or it could be renamed.  linux-man-pages(7).  
linux-man-pages-man-pages(7).