Bug#1099696: etex.1: Some remarks and a patch with editorial changes for this man page
Package: texlive-base
Version: 2024.20250114-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 ' $' -e '\\~$' <file>" to find obvious 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:<stdin>:38: warning: trailing space in the line
troff:<stdin>:41: warning: trailing space in the line
troff:<stdin>:347: 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".
4:.if t .ds MF M\s-2ETAFONT\s0
8:.if t .ds MF M\s-2ETAFONT\s0
13:.if t .ds BX \fRB\s-2IB\s0\fP\*(TX
16:.if t .ds LX \fRL\\h'-0.36m'\\v'-0.15v'\s-2A\s0\\h'-0.15m'\\v'0.15v'\fP\*(TX
23:.if t .ds WB W\s-2EB\s0
* 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.12-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-base depends on:
ii debconf [debconf-2.0] 1.5.89
ii libpaper-utils 2.2.5-0.3+b1
ii sensible-utils 0.0.24
ii tex-common 6.19
ii texlive-binaries 2024.20240313.70630+ds-5+b1
ii ucf 3.0050
ii xdg-utils 1.2.1-2
Versions of packages texlive-base recommends:
ii lmodern 2.005-1
Versions of packages texlive-base suggests:
ii ghostscript [postscript-viewer] 10.04.0~dfsg-2+b1
ii gv [postscript-viewer] 1:3.7.4-2+b2
ii mupdf [pdf-viewer] 1.25.1+ds1-5+b2
pn perl-tk <none>
ii xpdf [pdf-viewer] 3.04+git20250103-1+b1
pn xzdec <none>
Versions of packages tex-common depends on:
ii ucf 3.0050
Versions of packages tex-common suggests:
pn debhelper <none>
Versions of packages texlive-base is related to:
ii tex-common 6.19
ii texlive-binaries 2024.20240313.70630+ds-5+b1
-- debconf information excluded
Input file is etex.1
Output from "mandoc -T lint etex.1": (shortened list)
Remove trailing space with: sed -e 's/ *$//'
1 skipping paragraph macro: PP empty
3 whitespace at end of input line
-.-.
Output from "test-nroff -mandoc -t -ww -z etex.1": (shortened list)
Remove trailing space with: sed -e 's/ *$//'
3 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
3
-.-.
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.
47:.B -fmt
76:.BI -fmt \ format
84:.B -enc
87:.BR -ini .
91:.B -etex
94:.BR -ini .
96:.B -file-line-error
101:.B -no-file-line-error
106:.B -file-line-error-style
108:.B -file-line-error
111:.B -halt-on-error
114:.B -help
117:.B -ini
125:.BI -interaction \ mode
135:.B -ipc
139:.B -ipc-start
141:.BR -ipc ,
145:.BI -jobname \ name
150:.BI -kpathsea-debug \ bitmask
155:.BI -mktex \ fmt
165:.B -mltex
167:.BR -ini .
169:.BI -no-mktex \ fmt
179:.BI -output-comment \ string
186:.BI -output-directory \ directory
193:.B -parse-first-line
197:.B -translate-file
200:.B -no-parse-first-line
203:.BI -progname \ name
208:.B -recorder
213:.B -shell-escape
221:.B -no-shell-escape
228:.B -src-specials
233:.BI -src-specials \ where
248:.BI -translate-file \ tcxname
254:.BI -default-translate-file \ tcxname
256:.B -translate-file
261:.B -version
-.-.
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 "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.
Use
#!/usr/bin/sh
sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\. */\1.\n/g' $1
to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"
[List of affected lines removed.]
-.-.
Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".
[List of affected lines removed.]
etex.1:62:several new primitives are added that facilitate (among other things)
etex.1:292:read; for input, no suffixes (such as ``.tex'') are added by default,
etex.1:342:Predigested e-\*(TX format (.\|fmt) files.
-.-.
Space after an end of sentence.
[List of affected lines removed.]
-.-
Put a subordinate sentence (after a comma) on a new line.
[List of affected lines removed.]
Section headings (.SH and .SS) do not need quoting their arguments.
369:.SH "SEE ALSO"
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z ":
troff:<stdin>:38: warning: trailing space in the line
troff:<stdin>:41: warning: trailing space in the line
troff:<stdin>:347: 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".
4:.if t .ds MF M\s-2ETAFONT\s0
8:.if t .ds MF M\s-2ETAFONT\s0
13:.if t .ds BX \fRB\s-2IB\s0\fP\*(TX
16:.if t .ds LX \fRL\\h'-0.36m'\\v'-0.15v'\s-2A\s0\\h'-0.15m'\\v'0.15v'\fP\*(TX
23:.if t .ds WB W\s-2EB\s0
-.-.
Spelling
Codespell:
direcory ==> directory
interchangable ==> interchangeable
-.-
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- etex.1 2025-03-06 21:04:41.869856197 +0000
+++ etex.1.new 2025-03-06 21:30:07.962419783 +0000
@@ -1,26 +1,26 @@
.TH ETEX 1 "1 March 2011" "Web2C 2015"
.\"=====================================================================
.if n .ds MF Metafont
-.if t .ds MF M\s-2ETAFONT\s0
+.if t .ds MF M\s-2ETAFONT\s+2
.if t .ds TX \fRT\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X\fP
.if n .ds TX TeX
.if n .ds MF Metafont
-.if t .ds MF M\s-2ETAFONT\s0
+.if t .ds MF M\s-2ETAFONT\s+2
.ie t .ds OX \fIT\v'+0.25m'E\v'-0.25m'X\fP for troff
.el .ds OX TeX for nroff
.\" the same but obliqued
.\" 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
.if t .ds AY \fRA\\h'-0.1667m'\\v'0.20v'M\\v'-0.20v'\\h'-0.125m'S\fP\*(LX
.if n .ds AY AmSLaTeX
.if n .ds WB Web
-.if t .ds WB W\s-2EB\s0
+.if t .ds WB W\s-2EB\s+2
.\"=====================================================================
.SH NAME
etex \- extended (plain) TeX
@@ -35,16 +35,16 @@ Run the e-\*(TX typesetter on
.IR file ,
by default 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 e-\*(TX commands can be given, the first
of which must start with a backslash.
-With a
+With a
.BI & format
argument e-\*(TX 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
@@ -56,7 +56,7 @@ respecting Knuth's wish that \*(TX shoul
.PP
e-\*(TX can be used in two different modes: in
.I compatibility mode
-it is supposed to be completely interchangable with standard \*(TX.
+it is supposed to be completely interchangeable with standard \*(TX.
In
.I extended mode
several new primitives are added that facilitate (among other things)
@@ -73,7 +73,7 @@ implementation.
.SH OPTIONS
This version of e-\*(TX understands the following command line options.
.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
@@ -81,40 +81,40 @@ e-\*(TX was called or a
.I %&
line.
.TP
-.B -enc
+.B \-enc
Enable the enc\*(TX extensions. This option is only effective in
combination with
-.BR -ini .
+.BR \-ini .
For documentation of the enc\*(TX extensions see
.BR http://www.olsak.net/enctex.html .
.TP
-.B -etex
+.B \-etex
Enable the e-\*(TX extensions. This option is only effective in
combination with
-.BR -ini .
+.BR \-ini .
.TP
-.B -file-line-error
+.B \-file-line-error
Print error messages in the form
.I file:line:error
which is similar to the way many compilers format them.
.TP
-.B -no-file-line-error
+.B \-no-file-line-error
Disable printing error messages in the
.I file:line:error
style.
.TP
-.B -file-line-error-style
+.B \-file-line-error-style
This is the old name of the
-.B -file-line-error
+.B \-file-line-error
option.
.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
Start in
.I INI
mode, which is used to dump formats. The
@@ -122,7 +122,7 @@ mode, which is used to dump formats. Th
mode can be used for typesetting, but no format is preloaded, and
basic initializations like setting catcodes may be required.
.TP
-.BI -interaction \ mode
+.BI \-interaction \ mode
Sets the interaction mode. The mode can be either
.IR batchmode ,
.IR nonstopmode ,
@@ -132,27 +132,27 @@ 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 -jobname \ name
+.BI \-jobname \ name
Use
.I name
for the job name, instead of deriving it from the name of the input file.
.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 -mktex \ fmt
+.BI \-mktex \ fmt
Enable
.RI mktex fmt ,
where
@@ -162,11 +162,11 @@ must be either
or
.IR tfm .
.TP
-.B -mltex
+.B \-mltex
Enable ML\*(TX extensions. Only effective in combination with
-.BR -ini .
+.BR \-ini .
.TP
-.BI -no-mktex \ fmt
+.BI \-no-mktex \ fmt
Disable
.RI mktex fmt ,
where
@@ -176,41 +176,41 @@ must be either
or
.IR tfm .
.TP
-.BI -output-comment \ string
+.BI \-output-comment \ string
Use
.I string
for the
.I 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, the 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 or a
-.B -translate-file
+.B \-translate-file
option.
.TP
-.B -no-parse-first-line
+.B \-no-parse-first-line
Disable parsing of the first line of the main input file.
.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 .fls .
.TP
-.B -shell-escape
+.B \-shell-escape
Enable the
.BI \ewrite18{ command }
construct. The
@@ -218,19 +218,19 @@ construct. The
can be any shell command. This construct is normally
disallowed for security reasons.
.TP
-.B -no-shell-escape
+.B \-no-shell-escape
Disable the
.BI \ewrite18{ command }
construct, even if it is enabled in the
.I texmf.cnf
file.
.TP
-.B -src-specials
+.B \-src-specials
Insert source specials into the
.I DVI
file.
.TP
-.BI -src-specials \ where
+.BI \-src-specials \ where
Insert source specials in certain placed of the
.I DVI
file.
@@ -245,20 +245,20 @@ is a comma-separated value list:
or
.IR vbox .
.TP
-.BI -translate-file \ tcxname
+.BI \-translate-file \ tcxname
Use the
.I tcxname
translation table to set the mapping of input characters and
re-mapping of output characters.
.TP
-.BI -default-translate-file \ tcxname
+.BI \-default-translate-file \ tcxname
Like
-.B -translate-file
+.B \-translate-file
except that a
.I %&
line can overrule this setting.
.TP
-.B -version
+.B \-version
Print version information and exit.
.\"=====================================================================
.SH ENVIRONMENT
@@ -272,7 +272,6 @@ One caveat: In most e-\*(TX formats, you
give directly to e-\*(TX, 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, e-\*(TX puts its output files in the current directory. If
@@ -303,7 +302,7 @@ that user files are found before system
component will be replaced with the paths defined in the
.I texmf.cnf
file. For example, set TEXINPUTS to ".:/home/user/tex:" to prepend the
-current direcory and ``/home/user/tex'' to the standard search path.
+current directory and ``/home/user/tex'' to the standard search path.
.TP
.B TEXFORMATS
Search path for format files.
@@ -344,7 +343,7 @@ Predigested e-\*(TX format (.\|fmt) file
.SH NOTES
Starting with version 1.40, pdf\*(TX incorporates the e-\*(TX
extensions, so in this installation e\*(TX may be just a symbolic link to
-pdf\*(TX. See
+pdf\*(TX. See
.BR pdftex (1).
This manual page is not meant to be exhaustive. The complete
documentation for this version of e-\*(TX can be found in the info
@@ -366,7 +365,7 @@ but when it does the generated
.I DVI
file will be invalid.
.\"=====================================================================
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR pdftex (1),
.BR tex (1),
.BR mf (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
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
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 -d -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 from 'diff -d -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)
-.-
Reply to: