Bug#1088004: update-perl-sax-parsers.8: Some remarks and editorial changes for this man page
Bjarni Ingi Gislason
bjarniig at simnet.is
Thu Nov 21 19:42:56 GMT 2024
Package: libxml-sax-perl
Version: 1.02+dfsg-3
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>':91
troff:<stdin>:91: warning: trailing space in the line
troff: backtrace: file '<stdin>':103
troff:<stdin>:103: warning: trailing space in the line
troff: backtrace: file '<stdin>':125
troff:<stdin>:125: warning: trailing space in the line
troff: backtrace: file '<stdin>':135
troff:<stdin>:135: 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.7-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 libxml-sax-perl depends on:
ii libxml-namespacesupport-perl 1.12-2
ii libxml-sax-base-perl 1.09-3
ii perl 5.40.0-7
ii ucf 3.0043+nmu1
Versions of packages libxml-sax-perl recommends:
ii libwww-perl 6.77-1
ii libxml-sax-expat-perl 0.51-2
libxml-sax-perl suggests no packages.
-- no debconf information
-------------- next part --------------
Input file is update-perl-sax-parsers.8
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 update-perl-sax-parsers.8 ": (shortened list)
4 whitespace at end of input line
-.-.
Output from "test-groff -mandoc -t -ww -b -z update-perl-sax-parsers.8 ": (shortened list)
4 trailing space in the line
-.-.
Output from "mandoc -T lint update-perl-sax-parsers.8 ":
mandoc: update-perl-sax-parsers.8:91:40: STYLE: whitespace at end of input line
mandoc: update-perl-sax-parsers.8:103:12: STYLE: whitespace at end of input line
mandoc: update-perl-sax-parsers.8:125:29: STYLE: whitespace at end of input line
mandoc: update-perl-sax-parsers.8:135:9: 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".
91:This option was added in version 0.3 of
103:By default,
125:Starting with version 0.3 of
135:into the
-.-.
Change '-' (\-) to '\(en' (en-dash) for a numeric range.
GNU gnulib has recently (2023-06-18) updated its
"build_aux/update-copyright" to recognize "\(en" in man pages.
update-perl-sax-parsers.8:168:Copyright \(co 2001-2003 Ardo van Rangelrooij
-.-.
Change -- in x--y to \(em (em-dash), or, if an
option, to \-\-
20:.B --add
25:.B --remove
30:.B --update
44:.B --add
49:.B --remove
54:.B --update
63:.B --file
65:.B --ucf
68:.B --directory
70:.B --add
72:.B --remove
76:.B --update
81:.B --file
85:.B --priority XX
97:.B --directory
100:.B --ucf X
106:.B --file
111:.B --quiet
114:.B --test
117:.B --version
120:.B --help
133:.B --update
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
108:.IR not
136:.IR ParserDetails.ini
-.-.
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.
57:The modules will be listed in an order of ascending priority. See
64:option is used. See also the
88:to the filename of the ParserDetails.d entry. See the PARSER PRIORITIES
128:of the files in the ParserDetails.d directory. Specifically, the file
137:file. The last parser in the file, ie. the one with the highest priority,
-.-.
Test nr. 44:
The section part for a manual page is set in roman font.
61:.B ucf(1) ,
102:.B ucf(1) .
104:.B ucf(1)
-.-.
Two or more space charaters between printable characters
74:per-module Perl SAX parser module info file. When used one or more
78:generating the ParserDetails.ini file. Default is
82:Indicates the ParserDetails.ini file up be updated. Default is
87:removed. The priority will be encoded
173:later for copying conditions. There is
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":
troff: backtrace: file '<stdin>':91
troff:<stdin>:91: warning: trailing space in the line
troff: backtrace: file '<stdin>':103
troff:<stdin>:103: warning: trailing space in the line
troff: backtrace: file '<stdin>':125
troff:<stdin>:125: warning: trailing space in the line
troff: backtrace: file '<stdin>':135
troff:<stdin>:135: warning: trailing space in the line
-.-
Addittion:
Remove the word "removed" after "added" in paragraph for option '--priority XX'.
-------------- next part --------------
--- update-perl-sax-parsers.8 2024-11-21 19:04:36.629271144 +0000
+++ update-perl-sax-parsers.8.new 2024-11-21 19:34:59.140631299 +0000
@@ -17,17 +17,17 @@ update-perl-sax-parsers \- (de)register
.SH SYNOPSIS
.B update-perl-sax-parsers
.RI [ options ]
-.B --add
+.B \-\-add
.I parser_module
.PP
.B update-perl-sax-parsers
.RI [ options ]
-.B --remove
+.B \-\-remove
.I parser_module
.PP
.B update-perl-sax-parsers
.RI [ options ]
-.B --update
+.B \-\-update
.\"
.\" ----------------------------------------------------------------------
.SH DESCRIPTION
@@ -41,100 +41,106 @@ and the overall Perl SAX parser modules
.\" ----------------------------------------------------------------------
.SH OPTIONS
.TP
-.B --add
+.B \-\-add
Adds the per-module info file for the indicated Perl SAX parser module
to the directory
.IR /var/lib/libxml-sax-perl/ParserDetails.d .
.TP
-.B --remove
+.B \-\-remove
Removes the per-module info file for Perl SAX parser module from the
directory
.IR /var/lib/libxml-sax-perl/ParserDetails.d .
.TP
-.B --update
+.B \-\-update
updates the overall Perl SAX parser modules info file
.IR /etc/perl/XML/SAX/ParserDetails.ini .
-The modules will be listed in an order of ascending priority. See
-the PARSER PRIORITIES section below.
+The modules will be listed in an order of ascending priority.
+See the PARSER PRIORITIES section below.
The file will be managed with
-.B ucf(1) ,
+.BR ucf (1),
unless the
-.B --file
-option is used. See also the
-.B --ucf
+.B \-\-file
+option is used.
+See also the
+.B \-\-ucf
option below.
.TP
-.B --directory
+.B \-\-directory
When used with
-.B --add
+.B \-\-add
or with
-.B --remove
+.B \-\-remove
indicates the ParserDetails.d directory to use for storing the
-per-module Perl SAX parser module info file. When used one or more
-times with
-.B --update
+per-module Perl SAX parser module info file.
+When used one or more times with
+.B \-\-update
indicates the ParserDetails.d directories to be used as source for
-generating the ParserDetails.ini file. Default is
+generating the ParserDetails.ini file.
+Default is
.IR /var/lib/libxml-sax-perl/ParserDetails.d .
.TP
-.B --file
-Indicates the ParserDetails.ini file up be updated. Default is
+.B \-\-file
+Indicates the ParserDetails.ini file up be updated.
+Default is
.IR /etc/perl/XML/SAX/ParserDetails.ini .
.TP
-.B --priority XX
-Specifies the priority of the SAX parser module to be added
-removed. The priority will be encoded
-to the filename of the ParserDetails.d entry. See the PARSER PRIORITIES
-section below.
+.B \-\-priority XX
+Specifies the priority of the SAX parser module to be added.
+The priority will be encoded
+to the filename of the ParserDetails.d entry.
+See the PARSER PRIORITIES section below.
-This option was added in version 0.3 of
+This option was added in version 0.3 of
.B update-perl-sax-parsers .
Use the value "0" to disable the encoding and match the behaviour
of earlier versions of the script.
The default priority value is 50, unless
-.B --directory
+.B \-\-directory
was specified, in which case the default is 0 (disabled.)
.TP
-.B --ucf X
+.B \-\-ucf X
Forcibly enable (X != 0) or disable (X = 0) of
-.B ucf(1) .
-By default,
-.B ucf(1)
+.BR ucf (1).
+By default,
+.BR ucf (1)
will be used to manage the ParserDetails.ini file when
-.B --file
+.B \-\-file
is
-.IR not
+.I not
specified.
.TP
-.B --quiet
+.B \-\-quiet
Prevents any diagnostic output.
.TP
-.B --test
+.B \-\-test
Prevents the modification of any files and enables debugging mode.
.TP
-.B --version
+.B \-\-version
Displays the version information and exits.
.TP
-.B --help
+.B \-\-help
Display the usage information and exits.
.\"
.\" ----------------------------------------------------------------------
.SH PARSER PRIORITIES
-Starting with version 0.3 of
+Starting with version 0.3 of
.B update-perl-sax-parsers ,
the parsers are assigned a priority value that is encoded into the names
-of the files in the ParserDetails.d directory. Specifically, the file
-name will be "XX-Some::Module", where XX denotes the priority and Some::Module
-is the name of the parser module.
+of the files in the ParserDetails.d directory.
+Specifically,
+the file name will be "XX-Some::Module",
+where XX denotes the priority
+and Some::Module is the name of the parser module.
When
-.B --update
+.B \-\-update
is called, the parsers are listed in an order of ascending priority
-into the
-.IR ParserDetails.ini
-file. The last parser in the file, ie. the one with the highest priority,
+into the
+.I ParserDetails.ini
+file.
+The last parser in the file, ie. the one with the highest priority,
is the
.B default
XML::SAX parser.
@@ -165,12 +171,13 @@ Niko Tyni <ntyni at iki.fi>
.\"
.\" ----------------------------------------------------------------------
.SH COPYRIGHT
-Copyright \(co 2001-2003 Ardo van Rangelrooij
+Copyright \(co 2001\(en2003 Ardo van Rangelrooij
Copyright \(co 2007 Niko Tyni
.PP
This is free software; see the GNU General Public Licence version 2 or
-later for copying conditions. There is
+later for copying conditions.
+There is
.I no
warranty.
.\"
More information about the pkg-perl-maintainers
mailing list