Re: man page style conventions

[Lennart Jablonka <humm@ljabl.com>]

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).