diff options
Diffstat (limited to 'man7/man-pages.7')
| -rw-r--r-- | man7/man-pages.7 | 116 |
1 files changed, 58 insertions, 58 deletions
diff --git a/man7/man-pages.7 b/man7/man-pages.7 index aafb5785c2..2870c2db8d 100644 --- a/man7/man-pages.7 +++ b/man7/man-pages.7 @@ -102,7 +102,7 @@ Please limit source code line length to no more than about 75 characters wherever possible. This helps avoid line-wrapping in some mail clients when patches are submitted inline. - +.PP New sentences should be started on new lines. This makes it easier to see the effect of patches, which often operate at the level of individual sentences. @@ -138,11 +138,11 @@ Dates should be written in the form YYYY-MM-DD. .TP .I source The source of the command, function, or system call. - +.IP For those few \fIman-pages\fP pages in Sections 1 and 8, probably you just want to write .IR GNU . - +.IP For system calls, just write .IR "Linux" . (An earlier practice was to write the version number @@ -150,15 +150,15 @@ of the kernel from which the manual page was being written/checked. However, this was never done consistently, and so was probably worse than including no version number. Henceforth, avoid including a version number.) - +.IP For library calls that are part of glibc or one of the other common GNU libraries, just use .IR "GNU C Library" ", " GNU , or an empty string. - +.IP For Section 4 pages, use .IR "Linux" . - +.IP In cases of doubt, just write .IR Linux ", or " GNU . .TP @@ -214,13 +214,13 @@ be especially useful for pages in Sections 4 and 5). However, before doing this, consider whether you could use the traditional headings, with some subsections (\fI.SS\fP) within those sections. - +.PP The following list elaborates on the contents of each of the above sections. .TP 14 .B NAME The name of this manual page. - +.IP See .BR man (7) for important details of the line(s) that should follow the @@ -232,7 +232,7 @@ dictates otherwise. .TP .B SYNOPSIS A brief summary of the command or function's interface. - +.IP For commands, this shows the syntax of the command and its arguments (including options); boldface is used for as-is text and italics are used to @@ -242,7 +242,7 @@ separate choices, and ellipses (\&...) can be repeated. For functions, it shows any required data declarations or .B #include directives, followed by the function declaration. - +.IP Where a feature test macro must be defined in order to obtain the declaration of a function (or a variable) from a header file, then the SYNOPSIS should indicate this, as described in @@ -251,12 +251,12 @@ then the SYNOPSIS should indicate this, as described in .TP .B CONFIGURATION Configuration details for a device. - +.IP This section normally appears only in Section 4 pages. .TP .B DESCRIPTION An explanation of what the program, function, or format does. - +.IP Discuss how it interacts with files and standard input, and what it produces on standard output or standard error. Omit internals and implementation details unless they're critical for @@ -271,7 +271,7 @@ section. .\" section (and just place an overview in the .\" .B DESCRIPTION .\" section). - +.IP When describing new behavior or new flags for a system call or library function, be careful to note the kernel or C library version @@ -292,7 +292,7 @@ who are constrained to using older kernel or C library versions .B OPTIONS A description of the command-line options accepted by a program and how they change its behavior. - +.IP This section should appear only for Section 1 and 8 manual pages. .\" .TP .\" .B USAGE @@ -301,7 +301,7 @@ This section should appear only for Section 1 and 8 manual pages. .B EXIT STATUS A list of the possible exit status values of a program and the conditions that cause these values to be returned. - +.IP This section should appear only for Section 1 and 8 manual pages. .TP .B RETURN VALUE @@ -315,7 +315,7 @@ values that may be placed in .I errno in the event of an error, along with information about the cause of the errors. - +.IP Where several different conditions produce the same error, the preferred approach is to create separate list entries (with duplicate error names) for each of the conditions. @@ -323,7 +323,7 @@ This makes the separate conditions clear, may make the list easier to read, and allows metainformation (e.g., kernel version number where the condition first became applicable) to be more easily marked for each condition. - +.IP .IR "The error list should be in alphabetical order" . .TP .B ENVIRONMENT @@ -334,7 +334,7 @@ and how they affect it. A list of the files the program or function uses, such as configuration files, startup files, and files the program directly operates on. - +.IP Give the full pathname of these files, and use the installation process to modify the directory part to match user preferences. For many programs, the default installation location is in @@ -378,7 +378,7 @@ for further details. A brief summary of the Linux kernel or glibc versions where a system call or library function appeared, or changed significantly in its operation. - +.IP As a general rule, every new interface should include a VERSIONS section in its manual page. Unfortunately, @@ -391,7 +391,7 @@ interfaces that have been added in Linux 2.4 or later (i.e., changes since kernel 2.2), and library functions that have been added to glibc since version 2.1 (i.e., changes since glibc 2.0). - +.IP The .BR syscalls (2) manual page also provides information about kernel versions @@ -400,11 +400,11 @@ in which various system calls first appeared. .B CONFORMING TO A description of any standards or conventions that relate to the function or command described by the manual page. - +.IP The preferred terms to use for the various standards are listed as headings in .BR standards (7). - +.IP For a page in Section 2 or 3, this section should note the POSIX.1 version(s) that the call conforms to, @@ -413,21 +413,21 @@ and also whether the call is specified in C99. or the SVr4 and 4.xBSD implementation standards, unless the call was specified in those standards, but isn't in the current version of POSIX.1.) - +.IP If the call is not governed by any standards but commonly exists on other systems, note them. If the call is Linux-specific, note this. - +.IP If this section consists of just a list of standards (which it commonly does), terminate the list with a period (\(aq.\(aq). .TP .B NOTES Miscellaneous notes. - +.IP For Section 2 and 3 man pages you may find it useful to include subsections (\fBSS\fP) named \fILinux Notes\fP and \fIGlibc Notes\fP. - +.IP In Section 2, use the heading .I "C library/kernel differences" to mark off notes that describe the differences (if any) between @@ -441,13 +441,13 @@ and other questionable activities. .B EXAMPLE One or more examples demonstrating how this function, file or command is used. - +.IP For details on writing example programs, see \fIExample Programs\fP below. .TP .B AUTHORS A list of authors of the documentation or program. - +.IP \fBUse of an AUTHORS section is strongly discouraged\fP. Generally, it is better not to clutter every page with a list of (over time potentially numerous) authors; @@ -459,7 +459,7 @@ an address for reporting bugs, place this under the BUGS section. .B SEE ALSO A comma-separated list of related man pages, possibly followed by other related pages or documents. - +.IP The list should be ordered by section number and then alphabetically by name. Do not terminate this list with a period. @@ -474,7 +474,7 @@ and directives. Hyphenation of individual page names can be prevented by preceding words with the string "\\%". - +.IP Given the distributed, autonomous nature of FOSS projects and their documentation, it is sometimes necessary\(emand in many cases desirable\(emthat the SEE ALSO section includes references to @@ -497,7 +497,7 @@ pronoun is acceptable. For manual pages that describe a command (typically in Sections 1 and 8), the arguments are always specified using italics, .IR "even in the SYNOPSIS section" . - +.PP The name of the command, and its options, should always be formatted in bold. .\" @@ -510,7 +510,7 @@ where the rest of the function is specified in bold: .BI " int myfunction(int " argc ", char **" argv ); .PP Variable names should, like argument names, be specified in italics. - +.PP Any reference to the subject of the current manual page should be written with the name in bold followed by a pair of parentheses in Roman (normal) font. @@ -546,7 +546,7 @@ When enumerating a list of error codes, the codes are in bold (this list usually uses the .B \&.TP macro). - +.PP Complete commands should, if long, be written as an indented line on their own, with a blank line before and after the command, for example @@ -569,7 +569,7 @@ Expressions, if not written on a separate indented line, should be specified in italics. Again, the use of nonbreaking spaces may be appropriate if the expression is inlined with normal text. - +.PP When showing example shell sessions, user input should be formatted in bold, for example .PP .in +4n @@ -596,7 +596,7 @@ 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.) - +.PP Control characters should be written in bold face, with no quotes; for example, .BR ^X . @@ -606,7 +606,7 @@ Starting with release 2.59, follows American spelling conventions (previously, there was a random mix of British and American spellings); please write all new pages and patches according to these conventions. - +.PP Aside from the well-known spelling differences, there are a few other subtleties to watch for: .IP * 3 @@ -627,7 +627,7 @@ capitalize the first word in the heading, but otherwise use lowercase, except where English usage (e.g., proper nouns) or programming language requirements (e.g., identifier names) dictate otherwise. For example: - +.PP .SS Unicode under Linux .\" .SS Indentation of structure definitions, shell session logs, and so on @@ -730,7 +730,7 @@ Unixes UNIX systems Use the correct spelling and case for trademarks. The following is a list of the correct spellings of various relevant trademarks that are sometimes misspelled: - +.PP DG/UX HP-UX UNIX @@ -747,10 +747,10 @@ is the .IR "null byte", a byte with the value 0, represented in C via the character constant .IR \(aq\e0\(aq . - +.PP The preferred term for the pointer is "null pointer" or simply "NULL"; avoid writing "NULL pointer". - +.PP 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". @@ -766,17 +766,17 @@ macro pair .BR groff_man (7)). This produces proper hyperlinks that can be used in a web browser, when rendering a page with, say: - +.PP 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"). - +.PP The only place where such abbreviations may be acceptable is in .I short parenthetical asides (e.g., like this one). - +.PP 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 @@ -790,7 +790,7 @@ surrounding spaces. .SS Hyphenation of attributive compounds Compound terms should be hyphenated when used attributively (i.e., to qualify a following noun). Some examples: - +.PP 32-bit value command-line argument floating-point number @@ -803,7 +803,7 @@ 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: - +.PP interprocess multithreaded multiprocess @@ -824,16 +824,16 @@ The following list gives some examples of the preferred forms: subcomponent subdirectory subsystem - +.PP Hyphens should be retained when the prefixes are used in nonstandard English words, with trademarks, proper nouns, acronyms, or compound terms. Some examples: - +.PP non-ASCII non-English non-NULL non-real-time - +.PP Finally, note that "re-create" and "recreate" are two different verbs, and the former is probably what you want. .SS Real minus character @@ -841,16 +841,16 @@ Where a real minus character is required (e.g., for numbers such as \-1, or when writing options that have a leading dash, such as in .IR "ls\ \-l"), use the following form in the man page source: - +.PP \\\- - +.PP 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: - +.PP \\(aqC\\(aq - +.PP where .I C is the quoted character. @@ -887,16 +887,16 @@ Ritchie style, with 4-space indents. (Avoid the use of TAB characters in source code!) The following command can be used to format your source code to something close to the preferred style: - +.IP indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c .IP * For consistency, all example programs should terminate using either of: - +.IP exit(EXIT_SUCCESS); exit(EXIT_FAILURE); - +.IP Avoid using the following forms to terminate a program: - +.IP exit(0); exit(1); return n; @@ -906,9 +906,9 @@ program source code, mark off the source code with a subsection heading .IR "Program source" , as in: - +.IP .SS Program source - +.IP Always do this if the explanatory text includes a shell session log. .PP If you include a shell session log demonstrating the use of a program |