Bug#1093311: texdoctk.1: Some remarks and a patch with editorial changes for this man page
Package: texlive-base
Version: 2024.20241115-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 ' $' <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?
an.tmac:<stdin>:1: style: .TH missing third argument; consider document modification date in ISO 8601 format (YYYY-MM-DD)
an.tmac:<stdin>:1: style: .TH missing fourth argument; consider package/project name and version (e.g., "groff 1.23.0")
troff:<stdin>:110: 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.12.9-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
ii sensible-utils 0.0.24
ii tex-common 6.18
ii texlive-binaries 2024.20240313.70630+ds-5+b1
ii ucf 3.0046
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.24.10+ds1-1
pn perl-tk <none>
ii xpdf [pdf-viewer] 3.04+git20240613-1+b2
pn xzdec <none>
Versions of packages tex-common depends on:
ii ucf 3.0046
Versions of packages tex-common suggests:
pn debhelper <none>
Versions of packages texlive-base is related to:
ii tex-common 6.18
ii texlive-binaries 2024.20240313.70630+ds-5+b1
-- debconf information excluded
Input file is texdoctk.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
-.-
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 texdoctk.1": (shortened list)
6 input text line longer than 80 bytes
1 missing date, using ""
3 skipping paragraph macro
1 whitespace at end of input line
-.-.
Output from "test-groff -mandoc -t -ww -z texdoctk.1": (shortened list)
1 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
1
-.-.
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.
texdoctk.1:214:Copyright (C) 2000-2004 Thomas Ruedas
-.-.
Use "\e" to print the escape character instead of "\\" (which gets
interpreted in copy mode).
167:at end, behind \\endinput; some .sty files have well-organized documentation
-.-.
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.
6:-[aq]
59:toggle verbose mode (see option -v); default is off.
62:if a listbox contains only one item (see option -a)
-.-.
Find a repeated word
! 136 --> the
-.-.
Add a comma (or \&) after "e.g." and "i.e.", or use English words
(man-pages(7)).
Abbreviation points should be protected against being interpreted as
an end of sentence, if they are not, and that independent of the
current place on the line.
23:default, so a redirect is needed, e.g.
65:i.e. treat the file as plain text. \fBtexdoctk\fP should recognize the usual file
95:file but to stdout by default, so a redirect is needed, e.g.
200:font; this will become visible e.g. at hi-res screens, where the label font is
-.-.
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 "\&".
N.B.
The number of lines affected can be too large to be in a patch.
11:different derivatives (mainly LaTeX). It is optimized and included in
21:converter menus for switching on/off output redirect. This is due to the fact
30:as well as some warning popup windows. This can also be set in a
35:frequently happen in search results). This can also be set in a configuration
46:for the duration of the program call or as new defaults. The latter case is
48:~/.texdocrc file. The system defaults cannot be edited with the Settings
65:i.e. treat the file as plain text. \fBtexdoctk\fP should recognize the usual file
67:freely invented names. Default is on; if switched off, trying to view such
68:files will raise an error. The switch does not influence printing: unrecognized
75:For text files, \fBtexdoctk\fP provides an own viewer. If this viewer is disabled,
80:non-PS files into PostScript. Here are some suggestions:
100:text editor. The optional user configuration file is ~/.texdocrc and can
102:whole. The preferred way of changing it is through the Settings menu.
105:with a special format. It is divided into 17 sections corresponding to the
106:17 buttons that are active by default. Each section begins with a line
112:is the text as it appears in the button. This title is
116:\fIpackage-label\fP;Short description for listbox (opt. \fIpackage-name\fP);path in doc directory;optional keywords
118:(without breaking the line!). Comments (initiated with a #) and empty lines
119:are ignored by the program. The second field is the text displayed in the
127:tree. The corresponding documentation can be made accessible by an additional
128:database $TEXMFLOCAL/texdoctk/texdoctk-local.dat. Furthermore, individual
131:$TEXMFHOME/texdoctk/texdoctk-pers.dat. After creating such files, texhash
136:additional entries. For example, if the the package
148:will then be appended to the list of entries in the Graphics category. The 18th
152:button active with that label. Note that you cannot have more than 18
158:-?- directly after the semicolon, where ? is 0, 1, 2 or 3; these are flags
200:font; this will become visible e.g. at hi-res screens, where the label font is
210:the Debian GNU/Linux system (but may be used by others). It is now maintained
216:This is free software; see the source for copying conditions. There is NO
-.-.
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.
Line 116, length 115
\fIpackage-label\fP;Short description for listbox (opt. \fIpackage-name\fP);path in doc directory;optional keywords
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z ":
an.tmac:<stdin>:1: style: .TH missing third argument; consider document modification date in ISO 8601 format (YYYY-MM-DD)
an.tmac:<stdin>:1: style: .TH missing fourth argument; consider package/project name and version (e.g., "groff 1.23.0")
troff:<stdin>:110: warning: trailing space in the line
-.-
Additionally
Typeset options in chanpter OPTIONS in bold, not italic.
See man-pages(7).
--- texdoctk.1 2025-01-17 15:42:47.986385971 +0000
+++ texdoctk.1.new 2025-01-17 16:05:48.228518592 +0000
@@ -3,7 +3,7 @@
texdoctk \- GUI for easier access of TeX package and program documentations
.SH SYNOPSIS
.B texdoctk
--[aq]
+\-[aq]
.SH "DESCRIPTION"
.B texdoctk
is a GUI for easier access to a large part of the vast amount
@@ -20,28 +20,26 @@ below).
In the settings window you see a checkbox in the html->ps and text->ps
converter menus for switching on/off output redirect. This is due to the fact
that some converters do not write their output into a file but to stdout by
-default, so a redirect is needed, e.g.
+default, so a redirect is needed, e.g.,
.PP
a2ps myfile.txt >myfile.ps
.SH "OPTIONS"
.TP
-.I "\-v"
+.B "\-v"
verbose: enable some viewer messages which are otherwise sent to stderr,
as well as some warning popup windows. This can also be set in a
configuration file.
.TP
-.I "\-a"
+.B "\-a"
autoview: autostart viewer if a listbox contains only one item (this will
frequently happen in search results). This can also be set in a configuration
file.
.SH "CONFIGURATION"
-.PP
The configuration is controlled by the system default configuration file
($TEXMFMAIN)/texdoctk/texdocrc.defaults, most of whose entries can though be
overridden by the users' own optional ~/.texdocrc files and/or command line
options.
.SS The Settings menu and configuration files
-.PP
The Settings menu is used to change the user-definable settings of \fBtexdoctk\fP
for the duration of the program call or as new defaults. The latter case is
the purpose of the Save button, which generates or rewrites the user's own
@@ -56,13 +54,13 @@ stored.
General viewer behaviour
.I Suppress error messages
-toggle verbose mode (see option -v); default is off.
+toggle verbose mode (see option \-v); default is off.
.I Autostart viewer for one-item listboxes
-if a listbox contains only one item (see option -a)
+if a listbox contains only one item (see option \-a)
.I Use text viewer for unknown file format
-i.e. treat the file as plain text. \fBtexdoctk\fP should recognize the usual file
+i.e., treat the file as plain text. \fBtexdoctk\fP should recognize the usual file
formats and also relate names like README to plain text, but some docs may have
freely invented names. Default is on; if switched off, trying to view such
files will raise an error. The switch does not influence printing: unrecognized
@@ -92,7 +90,7 @@ Acrobat Reader (http://www.adobe.com)
The html->ps and text->ps converter menus for switching on/off output redirect.
This is due to the fact that some converters do not write their output into a
-file but to stdout by default, so a redirect is needed, e.g.
+file but to stdout by default, so a redirect is needed, e.g.,
.B a2ps myfile.txt >myfile.ps
.PP
The system-wide configuration file is ($TEXMFMAIN)/texdoctk/texdocrc.defaults
@@ -107,13 +105,14 @@ with a special format. It is divided int
@\fIsection_name\fP
-where
+where
.I section_name
is the text as it appears in the button. This title is
followed by the descriptive entries for each documentation, which have this
format:
-\fIpackage-label\fP;Short description for listbox (opt. \fIpackage-name\fP);path in doc directory;optional keywords
+\fIpackage-label\fP;Short description for listbox (opt.
+\fIpackage-name\fP);path in doc directory;optional keywords
(without breaking the line!). Comments (initiated with a #) and empty lines
are ignored by the program. The second field is the text displayed in the
@@ -133,7 +132,7 @@ must be executed.
.PP
Both types of databases must have the same structure as the system database,
although they need (and should) not include all its sections if there are no
-additional entries. For example, if the the package
+additional entries. For example, if the package
.I foo
is added to the local tree such that its documentation file is
($TEXMFLOCAL)/doc/latex/foo/foo.dvi and it is decided that it fits best into
@@ -164,7 +163,7 @@ it without the code, which would normall
no specific place, scattered between the code
.TP
1
-at end, behind \\endinput; some .sty files have well-organized documentation
+at end, behind \eendinput; some .sty files have well-organized documentation
behind the end of the actual code, where TeX doesn't see it upon compilation
.TP
2
@@ -177,7 +176,6 @@ as 2, but with a blank line as terminati
See the system database for plenty of examples.
.SH "FILES"
-.PP
\& $TEXMFMAIN/texdoctk/texdocrc.defaults
system-wide configuration file
.PP
@@ -197,7 +195,7 @@ Widget placement in topic toplevels beco
or shrunk.
.PP
The font in the frame labels of the Settings menu are not forced to the default
-font; this will become visible e.g. at hi-res screens, where the label font is
+font; this will become visible e.g., at hi-res screens, where the label font is
not scaled up.
.PP
Netscape and Mozilla error output will be written to stderr even if the quiet
@@ -211,7 +209,7 @@ the Debian GNU/Linux system (but may be
by Thomas Ruedas.
.SH COPYRIGHT
-Copyright (C) 2000-2004 Thomas Ruedas
+Copyright (C) 2000\(en2004 Thomas Ruedas
.br
This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Reply to: