a2ps.1: Some remarks and editorial changes for this man page

--UCs5Nop2WwvzDuM5
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

Package: a2ps
Version: 1:4.15.6-1
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>':259
troff:<stdin>:259: 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.11.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 a2ps depends on:
ii  file       1:5.45-3+b1
ii  libc6      2.40-3
ii  libgc1     1:8.2.8-1
ii  libpaper1  1.1.29+b2
ii  psutils    1.17.dfsg-5

Versions of packages a2ps recommends:
ii  bzip2                     1.0.8-6
pn  lpr | rlpr | cups-client  <none>
ii  wdiff                     1.2.2-6

Versions of packages a2ps suggests:
ii  emacsen-common                       3.0.5
ii  ghostscript                          10.04.0~dfsg-1
ii  groff                                1.23.0-5
ii  gv                                   1:3.7.4-2+b2
pn  html2ps                              <none>
ii  imagemagick                          8:6.9.13.12+dfsg1-1+b1
ii  imagemagick-6.q16 [imagemagick]      8:6.9.13.12+dfsg1-1+b1
pn  t1-cyrillic                          <none>
ii  texlive-binaries [texlive-base-bin]  2024.20240313.70630+ds-5

-- no debconf information

--UCs5Nop2WwvzDuM5
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="chk_man.err.a2ps.1"

Input file is a2ps.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  a2ps.1 ": (shortened list)

      2 input text line longer than 80 bytes
      1 skipping paragraph macro

-.-.

Output from "test-groff -mandoc -t -ww -b -z a2ps.1 ": (shortened list)

      1 font name 'CW' is deprecated

-.-.

Output from "mandoc -T lint  a2ps.1 ":

mandoc: a2ps.1:10:2: WARNING: skipping paragraph macro: PP after SH
mandoc: a2ps.1:100:90: STYLE: input text line longer than 80 bytes: The options \fB\-1\f...
mandoc: a2ps.1:101:85: STYLE: input text line longer than 80 bytes: layouts with 80 colu...
-.-.

-.-.

Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended.
  " \(em " creates a too big gap in the text (in "troff").

An en-dash is usually surrounded by a space,
while an em-dash is used without spaces.
"man" (1 byte characters in input) transforms an en-dash (\(en) to one
HYPHEN-MINUS,
and an em-dash to two HYPHEN-MINUSES without considering the space
around it.
If "--" are two single "-" (end of options) then use "\-\-".

a2ps.1:259:\f(CW$ a2ps -P lw --toc src/*\fR

-.-.

Change -- in x--y to \(em (em-dash), or, if an
option, to \-\-

259:\f(CW$ a2ps -P lw --toc src/*\fR

-.-.

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.

259:\f(CW$ a2ps -P lw --toc src/*\fR
263:\f(CW$ a2ps -P display sample.ps sample.html\fR
267:\f(CW$ a2ps -=mail -4 mailbox\fR
271:\f(CW$ a2ps -=book paper.dvi.gz -d\fR

-.-.

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.

7:[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
100:The options \fB\-1\fR.. \fB\-9\fR affect several primitive parameters to set up predefined

-.-.

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 100, length 90

The options \fB\-1\fR.. \fB\-9\fR affect several primitive parameters to set up predefined

Line 101, length 85

layouts with 80 columns.  Therefore the order matters: `\-R \fB\-f40\fR \fB\-2\fR' is

Line 128, length 91

\fB\-\-non\-printable\-format\fR=\fI\,FMT\/\fR specify how non\-printable chars are printed


-.-.

Put a parenthetical sentence, phrase on a separate line,
if not part of a code.
See man-pages(7), item "semantic newline".

a2ps.1:103:options (`\-\-columns', `\-\-font\-size' etc.).
a2ps.1:197:enable pretty\-printing (set style to LANG)
a2ps.1:277:The system configuration file (usually \fI/usr/local/etc/a2ps.cfg\fR)

-.-.

Two or more space charaters between printable characters.

When the distance is between sentences,
start the beginning of the second one on a separate line
("semantic newline").

11:Convert FILE(s) or standard input to PostScript.  By default, the output is
12:sent to the default printer.  An output file may be specified with \fB\-o\fR.
46:After having performed the task, exit successfully.  Detailed lists may provide
101:layouts with 80 columns.  Therefore the order matters: `\-R \fB\-f40\fR \fB\-2\fR' is
102:equivalent to `\-2'.  To modify the layout, use `\-2Rf40', or compose primitive
212:leave output to file FILE.  If FILE is `\-',
255:By default a2ps is tuned to do what you want to, so trust it.  To pretty print
273:a2ps reads several files before the command line options.  In order,
311:is maintained as a Texinfo manual.  If the

-.-.

Output from "test-groff  -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z ":

troff: backtrace: file '<stdin>':259
troff:<stdin>:259: warning: font name 'CW' is deprecated

-.-

  'CW' changed to 'CR'. 

--UCs5Nop2WwvzDuM5
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="a2ps.1.diff"

--- a2ps.1	2024-11-25 23:38:42.068108362 +0000
+++ a2ps.1.new	2024-11-26 02:20:42.141699091 +0000
@@ -4,16 +4,18 @@
 a2ps \- format files for printing on a PostScript printer
 .SH SYNOPSIS
 .B a2ps
-[\fI\,OPTION\/\fR]... [\fI\,FILE\/\fR]...
+[\fI\,OPTION\/\fR]...\& [\fI\,FILE\/\fR]...
 .SH DESCRIPTION
 .\" Add any additional description here
 .PP
-Convert FILE(s) or standard input to PostScript.  By default, the output is
-sent to the default printer.  An output file may be specified with \fB\-o\fR.
+Convert FILE(s) or standard input to PostScript.
+By default,
+the output is sent to the default printer.
+An output file may be specified with \fB\-o\fR.
 .PP
 Mandatory arguments to long options are mandatory for short options too.
-Long options marked with `*' require a yes/no argument, corresponding short
-options stand for `yes'.
+Long options marked with `*' require a yes/no argument,
+corresponding short options stand for `yes'.
 .PP
 Tasks:
 .TP
@@ -43,8 +45,8 @@ encodings, features, variables, media, p
 printers, prologues, style\-sheets,
 user\-options)
 .PP
-After having performed the task, exit successfully.  Detailed lists may provide
-additional help on specific features.
+After having performed the task, exit successfully.
+Detailed lists may provide additional help on specific features.
 .PP
 Global:
 .TP
@@ -60,7 +62,7 @@ use the user defined shortcut OPTION
 \fB\-\-debug\fR
 enable debugging features
 .TP
-\fB\-D\fR, \fB\-\-define\fR=\fI\,KEY[\/\fR:VALUE]
+\fB\-D\fR, \fB\-\-define\fR=\fI\,KEY\/\fR[:\fIVALUE\fR]
 unset variable KEY or set to VALUE
 .PP
 Sheets:
@@ -97,10 +99,13 @@ print borders around columns
 \fB\-\-margin\fR[=\fI\,NUM\/\fR]
 define an interior margin of size NUM
 .PP
-The options \fB\-1\fR.. \fB\-9\fR affect several primitive parameters to set up predefined
-layouts with 80 columns.  Therefore the order matters: `\-R \fB\-f40\fR \fB\-2\fR' is
-equivalent to `\-2'.  To modify the layout, use `\-2Rf40', or compose primitive
-options (`\-\-columns', `\-\-font\-size' etc.).
+The options \fB\-1\fR..\fB\-9\fR affect several primitive parameters to set
+up predefined layouts with 80 columns.
+Therefore the order matters:
+`\-R \fB\-f40\fR \fB\-2\fR' is equivalent to `\-2'.
+To modify the layout,
+use `\-2Rf40', or compose primitive options
+(`\-\-columns', `\-\-font\-size' etc.).
 .PP
 Virtual pages:
 .TP
@@ -125,7 +130,8 @@ process FILE as a man page (same as \fB\
 \fB\-T\fR, \fB\-\-tabsize\fR=\fI\,NUM\/\fR
 set tabulator size to NUM
 .HP
-\fB\-\-non\-printable\-format\fR=\fI\,FMT\/\fR specify how non\-printable chars are printed
+\fB\-\-non\-printable\-format\fR=\fI\,FMT\/\fR specify how non\-printable \
+chars are printed
 .PP
 Headings:
 .TP
@@ -187,9 +193,10 @@ delegate files to another application
 \fB\-\-toc\fR[=\fI\,TEXT\/\fR]
 generate a table of content
 .PP
-When delegations are enabled, a2ps may use other applications to handle the
-processing of files that should not be printed as raw information, e.g., HTML
-PostScript, PDF etc.
+When delegations are enabled,
+a2ps may use other applications to handle the processing of files
+that should not be printed as raw information,
+e.g., HTML, PostScript, PDF, etc.
 .PP
 Pretty\-printing:
 .TP
@@ -197,7 +204,7 @@ Pretty\-printing:
 enable pretty\-printing (set style to LANG)
 .TP
 \fB\-\-highlight\-level\fR=\fI\,LEVEL\/\fR
-set pretty printing highlight LEVEL
+set pretty printing highlight LEVEL.
 LEVEL can be none, normal or heavy
 .TP
 \fB\-g\fR
@@ -209,8 +216,8 @@ level of comments stripping
 Output:
 .TP
 \fB\-o\fR, \fB\-\-output\fR=\fI\,FILE\/\fR
-leave output to file FILE.  If FILE is `\-',
-leave output to stdout.
+leave output to file FILE.
+If FILE is `\-', leave output to stdout.
 .TP
 \fB\-\-version\-control\fR=\fI\,WORD\/\fR
 override the usual version control
@@ -240,10 +247,10 @@ print NUM copies of each page
 set the duplex MODE (`1' or `simplex',
 `2' or `duplex', `tumble')
 .TP
-\fB\-S\fR, \fB\-\-setpagedevice\fR=\fI\,K[\/\fR:V]
+\fB\-S\fR, \fB\-\-setpagedevice\fR=\fI\,K\/\fR[:\fIV\fP]
 pass a page device definition to output
 .TP
-\fB\-\-statusdict\fR=\fI\,K[\/\fR:[:]V]
+\fB\-\-statusdict\fR=\fI\,K\/\fR[:[:]\fIV\fP]
 pass a statusdict definition to the output
 .TP
 \fB\-k\fR, \fB\-\-page\-prefeed\fR
@@ -252,31 +259,34 @@ enable page prefeed
 \fB\-K\fR, \fB\-\-no\-page\-prefeed\fR
 disable page prefeed
 .PP
-By default a2ps is tuned to do what you want to, so trust it.  To pretty print
-the content of the `src' directory and a table of content, and send the result
-to the printer `lw',
+By default a2ps is tuned to do what you want to, so trust it.
+To pretty print the content of the `src' directory
+and a table of content,
+and send the result to the printer `lw',
 .IP
-\f(CW$ a2ps -P lw --toc src/*\fR
+\f(CR$ a2ps \-P lw \-\-toc src/*\fR
 .PP
 To process the files `sample.ps' and `sample.html' and display the result,
 .IP
-\f(CW$ a2ps -P display sample.ps sample.html\fR
+\f(CR$ a2ps \-P display sample.ps sample.html\fR
 .PP
 To process a mailbox in 4 up,
 .IP
-\f(CW$ a2ps -=mail -4 mailbox\fR
+\f(CR$ a2ps \-=mail \-4 mailbox\fR
 .PP
-To print as a booklet on the default printer, which is duplex capable,
+To print as a booklet on the default printer,
+which is duplex capable,
 .IP
-\f(CW$ a2ps -=book paper.dvi.gz -d\fR
+\f(CR$ a2ps \-=book paper.dvi.gz \-d\fR
 .SH FILES
-a2ps reads several files before the command line options.  In order,
-they are:
+a2ps reads several files before the command line options.
+In order, they are:
 
 .IP 1.
-The system configuration file (usually \fI/usr/local/etc/a2ps.cfg\fR)
-unless you have defined the environment variable \fIA2PS_CONFIG\fR, in
-which case a2ps reads the file it points to;
+The system configuration file
+(usually \fI/usr/local/etc/a2ps.cfg\fR)
+unless you have defined the environment variable \fIA2PS_CONFIG\fR,
+in which case a2ps reads the file it points to;
 
 .IP 2.
 the user's home configuration file (\fI$HOME/.a2ps/a2psrc\fR)
@@ -284,8 +294,8 @@ the user's home configuration file (\fI$
 .IP 3.
 the file \fI.a2psrc\fR in the current directory.
 
-See the info manual for more information, including a description of the
-configuration file format.
+See the info manual for more information,
+including a description of the configuration file format.
 .SH AUTHOR
 Written by Akim Demaille, Miguel Santana, and Reuben Thomas.
 .SH "REPORTING BUGS"
@@ -308,11 +318,13 @@ There is NO WARRANTY, to the extent perm
 .PP
 The full documentation for
 .B a2ps
-is maintained as a Texinfo manual.  If the
+is maintained as a Texinfo manual.
+If the
 .B info
 and
 .B a2ps
-programs are properly installed at your site, the command
+programs are properly installed at your site,
+the command
 .IP
 .B info a2ps
 .PP

--UCs5Nop2WwvzDuM5--