[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
>
- Re: [groff] groff as the basis for comprehensive documentation?, (continued)
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, Ingo Schwarze, 2018/04/22
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/22
- Re: [groff] groff as the basis for comprehensive documentation?, G. Branden Robinson, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, Nate Bargmann, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?,
John Gardner <=
- Re: [groff] groff as the basis for comprehensive documentation?, Ralph Corderoy, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, John Gardner, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, Ralph Corderoy, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, Nate Bargmann, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, James K. Lowden, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, G. Branden Robinson, 2018/04/21
- Re: [groff] groff as the basis for comprehensive documentation?, Ingo Schwarze, 2018/04/22
- Re: [groff] groff as the basis for comprehensive documentation?, Ralph Corderoy, 2018/04/25
- Re: [groff] groff as the basis for comprehensive documentation?, Steve Izma, 2018/04/25