Bug#1072254: tex2aspc.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>':6
troff:<stdin>:6: warning: trailing space in the line
troff: backtrace: file '<stdin>':21
troff:<stdin>:21: warning: trailing space in the line
troff: backtrace: file '<stdin>':23
troff:<stdin>:23: warning: trailing space in the line
troff: backtrace: file '<stdin>':27
troff:<stdin>:27: warning: trailing space in the line
troff: backtrace: file '<stdin>':28
troff:<stdin>:28: warning: trailing space in the line
troff: backtrace: file '<stdin>':30
troff:<stdin>:30: warning: ignoring escape character before 'T'
* 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 tex2aspc.1": (possibly shortened list)
mandoc: tex2aspc.1:6:66: STYLE: whitespace at end of input line
mandoc: tex2aspc.1:12:13: STYLE: whitespace at end of input line
mandoc: tex2aspc.1:21:52: STYLE: whitespace at end of input line
mandoc: tex2aspc.1:23:13: STYLE: whitespace at end of input line
mandoc: tex2aspc.1:27:9: STYLE: whitespace at end of input line
mandoc: tex2aspc.1:28:17: STYLE: whitespace at end of input line
mandoc: tex2aspc.1:30:42: WARNING: undefined escape, printing literally: \T
mandoc: tex2aspc.1:36:112: STYLE: input text line longer than 80 bytes: assumes that & and |...
mandoc: tex2aspc.1:42:4: STYLE: whitespace at end of input line
mandoc: tex2aspc.1:45:12: STYLE: whitespace at end of input line
-.-.
Remove space characters at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
6:tex2aspc \- converts conventional MusiXTeX scores to .aspc format
12:.B tex2aspc
21:This program re-factors (sequences of) conventional
23:in a measure
27:features
28:only provided by
42:.PP
45:.SH AUTHOR
-.-.
Use "\e" to print the escape character instead of "\\" (which gets
interpreted in copy mode).
22:note-spacing commands (\\notes \\Notes \\NOtes ...)
25:a single \\anotes command.
36:assumes that & and | (rather than \\nextinstrument and \\nextstaff) are used to separate instruments and staffs.
-.-.
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.
tex2aspc.1: line 36 length 112
assumes that & and | (rather than \\nextinstrument and \\nextstaff) are used to separate instruments and staffs.
-.-.
Output from "test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -K utf8 -t -ww -z -K utf8":
troff: backtrace: file '<stdin>':6
troff:<stdin>:6: warning: trailing space in the line
troff: backtrace: file '<stdin>':21
troff:<stdin>:21: warning: trailing space in the line
troff: backtrace: file '<stdin>':23
troff:<stdin>:23: warning: trailing space in the line
troff: backtrace: file '<stdin>':27
troff:<stdin>:27: warning: trailing space in the line
troff: backtrace: file '<stdin>':28
troff:<stdin>:28: warning: trailing space in the line
troff: backtrace: file '<stdin>':30
troff:<stdin>:30: warning: ignoring escape character before 'T'
--- tex2aspc.1 2024-05-31 00:36:37.067135796 +0000
+++ tex2aspc.1.new 2024-05-31 00:42:03.778851779 +0000
@@ -1,48 +1,43 @@
.\" This manpage is licensed under the GNU Public License
.TH TEX2ASPC 1 2018-02-14 "" ""
-
+.
.SH NAME
-
-tex2aspc \- converts conventional MusiXTeX scores to .aspc format
+tex2aspc \- converts conventional MusiXTeX scores to .aspc format
for processing by
.BR autosp (1).
-
+.
.SH SYNOPSIS
-
-.B tex2aspc
-.RB [ \-v\ |\ \-\-version\ |\ \-h\ |\ \-\-help ]
-
.B tex2aspc
-.IR infile [\fR.tex\fP]
-.RI [ outfile [ \fR.aspc\fP ]]
+.\".RB [ \-v\ |\ \-\-version\ |\ \-h\ |\ \-\-help ]
+.RB [ \-v " | " \-\-version " | " \-h " | " \-\-help ]
+.B tex2aspc
+.IR infile [ \fB.tex\fP ]
+.RI [ outfile [ \fB.aspc\fP ]]
+.
.SH DESCRIPTION
-
-This program re-factors (sequences of) conventional
-note-spacing commands (\\notes \\Notes \\NOtes ...)
-in a measure
+This program re-factors (sequences of) conventional
+note-spacing commands (\enotes \eNotes \eNOtes ...\&)
+in a measure
into
-a single \\anotes command.
+a single \eanotes command.
This is intended for "legacy" scores in order to take advantage of
-features
-only provided by
+features
+only provided by
.BR autosp (1),
-such as "global" skips and processing of \TransformNotes commands.
-
+such as "global" skips and processing of TransformNotes commands.
+.
.SH LIMITATIONS
-
-
.B tex2aspc
-assumes that & and | (rather than \\nextinstrument and \\nextstaff) are used to separate instruments and staffs.
+assumes that & and | (rather than \enextinstrument and \enextstaff) are used
+to separate instruments and staffs.
User-defined macros are not processed or expanded.
-
+.
.SH SEE ALSO
.BR autosp (1)
-.PP
+.PP
musixdoc.pdf
-
-.SH AUTHOR
+.
+.SH AUTHOR
This program and manual page were written by Bob Tennent <rdt@cs.queensu.ca>.
-
-
Reply to: