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

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

Package: sharutils
Version: 1:4.15.2-9
Severity: minor
Tags: patch

   * What led up to the situation?

     Checking for defects with

[test-]groff -mandoc -t -K utf8 -rF0 -rHY=0 -ww -b -z < "man page"

  [test-groff is a script in the repository for "groff"] (local copy and
"troff" slightly changed by me).

   * What was the outcome of this action?

troff: backtrace: file '<stdin>':30
troff:<stdin>:30: warning: register 'Pp' not defined

   * 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.10.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 sharutils depends on:
ii  libc6  2.40-2

sharutils recommends no packages.

Versions of packages sharutils suggests:
pn  bsd-mailx | mailx  <none>
pn  sharutils-doc      <none>

-- no debconf information

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

  Any program (person), that produces man pages, should check its content for
defects by using

groff -mandoc -t -ww -b -z [ -K utf8 | k ] <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 outputs 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 uuencode.1": (possibly shortened list)

mandoc: uuencode.1:89:2: WARNING: skipping paragraph macro: PP empty
mandoc: uuencode.1:113:2: WARNING: skipping paragraph macro: PP empty
mandoc: uuencode.1:122:95: STYLE: input text line longer than 80 bytes: This program is rele...

-.-.

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.

uuencode.1:121:Copyright (C) 1994-2015 Free Software Foundation, Inc. all rights reserved.

-.-.

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.

N.B.

  The number of lines affected can be too large to be in a patch.


Line 74, length 108

.NOP \f\*[B-Font]\-R\f[] [\f\*[I-Font]cfgfile\f[]], \f\*[B-Font]\-\-save-opts\f[] [=\f\*[I-Font]cfgfile\f[]]

Line 79, length 137

.NOP \f\*[B-Font]\-r\f[] \f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-load-opts\f[]=\f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-no-load-opts\f[]

Line 85, length 104

.NOP \f\*[B-Font]\-v\f[] [{\f\*[I-Font]v|c|n\f[] \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}]}]

Line 122, length 95

This program is released under the terms of the GNU General Public License, version 3 or later.


-.-.

Name of a manual is set in bold, the section in roman.
See man-pages(7).

115:uudecode(1), uuencode(5)

-.-.

79:.NOP \f\*[B-Font]\-r\f[] \f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-load-opts\f[]=\f\*[I-Font]cfgfile\f[], \f\*[B-Font]\-\-no-load-opts\f[]
81:The \fIno-load-opts\fP form will disable the loading
82:of earlier config/rc/ini files.  \fI\-\-no-load-opts\fP is handled early,

-.-.

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

troff: backtrace: file '<stdin>':30
troff:<stdin>:30: warning: register 'Pp' not defined


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

--- uuencode.1	2024-09-21 19:03:40.469818686 +0000
+++ uuencode.1.new	2024-09-21 19:14:40.218263365 +0000
@@ -1,3 +1,10 @@
+.\" PARAGRAPH SPACE
+.if t \{\
+.       nr Pp .5v
+.\}
+.if n \{\
+.       nr Pp 1v
+.\}
 .de1 NOP
 .  it 1 an-trap
 .  if \\n[.$] \,\\$*\/
@@ -86,7 +93,6 @@ out of order.
 Output version of program and exit.  The default mode is `v', a simple
 version.  The `c' mode will print copyright information and `n' will
 print the full copyright notice.
-.PP
 .SH "OPTION PRESETS"
 Any option that is not marked as \fInot presettable\fP may be preset
 by loading values from configuration ("RC" or ".INI") file(s).
@@ -110,16 +116,16 @@ A specified configuration file could not
 .NOP 70 " (EX_SOFTWARE)"
 libopts had an internal operational error.  Please report
 it to [email protected].  Thank you.
-.PP
 .SH "SEE ALSO"
-uudecode(1), uuencode(5)
+.BR uudecode "(1), " uuencode (5)
 .SH HISTORY
 The \fBuuencode\fP command first appeared in BSD 4.0.
 .SH "AUTHORS"
 Free Software Foundation, Inc.
 .SH "COPYRIGHT"
-Copyright (C) 1994-2015 Free Software Foundation, Inc. all rights reserved.
-This program is released under the terms of the GNU General Public License, version 3 or later.
+Copyright (C) 1994\(en2015 Free Software Foundation, Inc.\& all rights reserved.
+This program is released under the terms of the GNU General Public License,
+version 3 or later.
 .SH BUGS
 Please put \fBsharutils\fP in the subject line for emailed bug
 reports.  It helps to spot the message.

--Xcvo2c6XRWv5VetW--