On 01/06/14 09:17, Mike Frysinger wrote:
> 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"
Yes, better. Changed.
> project.
>
> also, is that quoting really necessary ?
No; fixed.
> and should the - be escaped ?
No. Maybe I need to clarify something. In general, the only time
you need a real dash is for numbers and pieces of code.
> 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.
Done.
>> .SS Use of gender-neutral language
>> As far as possible, use gender-neutral language in the text of man
>> page.
>
> page->pages ?
Already fixed.
>> 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.
Removed.
>> .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 ?
"where" seems better to me.
>> .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.
I might add this later.
>> .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)".
Yup. Made some changes here.
>> .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:
Done.
> 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.
Here the distinction is "Roman" versus "Italic". It's the term used
by the "man" macros.
>> American English tends to use the forms "backward" "upward", 'toward",
> there's a stray single quote before the toward rather than double quote
Thanks,
>> .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
I added
.SS Unicode under Linux
as an example
>> .SS Preferred terms
>
> how about:
> 32-bit 32bit Also applies to 64-bit/128-bit/etc...
Added.
> filesystem file system, fs
Added.
>> 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
I added a reference to that section.
>> .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. "").
Do you have a suggested wording?
>> .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"
It's rarely been a problem, so I'm loathe to clutter the list with
that guideline (but I agree with it).
>> .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.
Done.
>> .SS Example programs and shell sessions
>> Manual pages can include example programs demonstrating how to
>> use a system call or library function.
>
> can->may
Done.
Thanks for checking this over, Mike.
Updated version is in Git.
Cheers,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
