Commit: runtime(doc): update xxd manpage and mention $NO_COLOR env

[Christian Brabandt]

runtime(doc): update xxd manpage and mention $NO_COLOR env

Commit: https://github.com/vim/vim/commit/b74ebfc6bf343ed825b111157261a8d99da6d670
Author: Christian Brabandt <c...@256bit.org>
Date: Tue Oct 3 16:55:18 2023 +0200

runtime(doc): update xxd manpage and mention $NO_COLOR env

also regenerate the xxd.man document page.

fixes: #13257

Signed-off-by: Christian Brabandt <c...@256bit.org>

diff --git a/runtime/doc/xxd.1 b/runtime/doc/xxd.1
index e52ef888d..7cd6ae8c7 100644
--- a/runtime/doc/xxd.1
+++ b/runtime/doc/xxd.1
@@ -136,10 +136,15 @@ particular column layout. Additional whitespace and line breaks are allowed
anywhere.
.TP
.IR \-R " " when
-In output the hex-value and the value are both colored with the same color depending on the hex-value. Mostly helping to differentiate printable and non-printable characters.
+In output the hex-value and the value are both colored with the same color
+depending on the hex-value. Mostly helping to differentiate printable and
+non-printable characters.
.I IwhenP
is
.BR never ", " always ", or " auto .
+When the
+.BR $NO_COLOR
+environment variable is set, colorization will be disabled.
.TP
.I \-seek offset
When used after
diff --git a/runtime/doc/xxd.man b/runtime/doc/xxd.man
index 26077265a..06cc784c4 100644
--- a/runtime/doc/xxd.man
+++ b/runtime/doc/xxd.man
@@ -103,7 +103,8 @@ OPTIONS
In output the hex-value and the value are both colored with the
same color depending on the hex-value. Mostly helping to differ‐
entiate printable and non-printable characters. when is never,
- always, or auto.
+ always, or auto. When the $NO_COLOR environment variable is
+ set, colorization will be disabled.

-seek offset
When used after -r: revert with <offset> added to file positions
@@ -111,9 +112,9 @@ OPTIONS

-s [+][-]seek
Start at <seek> bytes abs. (or rel.) infile offset. + indicates
- that the seek is relative to the current stdin file position
+ that the seek is relative to the current stdin file position
(meaningless when not reading from stdin). - indicates that the
- seek should be that many characters from the end of the input
+ seek should be that many characters from the end of the input
(or if combined with +: before the current stdin file position).
Without -s option, xxd starts at the current file position.

@@ -123,20 +124,20 @@ OPTIONS
Show version string.

CAVEATS
- xxd -r has some built-in magic while evaluating line number informa‐
- tion. If the output file is seekable, then the line numbers at the
- start of each hex dump 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 seekable, only gaps are allowed, which will
+ xxd -r has some built-in magic while evaluating line number informa‐
+ tion. If the output file is seekable, then the line numbers at the
+ start of each hex dump 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 seekable, only gaps are allowed, which will
be filled by null-bytes.

xxd -r never generates parse errors. Garbage is silently skipped.

When editing hex dumps, please note that xxd -r 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)
+ -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.
+ 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.

Note the difference between
@@ -144,28 +145,28 @@ CAVEATS
and
% xxd -i < file

- xxd -s +seek may be different from xxd -s seek, as lseek(2) is used to
+ xxd -s +seek may be different from xxd -s seek, as 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
+ 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!):

- Rewind stdin before reading; needed because the `cat' has already read
+ Rewind stdin before reading; needed because the `cat' has already read
to the end of stdin.
% sh -c "cat > plain_copy; xxd -s 0 > hex_copy" < file

- Hex dump from file position 0x480 (=1024+128) onwards. The `+' sign
+ 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.
- % sh -c "dd of=plain_snippet bs=1k count=1; xxd -s +128 > hex_snippet"
+ % sh -c "dd of=plain_snippet bs=1k count=1; xxd -s +128 > hex_snippet"
< file

Hex dump from file position 0x100 (=1024-768) onwards.
% sh -c "dd of=plain_snippet bs=1k count=1; xxd -s +-768 > hex_snippet"
< file

- 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
+ 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.

EXAMPLES
@@ -209,7 +210,7 @@ EXAMPLES
% xxd -s 0x36 -l 13 -c 13 xxd.1
0000036: 3235 7468 204d 6179 2031 3939 36 25th May 1996

- Create a 65537 byte file with all bytes 0x00, except for the last one
+ Create a 65537 byte file with all bytes 0x00, except for the last one
which is 'A' (hex 0x41).
% echo "010000: 41" | xxd -r > file

@@ -220,11 +221,11 @@ EXAMPLES
000fffc: 0000 0000 40 ....A

Create a 1 byte file containing a single 'A' character. The number af‐
- ter '-r -s' adds to the line numbers found in the file; in effect, the
+ ter '-r -s' adds to the line numbers found in the file; in effect, the
leading bytes are suppressed.
% echo "010000: 41" | xxd -r -s -0x10000 > file

- Use xxd as a filter within an editor such as vim(1) to hex dump a re‐
+ Use xxd as a filter within an editor such as vim(1) to hex dump a re‐
gion marked between `a' and `z'.
:'a,'z!xxd