man-pages.7: Add a FORMATTING AND WORDING CONVENTIONS section

In man-pages-5.11, a large number of pages were edited to achieve
greater consistency in the SYNOPIS, RETURN VALUE and ATTRIBUTES
sections. To avoid future inconsistencies, try to capture some of
the preferred conventions in text in man-pages(7).

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

1 files changed, 95 insertions, 0 deletions

diff --git a/man7/man-pages.7 b/man7/man-pages.7
index 0e70827146..71b670c5e9 100644
--- a/man7/man-pages.7
+++ b/man7/man-pages.7
@@ -493,6 +493,101 @@ Given the distributed, autonomous nature of FOSS projects
 and their documentation, it is sometimes necessary\(emand in many cases
 desirable\(emthat the SEE ALSO section includes references to
 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
+.IR 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 * 3
+to separate long lists of function prototypes ino relates groups
+(see for example
+.BR list (3));
+.IP *
+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. 3
+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:
+.PP
+.RS
+.nf
+.BI "int tcsetattr(int " fd ", int " optional_actions ,
+.BI "              const struct termios *" termios_p );
+.fi
+.RE
+.IP 2. 3
+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:
+.PP
+.RS
+.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
+.RE
+.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 potentialy 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 * 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 *
+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 *
+Make free use of
+.IR T{ / T}
+macro pair 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
 .IR man-pages