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 IwhenP 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 -- -- You received this message from the "vim_dev" maillist. Do not top-post! Type your reply below the text you are replying to. For more information, visit http://www.vim.org/maillist.php --- You received this message because you are subscribed to the Google Groups "vim_dev" group. To unsubscribe from this group and stop receiving emails from it, send an email to vim_dev+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/vim_dev/E1qngsW-005uMJ-Fo%40256bit.org.