From ba83bc0d89af7b7e5dad54c08f00c84d25dbc993 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Tue, 22 May 2007 23:46:32 +0000 Subject: [PATCH] Conventions for writing Linux man-pages. --- man7/man-pages.7 | 481 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 481 insertions(+) create mode 100644 man7/man-pages.7 diff --git a/man7/man-pages.7 b/man7/man-pages.7 new file mode 100644 index 000000000..049807d1d --- /dev/null +++ b/man7/man-pages.7 @@ -0,0 +1,481 @@ +.\" (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 +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of this +.\" manual under the conditions for verbatim copying, provided that the +.\" entire resulting derived work is distributed under the terms of a +.\" permission notice identical to this one. +.\" +.\" Since the Linux kernel and libraries are constantly changing, this +.\" manual page may be incorrect or out-of-date. The author(s) assume no +.\" responsibility for errors or omissions, or for damages resulting from +.\" the use of the information contained herein. The author(s) may not +.\" have taken the same level of care in the production of this manual, +.\" which is licensed free of charge, as they might when working +.\" professionally. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" FIXME Add some SEE ALSO references to this page from: +.\" man.1, man.7, mdoc.7, and perhaps intro.* +.\" Also write up in HOWTOHELP +.\" +.TH MAN-PAGES 7 2007-05-30 "Linux" "Linux Programmer's Manual" +.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 comprises Sections 2, 3, 4, 5, and 7 of the Linux manual pages. +The conventions described on this page may also be useful +for authors writing man pages for other projects. +.SS Sections of the Manual Pages +.PP +The manual Sections are traditionally defined as follows: +.RS +.TP 10 +.B 1 Commands (Programs) +Those commands that can be executed by the user from within +a shell. +.TP +.B 2 System calls +Those functions which must be performed by the kernel. +.TP +.B 3 Library calls +Most of the +.I libc +functions. +.TP +.B 4 Special files (devices) +Files found in +.IR /dev . +.TP +.B 5 File formats and conventions +The format for +.I /etc/passwd +and other human-readable files. +.TP +.B 6 Games +.TP +.B 7 Conventions and miscellaneous +Overviews of various topics, conventions and protocols, +character set standards, 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. +.RE +.SS Macro package +New manual pages should be marked up using the +.B groff tmac.an +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 75 characters +wherever possible. +This helps avoid line-wrapping in some mail clients when patches are +submitted inline. + +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. +.SS Title line +The first command in a man page should be a \fBTH\fP command: +.RS +.sp +.B \&.TH +.IR "title section date source manual" +.sp +.RE +where: +.RS +.TP 10 +.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 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. +Dates should be written in the form YYYY-MM-DD. +.TP +.I source +The source of the command, function, or system call. +.sp +For those few \fIman-pages\fP pages in Sections 1 and 8, +probably you just want to write +.IR GNU . +.sp +For system calls, just write +.IR "Linux" . +(An earlier practice was to write the version number +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.) +.sp +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. +.sp +For Section 4 pages, use +.IR "Linux" . +.sp +In cases of doubt, just write +.IR Linux ", or " GNU . +.TP +.I manual +The title of the manual (e.g., for Section 2 and 3 pages in +the \fIman-pages\fP package, use +.IR "Linux Programmer's Manual" ). +.RE +.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. +Srrange a new manual page so that sections +are placed in the order shown in the list. +.in +0.5i +.nf + +\fBNAME\fP +\fBSYNOPSIS\fP +\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 +VERSIONS [Normally only in Sections 2, 3] +CONFORMING TO +NOTES +BUGS +EXAMPLE +.\" AUTHOR sections are discouraged +AUTHOR [Discouraged] +\fBSEE ALSO\fP + +.fi +.in +.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. + +The following list elaborates on the contents of each of +the above sections. +.TP 14 +.B NAME +The name of this manual page. +See +.BR man (7) +for important details of the line(s) that should follow the +\fB.SH NAME\fI command. +.TP +.B SYNOPSIS +briefly describes the command or function's interface. +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. +.TP +.B DESCRIPTION +gives an explanation of what the program, function, or format does. +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). +.TP +.B OPTIONS +describes the command-line options accepted by a +program and how they change its behavior. +This section should only appear for Section 1 and 8 manual pages. +.\" .TP +.\" .B USAGE +.\" describes the grammar of any sublanguage this implements. +.\" FIXME document VERSIONS +.\" FIXME document other common Section Heading types +.\" FIXME make a clear statement about the order of Sections +.TP +.B EXIT STATUS +lists the possible exit status values of a program and +the conditions that cause these values to be returned. +This section should only appear 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. +.TP +.B ENVIRONMENT +lists all environment variables that affect the program or function +and how they affect it. +.TP +.B FILES +lists the files the program or function uses, such as +configuration files, startup files, +and files the program directly operates on. +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 VERSIONS +A brief summary of the Linux kernel or glibc versions where a +system call or library function appeared, +or changed significantly in its operation. +.TP +.B CONFORMING TO +describes any standards or conventions that relate to the function or command described by the manula page. +For a page in Section 2 or 3, this section should note the POSIX.1 +version(s) that the call conforms to. +If the call is not governed by any standards but exists on other +systems, note them. +If the call is Linux specific, note this. +When talking about standards and systems +here is probably no need to talk about anything more than +C89, C99, POSIX.1-2001 (or later), xBSD, and SVr4, and perhaps Solaris +(see +.BR standards (7)). +.TP +.B NOTES +provides miscellaneous notes. +For Section 2 and 3 man pages you may find it usful to include +subsections (\fBSS\fP) named \fILinux Notes\fP and \fIGlibc Notes\fP. +.TP +.B BUGS +lists limitations, known defects or inconveniences, +and other questionable activities. +.TP +.B EXAMPLE +provides one or more examples describing how this function, file or +command is used. +For details on writing example programs, see \fIExample Programs\fP below. +.TP +.B AUTHOR +lists authors of the documentation or program so you can mail in bug +reports. +.BR "Use of an AUTHOR section is discouraged for pages in +the \fIman-pages\fP package". +(One exception is Section 4 pages that list the authors of +device drivers, to whom software bugs should be sent.) +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. +.TP +.B SEE ALSO +lists related man pages, ordered by section number and +alphabetically by name, possibly followed by +other related pages or documents. +.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: +.PP +.RS +.BI " int myfunction(int " argc ", char **" argv ); +.RE +.PP +Filenames are always in italics (e.g., +.IR "/usr/include/stdio.h" ), +except in the SYNOPSIS section, where included files are in bold (e.g., +.BR "#include " ). +.PP +Special macros, which are usually in upper case, 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 +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, +e.g., +.BR man (). +The preferred way to write this in the source file is: +.nf + + .BR man () + +.fi +(Using this format, rather than the use of "\\fB...\\fP()" +makes it easier to write tools that parse man page source files.) +.PP +Any reference to another man page +should be written with the name in bold, +\fIalways\fP 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: +.nf + + .BR intro (2) + +.fi +(Including the section number in cross references lets tools like +.BR man2html (1) +create properly hyperlinked pages.) +.SS Example Programs +Manual pages can include example programs demonstrating how to +use a system call or library function. +However, note the following: +.TP 3 +* +Example programs should be written in C. +.TP +* +An example program is only necessary and useful 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. +.TP +* +Example programs should be fairly short (preferably < 100 lines; +ideally < 50 lines). +.TP +* +Example programs should do error checking after system calls and +library function calls. +.TP +* +Example programs should be complete, and compile without +warnings when compiled with \fIcc -Wall\fP. +.TP +* +Where possible and appropriate, example programs should allow +experimentation, by varying their behaviour based on inputs +(ideally from command-line arguments, or alternatively, via +input read by the program). +.TP +* +Example programs should be laid out according to Kernighan and +Ritchie style, with a few concessions: +.RS +.TP 3 +\(bu +4-space indents are preferred. +(Avoid the use of TAB characters in source code!) +.TP +\(bu +In the interests of keeping a program short, compressing +error-handling code such as in the following is acceptable: +.nf + + if (func(...) == -1) + { perror("func"); exit(EXIT_FAILURE); } +.fi +.RE +.PP +For some examples of what example programs should look like, see +.BR wait (2) +and +.BR pipe (2). +.SH EXAMPLE +For canonical examples of how man pages in the +.BR man-pages +package should look, see +.BR pipe (2) +and +.BR fcntl (2). +.SH SEE ALSO +.BR man (1), +.BR man2html (1), +.BR man (7), +.BR mdoc (7)