summaryrefslogtreecommitdiffstats
path: root/man7/man-pages.7
diff options
context:
space:
mode:
Diffstat (limited to 'man7/man-pages.7')
-rw-r--r--man7/man-pages.71227
1 files changed, 0 insertions, 1227 deletions
diff --git a/man7/man-pages.7 b/man7/man-pages.7
deleted file mode 100644
index c7eeb0a..0000000
--- 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 2023-10-31 "Linux man-pages 6.7"
-.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:
-.P
-.RS
-.B \&.TH
-.I "title section date source manual-section"
-.RE
-.P
-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.
-.P
-.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
-.P
-.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.
-.P
-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.
-.P
-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.
-.P
-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 .P )
-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.
-.P
-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).
-.P
-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" .
-.P
-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:
-.P
-.BI " int myfunction(int " argc ", char **" argv );
-.P
-Variable names should, like argument names, be specified in italics.
-.P
-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:
-.P
-.EX
- .BR fcntl ()
-.EE
-.P
-(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".
-.P
-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 .P
-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).
-.P
-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> ).
-.P
-Special macros, which are usually in uppercase, are in bold (e.g.,
-.BR MAXINT ).
-Exception: don't boldface NULL.
-.P
-When enumerating a list of error codes, the codes are in bold (this list
-usually uses the
-.B \&.TP
-macro).
-.P
-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
-.P
-.in +4n
-.EX
-man 7 man\-pages
-.EE
-.in
-.P
-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 ).
-.P
-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.
-.P
-When showing example shell sessions,
-user input should be formatted in bold,
-for example
-.P
-.in +4n
-.EX
-$ \fBdate\fP
-Thu Jul 7 13:01:27 CEST 2016
-.EE
-.in
-.P
-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:
-.P
-.EX
- .BR intro (2)
-.EE
-.P
-(Including the section number in cross references lets tools like
-.BR man2html (1)
-create properly hyperlinked pages.)
-.P
-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.
-.P
-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:
-.P
-.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 .P
-or
-.IR .IP ).
-For example:
-.P
-.in +4n
-.EX
-\&.P
-\&.in +4n
-\&.EX
-int
-main(int argc, char *argv[])
-{
- return 0;
-}
-\&.EE
-\&.in
-\&.P
-.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
-.P
-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] .
-.P
-The preferred term for the pointer is "null pointer" or simply "NULL";
-avoid writing "NULL pointer".
-.P
-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:
-.P
-.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").
-.P
-The only place where such abbreviations may be acceptable is in
-.I short
-parenthetical asides (e.g., like this one).
-.P
-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
-.P
-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
-.P
-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:
-.P
-.in +4n
-.EX
-\e\-
-.EE
-.in
-.P
-This guideline applies also to code examples.
-.P
-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.
-.P
-To produce unslanted single quotes that render well in ASCII, UTF-8, and PDF,
-use "\e[aq]" ("apostrophe quote"); for example
-.P
-.in +4n
-.EX
-\e[aq]C\e[aq]
-.EE
-.in
-.P
-where
-.I C
-is the quoted character.
-This guideline applies also to character constants used in code examples.
-.P
-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.
-.P
-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.
-.P
-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.
-.P
-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)