Re: man page style conventions

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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




[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux