On Thursday 02 January 2014 21:55:56 Michael Kerrisk (man-pages) wrote:
> .SH STYLE GUIDE
> The following subsections represent the beginnings of a style guide
> for the
> .IR "man-pages"
> project.
these are the kind of time based sentences that hang around for years ;)
how about:
The following subsections describe the preferred style for the
.IR "man-pages"
project.
also, is that quoting really necessary ? and should the - be escaped ? you
don't do it below, and the style guide seems to indicate you should :)
> For details not covered below, the Chicago Manual of Style
> is usually a good source.
would also add a suggestion of grepping around for pre-existing usage in the
tree.
> .SS Use of gender-neutral language
> As far as possible, use gender-neutral language in the text of man
> page.
page->pages ?
> Use of "they" ("them", "themself", "their") as a gender-neutral singular
> pronoun is acceptable for pages in the
> .IR man-pages
> project.
do we really need to mention the man-pages project again ? seems superfluous
here.
> .SS Font conventions
> .PP
> For functions, the arguments are always specified using italics,
> .IR "even in the SYNOPSIS section" ,
> where the rest of the function is specified in bold:
where->while ?
> .PP
> .BI " int myfunction(int " argc ", char **" argv );
> .PP
> Variable names should, like argument names, be specified in italics.
add a .PP for casts ?
how about discussing spacing ? none before the argument list, but there
should be one between a cast and the casted object.
> .PP
> Filenames (whether pathnames, or references to files in the
> .I /usr/include
> directory)
> are always in italics (e.g.,
> .IR <stdio.h> ),
> except in the SYNOPSIS section, where included files are in bold (e.g.,
> .BR "#include <stdio.h>" ).
> When referring to a standard include file under
> .IR /usr/include ,
> specify the header file surrounded by angle brackets,
> in the usual C way (e.g.,
> .IR <stdio.h> ).
i wonder if we should say something like "a standard library include" rather
than explicitly listing "/usr/include". after all, some headers are provided
by the C compiler (and likely won't be in /usr/include), and that path isn't
applicable when talking about cross-compilers or user-based installs, or other
not-quite-as-funky setups. we could retain one mention of /usr/include in an
aside like "(e.g. headers in /usr/include)".
> .PP
> Complete commands should, if long,
> be written as an indented line on their own, for example
> .in +4n
> .nf
>
> man 7 man-pages
>
> .fi
> .in
should also mention that there should be a blank line before/after it.
otherwise, this code would pass the guide:
Complete commands ...
.br
man 7 man-pages
> .PP
> Any reference to the subject of the current manual page
> should be written with the name in bold.
> If the subject is a function (i.e., this is a Section 2 or 3 page),
> then the name should be followed by a pair of parentheses
> in Roman (normal) font.
is "Roman" really necessary here ? it's not like changing fonts is even
feasible in man pages.
> American English tends to use the forms "backward" "upward", 'toward",
there's a stray single quote before the toward rather than double quote
> .SS Capitalization
> In subsection ("SS") headings,
> capitalize the first word in the heading, but otherwise use lower case,
> except where English usage (e.g., proper nouns) or programming
> language requirements (e.g., identifier names) dictate otherwise.
might be useful to include an example here
> .SS Preferred terms
how about:
32-bit 32bit Also applies to 64-bit/128-bit/etc...
filesystem file system, fs
> The following table lists some preferred terms to use in man pages,
> mainly to ensure consistency across pages.
the run time/user space/etc... items could do with a note pointing to the
hyphenation section below
> .SS NULL, NUL, null pointer, and null character
would be nice to have a sentence on the preferred wording when talking about
an empty C string (i.e. "").
> .SS Use of e.g., i.e., etc., a.k.a., and similar
how about also discouraging use of lists like "this/that/other/etc..." in
favor of "this, that, other, and so on"
> .SS Em-dashes
> The way to write an em-dash (\(em) in *roff is with the macro "\\(em".
> Em-dashes should be written
> .I without
> surrounding spaces.
would be nice to add an example of what this is replacing as not everyone
knows what an "em dash" is.
> .SS Example programs and shell sessions
> Manual pages can include example programs demonstrating how to
> use a system call or library function.
can->may
-mike
Attachment:
signature.asc
Description: This is a digitally signed message part.
