Package: xxd
Version: 2:9.0.1672-1
Severity: minor
Tags: patch
Dear Maintainer,
here are some notes and editorial fixes for the man page.
The patch is in the attachment.
-.-.
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
"groff -man -Z" instead of "nroff -man"
-.-.
Output from "mandoc -T lint xxd.1":
mandoc: xxd.1:57:2: WARNING: skipping paragraph macro: PP empty
mandoc: xxd.1:161:2: WARNING: skipping paragraph macro: PP after SH
mandoc: xxd.1:177:141: STYLE: input text line longer than 80 bytes: hexdump
with xxd \-r...
mandoc: xxd.1:211:97: STYLE: input text line longer than 80 bytes: The author
prefers t...
mandoc: xxd.1:213:2: WARNING: skipping paragraph macro: PP after SH
mandoc: xxd.1:214:2: WARNING: skipping paragraph macro: br after PP
mandoc: xxd.1:220:2: WARNING: skipping paragraph macro: br after PP
mandoc: xxd.1:226:2: WARNING: skipping paragraph macro: br after PP
mandoc: xxd.1:242:2: WARNING: skipping paragraph macro: br before sp
mandoc: xxd.1:244:2: WARNING: skipping paragraph macro: br after sp
mandoc: xxd.1:251:52: STYLE: whitespace at end of input line
mandoc: xxd.1:259:53: STYLE: whitespace at end of input line
mandoc: xxd.1:263:53: STYLE: whitespace at end of input line
mandoc: xxd.1:265:52: STYLE: whitespace at end of input line
mandoc: xxd.1:269:2: WARNING: skipping paragraph macro: br after PP
mandoc: xxd.1:276:2: WARNING: skipping paragraph macro: br after PP
mandoc: xxd.1:284:2: WARNING: skipping paragraph macro: br before sp
mandoc: xxd.1:286:2: WARNING: skipping paragraph macro: br after sp
mandoc: xxd.1:295:2: WARNING: skipping paragraph macro: br after PP
mandoc: xxd.1:301:2: WARNING: skipping paragraph macro: br after PP
mandoc: xxd.1:343:2: WARNING: skipping paragraph macro: PP empty
mandoc: xxd.1:368:2: WARNING: skipping paragraph macro: br at the end of SH
mandoc: xxd.1:372:2: WARNING: skipping paragraph macro: br at the end of SH
mandoc: xxd.1:376:2: WARNING: skipping paragraph macro: br after SH
mandoc: xxd.1:393:2: WARNING: skipping paragraph macro: PP empty
-.-.
Add a (no-break, "\ " or "\~") space between a number and a unit,
as these are not one entity.'
202:the 1k where dd left off.
-.-.
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.
148:bytes abs. (or rel.) infile offset.
-.-.
Use the correct macro for the font change of a single argument or
split the argument into two.
83:.IR \-e
-.-.
Use "\e" to print the escape character instead of "\\" (which gets
interpreted in copy mode).
257:0000030: 220a 2e5c 2220 3231 7374 204d "..\\" 21st M
259:000003c: 6179 2031 3939 360a 2e5c 2220 ay 1996..\\"
263:0000054: 686f 723a 0a2e 5c22 2020 2020 hor:..\\"
-.-.
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.
The amount of space between sentences in the output can then be
controlled with the ".ss" request.
N.B
The number of lines affected is 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 maxmimum for \-ps. With \-ps, 0 results in one long line of output.
80:This does not change the hexadecimal representation. The option is
108:Output in C include file style. A complete static array definition is
written
117:Override the variable name output when \-i is used. The array is named
126:Output in postscript continuous hexdump style. Also known as plain hexdump
132:it. Use the combination
135:particular column layout. Additional Whitespace and line-breaks are allowed
148:bytes abs. (or rel.) infile offset.
156:Use upper case hex letters. Default is lower case.
165:hexdump line may be out of order, lines may be missing, or overlapping. In
166:these cases xxd will lseek(2) to the next position. If the output file is
not
170:never generates parse errors. Garbage is silently skipped.
175:data (see option \-c). This also means, that changes to the printable ascii
(or
176:ebcdic) columns are always ignored. Reverting a plain (or postscript) style
177:hexdump 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.
371:Use entirely at your own risk. Copy files. Trace it. Become a wizard.
-.-.
Split lines longer than 100 characters into two or more lines.
Appropriate break points are the end of a sentence and a subordinate
clause; after punctuation marks.
xxd.1: line 177 length 141
hexdump 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.
-.-.
The name of a man page is set in bold type and the section in roman (see
man-pages(7)).
166:these cases xxd will lseek(2) to the next position. If the output file is
not
190:as lseek(2) is used to "rewind" input. A '+'
211:The author prefers to monitor the effect of xxd with strace(1) or truss(1),
whenever \-s is used.
367:uuencode(1), uudecode(1), patch(1)
-.-.
Protect a period (.) or a apostrophe (') with '\&' from becoming a
control character, if it could end up at the start of a line (by
splitting the line into more lines).
60:Toggle autoskip: A single '*' replaces nul-lines. Default off.
190:as lseek(2) is used to "rewind" input. A '+'
312:Create a 1 byte file containing a single 'A' character.
313:The number after '\-r \-s' adds to the linenumbers found in the file;
-.-.
Name of a manual is set in bold, the section in roman.
See man-pages(7).
319:.B vim(1)
325:.B vim(1)
331:.B vim(1)
367:uuencode(1), uudecode(1), patch(1)
-.-.
Output from "test-nroff -man -b -ww -z -rCHECKSTYLE=3":
[ "test-groff" is a developmental version of "groff" ]
Input file is ./xxd.1
Output from "test-groff -b -mandoc -dAD=l -rF0 -rHY=0 -t -w w -z
-rSTYLECHECK=3":
an.tmac:<stdin>:83: style: .IR expects at least 2 arguments, got 1
troff: backtrace: file '<stdin>':251
troff:<stdin>:251: warning: trailing space in the line
troff: backtrace: file '<stdin>':259
troff:<stdin>:259: warning: trailing space in the line
troff: backtrace: file '<stdin>':263
troff:<stdin>:263: warning: trailing space in the line
troff: backtrace: file '<stdin>':265
troff:<stdin>:265: warning: trailing space in the line
-.-.
-- System Information:
Debian Release: trixie/sid
APT prefers testing
APT policy: (500, 'testing')
Architecture: amd64 (x86_64)
Kernel: Linux 6.3.7-1 (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.37-3
xxd recommends no packages.
xxd suggests no packages.
-- no debconf information
--- xxd.1 2023-07-08 20:53:12.000000000 +0000
+++ xxd.1.new 2023-07-08 21:15:03.000000000 +0000
@@ -54,10 +54,9 @@ Thus
and
.B \-cols 8
are all equivalent.
-.PP
.TP
.IR \-a " | " \-autoskip
-Toggle autoskip: A single '*' replaces nul-lines. Default off.
+Toggle autoskip: A single \&'*' replaces nul-lines. Default off.
.TP
.IR \-b " | " \-bits
Switch to bits (binary digits) dump, rather than hexdump.
@@ -80,7 +79,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 hexdump.
This option treats byte groups as words in little-endian byte order.
The default grouping of 4 bytes may be changed using
@@ -145,7 +144,7 @@ added to file positions found in hexdump
.I \-s [+][\-]seek
Start at
.RI < seek >
-bytes abs. (or rel.) infile offset.
+bytes abs.\& (or rel.\&) infile offset.
\fI+ \fRindicates that the seek is relative to the current stdin file position
(meaningless when not reading from stdin). \fI\- \fRindicates that the seek
should be that many characters from the end of the input (or if combined with
@@ -158,12 +157,13 @@ Use upper case hex letters. Default is l
.IR \-v " | " \-version
Show version string.
.SH CAVEATS
-.PP
.I xxd \-r
has some builtin magic while evaluating line number information.
If the output file is seekable, then the linenumbers at the start of each
hexdump line may be out of order, lines may be missing, or overlapping. In
-these cases xxd will lseek(2) to the next position. If the output file is not
+these cases xxd will
+.BR lseek (2)
+to the next position. If the output file is not
seekable, only gaps are allowed, which will be filled by null-bytes.
.PP
.I xxd \-r
@@ -174,7 +174,9 @@ When editing hexdumps, 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
-hexdump 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.
+hexdump 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
@@ -187,7 +189,9 @@ and
.I xxd \-s +seek
may be different from
.IR "xxd \-s seek" ,
-as lseek(2) is used to "rewind" input. A '+'
+as
+.BR lseek (2)
+is used to "rewind" input. A \&'+'
makes a difference if the input source is stdin, and if stdin's file position
is not at the start of the file by the time xxd is started and given its input.
The following examples may help to clarify (or further confuse!)...
@@ -199,7 +203,7 @@ end of stdin.
.PP
Hexdump 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\~k where dd left off.
.br
\fI% sh \-c "dd of=plain_snippet bs=1k count=1; xxd \-s +128 > hex_snippet" <
file\fR
.PP
@@ -208,10 +212,12 @@ Hexdump from file position 0x100 ( = 102
\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
+.BR strace (1)
+or
+.BR truss (1),
+whenever \-s is used.
.SH EXAMPLES
-.PP
-.br
Print everything but the first three lines (hex 0x30 bytes) of
.BR file .
.br
@@ -223,7 +229,6 @@ Print 3 lines (hex 0x30 bytes) from the
.br
\fI% xxd \-s \-0x30 file\fR
.PP
-.br
Print 120 bytes as continuous hexdump with 20 octets per line.
.br
\fI% xxd \-l 120 \-ps \-c 20 xxd.1\fR
@@ -239,30 +244,28 @@ Print 120 bytes as continuous hexdump wi
20617574686f723a0a2e5c2220202020546f6e79
.br
204e7567656e74203c746f6e79407363746e7567
-.br
-.br
Hexdump 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
@@ -273,7 +276,6 @@ Display just the date from the file xxd.
.br
0000036: 3231 7374 204d 6179 2031 3939 36 21st May 1996
.PP
-.br
Copy
.B input_file
to
@@ -281,9 +283,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
@@ -292,13 +292,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
Hexdump this file with autoskip.
.br
\fI% xxd \-a \-c 12 file\fR
@@ -309,26 +307,26 @@ Hexdump this file with autoskip.
.br
000fffc: 0000 0000 40 ....A
.PP
-Create a 1 byte file containing a single 'A' character.
-The number after '\-r \-s' adds to the linenumbers found in the file;
+Create a 1 byte file containing a single \&'A' character.
+The number after \&'\-r \-s' adds to the linenumbers found in the file;
in effect, the leading bytes are suppressed.
.br
\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 hexdump 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 hexdump 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 hexdump. Move the cursor over the line and type:
.br
\fI!!xxd \-r\fR
@@ -340,7 +338,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
@@ -364,7 +361,9 @@ problems with output file.
4,5
desired seek position is unreachable.
.SH "SEE ALSO"
-uuencode(1), uudecode(1), patch(1)
+.BR uuencode (1),
+.BR uudecode (1),
+.BR patch (1)
.br
.SH WARNINGS
The tools weirdness matches its creators brain.
@@ -390,4 +389,3 @@ Manual page started by Tony Nugent
.br
Small changes by Bram Moolenaar.
Edited by Juergen Weigert.
-.PP
