Input file is a2ps.1 Any program (person), that produces man pages, should check the output for defects by using (both groff and nroff) [gn]roff -mandoc -t -ww -b -z -K utf8 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', 'mandoc', 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. Common defects: Input text line longer than 80 bytes. Not removing trailing spaces (in in- and output). The reason for these trailing spaces should be found and eliminated. Not beginning each input sentence on a new line. Lines should thus be shorter. See man-pages(7), item 'semantic newline'. -.- The difference between the formatted output of the original and patched file can be seen with: nroff -mandoc > nroff -mandoc > diff -u and for groff, using "printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -mandoc -Z - " instead of 'nroff -mandoc' 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 -b -z" export MAN_KEEP_STDERR=yes (or any non-empty value) -.-. Output from "mandoc -T lint a2ps.1 ": (shortened list) 2 input text line longer than 80 bytes 1 skipping paragraph macro -.-. Output from "test-groff -mandoc -t -ww -b -z a2ps.1 ": (shortened list) 1 font name 'CW' is deprecated -.-. Output from "mandoc -T lint a2ps.1 ": mandoc: a2ps.1:10:2: WARNING: skipping paragraph macro: PP after SH mandoc: a2ps.1:100:90: STYLE: input text line longer than 80 bytes: The options \fB\-1\f... mandoc: a2ps.1:101:85: STYLE: input text line longer than 80 bytes: layouts with 80 colu... -.-. -.-. Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em), if one is intended. " \(em " creates a too big gap in the text (in "troff"). 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 "\-\-". a2ps.1:259:\f(CW$ a2ps -P lw --toc src/*\fR -.-. Change -- in x--y to \(em (em-dash), or, if an option, to \-\- 259:\f(CW$ a2ps -P lw --toc src/*\fR -.-. 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. 259:\f(CW$ a2ps -P lw --toc src/*\fR 263:\f(CW$ a2ps -P display sample.ps sample.html\fR 267:\f(CW$ a2ps -=mail -4 mailbox\fR 271:\f(CW$ a2ps -=book paper.dvi.gz -d\fR -.-. Wrong distance between sentences in the input file. 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. 7:[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]... 100:The options \fB\-1\fR.. \fB\-9\fR affect several primitive parameters to set up predefined -.-. 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. Line 100, length 90 The options \fB\-1\fR.. \fB\-9\fR affect several primitive parameters to set up predefined Line 101, length 85 layouts with 80 columns. Therefore the order matters: `\-R \fB\-f40\fR \fB\-2\fR' is Line 128, length 91 \fB\-\-non\-printable\-format\fR=\fI\,FMT\/\fR specify how non\-printable chars are printed -.-. Put a parenthetical sentence, phrase on a separate line, if not part of a code. See man-pages(7), item "semantic newline". a2ps.1:103:options (`\-\-columns', `\-\-font\-size' etc.). a2ps.1:197:enable pretty\-printing (set style to LANG) a2ps.1:277:The system configuration file (usually \fI/usr/local/etc/a2ps.cfg\fR) -.-. Two or more space charaters between printable characters. When the distance is between sentences, start the beginning of the second one on a separate line ("semantic newline"). 11:Convert FILE(s) or standard input to PostScript. By default, the output is 12:sent to the default printer. An output file may be specified with \fB\-o\fR. 46:After having performed the task, exit successfully. Detailed lists may provide 101:layouts with 80 columns. Therefore the order matters: `\-R \fB\-f40\fR \fB\-2\fR' is 102:equivalent to `\-2'. To modify the layout, use `\-2Rf40', or compose primitive 212:leave output to file FILE. If FILE is `\-', 255:By default a2ps is tuned to do what you want to, so trust it. To pretty print 273:a2ps reads several files before the command line options. In order, 311:is maintained as a Texinfo manual. If the -.-. Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ": troff: backtrace: file '':259 troff::259: warning: font name 'CW' is deprecated -.- 'CW' changed to 'CR'.