Bug#1088318: aleph.1: Some remarks and editorial changes for this man page
Package: texlive-binaries
Version: 2024.20240313.70630+ds-5
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"
[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?
troff: backtrace: file '<stdin>':33
troff:<stdin>:33: warning: trailing space in the line
troff: backtrace: file '<stdin>':36
troff:<stdin>:36: warning: trailing space in the line
troff: backtrace: file '<stdin>':163
troff:<stdin>:163: warning: trailing space in the line
-.-
* 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.11.9-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-binaries depends on:
ii libc6 2.40-3
ii libcairo2 1.18.2-2
ii libfontconfig1 2.15.0-1.1+b1
ii libfreetype6 2.13.3+dfsg-1
ii libgcc-s1 14.2.0-8
ii libgraphite2-3 1.3.14-2+b1
ii libharfbuzz0b 10.0.1-1
ii libicu72 72.1-5+b1
ii libkpathsea6 2024.20240313.70630+ds-5
ii libmpfi0 1.5.4+ds-4
ii libmpfr6 4.2.1-1+b2
ii libpaper1 1.1.29+b2
ii libpixman-1-0 0.44.0-3
ii libpng16-16t64 1.6.44-2
ii libpotrace0 1.16-2+b2
ii libptexenc1 2024.20240313.70630+ds-5
ii libstdc++6 14.2.0-8
ii libsynctex2 2024.20240313.70630+ds-5
ii libteckit0 2.5.12+ds1-1+b1
ii libtexlua53-5 2024.20240313.70630+ds-5
ii libx11-6 2:1.8.10-2
ii libxaw7 2:1.0.16-1
ii libxi6 2:1.8.2-1
ii libxmu6 2:1.1.3-3+b3
ii libxpm4 1:3.5.17-1+b2
ii libxt6t64 1:1.2.1-1.2+b1
ii libzzip-0-13t64 0.13.72+dfsg.1-1.2+b1
ii perl 5.40.0-7
ii t1utils 1.41-4
ii tex-common 6.18
ii zlib1g 1:1.3.dfsg+really1.3.1-1+b1
Versions of packages texlive-binaries recommends:
pn dvisvgm <none>
ii texlive-base 2024.20241115-1
Versions of packages texlive-binaries suggests:
pn hintview <none>
pn texlive-binaries-sse2 <none>
Versions of packages tex-common depends on:
ii ucf 3.0043+nmu1
Versions of packages tex-common suggests:
pn debhelper <none>
Versions of packages texlive-binaries is related to:
ii tex-common 6.18
ii texlive-base 2024.20241115-1
-- no debconf information
Input file is aleph.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 aleph.1 ": (shortened list)
1 skipping paragraph macro
3 whitespace at end of input line
-.-.
Output from "test-groff -mandoc -t -ww -b -z aleph.1 ": (shortened list)
3 trailing space in the line
-.-.
Output from "mandoc -T lint aleph.1 ":
mandoc: aleph.1:33:70: STYLE: whitespace at end of input line
mandoc: aleph.1:36:7: STYLE: whitespace at end of input line
mandoc: aleph.1:163:64: STYLE: whitespace at end of input line
mandoc: aleph.1:180:2: WARNING: skipping paragraph macro: PP empty
-.-.
Remove space characters at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
33:If the file argument has no extension, ".tex" will be appended to it.
36:With a
163:can be any Bourne shell command. By default, this construct is
-.-.
Change -- in x--y to \(em (em-dash), or, if an
option, to \-\-
56:Run aleph --help to see the complete list of options; this is not
66:.BI --fmt \ format
74:.B --halt-on-error
77:.B --help
80:.B --ini
85:.BI --interaction \ mode
95:.B --ipc
99:.B --ipc-start
101:.BR --ipc ,
105:.BI --kpathsea-debug \ bitmask
110:.BI --maketex \ fmt
120:.BI --no-maketex \ fmt
130:.BI --output-comment \ string
135:.BI --output-directory \ directory
142:.B --parse-first-line
147:.BI --progname \ name
152:.B --recorder
158:.B --shell-escape
166:.B --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.
42:.B -fmt
59:.BI -cnf-line \ string
-.-.
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").
N.B.
The number of lines affected can be too large to be in a patch.'
47:typesetting. It uses Unicode, and has additional primitives for
64:configuration line. See the Kpathsea manual.
86:Sets the interaction mode. The mode can be one of
96:Send DVI output to a socket as well as the usual output file. Whether
102:and starts the server at the other end as well. Whether this option
106:Sets path searching debugging flags according to the bitmask. See the
138:instead of the current directory. Look up input files in
153:Enable the filename recorder. This leaves a trace of the files opened
161:construct. The
163:can be any Bourne shell command. By default, this construct is
178:expanded, not taken as part of the filename. Other programs, such as
183:Normally, Aleph puts its output files in the current directory. If
186:There is no default value for that variable. For example, if you say
195:if any output is produced.) TEXMFOUTPUT is also checked for input
207:that user files are found before system files. An empty path
210:file. For example, set TEXINPUTS to ".:/home/user/tex:" to prepend the
214:Command template for switching to editor. The default, usually
219:This manual page is not meant to be exhaustive. The complete
228:extent with the definition of Aleph. When such extensions are
235:dimensions are added or subtracted. Cases where this occurs are rare,
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':33
troff:<stdin>:33: warning: trailing space in the line
troff: backtrace: file '<stdin>':36
troff:<stdin>:36: warning: trailing space in the line
troff: backtrace: file '<stdin>':163
troff:<stdin>:163: warning: trailing space in the line
-.-
Bad use of \s0 in a string definition, the string "X" could be resized,
for example with "\s-1\*X\s0".
10:.if t .ds BX \fRB\s-2IB\s0\fP\*(TX
13:.if t .ds LX \fRL\\h'-0.36m'\\v'-0.15v'\s-2A\s0\\h'-0.15m'\\v'0.15v'\fP\*(TX
--- aleph.1 2024-11-26 20:45:01.650034137 +0000
+++ aleph.1.new 2024-11-26 21:12:41.753728319 +0000
@@ -7,10 +7,10 @@
.ie t .ds OX \fIT\v'+0.25m'E\v'-0.25m'X\fP
.el .ds OX TeX
.\" BX definition must follow TX so BX can use TX
-.if t .ds BX \fRB\s-2IB\s0\fP\*(TX
+.if t .ds BX \fRB\s-2IB\s+2\fP\*(TX
.if n .ds BX BibTeX
.\" LX definition must follow TX so LX can use TX
-.if t .ds LX \fRL\\h'-0.36m'\\v'-0.15v'\s-2A\s0\\h'-0.15m'\\v'0.15v'\fP\*(TX
+.if t .ds LX \fRL\\h'-0.36m'\\v'-0.15v'\s-2A\s+2\\h'-0.15m'\\v'0.15v'\fP\*(TX
.if n .ds LX LaTeX
.if t .ds AX \fRA\\h'-0.1667m'\\v'0.20v'M\\v'-0.20v'\\h'-0.125m'S\fP\*(TX
.if n .ds AX AmSTeX
@@ -30,16 +30,16 @@ Run the Aleph typesetter on
.IR file ,
usually creating
.IR file.dvi .
-If the file argument has no extension, ".tex" will be appended to it.
+If the file argument has no extension, ".tex" will be appended to it.
Instead of a filename, a set of Aleph commands can be given, the first
of which must start with a backslash.
-With a
+With a
.BI & format
argument Aleph uses a different set of precompiled commands,
contained in
.IR format\fB.fmt\fP ;
it is usually better to use the
-.B -fmt
+.B \-fmt
.I format
option instead.
.PP
@@ -53,17 +53,17 @@ Aleph is no longer being actively develo
activity.
.\"=====================================================================
.SH OPTIONS
-Run aleph --help to see the complete list of options; this is not
+Run aleph \-\-help to see the complete list of options; this is not
exhaustive.
.TP
-.BI -cnf-line \ string
+.BI \-cnf-line \ string
Parse
.I string
as a
.I texmf.cnf
configuration line. See the Kpathsea manual.
.TP
-.BI --fmt \ format
+.BI \-\-fmt \ format
Use
.I format
as the name of the format to be used, instead of the name by which
@@ -71,18 +71,18 @@ Aleph was called or a
.I %&
line.
.TP
-.B --halt-on-error
+.B \-\-halt-on-error
Exit with an error code when an error is encountered during processing.
.TP
-.B --help
+.B \-\-help
Print help message and exit.
.TP
-.B --ini
+.B \-\-ini
Be `initial' Aleph for dumping formats; this is implicitly true if the
program is called as
.BR inialeph .
.TP
-.BI --interaction \ mode
+.BI \-\-interaction \ mode
Sets the interaction mode. The mode can be one of
.IR batchmode ,
.IR nonstopmode ,
@@ -92,22 +92,22 @@ and
The meaning of these modes is the same as that of the corresponding
\ecommands.
.TP
-.B --ipc
+.B \-\-ipc
Send DVI output to a socket as well as the usual output file. Whether
this option is available is the choice of the installer.
.TP
-.B --ipc-start
+.B \-\-ipc-start
As
-.BR --ipc ,
+.BR \-\-ipc ,
and starts the server at the other end as well. Whether this option
is available is the choice of the installer.
.TP
-.BI --kpathsea-debug \ bitmask
+.BI \-\-kpathsea-debug \ bitmask
Sets path searching debugging flags according to the bitmask. See the
.I Kpathsea
manual for details.
.TP
-.BI --maketex \ fmt
+.BI \-\-maketex \ fmt
Enable
.RI mktex fmt ,
where
@@ -117,7 +117,7 @@ must be one of
or
.IR tfm .
.TP
-.BI --no-maketex \ fmt
+.BI \-\-no-maketex \ fmt
Disable
.RI mktex fmt ,
where
@@ -127,43 +127,43 @@ must be one of
or
.IR tfm .
.TP
-.BI --output-comment \ string
+.BI \-\-output-comment \ string
Use
.I string
for the DVI file comment instead of the date.
.TP
-.BI --output-directory \ directory
+.BI \-\-output-directory \ directory
Write output files in
.I directory
instead of the current directory. Look up input files in
.I directory
first, then along the normal search path.
.TP
-.B --parse-first-line
+.B \-\-parse-first-line
If the first line of the main input file begins with
.I %&
parse it to look for a dump name.
.TP
-.BI --progname \ name
+.BI \-\-progname \ name
Pretend to be program
.IR name .
This affects both the format used and the search paths.
.TP
-.B --recorder
+.B \-\-recorder
Enable the filename recorder. This leaves a trace of the files opened
for input and output in a file with extension
.IR .ofl .
(This option is always on.)
.TP
-.B --shell-escape
+.B \-\-shell-escape
Enable the
.BI \ewrite18{ command }
construct. The
.I command
-can be any Bourne shell command. By default, this construct is
+can be any Bourne shell command. By default, this construct is
enabled in a restricted mode, for security reasons.
.TP
-.B --version
+.B \-\-version
Print version information and exit.
.\"=====================================================================
.SH ENVIRONMENT
@@ -177,7 +177,6 @@ One caveat: In most Aleph formats, you c
give directly to Aleph, because ~ is an active character, and hence is
expanded, not taken as part of the filename. Other programs, such as
\*(MF, do not have this problem.
-.PP
.TP
.B TEXMFOUTPUT
Normally, Aleph puts its output files in the current directory. If
Reply to: