Bug#1072319: ttf2pk.1: some remarks and editorial changes for this man page
Package: texlive-binaries
Version: 2023.20230311.66589-9+b2
Severity: minor
Tags: patch
Dear Maintainer,
* What led up to the situation?
Checking for defects with
[test-][g|n]roff -mandoc -t -K utf8 -ww -b -z <man page>
[test-groff is a script in the repository for "groff"]
* What was the outcome of this action?
troff: backtrace: file '<stdin>':76
troff:<stdin>:76: warning: trailing space in the line
troff: backtrace: '<stdin>':55: macro 'C'
<following is a bug in troff>
troff: backtrace: file '<stdin>':253
troff:<stdin>:253: warning: ignoring font selection on interrupted line
* What outcome did you expect instead?
No output (warnings).
-,-
Remarks and a patch are in the attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.7.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-binaries depends on:
ii libc6 2.38-11
ii libcairo2 1.18.0-3+b1
ii libfontconfig1 2.15.0-1.1
ii libfreetype6 2.13.2+dfsg-1+b4
ii libgcc-s1 14-20240330-1
ii libgraphite2-3 1.3.14-2
ii libharfbuzz0b 8.3.0-2+b1
ii libicu72 72.1-4+b1
ii libkpathsea6 2023.20230311.66589-9+b2
ii libmpfr6 4.2.1-1+b1
ii libpaper1 1.1.29+b1
ii libpixman-1-0 0.42.2-1+b1
ii libpng16-16t64 1.6.43-5
ii libpotrace0 1.16-2+b1
ii libptexenc1 2023.20230311.66589-9+b2
ii libstdc++6 14-20240330-1
ii libsynctex2 2023.20230311.66589-9+b2
ii libteckit0 2.5.12+ds1-1
ii libtexlua53-5 2023.20230311.66589-9+b2
ii libx11-6 2:1.8.7-1+b1
ii libxaw7 2:1.0.14-1+b2
ii libxi6 2:1.8.1-1
ii libxmu6 2:1.1.3-3+b2
ii libxpm4 1:3.5.17-1+b1
ii libxt6t64 1:1.2.1-1.2
ii libzzip-0-13t64 0.13.72+dfsg.1-1.2+b1
ii perl 5.38.2-4
ii t1utils 1.41-4
ii tex-common 6.18
ii zlib1g 1:1.3.dfsg+really1.3.1-1
Versions of packages texlive-binaries recommends:
pn dvisvgm <none>
ii texlive-base 2023.20240207-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 2023.20240207-1
-- no debconf information
Any program (person), that produces man pages, should check its content for
defects by using
groff -mandoc -t -ww -b -z [ -K utf8 | k ] <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' 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.
-.-
The difference between the formatted outputs can be seen with:
nroff -man <file1> > <out1>
nroff -man <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -man -Z - "
instead of "nroff -man"
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 -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint ttf2pk.1": (possibly shortened list)
mandoc: ttf2pk.1:76:69: STYLE: whitespace at end of input line
-.-.
Lines containing '\c':
95:Use only `\c
97:as the extension instead of `\c
98:.C \&. \c
99:.RI < \%resolution >\c
128:and the used file search library (e.g.\ \c
183:in map files\(em\c
236:with `\c
237:.BI \-r \ old-glyphname\ new-glyphname\c
239:are directly specified with `\c
251:For a description of subfonts (i.e., entries of the form `\c
252:.I <namestem>\c
253:.C @\c
254:.I <sfd-filename>\c
Remove space characters at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
76:CJKV (Chinese/Japanese/Korean/old Vietnamese) subfonts as created by
-.-.
Mark a full stop (.) and the exclamation mark (!) with "\&",
if it does not mean an end of a sentence.
This is a preventive action,
the paragraph could be reshaped, e.g., after changes.
When typing, one does not always notice when the line wraps after the
period.
There are too many examples of input lines in manual pages,
that end with an abbreviation point.
This marking is robust, and independent of the position on the line.
It corresponds to "\ " in TeX, and to "@:" in Texinfo.
98:.C \&. \c
-.-.
Add a (no-break, "\ " or "\~") space between a number and a unit,
as these are not one entity.
81:always assumes 10pt as the design size for the written \*(TX
123:The design size is always assumed to be 10pt.
-.-.
Use "\e" to print the escape character instead of "\\" (which gets
interpreted in copy mode).
273:You can use `\\' as the final character of a line to indicate that the
-.-.
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.
191:.C "ttf2tfm arial -p T1.enc -s 0.25 -P 1 -E 0 arials"
-.-.
Do not use "\s0" in a string definition but an absolute number,
as the size of the string could be changed.
Then a situation of "\s+X...\s+Y...\s0...\s0" could emerge.
Type size changes have an effect in "groff", but not in "nroff".
38:.ds LX \fRL\h'-0.36m'\v'-0.15v'\s-3A\s0\h'-0.15m'\v'0.15v'\fP\*(TX
-.-.
Output from "test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -K utf8 -t -ww -z -K utf8":
troff: backtrace: file '<stdin>':76
troff:<stdin>:76: warning: trailing space in the line
troff: backtrace: '<stdin>':55: macro 'C'
troff: backtrace: file '<stdin>':253
troff:<stdin>:253: warning: ignoring font selection on interrupted line
Bad use of \s0 in a string definition, the string could be resized.
38:.ds LX \fRL\h'-0.36m'\v'-0.15v'\s-3A\s0\h'-0.15m'\v'0.15v'\fP\*(TX
39:.el .ds LX \fRL\h'-0.36m'\v'-0.22v'\s-2A\s0\h'-0.15m'\v'0.22v'\fP\*(TX
--- ttf2pk.1 2024-05-31 13:36:36.686567085 +0000
+++ ttf2pk.1.new 2024-05-31 22:32:34.572210190 +0000
@@ -35,8 +35,8 @@ ttf2pk \- convert a TrueType font into T
.\" and here the same for \LaTeX
.if t \{\
.ie '\*(.T'dvi' \
-.ds LX \fRL\h'-0.36m'\v'-0.15v'\s-3A\s0\h'-0.15m'\v'0.15v'\fP\*(TX
-.el .ds LX \fRL\h'-0.36m'\v'-0.22v'\s-2A\s0\h'-0.15m'\v'0.22v'\fP\*(TX
+.ds LX \fRL\h'-0.36m'\v'-0.15v'\s-3A\s+3\h'-0.15m'\v'0.15v'\fP\*(TX
+.el .ds LX \fRL\h'-0.36m'\v'-0.22v'\s-2A\s+2\h'-0.15m'\v'0.22v'\fP\*(TX
.\}
.if n .ds LX LaTeX
.
@@ -52,7 +52,7 @@ ttf2pk \- convert a TrueType font into T
.\" a typewriter font
.if t \{\
.de C
-\fC\\$1\fP\\$2
+\f(CR\\$1\fP\\$2
..
.\}
.if n \{\
@@ -73,12 +73,12 @@ This program converts a TrueType font in
file; the created font can then be used with \*(TX
or \*(LX.
.PP
-CJKV (Chinese/Japanese/Korean/old Vietnamese) subfonts as created by
+CJKV (Chinese/Japanese/Korean/old Vietnamese) subfonts as created by
.B ttf2tfm
are also supported.
.PP
.B ttf2pk
-always assumes 10pt as the design size for the written \*(TX
+always assumes 10\~points (10pt) as the design size for the written \*(TX
font.
.
.
@@ -120,7 +120,7 @@ to process the font.
The resolution, given in dots per inch.
Currently the horizontal resolution is equal to the vertical
resolution.
-The design size is always assumed to be 10pt.
+The design size is always assumed to be 10\~points (10pt).
.TP
.B \-\^\-version
Shows the current version of
@@ -188,7 +188,7 @@ map file.
As an example, a call to
.PP
.in +2m
-.C "ttf2tfm arial -p T1.enc -s 0.25 -P 1 -E 0 arials"
+.C "ttf2tfm arial \-p T1.enc \-s 0.25 \-P 1 \-E 0 arials"
.PP
will produce the following line:
.PP
@@ -209,27 +209,27 @@ parameters and the corresponding entries
.PP
.in +4m
.ta 2i
--s Slant
+\-s Slant
.br
--e Extend
+\-e Extend
.br
--p Encoding
+\-p Encoding
.br
--f Fontindex
+\-f Fontindex
.br
--P Pid
+\-P Pid
.br
--E Eid
+\-E Eid
.br
--n PS=Yes
+\-n PS=Yes
.br
--N PS=Only
+\-N PS=Only
.br
--R Replacement
+\-R Replacement
.br
--x Rotate=Yes
+\-x Rotate=Yes
.br
--y Y-Offset
+\-y Y-Offset
.PP
Single replacement glyph names given to
.B ttf2tfm
@@ -243,7 +243,7 @@ They will be ignored if in subfont mode
One additional parameter in a map file is unique to
.BR ttf2pk :
`Hinting', which can take the values `On' or `Off'.
-Some fonts (e.g.\ the CJK part of
+Some fonts (e.g., the CJK part of
.C \%cyberbit.ttf )
are rendered incorrectly if hinting is activated.
Default is `On' (you can also use `Yes', `No', `1', and `0').
@@ -270,7 +270,7 @@ command line is found, otherwise the pro
Thus you can use any character invalid in a \*(TX
font name to start a comment line.
.PP
-You can use `\\' as the final character of a line to indicate that the
+You can use `\e' as the final character of a line to indicate that the
input is continued on the next line.
The backslash and the following newline character will be removed.
.PP
Reply to: