Package: cpio
Version: 2.15+dfsg-2
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 ' $' -e '\\~$' <file>" to find obvious 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?
an.tmac:<stdin>:204: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
* 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.12-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 cpio depends on:
ii libc6 2.40-7
cpio recommends no packages.
Versions of packages cpio suggests:
pn libarchive-dev <none>
-- no debconf information
Input file is cpio.1
Output from "mandoc -T lint cpio.1": (shortened list)
-.-.
Output from "test-nroff -mandoc -t -ww -z cpio.1": (shortened list)
1 Use macro '.B' for one argument or split argument.
1 .BR is for at least 2 arguments, got 1
-.-.
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 "-"
(begin of an option or end of options)
then use "\-\-".
cpio.1:341:Copyright \(co 2014--2023 Free Software Foundation, Inc.
-.-.
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.
186:values, prefix them with a plus sign, e.g.: \fB-R +0:+0\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.
Mark a final abbreviation point as such by suffixing it with "\&".
Some sentences (etc.) do not begin on a new line.
Split (sometimes) lines after a punctuation mark; before a conjunction.
Lines with only one (or two) space(s) between sentences could be split,
so latter sentences begin on a new line.
Use
#!/usr/bin/sh
sed -e '/^\./n' \
-e 's/\([[:alpha:]]\)\. */\1.\n/g' $1
to split lines after a sentence period.
Check result with the difference between the formatted outputs.
See also the attachment "general.bugs"
[List of affected lines removed.]
-.-.
The name of a man page is typeset in bold and the section in roman
(see man-pages(7)).
77:cpio(5)
-.-.
Space after an end of sentence.
[List of affected lines removed.]
-.-.
Use thousand markers to make large numbers easy to read
147:The obsolete binary format. (2147483647 bytes)
150:The old (POSIX.1) portable format. (8589934591 bytes)
154:having more than 65536 inodes. (4294967295 bytes)
160:The old tar format. (8589934591 bytes)
164:which are similar but not identical. (8589934591 bytes)
-.-.
Put a subordinate sentence (after a comma) on a new line.
[List of affected lines removed.]
-.-
Remove quotes when there is a printable
but no space character between them
and the quotes are not for emphasis (markup),
for example as an argument to a macro.
cpio.1:16:.TH CPIO 1 "April 29, 2023" "CPIO" "GNU CPIO"
-.-.
Section headings (.SH and .SS) do not need quoting their arguments.
331:.SH "RETURN VALUE"
334:.SH "SEE ALSO"
338:.SH "BUG REPORTS"
-.-.
Output from "test-nroff -mandoc -t -K utf8 -rF0 -rHY=0 -rCHECKSTYLE=10 -ww -z
":
an.tmac:<stdin>:204: misuse, warning: .BR is for at least 2 arguments, got 1
Use macro '.B' for one argument or split argument.
-.-.
Generally:
Split (sometimes) lines after a punctuation mark; before a conjunction.
--- cpio.1 2025-03-04 19:42:08.226952545 +0000
+++ cpio.1.new 2025-03-04 20:06:47.905868849 +0000
@@ -13,11 +13,12 @@
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with GNU cpio. If not, see <http://www.gnu.org/licenses/>.
-.TH CPIO 1 "April 29, 2023" "CPIO" "GNU CPIO"
+.TH CPIO 1 "April 29, 2023" CPIO "GNU CPIO"
.SH NAME
cpio \- copy files to and from archives
.SH SYNOPSIS
.B cpio
+.nf
{\fB\-o\fR|\fB\-\-create\fR} [\fB\-0acvABLV\fR] [\fB\-C\fR \fIBYTES\fR]
[\fB\-H\fR \fIFORMAT\fR] [\fB\-M\fR \fIMESSAGE\fR]
[\fB\-O\fR [[\fIUSER\fB@\fR]\fIHOST\fB:\fR]\fIARCHIVE\fR]
@@ -30,8 +31,10 @@ cpio \- copy files to and from archives
[\fB\-\-io\-size=\fIBYTES\fR] [\fB\-\-quiet\fR]
[\fB\-\-force\-local\fR] [\fB\-\-rsh\-command=\fICOMMAND\fR]
\fB<\fR \fIname-list\fR [\fB>\fR \fIarchive\fR]
+.fi
.B cpio
+.nf
{\fB\-i\fR|\fB\-\-extract\fR} [\fB\-bcdfmnrtsuvBSV\fR] [\fB\-C\fR \fIBYTES\fR]
[\fB\-E\fR \fIFILE\fR] [\fB\-H\fR \fIFORMAT\fR]
[\fB\-M\fR \fIMESSAGE\fR] [\fB\-R\fR [\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]]
@@ -51,8 +54,10 @@ cpio \- copy files to and from archives
[\fB\-\-only\-verify\-crc\fR] [\fB\-\-to\-stdout\fR] [\fB\-\-quiet\fR]
[\fB\-\-rsh\-command=\fICOMMAND\fR]
[\fIpattern\fR...] [\fB<\fR \fIarchive\fR]
+.fi
.B cpio
+.nf
{\fB\-p\fR|\fB\-\-pass\-through\fR} [\fB\-0adlmuvLV\fR]
[\fB\-R\fR [\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]]
[\fB\-\-null\fR] [\fB\-\-reset\-access\-time\fR]
@@ -62,9 +67,12 @@ cpio \- copy files to and from archives
[\fB\-\-owner=\fR[\fIUSER\fR][\fB:.\fR][\fIGROUP\fR]]
[\fB\-\-no\-preserve\-owner\fR] [\fB\-\-sparse\fR]
\fIdestination-directory\fR \fB<\fR \fIname-list\fR
+.fi
.B cpio
+.nf
{\fB\-?\fR|\fB\-\-help\fR|\fB\-\-usage\fR|\fB\-\-version\fR}
+.fi
.SH REPORTING BUGS
Report cpio bugs to bug-c...@gnu.org
.PP
@@ -74,7 +82,7 @@ General help using GNU software: <http:/
.PP
Report cpio translation bugs to <http://translationproject.org/team/>
.SH SEE ALSO
-cpio(5)
+.BR cpio (5)
.SH DESCRIPTION
GNU \fBcpio\fR copies files between archives and directories. It
supports the following archive formats: old binary cpio, old portable
@@ -144,24 +152,24 @@ parentheses gives maximum size for indiv
.RS
.TP
.B bin
-The obsolete binary format. (2147483647 bytes)
+The obsolete binary format. (2.147.483.647 bytes)
.TP
.B odc
-The old (POSIX.1) portable format. (8589934591 bytes)
+The old (POSIX.1) portable format. (8.589.934.591 bytes)
.TP
.B newc
The new (SVR4) portable format, which supports file systems
-having more than 65536 inodes. (4294967295 bytes)
+having more than 65.536 inodes. (4.294.967.295 bytes)
.TP
.B crc
The new (SVR4) portable format with a checksum added.
.TP
.B tar
-The old tar format. (8589934591 bytes)
+The old tar format. (8.589.934.591 bytes)
.TP
.B ustar
The POSIX.1 tar format. Also recognizes GNU tar archives,
-which are similar but not identical. (8589934591 bytes)
+which are similar but not identical. (8.589.934.591 bytes)
.TP
.B hpbin
The obsolete binary format used by HPUX's cpio (which stores
@@ -183,7 +191,7 @@ decimal digits only and, if so, treats t
correspondingly.
To avoid the lookup and ensure that arguments are treated as numeric
-values, prefix them with a plus sign, e.g.: \fB-R +0:+0\fR.
+values, prefix them with a plus sign, e.g.: \fB\-R +0:+0\fR.
.TP
.B \-\-quiet
Do not print the number of blocks copied at the end of the run.
@@ -201,7 +209,7 @@ Print a "\fB.\fR" for each file processe
Controls what warnings are displayed. The \fIFLAG\fR is one of
.BR none ,
to disable all warnings,
-.BR all
+.B all
to enable them,
.BR truncate ,
to enable warnings about field truncation, and
@@ -328,17 +336,17 @@ Write files with large blocks of zeros a
.TP
.BR \-u ", " \-\-unconditional
Replace all files unconditionally.
-.SH "RETURN VALUE"
+.SH RETURN VALUE
GNU \fBcpio\fR exits with code \fB0\fR if it was able to successfully
complete the requested operation. On errors, it exits with code \fB2\fR.
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR tar (1),
.BR rmt (8),
.BR mt (1).
-.SH "BUG REPORTS"
+.SH BUG REPORTS
Report bugs to <bug\-c...@gnu.org>.
.SH COPYRIGHT
-Copyright \(co 2014--2023 Free Software Foundation, Inc.
+Copyright \(co 2014\(en2023 Free Software Foundation, Inc.
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
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
-.-
Any "autogenerator" should check its products with the above mentioned
'groff', 'mandoc', and additionally with 'nroff ...'.
It should also check its input files for too long (> 80) lines.
This is just a simple quality control measure.
The "autogenerator" may have to be corrected to get a better man page,
the source file may, and any additional file may.
Common defects:
Not removing trailing spaces (in in- and output).
The reason for these trailing spaces should be found and eliminated.
"git" has a "tool" to point out whitespace,
see for example "git-apply(1)" and git-config(1)")
Not beginning each input sentence on a new line.
Line length and patch size should thus be reduced.
The script "reportbug" uses 'quoted-printable' encoding when a line is
longer than 1024 characters in an 'ascii' file.
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 -d -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 from 'diff -d -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)
-.-
