Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1227 insertions, 0 deletions

diff --git a/man/man7/man-pages.7 b/man/man7/man-pages.7
new file mode 100644
index 0000000..14ba7ba
--- /dev/null
+++ b/man/man7/man-pages.7
@@ -0,0 +1,1227 @@
+'\" 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 2024-05-02 "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:
+.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)