Dear Maintainer,
here are some notes and editorial fixes for the manual.
The patch is in the attachment.
-.-
The concerned man page was autogenerated (autogen).
-.-
Any program (person), that produces man pages, should check its content for
defects by using
groff -mandoc -t -ww -b -z [ -K utf8 | k ] <file>
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' 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.
-.-
The difference between the formatted outputs can be seen with:
nroff -man <file1> > <out1>
nroff -man <file2> > <out2>
diff -u <out1> <out2>
and for groff, using
"printf '%s\n%s\n' '.kern 0' '.ss 12 0' | groff -man -Z - "
instead of "nroff -man"
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 -z"
export MAN_KEEP_STDERR=yes (or any non-empty value)
-.-.
Output from "mandoc -T lint shar.1": (possibly shortened list)
mandoc: shar.1:536:2: WARNING: skipping paragraph macro: PP empty
mandoc: shar.1:579:2: WARNING: skipping paragraph macro: br after sp
mandoc: shar.1:615:2: WARNING: skipping paragraph macro: PP empty
mandoc: shar.1:625: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.
shar.1:624:Copyright (C) 1994-2015 Free Software Foundation, Inc. all rights reserved.
-.-.
Change two HYPHEN-MINUSES (code 0x2D) to an em-dash (\(em),
if one is intended. 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 "\-\-".
shar.1:42:(\fB--vanilla-operation\fP) or essentially a mailable \fBtar\fP
shar.1:46:recognized. If the \fB--intermix-type\fP option has been specified,
shar.1:74:e.g. \fB--gzip\fP. Those options, however, are being deprecated.
shar.1:76:with \fB-C xz\fP or \fB--compactor=xz\fP.
shar.1:142:This is an alias for the \fI--level-of-compression\fR option.
shar.1:215:the \fB--whole-size-limit\fP or \fB--split-size-limit\fP
shar.1:268:\fB--whole-size-limit\fP option.
shar.1:289:If the \fB--intermix-type\fP option is specified on the command
shar.1:295: { echo \--compact xz
shar.1:304:\fB--input-file-list=-\fP.
shar.1:314:files. See the \fB--net-headers\fP option.
shar.1:333:\fB--submitter\fP option. The \fIname\fP must be provided with the
shar.1:334:\fB--archive-name\fP option. If the archive name includes a slash
shar.1:389:especially if \fB--uuencode\fP or a compression option is used.
shar.1:412:(\fB--mixed-uuencode\fP) to text mode (\fB--text-files\fP).
shar.1:429:\fB--query-user\fP option is specified, the unpack will not
shar.1:431:\fB--cut-mark\fP is passed as a parameter to the script when
shar.1:448:together with vanilla mode (\fB--vanilla-operation\fP). Use this
shar.1:513:This is an alias for the \fI--quiet\fR option.
-.-.
Change (or include a "FIXME" paragraph about) misused SI (metric)
numeric prefixes (or names) to the binary ones, like Ki (kibi), Mi
(mebi), Gi (gibi), or Ti (tebi), if indicated.
If the metric prefixes are correct, add the definitions or an
explanation to avoid misunderstanding.
244:respectively. 4M (4194304) is the maximum allowed.
-.-.
Mark a full stop (.) and the exclamation mark (!) with "\&",
if it does not mean an end of a sentence.
This is a preventive action,
the paragraph could be reshaped, e.g., after changes.
When typing, one does not always notice when the line wraps after the
period.
There are too many examples of input lines in manual pages,
that end with an abbreviation point.
This marking is robust, and independent of the position on the line.
It corresponds to "\ " in TeX, and to "@:" in Texinfo.
74:e.g. \fB--gzip\fP. Those options, however, are being deprecated.
624:Copyright (C) 1994-2015 Free Software Foundation, Inc. all rights reserved.
-.-.
Change -- in x--y to \(em (em-dash), or, if an
option, to \-\-
42:(\fB--vanilla-operation\fP) or essentially a mailable \fBtar\fP
46:recognized. If the \fB--intermix-type\fP option has been specified,
74:e.g. \fB--gzip\fP. Those options, however, are being deprecated.
76:with \fB-C xz\fP or \fB--compactor=xz\fP.
142:This is an alias for the \fI--level-of-compression\fR option.
215:the \fB--whole-size-limit\fP or \fB--split-size-limit\fP
268:\fB--whole-size-limit\fP option.
289:If the \fB--intermix-type\fP option is specified on the command
304:\fB--input-file-list=-\fP.
314:files. See the \fB--net-headers\fP option.
333:\fB--submitter\fP option. The \fIname\fP must be provided with the
334:\fB--archive-name\fP option. If the archive name includes a slash
389:especially if \fB--uuencode\fP or a compression option is used.
412:(\fB--mixed-uuencode\fP) to text mode (\fB--text-files\fP).
429:\fB--query-user\fP option is specified, the unpack will not
431:\fB--cut-mark\fP is passed as a parameter to the script when
448:together with vanilla mode (\fB--vanilla-operation\fP). Use this
513:This is an alias for the \fI--quiet\fR option.
-.-.
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.
42:(\fB--vanilla-operation\fP) or essentially a mailable \fBtar\fP
46:recognized. If the \fB--intermix-type\fP option has been specified,
74:e.g. \fB--gzip\fP. Those options, however, are being deprecated.
76:with \fB-C xz\fP or \fB--compactor=xz\fP.
96:.in -4
142:This is an alias for the \fI--level-of-compression\fR option.
215:the \fB--whole-size-limit\fP or \fB--split-size-limit\fP
238:.in -4
264:.in -4
268:\fB--whole-size-limit\fP option.
289:If the \fB--intermix-type\fP option is specified on the command
295: { echo \--compact xz
304:\fB--input-file-list=-\fP.
314:files. See the \fB--net-headers\fP option.
333:\fB--submitter\fP option. The \fIname\fP must be provided with the
334:\fB--archive-name\fP option. If the archive name includes a slash
389:especially if \fB--uuencode\fP or a compression option is used.
412:(\fB--mixed-uuencode\fP) to text mode (\fB--text-files\fP).
429:\fB--query-user\fP option is specified, the unpack will not
431:\fB--cut-mark\fP is passed as a parameter to the script when
448:together with vanilla mode (\fB--vanilla-operation\fP). Use this
513:This is an alias for the \fI--quiet\fR option.
586:.in -4
-.-.
Strings longer than 3/4 of a standard line length (80)
85 .NOP \f\*[B-Font]\-g\f[] \f\*[I-Font]level\f[], \f\*[B-Font]\-\-level\-of\-compression\f[]=\f\*[I-Font]level\f[]
-.-.
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.
74:e.g. \fB--gzip\fP. Those options, however, are being deprecated.
-.-.
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.
shar.1: line 66 length 103
.NOP \f\*[B-Font]\-C\f[] \f\*[I-Font]program\f[], \f\*[B-Font]\-\-compactor\f[]=\f\*[I-Font]program\f[]
shar.1: line 85 length 112
.NOP \f\*[B-Font]\-g\f[] \f\*[I-Font]level\f[], \f\*[B-Font]\-\-level\-of\-compression\f[]=\f\*[I-Font]level\f[]
shar.1: line 147 length 103
.NOP \f\*[B-Font]\-b\f[] \f\*[I-Font]bits\f[], \f\*[B-Font]\-\-bits\-per\-code\f[]=\f\*[I-Font]bits\f[]
shar.1: line 210 length 106
.NOP \f\*[B-Font]\-o\f[] \f\*[I-Font]prefix\f[], \f\*[B-Font]\-\-output\-prefix\f[]=\f\*[I-Font]prefix\f[]
shar.1: line 223 length 106
.NOP \f\*[B-Font]\-l\f[] \f\*[I-Font]size\f[], \f\*[B-Font]\-\-whole\-size\-limit\f[]=\f\*[I-Font]size\f[]
shar.1: line 249 length 106
.NOP \f\*[B-Font]\-L\f[] \f\*[I-Font]size\f[], \f\*[B-Font]\-\-split\-size\-limit\f[]=\f\*[I-Font]size\f[]
shar.1: line 277 length 105
.NOP \f\*[B-Font]\-I\f[] \f\*[I-Font]file\f[], \f\*[B-Font]\-\-input\-file\-list\f[]=\f\*[I-Font]file\f[]
shar.1: line 310 length 101
.NOP \f\*[B-Font]\-n\f[] \f\*[I-Font]name\f[], \f\*[B-Font]\-\-archive\-name\f[]=\f\*[I-Font]name\f[]
shar.1: line 316 length 107
.NOP \f\*[B-Font]\-s\f[] \f\*[I-Font]who@where\f[], \f\*[B-Font]\-\-submitter\f[]=\f\*[I-Font]who@where\f[]
shar.1: line 391 length 105
.NOP \f\*[B-Font]\-d\f[] \f\*[I-Font]delim\f[], \f\*[B-Font]\-\-here\-delimiter\f[]=\f\*[I-Font]delim\f[]
shar.1: line 521 length 108
.NOP \f\*[B-Font]\-R\f[] [\f\*[I-Font]cfgfile\f[]], \f\*[B-Font]\-\-save-opts\f[] [=\f\*[I-Font]cfgfile\f[]]
shar.1: line 526 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[]
shar.1: line 532 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[]}]}]
shar.1: line 625 length 95
This program is released under the terms of the GNU General Public License, version 3 or later.
-.-.
Use the name of units in text; use symbols in tables and
calculations.
The rule is to have a (no-break, \~) space between a number and
its units (see "www.bipm.org/en/publications/si-brochure")
244:respectively. 4M (4194304) is the maximum allowed.
-.-.
Name of a manual is set in bold, the section in roman.
See man-pages(7).
617:unshar(1)
-.-.
Change a HYPHEN-MINUS (code 0x55, 2D) to a dash
(\-, minus) if it matches "[[:alph:]]-[[:alpha:]]" in the name of an
option).
Facilitates the copy and paste of an option in UTF-8 text.
Is not needed in ordinary words like "mother-in-law", that are not
copied and pasted to a command line (which needs ASCII code)
28:[\f\*[B-Font]\-\-option-name\f[][[=| ]\f\*[I-Font]value\f[]]]
42:(\fB--vanilla-operation\fP) or essentially a mailable \fBtar\fP
46:recognized. If the \fB--intermix-type\fP option has been specified,
141:.NOP \f\*[B-Font]\-\-level-for-gzip\f[]
142:This is an alias for the \fI--level-of-compression\fR option.
215:the \fB--whole-size-limit\fP or \fB--split-size-limit\fP
225:This option is a member of the whole-size-limit class of options.
246:Unlike the \fBsplit-size-limit\fP option, this allows the recipient
251:This option is a member of the whole-size-limit class of options.
268:\fB--whole-size-limit\fP option.
289:If the \fB--intermix-type\fP option is specified on the command
304:\fB--input-file-list=-\fP.
314:files. See the \fB--net-headers\fP option.
334:\fB--archive-name\fP option. If the archive name includes a slash
412:(\fB--mixed-uuencode\fP) to text mode (\fB--text-files\fP).
429:\fB--query-user\fP option is specified, the unpack will not
431:\fB--cut-mark\fP is passed as a parameter to the script when
435: sh shar-archive-file \-c
448:together with vanilla mode (\fB--vanilla-operation\fP). Use this
518:.NOP \f\*[B-Font]\-\&!\f[], \f\*[B-Font]\-\-more-help\f[]
521:.NOP \f\*[B-Font]\-R\f[] [\f\*[I-Font]cfgfile\f[]], \f\*[B-Font]\-\-save-opts\f[] [=\f\*[I-Font]cfgfile\f[]]
526:.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[]
528:The \fIno-load-opts\fP form will disable the loading
529:of earlier config/rc/ini files. \fI\-\-no-load-opts\fP is handled early,
632:Please send bug reports to: bug-gnu-utils@gnu.org
-.-.
Output from "test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -t -w w -z -K utf8":
troff: backtrace: file '<stdin>':30
troff:<stdin>:30: warning: register 'Pp' not defined
Where is this variable supposed to be defined?
-.-
Spelling mistakes
miscelleaneous -> miscellaneous
-.-
Use a thousands separator in long numbers
1000000 -> 1,000,000
1048576 -> 1,048,576
4194304 -> 4,194,304