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.
This commit is contained in:
Pádraig Brady committed 2014-05-26 12:31:50 +01:00
1 parent 347b392bd0
commit 442fafa54c
13 files changed
+72 -72

No files matched your search

+56 -60
View File
@@ -583,16 +583,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
@@ -4674,21 +4700,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
@@ -4975,7 +4987,7 @@ typically combined with @option{--head-count}; if
@option{--head-count} is not given, @command{shuf} repeats
indefinitely.
@zeroTerminatedOption
@optZeroTerminated
@end table
@@ -5228,7 +5240,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
@@ -6321,7 +6333,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
@@ -10329,11 +10341,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
@@ -11433,7 +11441,7 @@ The program accepts the following options. Also see @ref{Common options}.
@table @samp
@optNull{du}
@optNull
@item -a
@itemx --all
@@ -13223,11 +13231,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
@@ -13282,11 +13286,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
@@ -13619,23 +13619,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
@@ -13664,6 +13647,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}
@@ -14462,7 +14458,7 @@ The program accepts the following option. Also see @ref{Common options}.
@table @samp
@optNull{printenv}
@optNull
@end table
@@ -16292,7 +16288,7 @@ Options must precede operands.
@table @samp
@optNull{env}
@optNull
@item -u @var{name}
@itemx --unset=@var{name}
+1 -1
View File
@@ -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);
+1 -1
View File
@@ -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);
+1 -1
View File
@@ -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\
+1 -1
View File
@@ -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);
+1 -1
View File
@@ -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);
+1 -1
View File
@@ -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);
+1 -1
View File
@@ -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);
+1 -1
View File
@@ -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);
+3 -1
View File
@@ -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);
+1 -1
View File
@@ -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);
+1 -1
View File
@@ -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\
+3 -1
View File
@@ -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\