Package: groff
Version: upstream, GIT HEAD
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with
[test-][g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"
[test-groff is a script in the repository for "groff"] (local copy and
"troff" slightly changed by me).
* What was the outcome of this action?
troff: backtrace: file '<stdin>':4162
troff:<stdin>:4162: warning: trailing space in the line
troff: backtrace: file '<stdin>':11
troff:<stdin>:11: warning: macro 'I' not defined
troff: backtrace: file '<stdin>':18
troff:<stdin>:18: warning: macro 'MR' not defined
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':11
troff:<stdin>:11: warning: macro 'I' not defined
troff: backtrace: file '<stdin>':18
troff:<stdin>:18: warning: macro 'MR' not defined
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
Any program (person), that produces man pages, should check the output
for defects by using both groff and nroff.
[test][g|n]roff -mandoc -t -ww -b -z -K utf8 <man page>
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 outputs can be seen with:
nroff -mandoc <file1> > <out1>
nroff -mandoc <file2> > <out2>
diff -u <out1> <out2>
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 groff_man.7.man.in": (possibly shortened list)
mandoc: groff_man.7.man.in:1232:2: WARNING: skipping paragraph macro: PP empty
mandoc: groff_man.7.man.in:1242:2: WARNING: skipping paragraph macro: PP empty
mandoc: groff_man.7.man.in:2321:2: WARNING: skipping paragraph macro: br at the
end of SS
-.-.
Lines containing '\c' (' \c' does not make sense):
25:After processing by m4, both child pages in the above case will carry \c
610:.RB "].\|.\|.\& \e\- "\c
Separate an ellipsis from the preceding string with a space
character, if it does not mean a continuation of it.
See a manual of style about the difference between "abc..." and
"abc ...".
4162:To get a \(lqliteral\(rq.\|.\|. .\|.\|.should be input.
4212:Instead of.\|.\|. .\|.\|.should be considered.
4401:Instead of.\|.\|. .\|.\|.should be considered.
4460:Instead of.\|.\|. .\|.\|.do this.
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
610:.RB "].\|.\|.\& \e\- "\c
-.-.
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.
3619:.TP 9.25n \" "-rHY=0" + 2n + hand-tuned for PDF
-.-.
Three full stops (periods) are used for an ellipsis
3376:.\" ..and which Clark included in groff man(7) from 1.01 or earlier...
-.-.
Add a zero (0) in front of a decimal fraction that begins with a period
(.)
3540:.\" .5v after, as well as...
-.-.
Split a punctuation from a single argument, if a two-font macro is meant
228:.I roff;
252:.I break.
301:.I arguments,
490:.I section,
500:.I header-middle;
569:.I heading-text.
635:.I subheading-text.
750:.I inset-amount,
876:.I indentation,
1577:.I trailing-text.
1632:.I trailing-text.
3205:.I system.
3421:.I version.
3566:.I groff.
3622:.I adjustment-mode,
3715:.I footer-distance;
3849:.I subsection-indentation.
4350:.I level.
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':4162
troff:<stdin>:4162: warning: trailing space in the line
-.-.
Additionally (general):
Abbreviations get a '\&' added after their final full stop (.) to mark them as
such and not as an end of sentence.
There is no need to add a '\&' before a full stop (.) if it has a character
before it!
--- groff_man.7.man.in 2024-10-03 20:14:56.753076758 +0000
+++ groff_man.7.man.in.new 2024-10-07 18:16:21.140898051 +0000
@@ -22,7 +22,7 @@ _endif()dnl
These man pages serve multiple goals, one of which is to serve as a
model for good man page writing by people who examine their sources.
-After processing by m4, both child pages in the above case will carry \c
+After processing by m4, both child pages in the above case will carry
escape sequences followed by text lines starting with punctuation one
normally does not find in that position (and in the case of the period,
which has to be protected from interpretation as a control line).
@@ -225,7 +225,7 @@ A man page employs the Unix line-ending
(U+000A only).
.
Some basic Latin characters have special meaning to
-.I roff;
+.IR roff ;
see subsection \(lqPortability\(rq below.
.
.
@@ -249,7 +249,7 @@ are separated by spaces and newlines.
.\" Also tabs and leaders, but let's not discuss those in man(7).
.
A transition to a new output line is called a
-.I break.
+.IR break .
.
When formatted,
a word may be broken at hyphens,
@@ -298,7 +298,7 @@ put its name after a dot on a control li
This document uses the leading dot to identify macros.
.
Some macros interpret
-.I arguments,
+.IR arguments ,
words that follow its name.
.
A newline,
@@ -487,7 +487,7 @@ Use of the continuous-rendering option
replaces it with
.I identifier
and
-.I section,
+.IR section ,
as in the header.
.
.I header-middle
@@ -497,7 +497,7 @@ If
.I section
is an integer between 1 and\~9 (inclusive),
there is no need to specify
-.I header-middle;
+.IR header-middle ;
.I an.tmac
supplies text for it.
.
@@ -566,7 +566,7 @@ the macro plants a one-line input trap;
text on the next line
.\", which can be formatted with a macro, \" true but discouraged
becomes
-.I heading-text.
+.IR heading-text .
.
The heading text is set in bold
(or the font specified by the string
@@ -607,7 +607,7 @@ and must contain only text of the form
.RS \" Now indent further, visibly.
.IR topic [\c
.BI , " another-topic"\c
-.RB "].\|.\|.\& \e\- "\c
+.RB "].\|.\|.\&" " \e\- "\c
.I summary-description
.RE \" Move left margin back to .IP indentation.
for tools like
@@ -632,7 +632,7 @@ the macro plants a one-line input trap;
text on the next line
.\", which can be formatted with a macro, \" true but discouraged
becomes
-.I subheading-text.
+.IR subheading-text .
.
The subheading text is set in bold
(or the font specified by the string
@@ -708,7 +708,7 @@ before the spaces.
.
_endif()dnl
.IP
-.\" Also see subsection "History" below...
+.\" Also see subsection "History" below ...
.B .EX
and
.B .EE
@@ -747,7 +747,7 @@ Start a new relative inset level.
.
The current inset amount is saved,
then moved right by
-.I inset-amount,
+.IR inset-amount ,
if specified;
by the
.I indentation
@@ -873,7 +873,7 @@ text on the next line becomes the tag,
set without indentation.
.
Text on subsequent lines is indented by
-.I indentation,
+.IR indentation ,
if specified,
and by the amount of the
.B IN
@@ -1229,7 +1229,6 @@ produces the following output.
.YS
.
.
-.P
.SY groff
.B \-h
.YS
@@ -1239,7 +1238,6 @@ produces the following output.
.YS
.
.
-.P
.SY groff
.B \-v
.RI [ option\~ .\|.\|.\&]
@@ -1322,8 +1320,8 @@ follows the ellipsis when further text i
output line,
keeping its last period from being interpreted as the end of a
sentence
-.\" ...because it is followed by characters that are transparent to
-.\" end-of-sentence detection, and a newline...
+.\" ... because it is followed by characters that are transparent to
+.\" end-of-sentence detection, and a newline ...
and causing additional inter-sentence space to be placed after it.
.
See subsection \(lqPortability\(rq below.
@@ -1574,7 +1572,7 @@ and supported by the output driver.
If they are not,
.I address
is set in angle brackets after the link text and before
-.I trailing-text.
+.IR trailing-text .
.
If hyperlinking is enabled but there is no link text,
.I address
@@ -1629,7 +1627,7 @@ and supported by the output driver.
If they are not,
.I uri
is set in angle brackets after the link text and before
-.I trailing-text.
+.IR trailing-text .
.
If hyperlinking is enabled but there is no link text,
.I uri
@@ -2318,7 +2316,6 @@ file as well;
see section \(lqFiles\(rq below.
.
.
-.br
.ne 7v
.\" ====================================================================
.SS Strings
@@ -2780,7 +2777,7 @@ End a text line without inserting space
Normally,
if filling is enabled,
the end of a text line is treated like a space;
-.\" end-of-sentence detection is performed, and...
+.\" end-of-sentence detection is performed, and ...
an output line
.I may
break there
@@ -3202,7 +3199,7 @@ This macro exists only to render man pag
.
.IP
The inside footer is populated per the value of
-.I system.
+.IR system .
.
.
.RS \" Invisibly move left margin to current .IP indentation.
@@ -3373,7 +3370,7 @@ is set smaller and in bold.
Use of this macro,
an extension originating in SunOS\~4.0
.IR troff ,\" SunOS
-.\" ..and which Clark included in groff man(7) from 1.01 or earlier...
+.\" ... and which Clark included in groff man(7) from 1.01 or earlier ...
is deprecated.
.
.B .SM
@@ -3418,7 +3415,7 @@ This macro exists only to render man pag
.
.IP
The inside footer is populated per the value of
-.I version.
+.IR version .
.
.
.RS \" Invisibly move left margin to current .IP indentation.
@@ -3494,12 +3491,12 @@ appeared in 3BSD (1980).
.\" bitsavers_attunixSysalRelease3Jun80_33886798
Unix System\~III (1980) introduced
.B .P
-.\" ...and de-documented .LP...
+.\" ... and de-documented .LP ...
and exposed the registers
.B IN
and
.BR LL ,
-.\" ...as well as \n[PD], which we implement but don't expose.
+.\" ... as well as \n[PD], which we implement but don't expose.
which had been internal to Seventh Edition Unix
.IR man .
.
@@ -3517,7 +3514,7 @@ string.
.
4BSD (1980) added
.\" undocumented .VS and .VE macros to mark regions with 12-point box
-.\" rules (\[br]) as margin characters, as well as...
+.\" rules (\[br]) as margin characters, as well as ...
.B lq
and
.B rq
@@ -3537,13 +3534,13 @@ registers.
4.3BSD (1986) added
.\" undocumented .DS and .DE macros for "displays", which are .RS/.RE
.\" wrappers with filling disabled and vertical space of 1v before and
-.\" .5v after, as well as...
+.\" 0.5v after, as well as ...
.B .AT
and
.BR .P .
.
.\" Per Doug McIlroy in
-.\" <https://lists.gnu.org/archive/html/groff/2019-07/msg00038.html>...
+.\" <https://lists.gnu.org/archive/html/groff/2019-07/msg00038.html> ...
Ninth Edition Unix (1986) introduced
.B .EX
and
@@ -3563,7 +3560,7 @@ SunOS\~4.0 (1988) added
Except for
.BR .EX / .EE ,
James Clark implemented the foregoing features in early versions of
-.I groff.
+.IR groff .
.
Later,
.I groff
@@ -3575,7 +3572,7 @@ and originated
.BR .MT / .ME ,
and
.BR .UR / .UE .
-.\" ...along with implementations of OP, EX, and EE.
+.\" ... along with implementations of OP, EX, and EE.
.\"
.\" It's not clear exactly when `OP` showed up in DWB troff. It wasn't
.\" in 1.0 (1984), but was by the time of the 3.3 release (1992). Scans
@@ -3616,10 +3613,10 @@ reader preferences,
man pages should never manipulate them.
.
.
-.TP 9.25n \" "-rHY=0" + 2n + hand-tuned for PDF
+.TP 9.25n \" "\-rHY=0" + 2n + hand-tuned for PDF
.BI \-dAD= adjustment-mode
Set line adjustment to
-.I adjustment-mode,
+.IR adjustment-mode ,
which is typically
.RB \[lq] b \[rq]
for adjustment to both margins
@@ -3712,7 +3709,7 @@ in subsection \(lqDocument structure mac
.TP
.BI \-rFT= footer-distance
Set distance of the footer relative to the bottom of the page to
-.I footer-distance;
+.IR footer-distance ;
this amount is always negative.
.
At one half-inch above this location,
@@ -3846,7 +3843,7 @@ See subsection \(lqFont style macros\(rq
.TP
.BI \-rSN= subsection-indentation
Set indentation of subsection headings to
-.I subsection-indentation.
+.IR subsection-indentation .
.
The default is\~3n.
.
@@ -4159,7 +4156,7 @@ this translation is sometimes not desira
.TS
Lb Lb
RfCR LfCR.
-To get a \(lqliteral\(rq .\|.\|.\& .\|.\|.\& should be input.
+To get a \(lqliteral\(rq .\|.\|. .\|.\|.should be input.
_
\(aq \(rs(aq
\- \(rs\-
@@ -4209,7 +4206,7 @@ often a shorter or clearer alternative i
.TS
Cb Cb
LfCR LfCR.
-Instead of.\|.\|. .\|.\|.should be considered.
+Instead of .\|.\|. .\|.\|. should be considered.
_
\&.TP \(dq\(dq .TP
_
@@ -4226,6 +4223,7 @@ _
\fR.\|.\|. .RE
_
\&.B one two \(dq\(dq three .B one two three
+_
.TE
.
.
@@ -4347,7 +4345,7 @@ as an argument;
the
.B .RE
macro's argument is an inset
-.I level.
+.IR level .
.
.B .RE\~1
goes to the level before any
@@ -4398,7 +4396,7 @@ Review subsection \(lqHorizontal and ver
.TS
Lb Lb
LfCR LfCR.
-Instead of.\|.\|. .\|.\|.should be considered.
+Instead of .\|.\|. .\|.\|. should be considered.
_
\&.IP \(rs(bu 4n .IP \(rs(bu 4n
\fIparagraph \fIparagraph
@@ -4455,9 +4453,9 @@ when not ending a sentence.
.if t .ne 5v
.if n .ne 7v \" account for horizontal rules
.TS
-Cb Cb
+Lb Lb
LfCR LfCR.
-Instead of.\|.\|. .\|.\|.do this.
+Instead of .\|.\|. .\|.\|. do this.
_
\&.ds EL \[rs]&.\[rs]|.\[rs]|. Arguments are
Arguments are .IR src-file\[rs]\[ti] .\[rs]|.\[rs]|.\[rs]&
