Package: xxd
Version: 2:9.1.0496-1+b1
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>':150
troff:<stdin>:150: warning: trailing space in the line
troff: backtrace: file '<stdin>':267
troff:<stdin>:267: warning: trailing space in the line
troff: backtrace: file '<stdin>':275
troff:<stdin>:275: warning: trailing space in the line
troff: backtrace: file '<stdin>':279
troff:<stdin>:279: warning: trailing space in the line
troff: backtrace: file '<stdin>':281
troff:<stdin>:281: warning: trailing space in the line
* What outcome did you expect instead?
No output (no warnings).
-.-
General remarks and further material (declared as a "diff" file) are in the
attachments.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.9.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 xxd depends on:
ii libc6 2.39-6
xxd recommends no packages.
xxd suggests no packages.
-- no debconf information
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 errors:
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
(that is not confined to a markup)
in the first column.
Line length should thus be reduced.
-.-
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 xxd.1": (possibly shortened list)
mandoc: xxd.1:57:2: WARNING: skipping paragraph macro: PP empty
mandoc: xxd.1:149:36: STYLE: unterminated quoted argument
mandoc: xxd.1:150:9: STYLE: whitespace at end of input line
mandoc: xxd.1:177:2: WARNING: skipping paragraph macro: PP after SH
mandoc: xxd.1:193:143: STYLE: input text line longer than 80 bytes: hex dump
with xxd \-...
mandoc: xxd.1:227:97: STYLE: input text line longer than 80 bytes: The author
prefers t...
mandoc: xxd.1:229:2: WARNING: skipping paragraph macro: PP after SH
mandoc: xxd.1:230:2: WARNING: skipping paragraph macro: br after PP
mandoc: xxd.1:236:2: WARNING: skipping paragraph macro: br after PP
mandoc: xxd.1:242:2: WARNING: skipping paragraph macro: br after PP
mandoc: xxd.1:258:2: WARNING: skipping paragraph macro: br before sp
mandoc: xxd.1:260:2: WARNING: skipping paragraph macro: br after sp
mandoc: xxd.1:267:52: STYLE: whitespace at end of input line
mandoc: xxd.1:275:53: STYLE: whitespace at end of input line
mandoc: xxd.1:279:53: STYLE: whitespace at end of input line
mandoc: xxd.1:281:52: STYLE: whitespace at end of input line
mandoc: xxd.1:285:2: WARNING: skipping paragraph macro: br after PP
mandoc: xxd.1:292:2: WARNING: skipping paragraph macro: br after PP
mandoc: xxd.1:300:2: WARNING: skipping paragraph macro: br before sp
mandoc: xxd.1:302:2: WARNING: skipping paragraph macro: br after sp
mandoc: xxd.1:311:2: WARNING: skipping paragraph macro: br after PP
mandoc: xxd.1:317:2: WARNING: skipping paragraph macro: br after PP
mandoc: xxd.1:359:2: WARNING: skipping paragraph macro: PP empty
mandoc: xxd.1:385:2: WARNING: skipping paragraph macro: br at the end of SH
mandoc: xxd.1:389:2: WARNING: skipping paragraph macro: br at the end of SH
mandoc: xxd.1:393:2: WARNING: skipping paragraph macro: br after SH
mandoc: xxd.1:410:2: WARNING: skipping paragraph macro: PP empty
-.-.
Remove space characters at the end of lines.
Use "git apply ... --whitespace=fix" to fix extra space issues, or use
global configuration "core.whitespace".
150:When the
267:000000c: 7567 7573 7420 3139 3936 2220 ugust 1996"
275:000003c: 6179 2031 3939 360a 2e5c 2220 ay 1996..\\"
279:0000054: 686f 723a 0a2e 5c22 2020 2020 hor:..\\"
281:0000060: 546f 6e79 204e 7567 656e 7420 Tony Nugent
-.-.
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.
xxd.1.new:380:(c) 1990-1997 by Juergen Weigert
-.-
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.
218:the 1k where dd left off.
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
86:.IR \-e
151:.BR $NO_COLOR
-.-.
Use "\e" to print the escape character instead of "\\" (which gets
interpreted in copy mode).
273:0000030: 220a 2e5c 2220 3231 7374 204d "..\\" 21st M
275:000003c: 6179 2031 3939 360a 2e5c 2220 ay 1996..\\"
279:0000054: 686f 723a 0a2e 5c22 2020 2020 hor:..\\"
-.-.
Use a macro to change to the italic font, instead of \fI, if
possible (see man-pages(7)).
The macros have the italic corrections, but "\c" removes the "\/" part,
which is in the macro.
So "\/" must be added between the italic argument and the "\c" string.
Or
add the italic corrections.
.NB
Too many cases to be included in a patch
04:in normal mode, \fI4\fP in little-endian mode and \fI1\fP in bits mode.
121:\fIname\fP and the length is named \fIname\fP_len.
165:\fI+ \fRindicates that the seek is relative to the current stdin file
position
166:(meaningless when not reading from stdin). \fI\- \fRindicates that the seek
168:\fI+\fR: before the current stdin file position).
197:\fI% xxd \-i file\fR
201:\fI% xxd \-i < file\fR
214:\fI% sh \-c "cat > plain_copy; xxd \-s 0 > hex_copy" < file\fR
220:\fI% sh \-c "dd of=plain_snippet bs=1k count=1; xxd \-s +128 > hex_snippet"
< file\fR
224:\fI% sh \-c "dd of=plain_snippet bs=1k count=1; xxd \-s +\-768 >
hex_snippet" < file\fR
234:\fI% xxd \-s 0x30 file\fR
240:\fI% xxd \-s \-0x30 file\fR
245:\fI% xxd \-l 120 \-ps \-c 20 xxd.1\fR
263:\fI% xxd \-l 120 \-c 12 xxd.1\fR
288:\fI% xxd \-s 0x36 \-l 13 \-c 13 xxd.1\fR
299:\fI% xxd input_file | xxd \-r \-s 100 > output_file\fR
305:\fI% echo "0000037: 3574 68" | xxd \-r \- xxd.1\fR
307:\fI% xxd \-s 0x36 \-l 13 \-c 13 xxd.1\fR
315:\fI% echo "010000: 41" | xxd \-r > file\fR
320:\fI% xxd \-a \-c 12 file\fR
332:\fI% echo "010000: 41" | xxd \-r \-s \-0x10000 > file\fR
338:\fI:'a,'z!xxd\fR
344:\fI:'a,'z!xxd \-r\fR
350:\fI!!xxd \-r\fR
354:\fI% xxd \-c1 < /dev/term/b &\fR
356:\fI% stty < /dev/term/b \-echo \-opost \-isig \-icanon min 1\fR
358:\fI% echo \-n foo > /dev/term/b\fR
-.-.
Wrong distance between sentences.
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.
N.B.
The number of lines affected can be too large to be in the patch.
65:hexadecimal dump. Each line is preceded by a line number in hexadecimal and
66:followed by an ASCII (or EBCDIC) representation. The command line switches
72:octets per line. Default 16 (\-i: 12, \-ps: 30, \-b: 6). Max 256.
73:No maximum for \-ps. With \-ps, 0 results in one long line of output.
83:This does not change the hexadecimal representation. The option is
111:Output in C include file style. A complete static array definition is
written
120:Override the variable name output when \-i is used. The array is named
129:Output in PostScript continuous hex dump style. Also known as plain hex dump
135:it. Use the combination
138:particular column layout. Additional whitespace and line breaks are allowed
139:anywhere. Use the combination
145:depending on the hex-value. Mostly helping to differentiate printable and
164:bytes abs. (or rel.) infile offset.
172:Use upper-case hex letters. Default is lower-case.
181:hex dump line may be out of order, lines may be missing, or overlapping. In
182:these cases xxd will lseek(2) to the next position. If the output file is
not
186:never generates parse errors. Garbage is silently skipped.
191:data (see option \-c). This also means that changes to the printable ASCII
(or
192:EBCDIC) columns are always ignored. Reverting a plain (or PostScript) style
193:hex dump with xxd \-r \-p does not depend on the correct number of columns.
Here, anything that looks like a pair of hex digits is interpreted.
388:Use entirely at your own risk. Copy files. Trace it. Become a wizard.
-.-.
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 193, length 143
hex dump with xxd \-r \-p does not depend on the correct number of columns.
Here, anything that looks like a pair of hex digits is interpreted.
Line 220, length 85
\fI% sh \-c "dd of=plain_snippet bs=1k count=1; xxd \-s +128 > hex_snippet" <
file\fR
Line 224, length 87
\fI% sh \-c "dd of=plain_snippet bs=1k count=1; xxd \-s +\-768 > hex_snippet" <
file\fR
Line 227, length 97
The author prefers to monitor the effect of xxd with strace(1) or truss(1),
whenever \-s is used.
-.-.
The section part for a manual page is set in roman font.
335:.B vim(1)
341:.B vim(1)
347:.B vim(1)
-.-.
Name of a manual is set in bold, the section in roman.
See man-pages(7).
335:.B vim(1)
341:.B vim(1)
347:.B vim(1)
384:uuencode(1), uudecode(1), patch(1)
-.-.
Output from "test-groff -b -mandoc -rF0 -rHY=0 -K utf8 -t -ww -z ":
troff: backtrace: file '<stdin>':150
troff:<stdin>:150: warning: trailing space in the line
troff: backtrace: file '<stdin>':267
troff:<stdin>:267: warning: trailing space in the line
troff: backtrace: file '<stdin>':275
troff:<stdin>:275: warning: trailing space in the line
troff: backtrace: file '<stdin>':279
troff:<stdin>:279: warning: trailing space in the line
troff: backtrace: file '<stdin>':281
troff:<stdin>:281: warning: trailing space in the line
--- xxd.1 2024-07-29 22:34:14.003303678 +0000
+++ xxd.1.new 2024-07-29 23:42:27.852382837 +0000
@@ -54,7 +54,6 @@ Thus
and
.B \-cols 8
are all equivalent.
-.PP
.TP
.IR \-a " | " \-autoskip
Toggle autoskip: A single '*' replaces NUL-lines. Default off.
@@ -83,7 +82,7 @@ Change the character encoding in the rig
This does not change the hexadecimal representation. The option is
meaningless in combinations with \-r, \-p or \-i.
.TP
-.IR \-e
+.I \-e
Switch to little-endian hex dump.
This option treats byte groups as words in little-endian byte order.
The default grouping of 4 bytes may be changed using
@@ -146,9 +145,9 @@ depending on the hex-value. Mostly helpi
non-printable characters.
.I \fIwhen\fP
is
-.BR never ", " always ", or " auto " (default: auto).
-When the
-.BR $NO_COLOR
+.BR never ", " always ", or " auto " (default: auto)."
+When the
+.B $NO_COLOR
environment variable is set, colorization will be disabled.
.TP
.I \-seek offset
@@ -174,7 +173,6 @@ Use upper-case hex letters. Default is l
.IR \-v " | " \-version
Show version string.
.SH CAVEATS
-.PP
.I xxd \-r
has some built-in magic while evaluating line number information.
If the output file is seekable, then the line numbers at the start of each
@@ -190,7 +188,8 @@ When editing hex dumps, please note that
skips everything on the input line after reading enough columns of hexadecimal
data (see option \-c). This also means that changes to the printable ASCII (or
EBCDIC) columns are always ignored. Reverting a plain (or PostScript) style
-hex dump with xxd \-r \-p does not depend on the correct number of columns.
Here, anything that looks like a pair of hex digits is interpreted.
+hex dump with xxd \-r \-p does not depend on the correct number of columns.
+Here, anything that looks like a pair of hex digits is interpreted.
.PP
Note the difference between
.br
@@ -215,31 +214,30 @@ end of stdin.
.PP
Hex dump from file position 0x480 (=1024+128) onwards.
The `+' sign means "relative to the current position", thus the `128' adds to
-the 1k where dd left off.
+the 1\ kibibyte (KiB) where dd left off.
.br
-\fI% sh \-c "dd of=plain_snippet bs=1k count=1; xxd \-s +128 > hex_snippet" <
file\fR
+\fI% sh \-c "dd of=plain_snippet bs=1k count=1; xxd \-s +128 > hex_snippet" \
+< file\fR
.PP
Hex dump from file position 0x100 (=1024\-768) onwards.
.br
-\fI% sh \-c "dd of=plain_snippet bs=1k count=1; xxd \-s +\-768 > hex_snippet"
< file\fR
+\fI% sh \-c "dd of=plain_snippet bs=1k count=1; xxd \-s +\-768 > hex_snippet" \
+< file\fR
.PP
However, this is a rare situation and the use of `+' is rarely needed.
-The author prefers to monitor the effect of xxd with strace(1) or truss(1),
whenever \-s is used.
+The author prefers to monitor the effect of xxd with strace(1) or truss(1),
+whenever \-s is used.
.SH EXAMPLES
-.PP
-.br
Print everything but the first three lines (hex 0x30 bytes) of
.BR file .
.br
\fI% xxd \-s 0x30 file\fR
.PP
-.br
Print 3 lines (hex 0x30 bytes) from the end of
.BR file .
.br
\fI% xxd \-s \-0x30 file\fR
.PP
-.br
Print 120 bytes as a continuous hex dump with 20 octets per line.
.br
\fI% xxd \-l 120 \-ps \-c 20 xxd.1\fR
@@ -255,41 +253,37 @@ Print 120 bytes as a continuous hex dump
20617574686f723a0a2e5c2220202020546f6e79
.br
204e7567656e74203c746f6e79407363746e7567
-.br
-.br
Hex dump the first 120 bytes of this man page with 12 octets per line.
.br
\fI% xxd \-l 120 \-c 12 xxd.1\fR
.br
0000000: 2e54 4820 5858 4420 3120 2241 .TH XXD 1 "A
.br
-000000c: 7567 7573 7420 3139 3936 2220 ugust 1996"
+000000c: 7567 7573 7420 3139 3936 2220 ugust 1996"
.br
0000018: 224d 616e 7561 6c20 7061 6765 "Manual page
.br
-0000024: 2066 6f72 2078 7864 220a 2e5c for xxd"..\\
+0000024: 2066 6f72 2078 7864 220a 2e5c for xxd"..\e
.br
-0000030: 220a 2e5c 2220 3231 7374 204d "..\\" 21st M
+0000030: 220a 2e5c 2220 3231 7374 204d "..\e" 21st M
.br
-000003c: 6179 2031 3939 360a 2e5c 2220 ay 1996..\\"
+000003c: 6179 2031 3939 360a 2e5c 2220 ay 1996..\e"
.br
0000048: 4d61 6e20 7061 6765 2061 7574 Man page aut
.br
-0000054: 686f 723a 0a2e 5c22 2020 2020 hor:..\\"
+0000054: 686f 723a 0a2e 5c22 2020 2020 hor:..\e"
.br
-0000060: 546f 6e79 204e 7567 656e 7420 Tony Nugent
+0000060: 546f 6e79 204e 7567 656e 7420 Tony Nugent
.br
000006c: 3c74 6f6e 7940 7363 746e 7567 <tony@sctnug
.PP
-.br
Display just the date from the file xxd.1
.br
\fI% xxd \-s 0x36 \-l 13 \-c 13 xxd.1\fR
.br
0000036: 3231 7374 204d 6179 2031 3939 36 21st May 1996
.PP
-.br
Copy
.B input_file
to
@@ -297,9 +291,7 @@ to
and prepend 100 bytes of value 0x00.
.br
\fI% xxd input_file | xxd \-r \-s 100 > output_file\fR
-.br
-.br
Patch the date in the file xxd.1
.br
\fI% echo "0000037: 3574 68" | xxd \-r \- xxd.1\fR
@@ -308,13 +300,11 @@ Patch the date in the file xxd.1
.br
0000036: 3235 7468 204d 6179 2031 3939 36 25th May 1996
.PP
-.br
Create a 65537 byte file with all bytes 0x00,
except for the last one which is 'A' (hex 0x41).
.br
\fI% echo "010000: 41" | xxd \-r > file\fR
.PP
-.br
Hex dump this file with autoskip.
.br
\fI% xxd \-a \-c 12 file\fR
@@ -332,19 +322,19 @@ in effect, the leading bytes are suppres
\fI% echo "010000: 41" | xxd \-r \-s \-0x10000 > file\fR
.PP
Use xxd as a filter within an editor such as
-.B vim(1)
+.BR vim (1)
to hex dump a region marked between `a' and `z'.
.br
\fI:'a,'z!xxd\fR
.PP
Use xxd as a filter within an editor such as
-.B vim(1)
+.BR vim (1)
to recover a binary hex dump marked between `a' and `z'.
.br
\fI:'a,'z!xxd \-r\fR
.PP
Use xxd as a filter within an editor such as
-.B vim(1)
+.BR vim (1)
to recover one line of a hex dump. Move the cursor over the line and type:
.br
\fI!!xxd \-r\fR
@@ -356,7 +346,6 @@ Read single characters from a serial lin
\fI% stty < /dev/term/b \-echo \-opost \-isig \-icanon min 1\fR
.br
\fI% echo \-n foo > /dev/term/b\fR
-.PP
.SH "RETURN VALUES"
The following error values are returned:
.TP
@@ -381,17 +370,14 @@ problems with output file.
4,5
desired seek position is unreachable.
.SH "SEE ALSO"
-uuencode(1), uudecode(1), patch(1)
-.br
+.BR uuencode "(1), " uudecode "(1), " patch (1)
.SH WARNINGS
The tool's weirdness matches its creator's brain.
Use entirely at your own risk. Copy files. Trace it. Become a wizard.
-.br
.SH VERSION
This manual page documents xxd version 1.7
.SH AUTHOR
-.br
-(c) 1990-1997 by Juergen Weigert
+(c) 1990\(en1997 by Juergen Weigert
.br
<[email protected]\-erlangen.de>
.LP
@@ -407,4 +393,3 @@ Manual page started by Tony Nugent
.br
Small changes by Bram Moolenaar.
Edited by Juergen Weigert.
-.PP
