--- Begin Message ---
Package: psutils
Version: 1.17.dfsg-5
Severity: minor
Tags: patch
* What led up to the situation?
Checking for defects with a new version
test-[g|n]roff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z < "man
page"
[Use "groff -e ' $' <file>" to find trailing spaces.]
["test-groff" is a script in the repository for "groff"; is not shipped]
(local copy and "troff" slightly changed by me).
[The fate of "test-nroff" was decided in groff bug #55941.]
* What was the outcome of this action?
an.tmac:<stdin>:1: style: .TH missing fourth argument; consider package/project
name and version (e.g., "groff 1.23.0")
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material, if a diff-file exist, are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.12.6-amd64 (SMP w/2 CPU threads; PREEMPT)
Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1),
LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: sysvinit (via /sbin/init)
Versions of packages psutils depends on:
ii libc6 2.40-4
Versions of packages psutils recommends:
ii ghostscript 10.04.0~dfsg-2+b1
psutils suggests no packages.
-- no debconf information
Input file is psnup.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 <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 output of the original and patched file
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 psnup.1": (shortened list)
1 input text line longer than 80 bytes
10 whitespace at end of input line
-.-.
Output from "test-groff -mandoc -t -ww -z psnup.1": (shortened list)
9 trailing space in the line
-.-.
Remove space characters (whitespace) at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
Number of lines affected is
10
-.-.
Change '-' (\-) to '\(en' (en-dash) for a numeric range.
GNU gnulib has recently (2023-06-18) updated its
"build_aux/update-copyright" to recognize "\(en" in man pages.
psnup.1:150:Copyright (C) Angus J. C. Duggan 1991-1995
-.-.
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.
141:groff -Tps -ms \fIfile\fP | psbook | psnup -2 | lpr
-.-.
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 152, length 253
psbook(1), psselect(1), pstops(1), epsffit(1), psnup(1), psresize(1),
psmerge(1), fixscribeps(1), getafm(1), fixdlsrps(1), fixfmps(1), fixpsditps(1),
fixpspps(1), fixtpps(1), fixwfwps(1), fixwpps(1), fixwwps(1), extractres(1),
includeres(1), showchar(1)
-.-.
The section part for a manual page is set in roman font.
135:.I psbook(1).
-.-.
Split a punctuation from a single argument, if a two-font macro is meant.
63:.B 10x14.
65:.B a4,
135:.I psbook(1).
-.-.
Name of a manual is set in bold, the section in roman.
See man-pages(7).
152:psbook(1), psselect(1), pstops(1), epsffit(1), psnup(1), psresize(1),
psmerge(1), fixscribeps(1), getafm(1), fixdlsrps(1), fixfmps(1), fixpsditps(1),
fixpspps(1), fixtpps(1), fixwfwps(1), fixwpps(1), fixwwps(1), extractres(1),
includeres(1), showchar(1)
-.-.
Put a subordinate sentence (after a comma) on a new line.
51:option gives the paper width, and the
60:option can be used as an alternative, to set the paper size to
66:but on a Debian system, /etc/papersize is consulted.
71:options set the input paper size, if it is different from the output
81:degrees clockwise), and the
87:normally uses `row-major' layout, where adjacent pages are placed in rows
91:option changes the order to `column-major', where successive pages are placed
96:option. This is useful for sheets of `thumbnail' pages, because the normal
105:option draws a line around the border of each page, of the specified width.
106:If the \fIlwidth\fR parameter is omitted, a default linewidth of 1 point is
123:cannot find a layout within its tolerance limit, it will abort with an error
126:can also be used, for compatibility with other n-up programs.
136:For example, using groff to create a PostScript document and lpr as
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:1: style: .TH missing fourth argument; consider package/project
name and version (e.g., "groff 1.23.0")
troff:<stdin>:58: warning: trailing space in the line
troff:<stdin>:133: warning: trailing space in the line
troff:<stdin>:134: warning: trailing space in the line
troff:<stdin>:136: warning: trailing space in the line
troff:<stdin>:137: warning: trailing space in the line
troff:<stdin>:139: warning: trailing space in the line
troff:<stdin>:143: warning: trailing space in the line
troff:<stdin>:145: warning: trailing space in the line
troff:<stdin>:147: 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 a sentence.
--- psnup.1 2025-01-04 22:19:07.857550795 +0000
+++ psnup.1.new 2025-01-04 23:09:26.142168212 +0000
@@ -48,44 +48,51 @@ Conventions.
.PP
The
.I \-w
-option gives the paper width, and the
+option gives the paper width,
+and the
.I \-h
option gives the paper height,
normally specified in
.B "cm"
or
.BR "in" .
-The
+The
.I \-p
-option can be used as an alternative, to set the paper size to
-.B a0, a1, a2, a3, a4, a5, b5, letter, legal, tabloid, statement,
-executive, folio, quarto or
-.B 10x14.
+option can be used as an alternative,
+to set the paper size to
+.B a0, a1, a2, a3, a4, a5, b5, letter, legal, tabloid, statement, \
+executive, folio, quarto
+or
+.BR 10x14 .
The default paper size is normally
-.B a4,
-but on a Debian system, /etc/papersize is consulted.
+.BR a4 ,
+but on a Debian system,
+/etc/papersize is consulted.
The
-.I \-W, \-H,
+.IR \-W ", " \-H ,
and
.I \-P
-options set the input paper size, if it is different from the output
-size. This makes it easy to impose pages of one size on a different size of
-paper.
+options set the input paper size,
+if it is different from the output size.
+This makes it easy to impose pages of one size on a different size of paper.
.PP
The
.I \-l
-option should be used for pages which are in landscape orientation (rotated 90
-degrees anticlockwise). The
+option should be used for pages
+which are in landscape orientation
+(rotated 90 degrees anticlockwise).
+The
.I \-r
-option should be used for pages which are in seascape orientation (rotated 90
-degrees clockwise), and the
+option should be used for pages which are in seascape orientation
+(rotated 90 degrees clockwise),
+and the
.I \-f
option should be used for pages which have the width and height interchanged,
but are not rotated.
.PP
.I Psnup
-normally uses `row-major' layout, where adjacent pages are placed in rows
-across the paper.
+normally uses `row-major' layout,
+where adjacent pages are placed in rows across the paper.
The
.I \-c
option changes the order to `column-major', where successive pages are placed
@@ -102,54 +109,67 @@ option is used to specify an additional
.PP
The
.I \-d
-option draws a line around the border of each page, of the specified width.
-If the \fIlwidth\fR parameter is omitted, a default linewidth of 1 point is
-assumed. The linewidth is relative to the original page dimensions,
-\fIi.e.\fR it is scaled down with the rest of the page.
+option draws a line around the border of each page,
+of the specified width.
+If the \fIlwidth\fR parameter is omitted,
+a default linewidth of 1 point is assumed.
+The linewidth is relative to the original page dimensions,
+\fIi.e.\&\fR it is scaled down with the rest of the page.
.PP
The scale chosen by
.I psnup
can be overridden with the
.I \-s
-option. This is useful to merge pages which are already reduced.
+option.
+This is useful to merge pages which are already reduced.
.PP
The
.I \-\fInup\fR
-option selects the number of logical pages to put on each sheet of paper. This
-can be any whole number;
+option selects the number of logical pages to put on each sheet of paper.
+This can be any whole number;
.I psnup
-tries to optimise the layout so that the minimum amount of space is wasted. If
+tries to optimise the layout
+so that the minimum amount of space is wasted.
+If
.I psnup
-cannot find a layout within its tolerance limit, it will abort with an error
-message. The alternative form
+cannot find a layout within its tolerance limit,
+it will abort with an error message.
+The alternative form
.I \-i \fInup\fR
-can also be used, for compatibility with other n-up programs.
+can also be used,
+for compatibility with other n-up programs.
.PP
.I Psnup
normally prints the page numbers of the pages re-arranged; the
.I \-q
option suppresses this.
.SH EXAMPLES
-The potential use of this utility is varied but one particular
-use is in conjunction with
-.I psbook(1).
-For example, using groff to create a PostScript document and lpr as
-the
-.SM UNIX
-print spooler a typical command line might look like this:
+The potential use of this utility is varied but one particular
+use is in conjunction with
+.BR psbook (1).
+For example,
+using groff to create a PostScript document
+and lpr as the
+.SM UNIX
+print spooler
+a typical command line might look like this:
.sp
-groff -Tps -ms \fIfile\fP | psbook | psnup -2 | lpr
+groff \-Tps \-ms \fIfile\fP | psbook | psnup \-2 | lpr
.sp
-Where file is a 4 page document this command will result in a
+Where file is a 4 page document this command will result in a
two page document printing two pages of \fIfile\fP per page and
-rearranges the page order to match the input pages 4 and 1
+rearranges the page order to match the input pages 4 and 1
on the first output page and
-pages 2 then 3 of the input document
+pages 2 then 3 of the input document
on the second output page.
.SH AUTHOR
-Copyright (C) Angus J. C. Duggan 1991-1995
+Copyright (C) Angus J.\& C.\& Duggan 1991\(en1995
.SH "SEE ALSO"
-psbook(1), psselect(1), pstops(1), epsffit(1), psnup(1), psresize(1),
psmerge(1), fixscribeps(1), getafm(1), fixdlsrps(1), fixfmps(1), fixpsditps(1),
fixpspps(1), fixtpps(1), fixwfwps(1), fixwpps(1), fixwwps(1), extractres(1),
includeres(1), showchar(1)
+.BR psbook "(1), " psselect "(1), " pstops "(1), " epsffit "(1), " psnup \
+"(1), " psresize "(1), " psmerge "(1), " fixscribeps "(1), " getafm "(1), " \
+fixdlsrps "(1), " fixfmps "(1), " fixpsditps "(1), " fixpspps "(1), " fixtpps \
+"(1), " fixwfwps "(1), " fixwpps "(1), " fixwwps "(1), " extractres "(1), " \
+includeres "(1), " showchar (1)
.SH TRADEMARKS
.B PostScript
is a trademark of Adobe Systems Incorporated.
--- End Message ---
