man-pages.7: Various improvements to style guide

Reported-by: Mike Frysinger <vapier@gentoo.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man7/man-pages.7

@@ -457,19 +457,17 @@ directives.
 Hyphenation of individual page names can be prevented
 by preceding words with the string "\\%".
 .SH STYLE GUIDE
-The following subsections represent the beginnings of a style guide
-for the
-.IR "man-pages"
+The following subsections describe the preferred style for the
+.IR man-pages
 project.
 For details not covered below, the Chicago Manual of Style
-is usually a good source.
+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 for pages in the
-.IR man-pages 
-project.
+pronoun is acceptable.
 .SS Font conventions
 .PP
 For functions, the arguments are always specified using italics,
@@ -480,15 +478,12 @@ where the rest of the function is specified in bold:
 .PP
 Variable names should, like argument names, be specified in italics.
 .PP
-Filenames (whether pathnames, or references to files in the
-.I /usr/include
-directory)
+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 include file under
-.IR /usr/include ,
+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> ).
@@ -503,7 +498,8 @@ usually uses the
 macro).
 .PP
 Complete commands should, if long,
-be written as an indented line on their own, for example
+be written as an indented line on their own,
+with a blank line before and after the command, for example
 .in +4n
 .nf
 
@@ -588,6 +584,10 @@ In subsection ("SS") headings,
 capitalize the first word in the heading, but otherwise use lower case,
 except where English usage (e.g., proper nouns) or programming
 language requirements (e.g., identifier names) dictate otherwise.
+Foe example:
+
+    .SS Unicode under Linux
+
 .SS Indentation of structure definitions, shell session logs, etc.
 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
@@ -610,6 +610,7 @@ 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
 pathname	path name
@@ -644,6 +645,9 @@ username	user name
 zeros	zeroes
 .TE
 .ad
+.PP See also the discussion
+.IR "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,
@@ -655,6 +659,9 @@ 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}
@@ -727,7 +734,10 @@ parenthetical asides (e.g., like this one).
 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) in *roff is with the macro "\\(em".
+The way to write an em-dash\(emthe glyph that appears
+at either end of this subphrase\(emin *roff is with the macro "\\(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.
@@ -735,6 +745,7 @@ surrounding spaces.
 Compound terms should be hyphenated when used attributively
 (i.e., to qualify a following noun) Some examples:
 
+    32-bit value
     command-line argument
     floating-point number
     run-time check
@@ -780,7 +791,9 @@ Some examples:
 Finally, note that "re-create" and "recreate" are two different verbs,
 and the former is probably what you want.
 .SS Real hyphen character
-Where a real hyphen character is required (e.g., for numbers such as \-1),
+Where a real hyphen character is required (e.g., for numbers such as \-1,
+or when writing options that have a leading dash, such as in
+.IR "ls\ \-l"),
 use the following form in the man page source
 
     \\-
@@ -797,7 +810,7 @@ where
 is the quoted character.
 This guideline applies also to character constants used in code examples.
 .SS Example programs and shell sessions
-Manual pages can include example programs demonstrating how to
+Manual pages may include example programs demonstrating how to
 use a system call or library function.
 However, note the following:
 .IP * 3