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

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: