diff --git a/man7/man-pages.7 b/man7/man-pages.7 index 66e213045..86ec3a592 100644 --- a/man7/man-pages.7 +++ b/man7/man-pages.7 @@ -27,7 +27,7 @@ .\" 2007-05-30 created by mtk, using text from old man.7 plus .\" rewrites and additional text. .\" -.TH MAN-PAGES 7 2013-07-24 "Linux" "Linux Programmer's Manual" +.TH MAN-PAGES 7 2014-01-03 "Linux" "Linux Programmer's Manual" .SH NAME man-pages \- conventions for writing Linux man pages .SH SYNOPSIS @@ -126,8 +126,7 @@ The section number in which the man page should be placed (e.g., .TP .I date The date of the last revision\(emremember to change this every time a -change is made to the man page, -since this is the most general way of doing version control. +nontrivial change is made to the man page. Dates should be written in the form YYYY-MM-DD. .TP .I source @@ -393,6 +392,9 @@ in which various system calls first appeared. .B CONFORMING TO describes any standards or conventions that relate to the function or command described by the manual page. +The preferred terms to use for the various standards are listed as +headings in +.BR standards (7). For a page in Section 2 or 3, this section should note the POSIX.1 version(s) that the call conforms to, @@ -454,6 +456,20 @@ and directives. Hyphenation of individual page names can be prevented by preceding words with the string "\\%". +.SH STYLE GUIDE +The following subsections represent the beginnings of a style guide +for the +.IR "man-pages" +project. +For details not covered below, the Chicago Manual of Style +is usually a good source. +.SS Use of gender-neutral language +As far as possible, use gender-neutral language in the text of man +page. +Use of "they" ("them", "themself", "their") as a gender-neutral singular +pronoun is acceptable for pages in the +.IR man-pages +project. .SS Font conventions .PP For functions, the arguments are always specified using italics, @@ -542,17 +558,245 @@ The preferred way to write this in the source file is: (Including the section number in cross references lets tools like .BR man2html (1) create properly hyperlinked pages.) + +Control characters should be written in bold face, +with no quotes; for example, +.BR ^X . .SS Spelling Starting with release 2.59, .I man-pages follows American spelling conventions -(previously, there was a random mix of British and American spallings); +(previously, there was a random mix of British and American spellings); please write all new pages and patches according to these conventions. + +Aside from the well-known spelling differences, +there are a few other subtleties to watch for: +.IP * 3 +American English tends to use the forms "backward" "upward", 'toward", +and so on +rather than the British forms "backwards", upwards", "towards", and so on. +.SS BSD version numbers +The classical scheme for writing BSD version numbers is +.IR x.yBSD , +where +.I x.y +is the version number (e.g., 4.2BSD). +Avoid forms such as +.IR "BSD 4.3" . .SS Capitalization -In subsection ("SS") headings -capitalize the first word in heading, but otherwise use lower case, +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. +.SS Indentation of structure definitions, shell session logs, etc. +When structure definitions, shell session logs, and so on are included +in running text, indent them by 4 spaces (i.e., a block enclosed by +.I ".in\ +4n" +and +.IR ".in" ). +.SS Preferred terms +The following table lists some preferred terms to use in man pages, +mainly to ensure consistency across pages. +.ad l +.TS +l l l +--- +l l l. +Term Avoid using Notes + +bit mask bitmask +built-in builtin +Epoch epoch T{ +For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC) +T} +filename file name +hostname host name +inode i-node +pathname path name +pseudoterminal pseudo-terminal +privileged port T{ +reserved port, +system port +T} +real-time T{ +realtime, +real-time +T} +run time runtime +saved set-group-ID T{ +saved group ID, +saved set-GID +T} +saved set-user-ID T{ +saved user ID, +saved set-UID +T} +set-group-ID set-GID, setgid +set-user-ID set-UID, setuid +superuser T{ +super user, +super-user +T} +timestamp time stamp +timezone time zone +user space userspace +username user name +zeros zeroes +.TE +.ad +.SS Terms to avoid +The following table lists some terms to avoid using in man pages, +along with some suggested alternatives, +mainly to ensure consistency across pages. +.ad l +.TS +l l l +--- +l l l. +Avoid Use instead Notes + +current process calling process T{ +A common mistake made by kernel programmers when writing man pages +T} +manpage T{ +man page, manual page +T} +minus infinity negative infinity +non-root unprivileged user +non-superuser unprivileged user +nonprivileged unprivileged +OS operating system +plus infinity positive infinity +pty pseudoterminal +runtime run time +tty terminal +Unices UNIX systems +Unixes UNIX systems +.TE +.ad +.SS Trademarks +Use the correct spelling of trademarks. +The following is a list of the correct spelling of various +relevant trademarks that are sometimes misspelled: + + DG/UX + HP-UX + UNIX + UnixWare +.SS NULL, NUL, null pointer, and null character +A +.IR "null pointer" +is a pointer that points to nothing, +and is normally indicated by the constant +.IR NULL . +On the other hand, +.I NUL +is the +.IR "null byte", +a byte with the value 0, represented in C via the character constant +.IR \(aq\e0\(aq . + +The preferred term for the pointer is "null pointer" or simply "NULL"; +avoid writing "NULL pointer". + +The preferred term for the byte is "null byte". +Avoid writing "NUL", since it is too easily confused with "NULL". +Avoid also the terms "zero byte" and "null character". +The byte that terminates a C string should be described +as "the terminating null byte"; +strings may be described as "null-terminated", +but avoid the use of "NUL-terminated". +.SS Hyperlinks +For hyperlinks, use the +.IR .UR / .UE +macro pair +(see +.BR groff_man (7)). +This produces proper hyperlinks that can be used in a web browser, +when rendering a page with, say: + + BROWSER=firefox man -H pagename +.SS Use of e.g., i.e., etc., a.k.a., and similar +In general, the use of abbreviations such as "e.g.", "i.e.", "etc.", "a.k.a." +should be avoided, in favor of suitable full wordings +("for example", "that is", "and so on", "also known as"). + +The only place where such abbreviations may be acceptable is in +.I short +parenthetical asides (e.g., like this one). + +Always include periods in such abbreviations, as shown here. +In addition, "e.g." and "i.e." should always be followed by a comma. +.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. +.SS Hyphenation of attributive compounds +Counpound terms should by hyphenated when used attributively +(i.e., to qualify a following noun) Some examples: + + command-line argument + floating-point number + run-time check + user-space function + wide-character string +.SS Hyphenation with multi, non, pre, re, sub, and so on +The general tendency in modern English is not to hyphenate +after prefixes such as "multi", "non", "pre", "re", "sub", and so on. +Manual pages should generally follow this rule when these prefixes are +used in natural English constructions with simple suffixes. +The following list gives some examples of the preferred forms: + + interprocess + multithreaded + multiprocess + nonblocking + nondefault + nonempty + noninteractive + nonnegative + nonportable + nonzero + preallocated + precreate + prerecorded + reestablished + reinitialize + rearm + reread + subcomponent + subdirectory + subsystem + +Hyphens should be retained when the prefixes are used in nonstandard +English words, with trademarks, proper nouns, acronyms, or compound terms. +Some examples: + + non-ASCII + non-English + non-NULL + non-real-time + +Finally, note that "re-create" and "recreate" are two different verbs, +and the former is probably what you want. +.SS Real hyphen character +Where a real hyphen character is required (e.g., for numbers such as \-1), +use the following form in the man page source + + \\- + +This guideline applies also to code examples. +.SS Character constants +To produce single quotes that render well in both ASCII and UTF-8, +use the following form for character constants in the man page source: + + \\(aqC\\(aq + +where +.I C +is the quoted character. +This guideline applies also to character constants used in code examples. .SS Example programs and shell sessions Manual pages can include example programs demonstrating how to use a system call or library function. @@ -584,6 +828,17 @@ Example programs should be laid out according to Kernighan and Ritchie style, with 4-space indents. (Avoid the use of TAB characters in source code!) .IP * +For consistency, all example programs terminate using either of; + + exit(EXIT_SUCCESS); + exit(EXIT_FAILURE); + +Avoid using the following forms to terminate a program: + + exit(0); + exit(1); + return n; +.IP * If there is extensive explanatory text before the program source code, mark off the source code with a susbsection heading @@ -608,12 +863,6 @@ For some examples of what example programs should look like, see .BR wait (2) and .BR pipe (2). -.SS Indentation of structure definitions, shell session logs, etc. -When structure definitions, shell session logs, and so on are included -in running text, indent them by 4 spaces (i.e., a block enclosed by -.I ".in\ +4n" -and -.IR ".in" ). .SH EXAMPLE For canonical examples of how man pages in the .I man-pages