diff options
Diffstat (limited to 'man7/man-pages.7')
| -rw-r--r-- | man7/man-pages.7 | 1227 |
1 files changed, 0 insertions, 1227 deletions
diff --git a/man7/man-pages.7 b/man7/man-pages.7 deleted file mode 100644 index d63f2d8f2..000000000 --- a/man7/man-pages.7 +++ /dev/null @@ -1,1227 +0,0 @@ -'\" t -.\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler -.\" (faith@cs.unc.edu and dwheeler@ida.org) -.\" and (C) Copyright 2007 Michael Kerrisk <mtk.manpages@gmail.com> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.\" 2007-05-30 created by mtk, using text from old man.7 plus -.\" rewrites and additional text. -.\" -.TH man-pages 7 (date) "Linux man-pages (unreleased)" -.SH NAME -man-pages \- conventions for writing Linux man pages -.SH SYNOPSIS -.B man -.RI [ section ] -.I title -.SH DESCRIPTION -This page describes the conventions that should be employed -when writing man pages for the Linux \fIman-pages\fP project, -which documents the user-space API provided by the Linux kernel -and the GNU C library. -The project thus provides most of the pages in Section 2, -many of the pages that appear in Sections 3, 4, and 7, -and a few of the pages that appear in Sections 1, 5, and 8 -of the man pages on a Linux system. -The conventions described on this page may also be useful -for authors writing man pages for other projects. -.SS Sections of the manual pages -The manual Sections are traditionally defined as follows: -.TP -.B 1 User commands (Programs) -Commands that can be executed by the user from within -a shell. -.TP -.B 2 System calls -Functions which wrap operations performed by the kernel. -.TP -.B 3 Library calls -All library functions excluding the system call wrappers -(Most of the -.I libc -functions). -.TP -.B 4 Special files (devices) -Files found in -.I /dev -which allow to access to devices through the kernel. -.TP -.B 5 File formats and configuration files -Describes various human-readable file formats and configuration files. -.TP -.B 6 Games -Games and funny little programs available on the system. -.TP -.B 7 Overview, conventions, and miscellaneous -Overviews or descriptions of various topics, conventions, and protocols, -character set standards, the standard filesystem layout, and miscellaneous -other things. -.TP -.B 8 System management commands -Commands like -.BR mount (8), -many of which only root can execute. -.\" .TP -.\" .B 9 Kernel routines -.\" This is an obsolete manual section. -.\" Once it was thought a good idea to document the Linux kernel here, -.\" but in fact very little has been documented, and the documentation -.\" that exists is outdated already. -.\" There are better sources of -.\" information for kernel developers. -.SS Macro package -New manual pages should be marked up using the -.B groff an.tmac -package described in -.BR man (7). -This choice is mainly for consistency: the vast majority of -existing Linux manual pages are marked up using these macros. -.SS Conventions for source file layout -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. -.SS Title line -The first command in a man page should be a -.B TH -command: -.PP -.RS -.B \&.TH -.I "title section date source manual-section" -.RE -.PP -The arguments of the command are as follows: -.TP -.I title -The title of the man page, written in all caps (e.g., -.IR MAN-PAGES ). -.TP -.I section -The section number in which the man page should be placed (e.g., -.IR 7 ). -.TP -.I date -The date of the last nontrivial change that was made to the man page. -(Within the -.I man-pages -project, the necessary updates to these timestamps are handled -automatically by scripts, so there is no need to manually update -them as part of a patch.) -Dates should be written in the form YYYY-MM-DD. -.TP -.I source -The name and version of the project that provides the manual page -(not necessarily the package that provides the functionality). -.TP -.I manual-section -Normally, this should be empty, -since the default value will be good. -.\" -.SS Sections within a manual page -The list below shows conventional or suggested sections. -Most manual pages should include at least the -.B highlighted -sections. -Arrange a new manual page so that sections -are placed in the order shown in the list. -.PP -.RS -.TS -l l. -\fBNAME\fP -LIBRARY [Normally only in Sections 2, 3] -\fBSYNOPSIS\fP -CONFIGURATION [Normally only in Section 4] -\fBDESCRIPTION\fP -OPTIONS [Normally only in Sections 1, 8] -EXIT STATUS [Normally only in Sections 1, 8] -RETURN VALUE [Normally only in Sections 2, 3] -.\" May 07: Few current man pages have an ERROR HANDLING section,,, -.\" ERROR HANDLING, -ERRORS [Typically only in Sections 2, 3] -.\" May 07: Almost no current man pages have a USAGE section,,, -.\" USAGE, -.\" DIAGNOSTICS, -.\" May 07: Almost no current man pages have a SECURITY section,,, -.\" SECURITY, -ENVIRONMENT -FILES -ATTRIBUTES [Normally only in Sections 2, 3] -VERSIONS [Normally only in Sections 2, 3] -STANDARDS -HISTORY -NOTES -CAVEATS -BUGS -EXAMPLES -.\" AUTHORS sections are discouraged -AUTHORS [Discouraged] -REPORTING BUGS [Not used in man-pages] -COPYRIGHT [Not used in man-pages] -\fBSEE ALSO\fP -.TE -.RE -.PP -.IR "Where a traditional heading would apply" ", " "please use it" ; -this kind of consistency can make the information easier to understand. -If you must, you can create your own -headings if they make things easier to understand (this can -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 -.B NAME -The name of this manual page. -.IP -See -.BR man (7) -for important details of the line(s) that should follow the -\fB.SH NAME\fP command. -All words in this line (including the word immediately -following the "\e\-") should be in lowercase, -except where English or technical terminological convention -dictates otherwise. -.TP -.B LIBRARY -The library providing a symbol. -.IP -It shows the common name of the library, -and in parentheses, -the name of the library file -and, if needed, the linker flag needed to link a program against it: -.RI ( libfoo "[, " \-lfoo ]). -.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 -indicate replaceable arguments. -Brackets ([]) surround optional arguments, vertical bars (|) -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 -.BR feature_test_macros (7). -.\" FIXME . Say something here about compiler options -.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 -understanding the interface. -Describe the usual case; -for information on command-line options of a program use the -.B OPTIONS -section. -.\" If there is some kind of input grammar or complex set of subcommands, -.\" consider describing them in a separate -.\" .B USAGE -.\" 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 -that introduced the change. -The preferred method of noting this information for flags is as part of a -.B .TP -list, in the following form (here, for a new system call flag): -.RS 16 -.TP -.BR XYZ_FLAG " (since Linux 3.7)" -Description of flag... -.RE -.IP -Including version information is especially useful to users -who are constrained to using older kernel or C library versions -(which is typical in embedded systems, for example). -.TP -.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 -.\" describes the grammar of any sublanguage this implements. -.TP -.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 -For Section 2 and 3 pages, this section gives a -list of the values the library routine will return to the caller -and the conditions that cause these values to be returned. -.TP -.B ERRORS -For Section 2 and 3 manual pages, this is a list of the -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. -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 -A list of all environment variables that affect the program or function -and how they affect it. -.TP -.B FILES -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 -.IR /usr/local , -so your base manual page should use -.I /usr/local -as the base. -.\" May 07: Almost no current man pages have a DIAGNOSTICS section; -.\" "RETURN VALUE" or "EXIT STATUS" is preferred. -.\" .TP -.\" .B DIAGNOSTICS -.\" gives an overview of the most common error messages and how to -.\" cope with them. -.\" You don't need to explain system error messages -.\" or fatal signals that can appear during execution of any program -.\" unless they're special in some way to the program. -.\" -.\" May 07: Almost no current man pages have a SECURITY section. -.\".TP -.\".B SECURITY -.\"discusses security issues and implications. -.\"Warn about configurations or environments that should be avoided, -.\"commands that may have security implications, and so on, especially -.\"if they aren't obvious. -.\"Discussing security in a separate section isn't necessary; -.\"if it's easier to understand, place security information in the -.\"other sections (such as the -.\" .B DESCRIPTION -.\" or -.\" .B USAGE -.\" section). -.\" However, please include security information somewhere! -.TP -.B ATTRIBUTES -A summary of various attributes of the function(s) documented on this page. -See -.BR attributes (7) -for further details. -.TP -.B VERSIONS -A summary of systems where the API performs differently, -or where there's a similar API. -.TP -.B STANDARDS -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 -This section should note the current standards to which the API conforms to. -.IP -If the API is not governed by any standards but commonly -exists on other systems, note them. -If the call is Linux-specific or GNU-specific, note this. -If it's available in the BSDs, note that. -.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 HISTORY -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 HISTORY section in its manual page. -Unfortunately, -many existing manual pages don't include this information -(since there was no policy to do so when they were written). -Patches to remedy this are welcome, -but, from the perspective of programmers writing new code, -this information probably matters only in the case of kernel -interfaces that have been added in Linux 2.4 or later -(i.e., changes since Linux 2.2), -and library functions that have been added to glibc since glibc 2.1 -(i.e., changes since glibc 2.0). -.IP -The -.BR syscalls (2) -manual page also provides information about kernel versions -in which various system calls first appeared. -.PP -Old versions of standards should be mentioned here, -rather than in STANDARDS, -for example, -SUS, SUSv2, and XPG, or the SVr4 and 4.xBSD implementation standards. -.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 -the C library wrapper function for a system call and -the raw system call interface provided by the kernel. -.TP -.B CAVEATS -Warnings about typical user misuse of an API, -that don't constitute an API bug or design defect. -.TP -.B BUGS -A list of limitations, known defects or inconveniences, -and other questionable activities. -.TP -.B EXAMPLES -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; -if you write or significantly amend a page, -add a copyright notice as a comment in the source file. -If you are the author of a device driver and want to include -an address for reporting bugs, place this under the BUGS section. -.TP -.B REPORTING BUGS -The -.I man-pages -project doesn't use a REPORTING BUGS section in manual pages. -Information on reporting bugs is instead supplied in the -script-generated COLOPHON section. -However, various projects do use a REPORTING BUGS section. -It is recommended to place it near the foot of the page. -.TP -.B COPYRIGHT -The -.I man-pages -project doesn't use a COPYRIGHT section in manual pages. -Copyright information is instead maintained in the page source. -In pages where this section is present, -it is recommended to place it near the foot of the page, just above SEE ALSO. -.TP -.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. -.IP -Where the SEE ALSO list contains many long manual page names, -to improve the visual result of the output, it may be useful to employ the -.I .ad l -(don't right justify) -and -.I .nh -(don't hyphenate) -directives. -Hyphenation of individual page names can be prevented -by preceding words with the string "\e%". -.IP -Given the distributed, autonomous nature of FOSS projects -and their documentation, it is sometimes necessary\[em]and in many cases -desirable\[em]that the SEE ALSO section includes references to -manual pages provided by other projects. -.SH FORMATTING AND WORDING CONVENTIONS -The following subsections note some details for preferred formatting and -wording conventions in various sections of the pages in the -.I man-pages -project. -.SS SYNOPSIS -Wrap the function prototype(s) in a -.IR .nf / .fi -pair to prevent filling. -.PP -In general, where more than one function prototype is shown in the SYNOPSIS, -the prototypes should -.I not -be separated by blank lines. -However, blank lines (achieved using -.IR .PP ) -may be added in the following cases: -.IP \[bu] 3 -to separate long lists of function prototypes into related groups -(see for example -.BR list (3)); -.IP \[bu] -in other cases that may improve readability. -.PP -In the SYNOPSIS, a long function prototype may need to be -continued over to the next line. -The continuation line is indented according to the following rules: -.IP (1) 5 -If there is a single such prototype that needs to be continued, -then align the continuation line so that when the page is -rendered on a fixed-width font device (e.g., on an xterm) the -continuation line starts just below the start of the argument -list in the line above. -(Exception: the indentation may be -adjusted if necessary to prevent a very long continuation line -or a further continuation line where the function prototype is -very long.) -As an example: -.IP -.in +4n -.nf -.BI "int tcsetattr(int " fd ", int " optional_actions , -.BI " const struct termios *" termios_p ); -.fi -.in -.IP (2) -But, where multiple functions in the SYNOPSIS require -continuation lines, and the function names have different -lengths, then align all continuation lines to start in the -same column. -This provides a nicer rendering in PDF output -(because the SYNOPSIS uses a variable width font where -spaces render narrower than most characters). -As an example: -.IP -.in +4n -.nf -.BI "int getopt(int " argc ", char * const " argv[] , -.BI " const char *" optstring ); -.BI "int getopt_long(int " argc ", char * const " argv[] , -.BI " const char *" optstring , -.BI " const struct option *" longopts ", int *" longindex ); -.fi -.in -.SS RETURN VALUE -The preferred wording to describe how -.I errno -is set is -.RI \[dq] errno -is set to indicate the error" -or similar. -.\" Before man-pages 5.11, many different wordings were used, which -.\" was confusing, and potentially made scripted edits more difficult. -This wording is consistent with the wording used in both POSIX.1 and FreeBSD. -.SS ATTRIBUTES -.\" See man-pages commit c466875ecd64ed3d3cd3e578406851b7dfb397bf -Note the following: -.IP \[bu] 3 -Wrap the table in this section in a -.IR ".ad\ l" / .ad -pair to disable text filling and a -.IR .nh / .hy -pair to disable hyphenation. -.IP \[bu] -Ensure that the table occupies the full page width through the use of an -.I lbx -description for one of the columns -(usually the first column, -though in some cases the last column if it contains a lot of text). -.IP \[bu] -Make free use of -.IR T{ / T} -macro pairs to allow table cells to be broken over multiple lines -(also bearing in mind that pages may sometimes be rendered to a -width of less than 80 columns). -.PP -For examples of all of the above, see the source code of various pages. -.SH STYLE GUIDE -The following subsections describe the preferred style for the -.I man-pages -project. -For details not covered below, the Chicago Manual of Style -is usually a good source; -try also grepping for preexisting usage in the project source tree. -.SS Use of gender-neutral language -As far as possible, use gender-neutral language in the text of man -pages. -Use of "they" ("them", "themself", "their") as a gender-neutral singular -pronoun is acceptable. -.\" -.SS Formatting conventions for manual pages describing commands -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. -.\" -.SS Formatting conventions for manual pages describing functions -For manual pages that describe functions (typically in Sections 2 and 3), -the arguments are always specified using italics, -.IR "even in the SYNOPSIS section" , -where the rest of the function is specified in bold: -.PP -.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. -For example, in the -.BR fcntl (2) -man page, references to the subject of the page would be written as: -.BR fcntl (). -The preferred way to write this in the source file is: -.PP -.EX - .BR fcntl () -.EE -.PP -(Using this format, rather than the use of "\efB...\efP()" -makes it easier to write tools that parse man page source files.) -.\" -.SS Use semantic newlines -In the source of a manual page, -new sentences should be started on new lines, -long sentences should be split into lines at clause breaks -(commas, semicolons, colons, and so on), -and long clauses should be split at phrase boundaries. -This convention, sometimes known as "semantic newlines", -makes it easier to see the effect of patches, -which often operate at the level of -individual sentences, clauses, or phrases. -.\" -.SS Lists -There are different kinds of lists: -.TP -Tagged paragraphs -These are used for a list of tags and their descriptions. -When the tags are constants (either macros or numbers) -they are in bold. -Use the -.B .TP -macro. -.IP -An example is this "Tagged paragraphs" subsection is itself. -.TP -Ordered lists -Elements are preceded by a number in parentheses (1), (2). -These represent a set of steps that have an order. -.IP -When there are substeps, -they will be numbered like (4.2). -.TP -Positional lists -Elements are preceded by a number (index) in square brackets [4], [5]. -These represent fields in a set. -The first index will be: -.RS -.TP -.B 0 -When it represents fields of a C data structure, -to be consistent with arrays. -.PD 0 -.TP -.B 1 -When it represents fields of a file, -to be consistent with tools like -.BR cut (1). -.PD -.RE -.TP -Alternatives list -Elements are preceded by a letter in parentheses (a), (b). -These represent a set of (normally) exclusive alternatives. -.TP -Bullet lists -Elements are preceded by bullet symbols -.RB ( \e[bu] ). -Anything that doesn't fit elsewhere is -usually covered by this type of list. -.TP -Numbered notes -Not really a list, -but the syntax is identical to "positional lists". -.PP -There should always be exactly -2 spaces between the list symbol and the elements. -This doesn't apply to "tagged paragraphs", -which use the default indentation rules. -.\" -.SS Formatting conventions (general) -Paragraphs should be separated by suitable markers (usually either -.I .PP -or -.IR .IP ). -Do -.I not -separate paragraphs using blank lines, as this results in poor rendering -in some output formats (such as PostScript and PDF). -.PP -Filenames (whether pathnames, or references to header files) -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 header file include, -specify the header file surrounded by angle brackets, -in the usual C way (e.g., -.IR <stdio.h> ). -.PP -Special macros, which are usually in uppercase, are in bold (e.g., -.BR MAXINT ). -Exception: don't boldface NULL. -.PP -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 -.PP -.in +4n -.EX -man 7 man\-pages -.EE -.in -.PP -If the command is short, then it can be included inline in the text, -in italic format, for example, -.IR "man 7 man-pages" . -In this case, it may be worth using nonbreaking spaces -(\e[ti]) at suitable places in the command. -Command options should be written in italics (e.g., -.IR \-l ). -.PP -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 -.EX -$ \fBdate\fP -Thu Jul 7 13:01:27 CEST 2016 -.EE -.in -.PP -Any reference to another man page -should be written with the name in bold, -.I always -followed by the section number, -formatted in Roman (normal) font, without any -separating spaces (e.g., -.BR intro (2)). -The preferred way to write this in the source file is: -.PP -.EX - .BR intro (2) -.EE -.PP -(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 \[ha]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 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 \[bu] 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. -.IP \[bu] -Opinions are divided on "acknowledgement" vs "acknowledgment". -The latter is predominant, but not universal usage in American English. -POSIX and the BSD license use the former spelling. -In the Linux man-pages project, we use "acknowledgement". -.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 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 -.in +4n -.EX -\&.SS Unicode under Linux -.EE -.in -.\" -.SS Indentation of structure definitions, shell session logs, and so on -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" ), -format them using the -.I .EX -and -.I .EE -macros, and surround them with suitable paragraph markers (either -.I .PP -or -.IR .IP ). -For example: -.PP -.in +4n -.EX -\&.PP -\&.in +4n -\&.EX -int -main(int argc, char *argv[]) -{ - return 0; -} -\&.EE -\&.in -\&.PP -.EE -.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 ll. -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 -filesystem file system -hostname host name -inode i-node -lowercase lower case, lower-case -nonzero non-zero -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} -superblock T{ -super block, -super-block -T} -symbolic link symlink -timestamp time stamp -timezone time zone -uppercase upper case, upper-case -usable useable -user space userspace -username user name -x86-64 x86_64 T{ -Except if referring to result of "uname\ \-m" or similar -T} -zeros zeroes -.TE -.PP -See also the discussion -.I Hyphenation of attributive compounds -below. -.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 - -32bit 32-bit T{ -same for 8-bit, 16-bit, etc. -T} -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 -tty terminal -Unices UNIX systems -Unixes UNIX systems -.TE -.ad -.\" -.SS Trademarks -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: -.IP -.TS -l. -DG/UX -HP-UX -UNIX -UnixWare -.TE -.SS NULL, NUL, null pointer, and null byte -A -.I 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] . -.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". -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: -.PP -.in +4n -.EX -BROWSER=firefox man -H pagename -.EE -.in -.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.", -"cf.", and "a.k.a." should be avoided, -in favor of suitable full wordings -("for example", "that is", "and so on", "compare to", "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 -The way to write an em-dash\[em]the glyph that appears -at either end of this subphrase\[em]in *roff is with the macro "\e[em]". -(On an ASCII terminal, an em-dash typically renders as two hyphens, -but in other typographical contexts it renders as a long dash.) -Em-dashes should be written -.I without -surrounding spaces. -.SS Hyphenation of attributive compounds -Compound terms should be hyphenated when used attributively -(i.e., to qualify a following noun). Some examples: -.IP -.TS -l. -32-bit value -command-line argument -floating-point number -run-time check -user-space function -wide-character string -.TE -.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: -.IP -.TS -l. -interprocess -multithreaded -multiprocess -nonblocking -nondefault -nonempty -noninteractive -nonnegative -nonportable -nonzero -preallocated -precreate -prerecorded -reestablished -reinitialize -rearm -reread -subcomponent -subdirectory -subsystem -.TE -.PP -Hyphens should be retained when the prefixes are used in nonstandard -English words, with trademarks, proper nouns, acronyms, or compound terms. -Some examples: -.IP -.TS -l. -non-ASCII -non-English -non-NULL -non-real-time -.TE -.PP -Finally, note that "re-create" and "recreate" are two different verbs, -and the former is probably what you want. -.\" -.SS Generating optimal glyphs -Where a real minus character is required (e.g., for numbers such as \-1, -for man page cross references such as -.BR utf\-8 (7), -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 -.in +4n -.EX -\e\- -.EE -.in -.PP -This guideline applies also to code examples. -.PP -The use of real minus signs serves the following purposes: -.\" https://lore.kernel.org/linux-man/20210121061158.5ul7226fgbrmodbt@localhost.localdomain/ -.IP \[bu] 3 -To provide better renderings on various targets other than -ASCII terminals, -notably in PDF and on Unicode/UTF\-8-capable terminals. -.IP \[bu] -To generate glyphs that when copied from rendered pages will -produce real minus signs when pasted into a terminal. -.PP -To produce unslanted single quotes that render well in ASCII, UTF-8, and PDF, -use "\e[aq]" ("apostrophe quote"); for example -.PP -.in +4n -.EX -\e[aq]C\e[aq] -.EE -.in -.PP -where -.I C -is the quoted character. -This guideline applies also to character constants used in code examples. -.PP -Where a proper caret (\[ha]) that renders well in both a terminal and PDF -is required, use "\\[ha]". -This is especially necessary in code samples, -to get a nicely rendered caret when rendering to PDF. -.PP -Using a naked "\[ti]" character results in a poor rendering in PDF. -Instead use "\\[ti]". -This is especially necessary in code samples, -to get a nicely rendered tilde when rendering to PDF. -.\" -.SS Example programs and shell sessions -Manual pages may include example programs demonstrating how to -use a system call or library function. -However, note the following: -.IP \[bu] 3 -Example programs should be written in C. -.IP \[bu] -An example program is necessary and useful only if it demonstrates -something beyond what can easily be provided in a textual -description of the interface. -An example program that does nothing -other than call an interface usually serves little purpose. -.IP \[bu] -Example programs should ideally be short -(e.g., a good example can often be provided in less than 100 lines of code), -though in some cases longer programs may be necessary -to properly illustrate the use of an API. -.IP \[bu] -Expressive code is appreciated. -.IP \[bu] -Comments should included where helpful. -Complete sentences in free-standing comments should be -terminated by a period. -Periods should generally be omitted in "tag" comments -(i.e., comments that are placed on the same line of code); -such comments are in any case typically brief phrases -rather than complete sentences. -.IP \[bu] -Example programs should do error checking after system calls and -library function calls. -.IP \[bu] -Example programs should be complete, and compile without -warnings when compiled with \fIcc\ \-Wall\fP. -.IP \[bu] -Where possible and appropriate, example programs should allow -experimentation, by varying their behavior based on inputs -(ideally from command-line arguments, or alternatively, via -input read by the program). -.IP \[bu] -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!) -The following command can be used to format your source code to -something close to the preferred style: -.IP -.in +4n -.EX -indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c -.EE -.in -.IP \[bu] -For consistency, all example programs should terminate using either of: -.IP -.in +4n -.EX -exit(EXIT_SUCCESS); -exit(EXIT_FAILURE); -.EE -.in -.IP -Avoid using the following forms to terminate a program: -.IP -.in +4n -.EX -exit(0); -exit(1); -return n; -.EE -.in -.IP \[bu] -If there is extensive explanatory text before the -program source code, mark off the source code -with a subsection heading -.IR "Program source" , -as in: -.IP -.in +4n -.EX -\&.SS Program source -.EE -.in -.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 -or other system feature: -.IP \[bu] 3 -Place the session log above the source code listing. -.IP \[bu] -Indent the session log by four spaces. -.IP \[bu] -Boldface the user input text, -to distinguish it from output produced by the system. -.PP -For some examples of what example programs should look like, see -.BR wait (2) -and -.BR pipe (2). -.SH EXAMPLES -For canonical examples of how man pages in the -.I man-pages -package should look, see -.BR pipe (2) -and -.BR fcntl (2). -.SH SEE ALSO -.BR man (1), -.BR man2html (1), -.BR attributes (7), -.BR groff (7), -.BR groff_man (7), -.BR man (7), -.BR mdoc (7) |