Package: texlive-extra-utils
Version: 2024.20241115-1
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")
troff:<stdin>:10: warning: trailing space in the line
troff:<stdin>:49: warning: trailing space in the line
an.tmac:<stdin>:62: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
* 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 texlive-extra-utils depends on:
ii libfile-homedir-perl 1.006-2
ii libunicode-linebreak-perl 0.0.20190101-1+b8
ii libyaml-tiny-perl 1.76-1
ii python3 3.12.8-1
ii tex-common 6.18
ii texlive-base 2024.20241115-1
ii texlive-binaries 2024.20240313.70630+ds-5+b1
ii texlive-latex-base 2024.20241115-1
ii texlive-luatex 2024.20241115-1
ii texlive-plain-generic 2024.20241115-1
Versions of packages texlive-extra-utils recommends:
ii ghostscript 10.04.0~dfsg-2+b1
pn liblog-log4perl-perl <none>
ii ruby 1:3.1+nmu1
ii texlive-latex-recommended 2024.20241115-1
Versions of packages texlive-extra-utils suggests:
pn chktex <none>
pn default-jre-headless <none>
pn dvidvi <none>
pn dvipng <none>
pn fragmaster <none>
pn lacheck <none>
pn latexdiff <none>
pn latexmk <none>
pn purifyeps <none>
pn xindy <none>
Versions of packages tex-common depends on:
ii ucf 3.0046
Versions of packages tex-common suggests:
pn debhelper <none>
Versions of packages texlive-extra-utils is related to:
ii tex-common 6.18
ii texlive-binaries 2024.20240313.70630+ds-5+b1
-- no debconf information
Input file is pdfbook2.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 pdfbook2.1": (shortened list)
8 input text line longer than 80 bytes
14 whitespace at end of input line
-.-.
Output from "test-groff -mandoc -t -ww -z pdfbook2.1": (shortened list)
1 .BR is for at least 2 arguments, got 1
1 Use macro '.B' for one argument or split argument.
2 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
14
-.-.
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 "-"
(begin of an option or end of options)
then use "\-\-".
pdfbook2.1:10:Create print-ready PDF files from some \fIINPUT\fR PDF files for
booklet printing. The resulting files need to be printed in landscape/long edge
double sided printing. The default paper format depends on the locale and is
choosen by pdfjam. It can be set with the --paper option.
pdfbook2.1:29:pdfbook2 --paper=letter input.pdf
pdfbook2.1:37:pdfbook2 --paper=a4paper input.pdf
pdfbook2.1:45:pdfbook2 --inner-margin=200 input.pdf
pdfbook2.1:65:.BR -h ", " --help
pdfbook2.1:70:.BR -p ", " --paper = \fISTR\fR
pdfbook2.1:73:.BR -s ", " --short-edge
pdfbook2.1:76:.BR -n ", " --no-crop
pdfbook2.1:81:.BR -o ", " --outer-margin = \fIINT\fR
pdfbook2.1:84:.BR -i ", " --inner-margin = \fIINT\fR
pdfbook2.1:87:.BR -t ", " --top-margin = \fIINT\fR
pdfbook2.1:90:.BR -b ", " --bottom-margin = \fIINT\fR
pdfbook2.1:95:.BR --signature = \fIINT\fR
pdfbook2.1:98:.BR --signature* = \fIINT\fR
pdfbook2.1:99:Same as --signature
pdfbook2.1:101:.BR --resolution = \fIINT\fR
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
62:.BR \-\-version
-.-.
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.
1:.TH pdfbook2 1 "January 22, 2020" "" "pdfbook2 - transform pdf files to
booklets"
10:Create print-ready PDF files from some \fIINPUT\fR PDF files for booklet
printing. The resulting files need to be printed in landscape/long edge double
sided printing. The default paper format depends on the locale and is choosen
by pdfjam. It can be set with the --paper option.
14:The \fIOUTPUT\fR is written to \fIINPUT\fR-book.pdf. Existing files will be
overwritten. All input files are processed seperatly.
29:pdfbook2 --paper=letter input.pdf
37:pdfbook2 --paper=a4paper input.pdf
45:pdfbook2 --inner-margin=200 input.pdf
65:.BR -h ", " --help
70:.BR -p ", " --paper = \fISTR\fR
73:.BR -s ", " --short-edge
76:.BR -n ", " --no-crop
81:.BR -o ", " --outer-margin = \fIINT\fR
84:.BR -i ", " --inner-margin = \fIINT\fR
87:.BR -t ", " --top-margin = \fIINT\fR
90:.BR -b ", " --bottom-margin = \fIINT\fR
95:.BR --signature = \fIINT\fR
98:.BR --signature* = \fIINT\fR
99:Same as --signature
101:.BR --resolution = \fIINT\fR
112:(c) 2015 - 2020 Johannes Neumann (http://www.neumannjo.de)
-.-.
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.
71:Format of the output paper dimensions as latex keyword (e.g. a4paper,
letterpaper, legalpaper, ...)
-.-.
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.
Mark a final abbreviation point as such by suffixing it with "\&".
10:Create print-ready PDF files from some \fIINPUT\fR PDF files for booklet
printing. The resulting files need to be printed in landscape/long edge double
sided printing. The default paper format depends on the locale and is choosen
by pdfjam. It can be set with the --paper option.
12:Before the pdf is composed the \fIINPUT\fR file is cropped to the relevant
area in order to discard unnecessary white spaces. In this process, all pages
are cropped to the same dimensions. Extra margins can be defined at the edges
of the booklet and in the middle where the binding occurs.
14:The \fIOUTPUT\fR is written to \fIINPUT\fR-book.pdf. Existing files will be
overwritten. All input files are processed seperatly.
25:to create input-book.pdf. To select a special \fBtype of paper\fR you can do
41:for standard A4. To increase the \fBinner margin for binding\fR use
49:to increase the default value of 150. You can submit \fBmultiple files\fR to
the
71:Format of the output paper dimensions as latex keyword (e.g. a4paper,
letterpaper, legalpaper, ...)
121:This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
details. You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
-.-.
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 1, length 81
.TH pdfbook2 1 "January 22, 2020" "" "pdfbook2 - transform pdf files to
booklets"
Line 10, length 280
Create print-ready PDF files from some \fIINPUT\fR PDF files for booklet
printing. The resulting files need to be printed in landscape/long edge double
sided printing. The default paper format depends on the locale and is choosen
by pdfjam. It can be set with the --paper option.
Line 12, length 289
Before the pdf is composed the \fIINPUT\fR file is cropped to the relevant area
in order to discard unnecessary white spaces. In this process, all pages are
cropped to the same dimensions. Extra margins can be defined at the edges of
the booklet and in the middle where the binding occurs.
Line 14, length 129
The \fIOUTPUT\fR is written to \fIINPUT\fR-book.pdf. Existing files will be
overwritten. All input files are processed seperatly.
Line 49, length 81
to increase the default value of 150. You can submit \fBmultiple files\fR to
the
Line 71, length 99
Format of the output paper dimensions as latex keyword (e.g. a4paper,
letterpaper, legalpaper, ...)
Line 96, length 93
Define the signature for the booklet handed to pdfjam, needs to be multiple of
4 (default: 4)
Line 119, length 241
This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.
Line 121, length 371
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with
this program. If not, see <http://www.gnu.org/licenses/>.
-.-.
Use \(en (en-dash) for a dash at the beginning of a line,
or between space characters,
not a minus (\-) or a hyphen (-), except in the NAME section.
pdfbook2.1:1:.TH pdfbook2 1 "January 22, 2020" "" "pdfbook2 - transform pdf
files to booklets"
pdfbook2.1:112:(c) 2015 - 2020 Johannes Neumann (http://www.neumannjo.de)
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
Not considered in a patch, too many lines.
pdfbook2.1:71:Format of the output paper dimensions as latex keyword (e.g.
a4paper, letterpaper, legalpaper, ...)
pdfbook2.1:85:Defines the inner margin between the pages in the booklet
(default: 150)
pdfbook2.1:110:pdfbook2 v1.4 (https://github.com/jenom/pdfbook2)
pdfbook2.1:112:(c) 2015 - 2020 Johannes Neumann (http://www.neumannjo.de)
pdfbook2.1:114:licensed under GPLv3 (http://www.gnu.org/licenses/gpl-3.0)
pdfbook2.1:119:This program is free software: you can redistribute it and/or
modify it under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your option)
any later version.
-.-.
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
a) an option in UTF-8 text
b) web addresses (URL).
Is not needed in ordinary words like "mother-in-law", that are not
copied and pasted to a command line (which needs ASCII code)
45:pdfbook2 --inner-margin=200 input.pdf
73:.BR -s ", " --short-edge
76:.BR -n ", " --no-crop
81:.BR -o ", " --outer-margin = \fIINT\fR
84:.BR -i ", " --inner-margin = \fIINT\fR
87:.BR -t ", " --top-margin = \fIINT\fR
90:.BR -b ", " --bottom-margin = \fIINT\fR
-.-.
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>:10: warning: trailing space in the line
troff:<stdin>:49: warning: trailing space in the line
an.tmac:<stdin>:62: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
-.-.
Spelling:
Found by "codespell":
choosen ==> chosen
seperatly ==> separately
Additionally (general):
Abbreviations get a '\&' added after their final full stop (.) to mark them
as such and not as an end of a sentence.
--- pdfbook2.1 2024-12-30 21:37:10.499674059 +0000
+++ pdfbook2.1.new 2024-12-30 22:39:13.096734461 +0000
@@ -1,4 +1,4 @@
-.TH pdfbook2 1 "January 22, 2020" "" "pdfbook2 - transform pdf files to
booklets"
+.TH pdfbook2 1 "January 22, 2020" "" "pdfbook2 \(en transform pdf files to
booklets"
.SH NAME
pdfbook2 \- transform pdf files into booklets for double-sided printing
@@ -7,11 +7,26 @@ pdfbook2 \- transform pdf files into boo
\fBpdfbook2\fR [ \fIoptions\fR ] \fIINPUT\fR [ \fIINPUT\fR, ...]
.SH DESCRIPTION
-Create print-ready PDF files from some \fIINPUT\fR PDF files for booklet
printing. The resulting files need to be printed in landscape/long edge double
sided printing. The default paper format depends on the locale and is choosen
by pdfjam. It can be set with the --paper option.
-.PP
-Before the pdf is composed the \fIINPUT\fR file is cropped to the relevant
area in order to discard unnecessary white spaces. In this process, all pages
are cropped to the same dimensions. Extra margins can be defined at the edges
of the booklet and in the middle where the binding occurs.
-.PP
-The \fIOUTPUT\fR is written to \fIINPUT\fR-book.pdf. Existing files will be
overwritten. All input files are processed seperatly.
+Create print-ready PDF files from some \fIINPUT\fR PDF files for booklet
+printing.
+The resulting files need to be printed in landscape/long edge double sided
+printing.
+The default paper format depends on the locale
+and is chosen by pdfjam.
+It can be set with the \-\-paper option.
+.PP
+Before the pdf is composed
+the \fIINPUT\fR file is cropped to the relevant area
+in order to discard unnecessary white spaces.
+In this process,
+all pages are cropped to the same dimensions.
+Extra margins can be defined at the edges of the booklet
+and in the middle
+where the binding occurs.
+.PP
+The \fIOUTPUT\fR is written to \fIINPUT\fR-book.pdf.
+Existing files will be overwritten.
+All input files are processed separately.
.SH EXAMPLE
To simply \fBcreate a booklet\fR from input.pdf you can use
@@ -22,11 +37,12 @@ pdfbook2 input.pdf
.RE
.fi
.PP
-to create input-book.pdf. To select a special \fBtype of paper\fR you can do
+to create input-book.pdf.
+To select a special \fBtype of paper\fR you can do
.PP
.nf
.RS
-pdfbook2 --paper=letter input.pdf
+pdfbook2 \-\-paper=letter input.pdf
.RE
.fi
.PP
@@ -34,20 +50,21 @@ for letter or
.PP
.nf
.RS
-pdfbook2 --paper=a4paper input.pdf
+pdfbook2 \-\-paper=a4paper input.pdf
.RE
.fi
.PP
-for standard A4. To increase the \fBinner margin for binding\fR use
+for standard A4.
+To increase the \fBinner margin for binding\fR use
.PP
.nf
.RS
-pdfbook2 --inner-margin=200 input.pdf
+pdfbook2 \-\-inner-margin=200 input.pdf
.RE
.fi
.PP
-to increase the default value of 150. You can submit \fBmultiple files\fR to
the
-script for processing like
+to increase the default value of 150.
+You can submit \fBmultiple files\fR to the script for processing like
.PP
.nf
.RS
@@ -58,47 +75,49 @@ pdfbook2 input1.pdf input2.pdf
which will result in input1-book.pdf and input2-book.pdf.
.SH OPTIONS
-.TP
-.BR \-\-version
+.TP
+.B \-\-version
show program's version number and exit
-.TP
-.BR -h ", " --help
+.TP
+.BR \-h ", " \-\-help
show help message and exit
.SS GENERAL
-.TP
-.BR -p ", " --paper = \fISTR\fR
-Format of the output paper dimensions as latex keyword (e.g. a4paper,
letterpaper, legalpaper, ...)
-.TP
-.BR -s ", " --short-edge
+.TP
+.BR \-p ", " \-\-paper = \fISTR\fR
+Format of the output paper dimensions as latex keyword
+(e.g., a4paper, letterpaper, legalpaper, ...)
+.TP
+.BR \-s ", " \-\-short-edge
Format the booklet for short-edge double-sided printing
-.TP
-.BR -n ", " --no-crop
+.TP
+.BR \-n ", " \-\-no-crop
Prevent the cropping to the content area
.SS MARGINS
-.TP
-.BR -o ", " --outer-margin = \fIINT\fR
+.TP
+.BR \-o ", " \-\-outer-margin = \fIINT\fR
Defines the outer margin in the booklet (default: 40)
-.TP
-.BR -i ", " --inner-margin = \fIINT\fR
+.TP
+.BR \-i ", " \-\-inner-margin = \fIINT\fR
Defines the inner margin between the pages in the booklet (default: 150)
-.TP
-.BR -t ", " --top-margin = \fIINT\fR
+.TP
+.BR \-t ", " \-\-top-margin = \fIINT\fR
Defines the top margin in the booklet (default: 30)
-.TP
-.BR -b ", " --bottom-margin = \fIINT\fR
+.TP
+.BR \-b ", " \-\-bottom-margin = \fIINT\fR
Defines the bottom margin in the booklet (default: 30)
.SS ADVANCED
-.TP
-.BR --signature = \fIINT\fR
-Define the signature for the booklet handed to pdfjam, needs to be multiple of
4 (default: 4)
-.TP
-.BR --signature* = \fIINT\fR
-Same as --signature
-.TP
-.BR --resolution = \fIINT\fR
+.TP
+.BR \-\-signature = \fIINT\fR
+Define the signature for the booklet handed to pdfjam,
+needs to be multiple of 4 (default: 4)
+.TP
+.BR \-\-signature* = \fIINT\fR
+Same as \-\-signature
+.TP
+.BR \-\-resolution = \fIINT\fR
Resolution used by ghostscript in bp (default: 72)
.SH "SEE ALSO"
@@ -109,13 +128,25 @@ Resolution used by ghostscript in bp (de
.SH ABOUT
pdfbook2 v1.4 (https://github.com/jenom/pdfbook2)
.br
-(c) 2015 - 2020 Johannes Neumann (http://www.neumannjo.de)
+(c) 2015\(en2020 Johannes Neumann (http://www.neumannjo.de)
.br
licensed under GPLv3 (http://www.gnu.org/licenses/gpl-3.0)
.br
based on pdfbook by David Firth with help from Marco Pessotto
.SH LICENSE
-This program is free software: you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option) any later
version.
-
-This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
details. You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
+This program is free software:
+you can redistribute it
+and/or modify it under the terms of the GNU General Public License as
+published by the Free Software Foundation,
+either version 3 of the License,
+or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY;
+without even the implied warranty of MERCHANTABILITY
+or FITNESS FOR A PARTICULAR PURPOSE.
+See the GNU General Public License for more details.
+You should have received a copy of the GNU General Public License
+along with this program.
+If not, see <http://www.gnu.org/licenses/>.
