groff
[Top][All Lists]
Advanced

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

Re: [groff] groff as the basis for comprehensive documentation?


From: John Gardner
Subject: Re: [groff] groff as the basis for comprehensive documentation?
Date: Sat, 21 Apr 2018 22:58:57 +1000

*> The section heading examples in man-pages(7) are in all upper case.*

It's ironic how this convention of unconventional formatting has stuck
around since the beginning, but in over 40 years of writing manpages,
nobody's been able to agree on a consistent way of hyphenating the damn
word.

Manpages, man-pages, or man\(empages?

On 21 April 2018 at 22:16, Nate Bargmann <address@hidden> wrote:

> * On 2018 21 Apr 02:07 -0500, G. Branden Robinson wrote:
> > In my opinion, which I am far too young and poorly-connected to have
> > proffered when it would have made any difference, the
> > forced-full-capitalization of section titles in man page sources is an
> > information-destroying transform done in the wrong place at the wrong
> > time.  Section headings should be capitalized as section titles normally
> > are in technical documentation: either like work titles, or first-letter
> > only, with the normal rules for proper nouns and adjectives respected.
>
> To be effective, I think one needs to get Michael Kerrisk of the
> man-pages project https://www.kernel.org/doc/man-pages/ on board.  The
> section heading examples in man-pages(7) are in all upper case.  I've
> been using this page and others of the project along with groff_man(7)
> as a guide for formatting my own pages.
>
> > This has been itching me for many years; thanks for the excuse to air
> > my grievance.  ;-)
>
> Glad to start the thread that has led a number of different directions!
> :-D
>
> - Nate
>
> --
>
> "The optimist proclaims that we live in the best of all
> possible worlds.  The pessimist fears this is true."
>
> Web: http://www.n0nb.us  GPG key: D55A8819  GitHub: N0NB
>


reply via email to

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