I noticed a few more inconsistencies in the description of the various --zero options, so I amended to the attached.
cheers, Pádraig.
>From 54d17616c3e7e45a634adbfa3cf73087b435d51d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email protected]> Date: Fri, 23 May 2014 00:45:57 +0100 Subject: [PATCH] doc: clarify --zero-terminated option * src/join.c (usage): Reword to avoid implication that the NUL byte is only generated as the output delimeter. * src/sort.c (usage): Likewise. * src/shuf.c (usage): Likewise. Also since we're changing the translation string take the opportunity to separate out the description to a separate string to reduce translation overhead. * src/uniq.c (usage): Likewise. * src/stty.c (usage): s/null/NUL/ for consistency. * src/basename.c (usage): Reword for accuracy/consistency. * src/dirname.c (usage): Likewise. * src/du.c (usage): Likewise. * src/env.c (usage): Likewise. * src/printenv.c (usage): Likewise. * src/readlink.c (usage): Likewise. * src/realpath.c (usage): Likewise. * doc/coreutils.texi: Consolidate/share the descriptions of --null, --zero and --zero-terminated. --- doc/coreutils.texi | 116 +++++++++++++++++++++++++--------------------------- src/basename.c | 2 +- src/dirname.c | 2 +- src/du.c | 2 +- src/env.c | 2 +- src/join.c | 2 +- src/printenv.c | 2 +- src/readlink.c | 2 +- src/realpath.c | 2 +- src/shuf.c | 4 +- src/sort.c | 2 +- src/stty.c | 2 +- src/uniq.c | 4 +- 13 files changed, 72 insertions(+), 72 deletions(-) diff --git a/doc/coreutils.texi b/doc/coreutils.texi index 592f4a6..d56642f 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -582,16 +582,42 @@ Do not treat the last operand specially when it is a directory or a symbolic link to a directory. @xref{Target directory}. @end macro -@macro optNull{cmd} -@item -0 -@opindex -0 -@itemx --null -@opindex --null +@macro outputNUL @cindex output NUL-byte-terminated lines Output a zero byte (ASCII NUL) at the end of each line, rather than a newline. This option enables other programs to parse the -output of @command{\cmd\} even when that output would contain data -with embedded newlines. +output even when that output would contain data with embedded newlines. +@end macro + +@macro optNull +@item -0 +@itemx --null +@opindex -0 +@opindex --null +@outputNUL +@end macro + +@macro optZero +@item -z +@itemx --zero +@opindex -z +@opindex --zero +@outputNUL +@end macro + +@macro optZeroTerminated +@item -z +@itemx --zero-terminated +@opindex -z +@opindex --zero-terminated +@cindex process zero-terminated items +Delimit items with a zero byte rather than a newline (ASCII LF). +I.e., treat input as items separated by ASCII NUL +and terminate output items with ASCII NUL. +This option can be useful in conjunction with @samp{perl -0} or +@samp{find -print0} and @samp{xargs -0} which do the same in order to +reliably handle arbitrary file names (even those containing blanks +or other special characters). @end macro @macro optSi @@ -4673,21 +4699,7 @@ For example, @code{sort -n -u} inspects only the value of the initial numeric string when checking for uniqueness, whereas @code{sort -n | uniq} inspects the entire line. @xref{uniq invocation}. -@macro zeroTerminatedOption -@item -z -@itemx --zero-terminated -@opindex -z -@opindex --zero-terminated -@cindex process zero-terminated items -Delimit items with a zero byte rather than a newline (ASCII LF). -I.e., treat input as items separated by ASCII NUL -and terminate output items with ASCII NUL. -This option can be useful in conjunction with @samp{perl -0} or -@samp{find -print0} and @samp{xargs -0} which do the same in order to -reliably handle arbitrary file names (even those containing blanks -or other special characters). -@end macro -@zeroTerminatedOption +@optZeroTerminated @end table @@ -4974,7 +4986,7 @@ typically combined with @option{--head-count}; if @option{--head-count} is not given, @command{shuf} repeats indefinitely. -@zeroTerminatedOption +@optZeroTerminated @end table @@ -5227,7 +5239,7 @@ Compare at most @var{n} characters on each line (after skipping any specified fields and characters). By default the entire rest of the lines are compared. -@zeroTerminatedOption +@optZeroTerminated @end table @@ -6320,7 +6332,7 @@ character is used to delimit the fields. Print a line for each unpairable line in file @var{file-number} (either @samp{1} or @samp{2}), instead of the normal output. -@zeroTerminatedOption +@optZeroTerminated @end table @@ -10328,11 +10340,7 @@ Suppress most error messages. @opindex --verbose Report error messages. -@item -z -@itemx --zero -@opindex -z -@opindex --zero -Separate output items with NUL characters. +@optZero @end table @@ -11432,7 +11440,7 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@optNull{du} +@optNull @item -a @itemx --all @@ -13222,11 +13230,7 @@ With this, an optional @var{suffix} must be specified using the Remove a trailing @var{suffix}. This option implies the @option{-a} option. -@item -z -@itemx --zero -@opindex -z -@opindex --zero -Separate output items with NUL characters. +@optZero @end table @@ -13281,11 +13285,7 @@ The program accepts the following option. Also see @ref{Common options}. @table @samp -@item -z -@itemx --zero -@opindex -z -@opindex --zero -Separate output items with NUL characters. +@optZero @end table @@ -13618,23 +13618,6 @@ This is the default mode of operation. @opindex --quiet Suppress diagnostic messages for specified file names. -@item -s -@itemx --strip -@itemx --no-symlinks -@opindex -s -@opindex --strip -@opindex --no-symlinks -Do not resolve symbolic links. Only resolve references to -@samp{/./}, @samp{/../} and remove extra @samp{/} characters. -When combined with the @option{-m} option, realpath operates -only on the file name, and does not touch any actual file. - -@item -z -@itemx --zero -@opindex -z -@opindex --zero -Separate output items with NUL characters. - @item --relative-to=@var{file} @opindex --relative-to @cindex relpath @@ -13663,6 +13646,19 @@ realpath --relative-base=/usr /tmp /usr/bin @result{} bin @end example +@item -s +@itemx --strip +@itemx --no-symlinks +@opindex -s +@opindex --strip +@opindex --no-symlinks +Do not resolve symbolic links. Only resolve references to +@samp{/./}, @samp{/../} and remove extra @samp{/} characters. +When combined with the @option{-m} option, realpath operates +only on the file name, and does not touch any actual file. + +@optZero + @end table @cindex exit status of @command{realpath} @@ -14461,7 +14457,7 @@ The program accepts the following option. Also see @ref{Common options}. @table @samp -@optNull{printenv} +@optNull @end table @@ -16291,7 +16287,7 @@ Options must precede operands. @table @samp -@optNull{env} +@optNull @item -u @var{name} @itemx --unset=@var{name} diff --git a/src/basename.c b/src/basename.c index 05c5c77..9521539 100644 --- a/src/basename.c +++ b/src/basename.c @@ -60,7 +60,7 @@ If specified, also remove a trailing SUFFIX.\n\ fputs (_("\ -a, --multiple support multiple arguments and treat each as a NAME\n\ -s, --suffix=SUFFIX remove a trailing SUFFIX; implies -a\n\ - -z, --zero separate output with NUL rather than newline\n\ + -z, --zero end each output line with NUL, not newline\n\ "), stdout); fputs (HELP_OPTION_DESCRIPTION, stdout); fputs (VERSION_OPTION_DESCRIPTION, stdout); diff --git a/src/dirname.c b/src/dirname.c index fa9f87e..e0599a3 100644 --- a/src/dirname.c +++ b/src/dirname.c @@ -57,7 +57,7 @@ removed; if NAME contains no /'s, output '.' (meaning the current directory).\n\ \n\ "), stdout); fputs (_("\ - -z, --zero separate output with NUL rather than newline\n\ + -z, --zero end each output line with NUL, not newline\n\ "), stdout); fputs (HELP_OPTION_DESCRIPTION, stdout); fputs (VERSION_OPTION_DESCRIPTION, stdout); diff --git a/src/du.c b/src/du.c index 890edb6..e4509fd 100644 --- a/src/du.c +++ b/src/du.c @@ -289,7 +289,7 @@ Summarize disk usage of each FILE, recursively for directories.\n\ emit_mandatory_arg_note (); fputs (_("\ - -0, --null end each output line with 0 byte rather than newline\n\ + -0, --null end each output line with NUL, not newline\n\ -a, --all write counts for all files, not just directories\n\ --apparent-size print apparent sizes, rather than disk usage; although\ \n\ diff --git a/src/env.c b/src/env.c index 6a5c246..2b37d98 100644 --- a/src/env.c +++ b/src/env.c @@ -60,7 +60,7 @@ Set each NAME to VALUE in the environment and run COMMAND.\n\ fputs (_("\ -i, --ignore-environment start with an empty environment\n\ - -0, --null end each output line with 0 byte rather than newline\n\ + -0, --null end each output line with NUL, not newline\n\ -u, --unset=NAME remove variable from the environment\n\ "), stdout); fputs (HELP_OPTION_DESCRIPTION, stdout); diff --git a/src/join.c b/src/join.c index fd8f22c..5c26e78 100644 --- a/src/join.c +++ b/src/join.c @@ -218,7 +218,7 @@ by whitespace. When FILE1 or FILE2 (not both) is -, read standard input.\n\ print them without trying to pair them\n\ "), stdout); fputs (_("\ - -z, --zero-terminated end lines with 0 byte, not newline\n\ + -z, --zero-terminated line delimiter is NUL, not newline\n\ "), stdout); fputs (HELP_OPTION_DESCRIPTION, stdout); fputs (VERSION_OPTION_DESCRIPTION, stdout); diff --git a/src/printenv.c b/src/printenv.c index f1e6594..e1faeb5 100644 --- a/src/printenv.c +++ b/src/printenv.c @@ -67,7 +67,7 @@ If no VARIABLE is specified, print name and value pairs for them all.\n\ "), program_name); fputs (_("\ - -0, --null end each output line with 0 byte rather than newline\n\ + -0, --null end each output line with NUL, not newline\n\ "), stdout); fputs (HELP_OPTION_DESCRIPTION, stdout); fputs (VERSION_OPTION_DESCRIPTION, stdout); diff --git a/src/readlink.c b/src/readlink.c index 5a44887..d63f07b 100644 --- a/src/readlink.c +++ b/src/readlink.c @@ -81,7 +81,7 @@ usage (int status) -q, --quiet,\n\ -s, --silent suppress most error messages\n\ -v, --verbose report error messages\n\ - -z, --zero separate output with NUL rather than newline\n\ + -z, --zero end each output line with NUL, not newline\n\ "), stdout); fputs (HELP_OPTION_DESCRIPTION, stdout); fputs (VERSION_OPTION_DESCRIPTION, stdout); diff --git a/src/realpath.c b/src/realpath.c index 4426572..0c55327 100644 --- a/src/realpath.c +++ b/src/realpath.c @@ -83,7 +83,7 @@ all but the last component must exist\n\ --relative-to=FILE print the resolved path relative to FILE\n\ --relative-base=FILE print absolute paths unless paths below FILE\n\ -s, --strip, --no-symlinks don't expand symlinks\n\ - -z, --zero separate output with NUL rather than newline\n\ + -z, --zero end each output line with NUL, not newline\n\ \n\ "), stdout); fputs (HELP_OPTION_DESCRIPTION, stdout); diff --git a/src/shuf.c b/src/shuf.c index 6ae0755..915f7b7 100644 --- a/src/shuf.c +++ b/src/shuf.c @@ -77,7 +77,9 @@ Write a random permutation of the input lines to standard output.\n\ -o, --output=FILE write result to FILE instead of standard output\n\ --random-source=FILE get random bytes from FILE\n\ -r, --repeat output lines can be repeated\n\ - -z, --zero-terminated end lines with 0 byte, not newline\n\ +"), stdout); + fputs (_("\ + -z, --zero-terminated line delimiter is NUL, not newline\n\ "), stdout); fputs (HELP_OPTION_DESCRIPTION, stdout); fputs (VERSION_OPTION_DESCRIPTION, stdout); diff --git a/src/sort.c b/src/sort.c index 3380be6..49caae5 100644 --- a/src/sort.c +++ b/src/sort.c @@ -504,7 +504,7 @@ Other options:\n\ \n\ "), DEFAULT_TMPDIR); fputs (_("\ - -z, --zero-terminated end lines with 0 byte, not newline\n\ + -z, --zero-terminated line delimiter is NUL, not newline\n\ "), stdout); fputs (HELP_OPTION_DESCRIPTION, stdout); fputs (VERSION_OPTION_DESCRIPTION, stdout); diff --git a/src/stty.c b/src/stty.c index 7bb3f51..3c48578 100644 --- a/src/stty.c +++ b/src/stty.c @@ -634,7 +634,7 @@ Output settings:\n\ "), stdout); fputs (_("\ * [-]ocrnl translate carriage return to newline\n\ - * [-]ofdel use delete characters for fill instead of null characters\n\ + * [-]ofdel use delete characters for fill instead of NUL characters\n\ * [-]ofill use fill (padding) characters instead of timing for delays\n\ * [-]olcuc translate lowercase characters to uppercase\n\ * [-]onlcr translate newline to carriage return-newline\n\ diff --git a/src/uniq.c b/src/uniq.c index deba0a3..54200ff 100644 --- a/src/uniq.c +++ b/src/uniq.c @@ -200,7 +200,9 @@ With no options, matching lines are merged to the first occurrence.\n\ -i, --ignore-case ignore differences in case when comparing\n\ -s, --skip-chars=N avoid comparing the first N characters\n\ -u, --unique only print unique lines\n\ - -z, --zero-terminated end lines with 0 byte, not newline\n\ +"), stdout); + fputs (_("\ + -z, --zero-terminated line delimiter is NUL, not newline\n\ "), stdout); fputs (_("\ -w, --check-chars=N compare no more than N characters in lines\n\ -- 1.7.7.6
