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

--jAmyF+6MCx3lvxLC
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:<stdin>:32: 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.10-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:7.1.1.39+dfsg1-3
ii  imagemagick-7.q16 [imagemagick]      8:7.1.1.39+dfsg1-3
pn  t1-cyrillic                          <none>
ii  texlive-binaries [texlive-base-bin]  2024.20240313.70630+ds-5

-- no debconf information

--jAmyF+6MCx3lvxLC
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="chk_man.err.card.1"

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

      1 skipping paragraph macro

-.-.

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

      1 font name 'CW' is deprecated

-.-.

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

mandoc: card.1:10:2: WARNING: skipping paragraph macro: PP after SH

-.-.

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.

card.1:40:Copyright \(co 1997\-99 Akim Demaille, Miguel Santana

-.-.

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.

32:\f(CW$ card -lfr a2ps -- -Pdisplay -4\fR

-.-.

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.

28:(e.g. \fB\-\-command=\fR'a2ps \fB\-\-help\fR')

-.-.

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

card.1:24:print the help in the language LL (default: English)

-.-.

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", see man-pages(7)).

42:This is free software; see the source for copying conditions.  There is NO
52:is maintained as a Texinfo manual.  If the

-.-.

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

troff:<stdin>:32: warning: font name 'CW' is deprecated

--jAmyF+6MCx3lvxLC
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="card.1.diff"

--- card.1	2024-12-05 21:06:03.718942006 +0000
+++ card.1.new	2024-12-05 22:06:11.915990950 +0000
@@ -4,10 +4,9 @@
 card \- print reference card of program options
 .SH SYNOPSIS
 .B card
-[\fI\,OPTION\/\fR]... \fI\,PROGRAM\/\fR...
+[\fI\,OPTION\/\fR]...\& \fI\,PROGRAM\/\fR...
 .SH DESCRIPTION
 .\" Add any additional description here
-.PP
 Print a reference card of the PROGRAMs thanks to their inline help.
 .SH OPTIONS
 .TP
@@ -21,15 +20,16 @@ display version information and exit
 save the output in FILE
 .TP
 \fB\-l\fR, \fB\-\-language\fR=\fI\,LL\/\fR
-print the help in the language LL (default: English)
+print the help in the language LL
+(default: English)
 .TP
 \fB\-\-command\fR=\fI\,CMD\/\fR
 perform pretty\-printing on the output of CMD
-(e.g. \fB\-\-command=\fR'a2ps \fB\-\-help\fR')
+(e.g., \fB\-\-command=\fR'a2ps \fB\-\-help\fR')
 .PP
 Options for a2ps are given after `\-\-', for instance
 .IP
-\f(CW$ card -lfr a2ps -- -Pdisplay -4\fR
+\f(CR$ card \-lfr a2ps \-\- \-Pdisplay \-4\fR
 .PP
 News, updates and documentation: https://www.gnu.org/software/a2ps/
 .SH AUTHOR
@@ -37,10 +37,11 @@ Written by Akim Demaille.
 .SH "REPORTING BUGS"
 Report bugs to <bug\[email protected]>.
 .SH COPYRIGHT
-Copyright \(co 1997\-99 Akim Demaille, Miguel Santana
+Copyright \(co 1997\(en99 Akim Demaille, Miguel Santana
 .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.
+This is free software; see the source for copying conditions.
+There is NO warranty;
+not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 .SH "SEE ALSO"
 .BR a2ps (1),
 .BR card (1),

--jAmyF+6MCx3lvxLC--