Bug#1091655: pamphletangler.1: Some remarks and a patch with editorial changes for this man page
Package: texlive-extra-utils
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?
troff:<stdin>:183: warning: font name 'CW' is deprecated
* 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.6-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-extra-utils depends on:
ii libfile-homedir-perl 1.006-2
ii libunicode-linebreak-perl 0.0.20190101-1+b8
ii libyaml-tiny-perl 1.76-1
ii python3 3.12.8-1
ii tex-common 6.18
ii texlive-base 2024.20241115-1
ii texlive-binaries 2024.20240313.70630+ds-5+b1
ii texlive-latex-base 2024.20241115-1
ii texlive-luatex 2024.20241115-1
ii texlive-plain-generic 2024.20241115-1
Versions of packages texlive-extra-utils recommends:
ii ghostscript 10.04.0~dfsg-2+b1
pn liblog-log4perl-perl <none>
ii ruby 1:3.1+nmu1
ii texlive-latex-recommended 2024.20241115-1
Versions of packages texlive-extra-utils suggests:
pn chktex <none>
pn default-jre-headless <none>
pn dvidvi <none>
pn dvipng <none>
pn fragmaster <none>
pn lacheck <none>
pn latexdiff <none>
pn latexmk <none>
pn purifyeps <none>
pn xindy <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-extra-utils is related to:
ii tex-common 6.18
ii texlive-binaries 2024.20240313.70630+ds-5+b1
-- no debconf information
Input file is pamphletangler.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 pamphletangler.1": (shortened list)
2 input text line longer than 80 bytes
-.-.
Output from "test-groff -mandoc -t -ww -z pamphletangler.1": (shortened list)
1 font name 'CW' is deprecated
-.-.
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 abbreviation point as such by suffixing them with "\&".
150:can be compiled regularly. This file contains documentation and source code
151:(just like in other forms of literate programming). This code snippets are
154:\&'getchunk' command (which will be typesetted acordingly). Finally, you run your
161:inside \*(L"changetext\*(R" for the line number. This is used so that error report
-.-.
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 154, length 81
\&'getchunk' command (which will be typesetted acordingly). Finally, you run your
Line 161, length 82
inside \*(L"changetext\*(R" for the line number. This is used so that error report
Line 165, length 87
Defaults to \*(L"{}\*(R" this is the text that will be replaced with the line number if
-.-.
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 "troff", but not in "nroff".
25:.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
-.-.
Add a zero (0) in front of a decimal fraction that begins with a period
(.)
6:.if t .sp .5v
77:. ds #V .8m
78:. ds #F .3m
84:. ds #V .6m
-.-.
Output from "test-groff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z ":
troff:<stdin>:183: warning: font name 'CW' is deprecated
Bad use of \s0 in a string definition, the string "X" could be resized,
for example with "\s-1\*X\s0".
25:.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
-.-.
Spelling:
acordingly ==> accordingly (from "codespell")
tagler -> tangler
typesetted -> typeset
--- pamphletangler.1 2024-12-29 10:49:28.593263392 +0000
+++ pamphletangler.1.new 2024-12-29 11:26:09.578347448 +0000
@@ -3,11 +3,15 @@
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
-.if t .sp .5v
+.if t .sp 0.5v
.if n .sp
..
.de Vb \" Begin verbatim text
-.ft CW
+.ie \\n(.g \{\
+. ie t .ft CR
+. el .ft R
+.\}
+.el .ft CW
.nf
.ne \\$1
..
@@ -22,7 +26,7 @@
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
-.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s+2\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
@@ -74,14 +78,14 @@
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
-. ds #V .8m
-. ds #F .3m
+. ds #V 0.8m
+. ds #F 0.3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
-. ds #V .6m
+. ds #V 0.6m
. ds #F 0
. ds #[ \&
. ds #] \&
@@ -145,25 +149,31 @@ pamphletangler \- Extract code bits from
\&\fBpamphletangler\fR [\s-1OPTION...\s0] \fI\s-1FILE\s0\fR \fI\s-1CHUNKNAME\s0\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
-The clojure pamphlet system is a system based on the clojure literate
-system. In the clojure's pamphlet system you have your main LaTeX file, which
-can be compiled regularly. This file contains documentation and source code
-(just like in other forms of literate programming). This code snippets are
-wrapped in the 'chunk' environment, hence they can be recognized by the tangler
-in order to extract them. Chunks can be included inside each other by the
-\&'getchunk' command (which will be typesetted acordingly). Finally, you run your
-LaTeX file through the tangler and get your desired chunk of code.
+The clojure pamphlet system is a system based on the clojure literate system.
+In the clojure's pamphlet system you have your main LaTeX file,
+which can be compiled regularly.
+This file contains documentation and source code
+(just like in other forms of literate programming).
+This code snippets are wrapped in the 'chunk' environment,
+hence they can be recognized by the tangler in order to extract them.
+Chunks can be included inside each other by the \&'getchunk' command
+(which will be typeset accordingly).
+Finally, you run your LaTeX file through the tangler
+and get your desired chunk of code.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\-L, \-\-line=linetext" 29
.IX Item "-L, --line=linetext"
-If set, this text will be inserted after jumps of lines, changing the string
-inside \*(L"changetext\*(R" for the line number. This is used so that error report
-refers to pamphlet line number instead of output line number
+If set, this text will be inserted after jumps of lines,
+changing the string inside \*(L"changetext\*(R" for the line number.
+This is used so that error report
+refers to pamphlet line number instead of output line number.
.IP "\-C, \-\-change=changetext" 29
.IX Item "-C, --change=changetext"
-Defaults to \*(L"{}\*(R" this is the text that will be replaced with the line number if
-the linetext option is specified
+Defaults to \*(L"{}\*(R"
+this is the text
+that will be replaced with the line number
+if the linetext option is specified
.IP "\-?, \-\-help" 29
.IX Item "-?, --help"
Give this help list
@@ -181,7 +191,7 @@ Print program version
Copyright (C) 2019 Ernesto Lanchares Sanchez.
.PP
.Vb 5
-\& The clojure\-pamphlet tagler is free software; you can redistribute
+\& The clojure\-pamphlet tangler is free software; you can redistribute
\& it and/or modify it under the terms of the GNU Lesser General
\& Public License as published by the Free Software Foundation;
\& either version 3 of the License, or (at your option) any later
Reply to: