Any program (person), that produces man pages, should check its content for defects by using groff -mandoc -t -ww -b -z [ -K utf8 | k ] The same goes for man pages that are used as an input. For a style guide use mandoc -T lint -.- So any generator should check its products with the above mentioned 'groff' and additionally with 'nroff ...'. This is just a simple quality control measure. The generator may have to be corrected to get a better man page, the source file may, and any additional file may. -.- The difference between the formatted outputs can be seen with: nroff -man > nroff -man > diff -u and for groff, using "printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -man -Z - " instead of "nroff -man" Add the option "-t", if the file contains a table. Read the output of "diff -u" with "less -R" or similar. -.-. If "man" (man-db) is used to check the manual for warnings, the following must be set: The option "-warnings=w" The environmental variable: export MAN_KEEP_STDERR=yes (or any non-empty value) or (produce only warnings): export MANROFFOPT="-ww -z" export MAN_KEEP_STDERR=yes (or any non-empty value) -.-. Output from "mandoc -T lint tar.1": (possibly shortened list) mandoc: tar.1:24:2: WARNING: skipping paragraph macro: sp after SS mandoc: tar.1:39:2: WARNING: skipping paragraph macro: sp after SS mandoc: tar.1:89:2: WARNING: skipping paragraph macro: PP empty mandoc: tar.1:90:1: WARNING: skipping paragraph macro: sp after PP mandoc: tar.1:230:2: WARNING: line scope broken: TP breaks TP mandoc: tar.1:857:2: WARNING: empty block: RS mandoc: tar.1:1252:2: WARNING: skipping paragraph macro: sp after SS mandoc: tar.1:1268:2: WARNING: skipping paragraph macro: PP empty mandoc: tar.1:1280:82: STYLE: input text line longer than 80 bytes: from their disk coun... -.-. Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em), if one is intended. An en-dash is usually surrounded by a space, while an em-dash is used without spaces. "man" (1 byte characters in input) transforms an en-dash (\(en) to one HYPHEN-MINUS, and an em-dash to two HYPHEN-MINUSES without considering the space around it. If "--" are two single "-" (end of options) then use "\-\-". tar.1:155:tar --create --file etc.tar --verbose /etc tar.1:159:tar --cre --file=etc.tar --verb /etc tar.1:634:--file=remotehost:/dev/sr0 tar.1:647:--rsh-command=/usr/bin/ssh tar.1:1147:Keywords applicable for \fBtar --create\fR: tar.1:1183:Keywords applicable for \fBtar --extract\fR: tar.1:1215:$ tar --warning=decompress-program -x -f archive.Z -.-. Change (or include a "FIXME" paragraph about) misused SI (metric) numeric prefixes (or names) to the binary ones, like Ki (kibi), Mi (mebi), Gi (gibi), or Ti (tebi), if indicated. If the metric prefixes are correct, add the definitions or an explanation to avoid misunderstanding. 751:suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the 1258: B Kilobytes \fISIZE\fR x 1024 1260: G Gigabytes \fISIZE\fR x 1024^3 1261: K Kilobytes \fISIZE\fR x 1024 1262: k Kilobytes \fISIZE\fR x 1024 1263: M Megabytes \fISIZE\fR x 1024^2 1265: T Terabytes \fISIZE\fR x 1024^4 -.-. Mark a full stop (.) and the exclamation mark (!) with "\&", if it does not mean an end of a sentence. This is a preventive action, the paragraph could be reshaped, e.g., after changes. When typing, one does not always notice when the line wraps after the period. There are too many examples of input lines in manual pages, that end with an abbreviation point. This marking is robust, and independent of the position on the line. It corresponds to "\ " in TeX, and to "@:" in Texinfo. 86:can be either a regular file or a device (e.g. a tape drive, hence the name 125:clustered together after a single dash, e.g. \fB\-vkp\fR. An option 127:the end of such a cluster, e.g. \fB\-vkpf a.tar\fR. 284:effect only if the archive is open for reading (e.g. with 450:Current blocking factor, i.e. number of 512-byte blocks in a record. 611:pattern, e.g. \fB\-\-xattrs\-exclude='user.*'\fR to include only 673:Current blocking factor, i.e. number of 512-byte blocks in a record. 751:suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the 867:order-sensitive, i.e. it affects all options that follow. 984:names separated by ASCII \fBLF\fR (i.e. one name per line). The 1007:command line, i.e. any names starting with a dash are treated as 1294:a compression option (e.g. \fB\-z\fR) was used and the external -.-. Change -- in x--y to \(em (em-dash), or, if an option, to \-\- 155:tar --create --file etc.tar --verbose /etc 159:tar --cre --file=etc.tar --verb /etc 1147:Keywords applicable for \fBtar --create\fR: 1183:Keywords applicable for \fBtar --extract\fR: 1215:$ tar --warning=decompress-program -x -f archive.Z -.-. Change a HYPHEN-MINUS (code 0x2D) to a minus(-dash) (\-), if it is in front of a name for an option, is a symbol for standard input, is a single character used to indicate an option, or is in the NAME section (man-pages(7)). N.B. - (0x2D), processed as a UTF-8 file, is changed to a hyphen (0x2010, groff \[u2010] or \[hy]) in the output. 134:tar -cvf etc.tar /etc 138:tar -c -v -f etc.tar /etc 155:tar --create --file etc.tar --verbose /etc 159:tar --cre --file=etc.tar --verb /etc 634:--file=remotehost:/dev/sr0 647:--rsh-command=/usr/bin/ssh 1147:Keywords applicable for \fBtar --create\fR: 1183:Keywords applicable for \fBtar --extract\fR: 1215:$ tar --warning=decompress-program -x -f archive.Z -.-. Find a repeated word ! 750 --> can -.-. Strings longer than 3/4 of a standard line length (80) 780 \fB\-\-pax\-option\fR=\fIkeyword\fR[[:]=\fIvalue\fR][,\fIkeyword\fR[[:]=\fIvalue\fR]]... -.-. Add a comma (or \&) after "e.g." and "i.e.", or use English words (man-pages(7)). Abbreviation points should be protected against being interpreted as an end of sentence, if they are not, and that independent of the current place on the line. 86:can be either a regular file or a device (e.g. a tape drive, hence the name 125:clustered together after a single dash, e.g. \fB\-vkp\fR. An option 127:the end of such a cluster, e.g. \fB\-vkpf a.tar\fR. 284:effect only if the archive is open for reading (e.g. with 450:Current blocking factor, i.e. number of 512-byte blocks in a record. 611:pattern, e.g. \fB\-\-xattrs\-exclude='user.*'\fR to include only 673:Current blocking factor, i.e. number of 512-byte blocks in a record. 751:suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the 867:order-sensitive, i.e. it affects all options that follow. 984:names separated by ASCII \fBLF\fR (i.e. one name per line). The 1007:command line, i.e. any names starting with a dash are treated as 1294:a compression option (e.g. \fB\-z\fR) was used and the external -.-. Wrong distance between sentences. Separate the sentences and subordinate clauses; each begins on a new line. See man-pages(7) ("Conventions for source file layout") and "info groff" ("Input Conventions"). The best procedure is to always start a new sentence on a new line, at least, if you are typing on a computer. Remember coding: Only one command ("sentence") on each (logical) line. E-mail: Easier to quote exactly the relevant lines. Generally: Easier to edit the sentence. Patches: Less unaffected text. Search for two adjacent words is easier, when they belong to the same line, and the same phrase. The amount of space between sentences in the output can then be controlled with the ".ss" request. N.B The number of lines affected can be too large to be in the patch. 86:can be either a regular file or a device (e.g. a tape drive, hence the name 125:clustered together after a single dash, e.g. \fB\-vkp\fR. An option 127:the end of such a cluster, e.g. \fB\-vkpf a.tar\fR. 284:effect only if the archive is open for reading (e.g. with 388:Type of the file. It is a single letter with the following meaning: 418:Time of last access. It is a decimal number, representing seconds 450:Current blocking factor, i.e. number of 512-byte blocks in a record. 611:pattern, e.g. \fB\-\-xattrs\-exclude='user.*'\fR to include only 673:Current blocking factor, i.e. number of 512-byte blocks in a record. 751:suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the 867:order-sensitive, i.e. it affects all options that follow. 984:names separated by ASCII \fBLF\fR (i.e. one name per line). The 1007:command line, i.e. any names starting with a dash are treated as 1178:Suppresses warnings about unreadable files or directories. This 1294:a compression option (e.g. \fB\-z\fR) was used and the external -.-. Split lines longer than 80 characters into two or more lines. Appropriate break points are the end of a sentence and a subordinate clause; after punctuation marks. tar.1: line 40 length 114 \fBtar\fR {\fB\-\-catenate\fR|\fB\-\-concatenate\fR} [\fIOPTIONS\fR] \fB\-\-file\fR \fIARCHIVE\fR \fIARCHIVE\fR... tar.1: line 42 length 89 \fBtar\fR \fB\-\-create\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...] tar.1: line 44 length 107 \fBtar\fR {\fB\-\-diff\fR|\fB\-\-compare\fR} [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...] tar.1: line 46 length 91 \fBtar\fR \fB\-\-delete\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...] tar.1: line 48 length 89 \fBtar\fR \fB\-\-append\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...] tar.1: line 50 length 89 \fBtar\fR \fB\-\-list\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...] tar.1: line 52 length 95 \fBtar\fR \fB\-\-test\-label\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fILABEL\fR...] tar.1: line 54 length 89 \fBtar\fR \fB\-\-update\fR [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIFILE\fR...] tar.1: line 56 length 108 \fBtar\fR {\fB\-\-extract\fR|\fB\-\-get\fR} [\fB\-\-file\fR \fIARCHIVE\fR] [\fIOPTIONS\fR] [\fIMEMBER\fR...] tar.1: line 660 length 92 \fB\-F\fR, \fB\-\-info\-script\fR=\fICOMMAND\fR, \fB\-\-new\-volume\-script\fR=\fICOMMAND\fR tar.1: line 780 length 88 \fB\-\-pax\-option\fR=\fIkeyword\fR[[:]=\fIvalue\fR][,\fIkeyword\fR[[:]=\fIvalue\fR]]... tar.1: line 1280 length 82 from their disk counterparts. If \fBtar\fR was given one of the \fB\-\-create\fR, -.-. Change a HYPHEN-MINUS (code 0x55, 2D) to a dash (\-, minus) if it matches "[[:alph:]]-[[:alpha:]]" in the name of an option). Facilitates the copy and paste of an option in UTF-8 text. Is not needed in ordinary words like "mother-in-law", that are not copied and pasted to a command line (which needs ASCII code) 600:.B \-\-no-selinux 647:--rsh-command=/usr/bin/ssh 751:suffix\fR, e.g. \fB\-\-record-size=10K\fR, for 10 Kilobytes. See the -.- Output from "test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -K utf8 -t -ww -z -K utf8": an.tmac::231: warning: cannot nest .TP or .TQ inside .TP; supply a tag