[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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: