Re: man page style conventions

[Alejandro Colomar <alx@kernel.org>]

[-- 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 --]