From: Pádraig Brady Date: Thu, 27 Nov 2025 21:02:45 +0000 (+0000) Subject: doc: html: reference each command option X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=796b8d1a661cc94a7e01662250d770eded24a581;p=thirdparty%2Fcoreutils.git doc: html: reference each command option * doc/coreutils.texi: Add anchors to each command option. This also has the advantage of removing over 1000 lines, through the use of macros. --- diff --git a/doc/coreutils.texi b/doc/coreutils.texi index 84102725a5..54acdaa642 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -587,42 +587,34 @@ insights to the overall process. @node Common options @chapter Common options -@macro optBackup -@item -b -@itemx --backup[=@var{method}] -@opindex -b -@opindex --backup +@macro optBackup{cmd} +@optItem{\cmd\,-b} +@optItemx{\cmd\,--backup,[=@var{method}]} @vindex VERSION_CONTROL @cindex backups, making @xref{Backup options}. Make a backup of each file that would otherwise be overwritten or removed. @end macro -@macro optBackupSuffix -@item -S @var{suffix} -@itemx --suffix=@var{suffix} -@opindex -S -@opindex --suffix +@macro optBackupSuffix{cmd} +@optItem{\cmd\,-S,@w{ }@var{suffix}} +@optItemx{\cmd\,--suffix,=@var{suffix}} Append @var{suffix} to each backup file made with @option{-b}. @xref{Backup options}. @end macro -@macro optTargetDirectory -@item -t @var{directory} -@itemx --target-directory=@var{directory} -@opindex -t -@opindex --target-directory +@macro optTargetDirectory{cmd} +@optItem{\cmd\,-t,@w{ }@var{directory}} +@optItemx{\cmd\,--target-directory,=@var{directory}} @cindex target directory @cindex destination directory Specify the destination @var{directory}. @xref{Target directory}. @end macro -@macro optNoTargetDirectory -@item -T -@itemx --no-target-directory -@opindex -T -@opindex --no-target-directory +@macro optNoTargetDirectory{cmd} +@optItem{\cmd\,-T} +@optItemx{\cmd\,--no-target-directory} @cindex target directory @cindex destination directory Do not treat the last operand specially when it is a directory or a @@ -636,11 +628,9 @@ rather than a newline. This option enables other programs to parse the output even when that output would contain data with embedded newlines. @end macro -@macro optNull -@item -0 -@itemx --null -@opindex -0 -@opindex --null +@macro optNull{cmd} +@optItem{\cmd\,-0} +@optItemx{\cmd\,--null} @outputNUL @end macro @@ -663,9 +653,8 @@ reliably handle arbitrary file names (even those containing blanks or other special characters). @end macro -@macro optSi -@item --si -@opindex --si +@macro optSi{cmd} +@optItem{\cmd\,--si} @cindex SI output Append an SI-style abbreviation to each size, such as @samp{M} for megabytes. Powers of 1000 are used, not 1024; @samp{M} stands for @@ -675,11 +664,9 @@ megabytes. Powers of 1000 are used, not 1024; @samp{M} stands for you prefer powers of 1024. @end macro -@macro optHumanReadable -@item -h -@itemx --human-readable -@opindex -h -@opindex --human-readable +@macro optHumanReadable{cmd} +@optItem{\cmd\,-h} +@optItemx{\cmd\,--human-readable} @cindex human-readable output Append a size letter to each size, such as @samp{M} for mebibytes. Powers of 1024 are used, not 1000; @samp{M} stands for 1,048,576 bytes. @@ -687,9 +674,8 @@ This option is equivalent to @option{--block-size=human-readable}. Use the @option{--si} option if you prefer powers of 1000. @end macro -@macro optStripTrailingSlashes -@item --strip-trailing-slashes -@opindex --strip-trailing-slashes +@macro optStripTrailingSlashes{cmd} +@optItem{\cmd\,--strip-trailing-slashes} @cindex stripping trailing slashes Remove any trailing slashes from each @var{source} argument. @xref{Trailing slashes}. @@ -1419,18 +1405,16 @@ a symlink or its referent. @table @samp -@macro choptH -@item -H -@opindex -H +@macro choptH{cmd} +@optItem{\cmd\,-H} @cindex symbolic link to directory, traverse if on the command line If @option{--recursive} (@option{-R}) is specified and a command line argument is a symbolic link to a directory, traverse it. @end macro @choptH -@macro choptL -@item -L -@opindex -L +@macro choptL{cmd} +@optItem{\cmd\,-L} @cindex symbolic link to directory, traverse each that is encountered In a recursive traversal, traverse every symbolic link to a directory that is encountered. @@ -1447,12 +1431,10 @@ the operation will be performed on the target of that symlink, possibly allowing the attacker to escalate privileges. @end macro - @choptL -@macro choptP -@item -P -@opindex -P +@macro choptP{cmd} +@optItem{\cmd\,-P} @cindex symbolic link to directory, never traverse Do not traverse any symbolic links. @end macro @@ -1746,63 +1728,46 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -A -@itemx --show-all -@opindex -A -@opindex --show-all +@optItem{cat,-A} +@optItemx{cat,--show-all} Equivalent to @option{-vET}. -@item -b -@itemx --number-nonblank -@opindex -b -@opindex --number-nonblank +@optItem{cat,-b} +@optItemx{cat,--number-nonblank} Number all nonempty output lines, starting with 1. -@item -e -@opindex -e +@optItem{cat,-e} Equivalent to @option{-vE}. -@item -E -@itemx --show-ends -@opindex -E -@opindex --show-ends +@optItem{cat,-E} +@optItemx{cat,--show-ends} Display a @samp{$} after the end of each line. The @code{\r\n} combination is shown as @samp{^M$}. -@item -n -@itemx --number -@opindex -n -@opindex --number +@optItem{cat,-n} +@optItemx{cat,--number} Number all output lines, starting with 1. This option is ignored if @option{-b} is in effect. -@item -s -@itemx --squeeze-blank -@opindex -s -@opindex --squeeze-blank +@optItem{cat,-s} +@optItemx{cat,--squeeze-blank} @cindex squeezing empty lines @cindex squeezing blank lines Suppress repeated adjacent blank lines; output just one empty line instead of several. -@item -t -@opindex -t +@optItem{cat,-t} Equivalent to @option{-vT}. -@item -T -@itemx --show-tabs -@opindex -T -@opindex --show-tabs +@optItem{cat,-T} +@optItemx{cat,--show-tabs} Display TAB characters as @samp{^I}. -@item -u -@opindex -u +@optItem{cat,-u} Ignored; for POSIX compatibility. -@item -v -@itemx --show-nonprinting -@opindex -v -@opindex --show-nonprinting +@optItem{cat,-v} +@optItemx{cat,--show-nonprinting} Display control characters except for LFD and TAB using @samp{^} notation and precede characters that have the high bit set with @samp{M-}. @@ -1852,23 +1817,17 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -b -@itemx --before -@opindex -b -@opindex --before +@optItem{tac,-b} +@optItemx{tac,--before} The separator is attached to the beginning of the record that it precedes in the file. -@item -r -@itemx --regex -@opindex -r -@opindex --regex +@optItem{tac,-r} +@optItemx{tac,--regex} Treat the separator string as a regular expression. -@item -s @var{separator} -@itemx --separator=@var{separator} -@opindex -s -@opindex --separator +@optItem{tac,-s,@w{ }@var{separator}} +@optItemx{tac,--separator,=@var{separator}} Use @var{separator} as the record separator, instead of newline. Note an empty @var{separator} is treated as a zero byte. I.e., input and output items are delimited with ASCII NUL. @@ -1941,10 +1900,8 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -b @var{style} -@itemx --body-numbering=@var{style} -@opindex -b -@opindex --body-numbering +@optItem{nl,-b,@w{ }@var{style}} +@optItemx{nl,--body-numbering,=@var{style}} Select the numbering style for lines in the body section of each logical page. When a line is not numbered, the current line number is not incremented, but the line number separator character is still @@ -1963,10 +1920,8 @@ expression @var{bre}. @xref{Regular Expressions, , Regular Expressions, grep, The GNU Grep Manual}. @end table -@item -d @var{cd} -@itemx --section-delimiter=@var{cd} -@opindex -d -@opindex --section-delimiter +@optItem{nl,-d,@w{ }@var{cd}} +@optItemx{nl,--section-delimiter,=@var{cd}} @cindex section delimiters of pages Set the section delimiter characters to @var{cd}; default is @samp{\:}. If only @var{c} is given, the second remains @samp{:}. @@ -1976,29 +1931,21 @@ matching is disabled. (Remember to protect @samp{\} or other metacharacters from shell expansion with quotes or extra backslashes.) -@item -f @var{style} -@itemx --footer-numbering=@var{style} -@opindex -f -@opindex --footer-numbering +@optItem{nl,-f,@w{ }@var{style}} +@optItemx{nl,--footer-numbering,=@var{style}} Analogous to @option{--body-numbering}. -@item -h @var{style} -@itemx --header-numbering=@var{style} -@opindex -h -@opindex --header-numbering +@optItem{nl,-h,@w{ }@var{style}} +@optItemx{nl,--header-numbering,=@var{style}} Analogous to @option{--body-numbering}. -@item -i @var{number} -@itemx --line-increment=@var{number} -@opindex -i -@opindex --line-increment +@optItem{nl,-i,@w{ }@var{number}} +@optItemx{nl,--line-increment,=@var{number}} Increment line numbers by @var{number} (default 1). @var{number} can be negative to decrement. -@item -l @var{number} -@itemx --join-blank-lines=@var{number} -@opindex -l -@opindex --join-blank-lines +@optItem{nl,-l,@w{ }@var{number}} +@optItemx{nl,--join-blank-lines,=@var{number}} @cindex empty lines, numbering @cindex blank lines, numbering Consider @var{number} (default 1) consecutive empty lines to be one @@ -2007,10 +1954,8 @@ than @var{number} consecutive empty lines occur, do not number them. An empty line is one that contains no characters, not even spaces or tabs. -@item -n @var{format} -@itemx --number-format=@var{format} -@opindex -n -@opindex --number-format +@optItem{nl,-n,@w{ }@var{format}} +@optItemx{nl,--number-format,=@var{format}} Select the line numbering format (default is @code{rn}): @table @samp @@ -2025,30 +1970,22 @@ right justified, no leading zeros; right justified, leading zeros. @end table -@item -p -@itemx --no-renumber -@opindex -p -@opindex --no-renumber +@optItem{nl,-p} +@optItemx{nl,--no-renumber} Do not reset the line number at the start of a logical page. -@item -s @var{string} -@itemx --number-separator=@var{string} -@opindex -s -@opindex --number-separator +@optItem{nl,-s,@w{ }@var{string}} +@optItemx{nl,--number-separator,=@var{string}} Separate the line number from the text line in the output with @var{string} (default is the TAB character). -@item -v @var{number} -@itemx --starting-line-number=@var{number} -@opindex -v -@opindex --starting-line-number +@optItem{nl,-v,@w{ }@var{number}} +@optItemx{nl,--starting-line-number,=@var{number}} Set the initial line number on each logical page to @var{number} (default 1). The starting @var{number} can be negative. -@item -w @var{number} -@itemx --number-width=@var{number} -@opindex -w -@opindex --number-width +@optItem{nl,-w,@w{ }@var{number}} +@optItemx{nl,--number-width,=@var{number}} Use @var{number} characters for line numbers (default 6). @end table @@ -2099,10 +2036,8 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -A @var{radix} -@itemx --address-radix=@var{radix} -@opindex -A -@opindex --address-radix +@optItem{od,-A,@w{ }@var{radix}} +@optItemx{od,--address-radix,=@var{radix}} @cindex radix for file offsets @cindex file offset radix Select the base in which file offsets are printed. @var{radix} can @@ -2121,8 +2056,7 @@ none (do not print offsets). The default is octal. -@item --endian=@var{order} -@opindex --endian +@optItem{od,--endian,=@var{order}} @cindex byte-swapping @cindex endianness Reorder input bytes, to handle inputs with differing byte orders, @@ -2131,27 +2065,21 @@ of the current system. Swapping is performed according to the specified @option{--type} size and endian @var{order}, which can be @samp{little} or @samp{big}. -@item -j @var{bytes} -@itemx --skip-bytes=@var{bytes} -@opindex -j -@opindex --skip-bytes +@optItem{od,-j,@w{ }@var{bytes}} +@optItemx{od,--skip-bytes,=@var{bytes}} Skip @var{bytes} input bytes before formatting and writing. If @var{bytes} begins with @samp{0x} or @samp{0X}, it is interpreted in hexadecimal; otherwise, if it begins with @samp{0}, in octal; otherwise, in decimal. @multiplierSuffixes{bytes} -@item -N @var{bytes} -@itemx --read-bytes=@var{bytes} -@opindex -N -@opindex --read-bytes +@optItem{od,-N,@w{ }@var{bytes}} +@optItemx{od,--read-bytes,=@var{bytes}} Output at most @var{bytes} bytes of the input. Prefixes and suffixes on @code{bytes} are interpreted as for the @option{-j} option. -@item -S @var{bytes} -@itemx --strings[=@var{bytes}] -@opindex -S -@opindex --strings +@optItem{od,-S,@w{ }@var{bytes}} +@optItemx{od,--strings,=@var{bytes}} @cindex string constants, outputting Instead of the normal output, output only @dfn{string constants}: at least @var{bytes} consecutive printable characters, @@ -2163,10 +2091,8 @@ are considered ASCII NUL terminated. If @var{bytes} is omitted with @option{--strings}, the default is 3. -@item -t @var{type} -@itemx --format=@var{type} -@opindex -t -@opindex --format +@optItem{od,-t,@w{ }@var{type}} +@optItemx{od,--format,=@var{type}} Select the format in which to output the file data. @var{type} is a string of one or more of the below type indicator characters. If you include more than one type indicator character in a single @var{type} @@ -2239,19 +2165,15 @@ double long double @end table -@item -v -@itemx --output-duplicates -@opindex -v -@opindex --output-duplicates +@optItem{od,-v} +@optItemx{od,--output-duplicates} Output consecutive lines that are identical. By default, when two or more consecutive output lines would be identical, @command{od} outputs only the first line, and puts just an asterisk on the following line to indicate the elision. -@item -w[@var{n}] -@itemx --width[=@var{n}] -@opindex -w -@opindex --width +@optItem{od,-w,@w{ }@var{n}} +@optItemx{od,--width,=@var{n}} Dump @code{n} input bytes per output line. This must be a multiple of the least common multiple of the sizes associated with the specified output types. @@ -2267,49 +2189,38 @@ specification options. These options accumulate. @table @samp -@item -a -@opindex -a +@optItem{od,-a} Output as named characters. Equivalent to @samp{-t a}. -@item -b -@opindex -b +@optItem{od,-b} Output as octal bytes. Equivalent to @samp{-t o1}. -@item -c -@opindex -c +@optItem{od,-c} Output as printable single byte characters, C backslash escapes or 3 digit octal sequences. Equivalent to @samp{-t c}. -@item -d -@opindex -d +@optItem{od,-d} Output as unsigned decimal two-byte units. Equivalent to @samp{-t u2}. -@item -f -@opindex -f +@optItem{od,-f} Output as floats. Equivalent to @samp{-t fF}. -@item -i -@opindex -i +@optItem{od,-i} Output as decimal ints. Equivalent to @samp{-t dI}. -@item -l -@opindex -l +@optItem{od,-l} Output as decimal long ints. Equivalent to @samp{-t dL}. -@item -o -@opindex -o +@optItem{od,-o} Output as octal two-byte units. Equivalent to @option{-t o2}. -@item -s -@opindex -s +@optItem{od,-s} Output as decimal two-byte units. Equivalent to @option{-t d2}. -@item -x -@opindex -x +@optItem{od,-x} Output as hexadecimal two-byte units. Equivalent to @samp{-t x2}. -@item --traditional -@opindex --traditional +@optItem{od,--traditional} Recognize the non-option label argument that traditional @command{od} accepted. The following syntax: @@ -2371,10 +2282,10 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -w @var{cols} -@itemx --wrap=@var{cols} -@opindex -w -@opindex --wrap +@optAnchor{base32,-w} +@optAnchor{base32,--wrap} +@optItem{base64,-w,@w{ }@var{cols}} +@optItemx{base64,--wrap,=@var{cols}} @cindex wrap data @cindex column to wrap data after During encoding, wrap lines after @var{cols} characters. This must be @@ -2383,20 +2294,20 @@ a positive number. The default is to wrap after 76 characters. Use the value 0 to disable line wrapping altogether. -@item -d -@itemx --decode -@opindex -d -@opindex --decode +@optAnchor{base32,-d} +@optAnchor{base32,--decode} +@optItem{base64,-d} +@optItemx{base64,--decode} @cindex Decode base64 data @cindex Base64 decoding Change the mode of operation, from the default of encoding data, to decoding data. Input is expected to be base64 encoded data, and the output will be the original data. -@item -i -@itemx --ignore-garbage -@opindex -i -@opindex --ignore-garbage +@optAnchor{base32,-i} +@optAnchor{base32,--ignore-garbage} +@optItem{base64,-i} +@optItemx{base64,--ignore-garbage} @cindex Ignore garbage in base64 stream When decoding, newlines are always accepted. During decoding, ignore unrecognized bytes, @@ -2434,22 +2345,19 @@ Supported @var{encoding}s are: @table @samp -@item --base64 -@opindex --base64 +@optItem{basenc,--base64} Encode into (or decode from with @option{-d/--decode}) base64 form. The format conforms to @uref{https://datatracker.ietf.org/doc/html/rfc4648#section-4, RFC 4648#4}. Equivalent to the @command{base64} command. -@item --base64url -@opindex --base64url +@optItem{basenc,--base64url} Encode into (or decode from with @option{-d/--decode}) file-and-url-safe base64 form (using @samp{_} and @samp{-} instead of @samp{+} and @samp{/}). The format conforms to @uref{https://datatracker.ietf.org/doc/html/rfc4648#section-5, RFC 4648#5}. -@item --base58 -@opindex --base58 +@optItem{basenc,--base58} Encode into (or decode from with @option{-d/--decode}) base58 form. The format conforms to @uref{https://datatracker.ietf.org/doc/html/draft-msporny-base58-03, @@ -2461,42 +2369,36 @@ For example this generates a unique 128 bit ID in 22 bytes: uuidgen | basenc --base16 -di | basenc --base58 @end example -@item --base32 -@opindex --base32 +@optItem{basenc,--base32} Encode into (or decode from with @option{-d/--decode}) base32 form. The encoded data uses the @samp{ABCDEFGHIJKLMNOPQRSTUVWXYZ234567=} characters. The format conforms to @uref{https://datatracker.ietf.org/doc/html/rfc4648#section-6, RFC 4648#6}. Equivalent to the @command{base32} command. -@item --base32hex -@opindex --base32hex +@optItem{basenc,--base32hex} Encode into (or decode from with @option{-d/--decode}) Extended Hex Alphabet base32 form. The encoded data uses the @samp{0123456789ABCDEFGHIJKLMNOPQRSTUV=} characters. The format conforms to @uref{https://datatracker.ietf.org/doc/html/rfc4648#section-7, RFC 4648#7}. -@item --base16 -@opindex --base16 +@optItem{basenc,--base16} Encode into (or decode from with @option{-d/--decode}) base16 (hexadecimal) form. The encoded data uses the @samp{0123456789ABCDEF} characters. The format conforms to @uref{https://datatracker.ietf.org/doc/html/rfc4648#section-8, RFC 4648#8}. -@item --base2lsbf -@opindex --base2lsbf +@optItem{basenc,--base2lsbf} Encode into (or decode from with @option{-d/--decode}) binary string form (@samp{0} and @samp{1}) with the @emph{least} significant bit of every byte first. -@item --base2msbf -@opindex --base2msbf +@optItem{basenc,--base2msbf} Encode into (or decode from with @option{-d/--decode}) binary string form (@samp{0} and @samp{1}) with the @emph{most} significant bit of every byte first. -@item --z85 -@opindex --z85 +@optItem{basenc,--z85} Encode into (or decode from with @option{-d/--decode}) Z85 form (a modified Ascii85 form). The encoded data uses the @samp{0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTU@ @@ -2603,58 +2505,45 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -c -@itemx --crown-margin -@opindex -c -@opindex --crown-margin +@optItem{fmt,-c} +@optItemx{fmt,--crown-margin} @cindex crown margin @dfn{Crown margin} mode: preserve the indentation of the first two lines within a paragraph, and align the left margin of each subsequent line with that of the second line. -@item -t -@itemx --tagged-paragraph -@opindex -t -@opindex --tagged-paragraph +@optItem{fmt,-t} +@optItemx{fmt,--tagged-paragraph} @cindex tagged paragraphs @dfn{Tagged paragraph} mode: like crown margin mode, except that if indentation of the first line of a paragraph is the same as the indentation of the second, the first line is treated as a one-line paragraph. -@item -s -@itemx --split-only -@opindex -s -@opindex --split-only +@optItem{fmt,-s} +@optItemx{fmt,--split-only} Split lines only. Do not join short lines to form longer ones. This prevents sample lines of code, and other such ``formatted'' text from being unduly combined. -@item -u -@itemx --uniform-spacing -@opindex -u -@opindex --uniform-spacing +@optItem{fmt,-u} +@optItemx{fmt,--uniform-spacing} Uniform spacing. Reduce spacing between words to one space, and spacing between sentences to two spaces. -@item -@var{width} -@itemx -w @var{width} -@itemx --width=@var{width} -@opindex -@var{width} -@opindex -w -@opindex --width +@optItem{fmt,-@var{width}} +@optItemx{fmt,-w,@w{ }@var{width}} +@optItemx{fmt,--width,=@var{width}} Fill output lines up to @var{width} characters (default 75 or @var{goal} plus 10, if @var{goal} is provided). -@item -g @var{goal} -@itemx --goal=@var{goal} -@opindex -g -@opindex --goal +@optItem{fmt,-g,@w{ }@var{goal}} +@optItemx{fmt,--goal,=@var{goal}} @command{fmt} initially tries to make lines @var{goal} characters wide. By default, this is 7% shorter than @var{width}. -@item -p @var{prefix} -@itemx --prefix=@var{prefix} +@optItem{fmt,-p,@w{ }@var{prefix}} +@optItemx{fmt,--prefix,=@var{prefix}} Only lines beginning with @var{prefix} (possibly preceded by whitespace) are subject to formatting. The prefix and any preceding whitespace are stripped for the formatting and then re-attached to each formatted output @@ -2712,6 +2601,7 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp +@optAnchor{pr,--pages} @item +@var{first_page}[:@var{last_page}] @itemx --pages=@var{first_page}[:@var{last_page}] @c The two following @opindex lines evoke warnings because they contain ':' @@ -2729,10 +2619,8 @@ is identical. By default, counting starts with the first page of input file (not first page printed). Line numbering may be altered by @option{-N} option. -@item -@var{column} -@itemx --columns=@var{column} -@opindex -@var{column} -@opindex --columns +@optItem{pr,-@var{column}} +@optItemx{pr,--columns,=@var{column}} @cindex down columns With each single @var{file}, produce @var{column} columns of output (default is 1) and print columns down, unless @option{-a} is used. The @@ -2748,32 +2636,26 @@ Lines of full length are joined in a free field format and @option{-S} option may set field separators. @option{-@var{column}} may not be used with the @option{-m} option. -@item -a -@itemx --across -@opindex -a -@opindex --across +@optItem{pr,-a} +@optItemx{pr,--across} @cindex across columns With each single @var{file}, print columns across rather than down. The @option{-@var{column}} option must be given with @var{column} greater than one. If a line is too long to fit in a column, it is truncated. -@item -c -@itemx --show-control-chars -@opindex -c -@opindex --show-control-chars +@optItem{pr,-c} +@optItemx{pr,--show-control-chars} Print control characters using hat notation (e.g., @samp{^G}); print other nonprinting characters in octal backslash notation. By default, nonprinting characters are not changed. -@item -d -@itemx --double-space -@opindex -d -@opindex --double-space +@optItem{pr,-d} +@optItemx{pr,--double-space} @cindex double spacing Double space the output. -@item -D @var{format} -@itemx --date-format=@var{format} +@optItem{pr,-D,@w{ }@var{format}} +@optItemx{pr,--date-format,=@var{format}} @cindex time formats @cindex formatting times Format header dates using @var{format}, using the same conventions as @@ -2798,47 +2680,36 @@ the @env{TZ} environment variable, or by the system default rules if @env{TZ} is not set. @xref{TZ Variable,, Specifying the Time Zone with @env{TZ}, libc, The GNU C Library Reference Manual}. -@item -e[@var{in-tabchar}[@var{in-tabwidth}]] -@itemx --expand-tabs[=@var{in-tabchar}[@var{in-tabwidth}]] -@opindex -e -@opindex --expand-tabs +@optItem{pr,-e,[@var{in-tabchar}[@var{in-tabwidth}]]} +@optItemx{pr,--expand-tabs,[=@var{in-tabchar}[@var{in-tabwidth}]]} @cindex input tabs Expand @var{tab}s to spaces on input. Optional argument @var{in-tabchar} is the input tab character (default is the TAB character). Second optional argument @var{in-tabwidth} is the input tab character's width (default is 8). -@item -f -@itemx -F -@itemx --form-feed -@opindex -F -@opindex -f -@opindex --form-feed +@optItem{pr,-f} +@optItemx{pr,-F} +@optItemx{pr,--form-feed} Use a form feed instead of newlines to separate output pages. This does not alter the default page length of 66 lines. -@item -h @var{header} -@itemx --header=@var{header} -@opindex -h -@opindex --header +@optItem{pr,-h,@w{ }@var{header}} +@optItemx{pr,--header,=@var{header}} Replace the file name in the header with the centered string @var{header}. When using the shell, @var{header} should be quoted and should be separated from @option{-h} by a space. -@item -i[@var{out-tabchar}[@var{out-tabwidth}]] -@itemx --output-tabs[=@var{out-tabchar}[@var{out-tabwidth}]] -@opindex -i -@opindex --output-tabs +@optItem{pr,-i,@w{ }[@var{out-tabchar}[@var{out-tabwidth}]]} +@optItemx{pr,--output-tabs,=[@var{out-tabchar}[@var{out-tabwidth}]]} @cindex output tabs Replace spaces with @var{tab}s on output. Optional argument @var{out-tabchar} is the output tab character (default is the TAB character). Second optional argument @var{out-tabwidth} is the output tab character's width (default is 8). -@item -J -@itemx --join-lines -@opindex -J -@opindex --join-lines +@optItem{pr,-J} +@optItemx{pr,--join-lines} Merge lines of full length. Used together with the column options @option{-@var{column}}, @option{-a -@var{column}} or @option{-m}. Turns off @option{-W/-w} line truncation; @@ -2849,19 +2720,15 @@ to disentangle the old (POSIX-compliant) options @option{-w} and @option{-s} along with the three column options. -@item -l @var{page_length} -@itemx --length=@var{page_length} -@opindex -l -@opindex --length +@optItem{pr,-l,@w{ }@var{page_length}} +@optItemx{pr,--length,=@var{page_length}} Set the page length to @var{page_length} (default 66) lines, including the lines of the header [and the footer]. If @var{page_length} is less than or equal to 10, the header and footer are omitted, as if the @option{-t} option had been given. -@item -m -@itemx --merge -@opindex -m -@opindex --merge +@optItem{pr,-m} +@optItemx{pr,--merge} Merge and print all @var{file}s in parallel, one in each column. If a line is too long to fit in a column, it is truncated, unless the @option{-J} option is used. @option{--sep-string[=@var{string}]} may be used. @@ -2874,10 +2741,8 @@ show no separators or line numbers. The default header becomes may be used with the @option{-h} or @option{--header} option to fill up the middle blank part. -@item -n[@var{number-separator}[@var{digits}]] -@itemx --number-lines[=@var{number-separator}[@var{digits}]] -@opindex -n -@opindex --number-lines +@optItem{pr,-n,[@var{number-separator}[@var{digits}]]} +@optItemx{pr,--number-lines,[=@var{number-separator}[@var{digits}]]} Provide @var{digits} digit line numbering (default for @var{digits} is 5). With multicolumn output the number occupies the first @var{digits} column positions of each text column or only each line of @option{-m} @@ -2898,17 +2763,13 @@ fixed number of spaces is always printed in the place of the @var{number-separator} TAB@. The tabification depends upon the output position. -@item -N @var{line_number} -@itemx --first-line-number=@var{line_number} -@opindex -N -@opindex --first-line-number +@optItem{pr,-N,@w{ }@var{line_number}} +@optItemx{pr,--first-line-number,=@var{line_number}} Start line counting with the number @var{line_number} at first line of first page printed (in most cases not the first line of the input file). -@item -o @var{margin} -@itemx --indent=@var{margin} -@opindex -o -@opindex --indent +@optItem{pr,-o,@w{ }@var{margin}} +@optItemx{pr,--indent,=@var{margin}} @cindex indenting lines @cindex left margin Indent each line with a margin @var{margin} spaces wide (default is zero). @@ -2916,17 +2777,13 @@ The total page width is the size of the margin plus the @var{page_width} set with the @option{-W/-w} option. A limited overflow may occur with numbered single column output (compare @option{-n} option). -@item -r -@itemx --no-file-warnings -@opindex -r -@opindex --no-file-warnings +@optItem{pr,-r} +@optItemx{pr,--no-file-warnings} Do not print a warning message when an argument @var{file} cannot be opened. (The exit status will still be nonzero, however.) -@item -s[@var{char}] -@itemx --separator[=@var{char}] -@opindex -s -@opindex --separator +@optItem{pr,-s,@w{ }@var{char}} +@optItemx{pr,--separator,=@var{char}} Separate columns by a single character @var{char}. The default for @var{char} is the TAB character without @option{-w} and @samp{no character} with @option{-w}. Without @option{-s} the default separator @@ -2934,11 +2791,8 @@ character} with @option{-w}. Without @option{-s} the default separator three column options (@option{-COLUMN}|@option{-a -COLUMN}|@option{-m}) unless @option{-w} is set. This is a POSIX-compliant formulation. - -@item -S[@var{string}] -@itemx --sep-string[=@var{string}] -@opindex -S -@opindex --sep-string +@optItem{pr,-S,[@var{string}]} +@optItemx{pr,--sep-string,[=@var{string}]} Use @var{string} to separate output columns. The @option{-S} option doesn't affect the @option{-W/-w} option, unlike the @option{-s} option which does. It does not affect line truncation or column alignment. @@ -2948,10 +2802,8 @@ Without @option{-S} or @option{-J}, @command{pr} uses a @samp{space} (same as @option{-S"@w{ }"}). If no @samp{@var{string}} argument is specified, @samp{""} is assumed. -@item -t -@itemx --omit-header -@opindex -t -@opindex --omit-header +@optItem{pr,-t} +@optItemx{pr,--omit-header} Do not print the usual header [and footer] on each page, and do not fill out the bottom of pages (with blank lines or a form feed). No page structure is produced, but form feeds set in the input files are retained. @@ -2960,23 +2812,17 @@ useful together with other options; e.g.: @option{-t -e4}, expand TAB characters in the input file to 4 spaces but don't make any other changes. Use of @option{-t} overrides @option{-h}. -@item -T -@itemx --omit-pagination -@opindex -T -@opindex --omit-pagination +@optItem{pr,-T} +@optItemx{pr,--omit-pagination} Do not print header [and footer]. In addition eliminate all form feeds set in the input files. -@item -v -@itemx --show-nonprinting -@opindex -v -@opindex --show-nonprinting +@optItem{pr,-v} +@optItemx{pr,--show-nonprinting} Print nonprinting characters in octal backslash notation. -@item -w @var{page_width} -@itemx --width=@var{page_width} -@opindex -w -@opindex --width +@optItem{pr,-w,@w{ }@var{page_width}} +@optItemx{pr,--width,=@var{page_width}} Set page width to @var{page_width} characters for multiple text-column output only (default for @var{page_width} is 72). The specified @var{page_width} is rounded down so that columns have equal width. @@ -2986,10 +2832,8 @@ Lines of full length are merged, regardless of the column options set. No @var{page_width} setting is possible with single column output. A POSIX-compliant formulation. -@item -W @var{page_width} -@itemx --page_width=@var{page_width} -@opindex -W -@opindex --page_width +@optItem{pr,-W,@w{ }@var{page_width}} +@optItemx{pr,--page-width,=@var{page_width}} Set the page width to @var{page_width} characters, honored with and without a column option. With a column option, the specified @var{page_width} is rounded down so that columns have equal width. Text lines are truncated, @@ -3034,33 +2878,25 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -b -@itemx --bytes -@opindex -b -@opindex --bytes +@optItem{fold,-b} +@optItemx{fold,--bytes} Count bytes rather than columns, so that tabs, backspaces, and carriage returns are each counted as taking up one column, just like other characters. -@item -c -@itemx --characters -@opindex -c -@opindex --characters +@optItem{fold,-c} +@optItemx{fold,--characters} Count characters rather than columns, meaning that lines containing characters wider than one column will be visually longer. -@item -s -@itemx --spaces -@opindex -s -@opindex --spaces +@optItem{fold,-s} +@optItemx{fold,--spaces} Break at word boundaries: the line is broken after the last blank before the maximum line length. If the line contains no such blanks, the line is broken at the maximum line length as usual. -@item -w @var{width} -@itemx --width=@var{width} -@opindex -w -@opindex --width +@optItem{fold,-w,@w{ }@var{width}} +@optItemx{fold,--width,@var{width}} Use a maximum line length of @var{width} columns instead of 80. For compatibility @command{fold} supports an obsolete option syntax @@ -3116,39 +2952,30 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -c [-]@var{num} -@itemx --bytes=[-]@var{num} -@opindex -c -@opindex --bytes +@optItem{head,-c,@w{ }[-]@var{num}} +@optItemx{head,--bytes,=[-]@var{num}} Print the first @var{num} bytes, instead of initial lines. However, if @var{num} is prefixed with a @samp{-}, print all but the last @var{num} bytes of each file. @multiplierSuffixes{num} -@item -n [-]@var{num} -@itemx --lines=[-]@var{num} -@opindex -n -@opindex --lines +@optItem{head,-n,@w{ }[-]@var{num}} +@optItemx{head,--lines,=[-]@var{num}} Output the first @var{num} lines. However, if @var{num} is prefixed with a @samp{-}, print all but the last @var{num} lines of each file. Size multiplier suffixes are the same as with the @option{-c} option. -@item -q -@itemx --quiet -@itemx --silent -@opindex -q -@opindex --quiet -@opindex --silent +@optItem{head,-q} +@optItemx{head,--quiet} +@optItemx{head,--silent} Never print file name headers. -@item -v -@itemx --verbose -@opindex -v -@opindex --verbose +@optItem{head,-v} +@optItemx{head,--verbose} Always print file name headers. -@optZeroTerminated +@optZeroTerminated{head} @end table @@ -3211,25 +3038,20 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -c [+]@var{num} -@itemx --bytes=[+]@var{num} -@opindex -c -@opindex --bytes +@optItem{tail,-c,@w{ }[+]@var{num}} +@optItemx{tail,--bytes,=[+]@var{num}} Output the last @var{num} bytes, instead of final lines. If @var{num} is prefixed with a @samp{+}, start printing with byte @var{num} from the start of each file. For example to skip the first byte use @code{tail -c +2}, while to skip all but the last byte use @code{tail -c 1}. @multiplierSuffixes{num} -@item --debug -@opindex --debug +@optItem{tail,--debug} Output extra information to standard error, like the --follow implementation being used. -@item -f -@itemx --follow[=@var{how}] -@opindex -f -@opindex --follow +@optItem{tail,-f} +@optItemx{tail,--follow,[=@var{how}]} @cindex growing files @vindex name @r{follow option} @vindex descriptor @r{follow option} @@ -3286,14 +3108,12 @@ by using a sub-second sleep interval, e.g., via an alias like this: alias tail='tail -s.1' @end example -@item -F -@opindex -F +@optItem{tail,-F} This option is the same as @option{--follow=name --retry}. That is, tail will attempt to reopen a file when it is removed. Should this fail, tail will keep trying until it becomes accessible again. -@item --max-unchanged-stats=@var{n} -@opindex --max-unchanged-stats +@optItem{tail,--max-unchanged-stats,=@var{n}} When tailing a file by name, if there have been @var{n} (default n=@value{DEFAULT_MAX_N_UNCHANGED_STATS_BETWEEN_OPENS}) consecutive iterations for which the file has not changed, then @@ -3305,18 +3125,15 @@ and when it prints the lines that have accumulated in the new log file. This option is meaningful only when polling (i.e., without inotify) and when following by name. -@item -n [+]@var{num} -@itemx --lines=[+]@var{} -@opindex -n -@opindex --lines +@optItem{tail,-n,@w{ }[+]@var{num}} +@optItemx{tail,--lines,=[+]@var{num}} Output the last @var{num} lines. If @var{num} is prefixed with a @samp{+}, start printing with line @var{num} from the start of each file. For example to skip the first line use @code{tail -n +2}, while to skip all but the last line use @code{tail -n 1}. Size multiplier suffixes are the same as with the @option{-c} option. -@item --pid=@var{pid} -@opindex --pid +@optItem{tail,--pid,=@var{pid}} When following by name or by descriptor, you may specify the process ID, @var{pid}, of one or more (by repeating @option{--pid}) writers of the @var{file} arguments. Then, @command{tail} will exit shortly @@ -3339,16 +3156,12 @@ terminate until long after the real writer has terminated. On some systems, @option{--pid} is not supported and @command{tail} outputs a warning. -@item -q -@itemx --quiet -@itemx --silent -@opindex -q -@opindex --quiet -@opindex --silent +@optItem{tail,-q} +@optItemx{tail,--quiet} +@optItemx{tail,--silent} Never print file name headers. -@item --retry -@opindex --retry +@optItem{tail,--retry} Indefinitely try to open the specified file. This option is useful mainly when following (and otherwise issues a warning). @@ -3363,10 +3176,8 @@ Without this option, when @command{tail} encounters a file that doesn't exist or is otherwise inaccessible, it reports that fact and never checks it again. -@item -s @var{number} -@itemx --sleep-interval=@var{number} -@opindex -s -@opindex --sleep-interval +@optItem{tail,-s,@w{ }@var{number}} +@optItemx{tail,--sleep-interval,=@var{number}} Change the number of seconds to wait between iterations (the default is 1.0). During one iteration, every specified file is checked to see if it has changed size. @@ -3377,13 +3188,11 @@ every @var{number} seconds. The @var{number} must be non-negative and can be a floating-point number in either the current or the C locale. @xref{Floating point}. -@item -v -@itemx --verbose -@opindex -v -@opindex --verbose +@optItem{tail,-v} +@optItemx{tail,--verbose} Always print file name headers. -@optZeroTerminated +@optZeroTerminated{tail} @end table @@ -3462,10 +3271,8 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -l @var{lines} -@itemx --lines=@var{lines} -@opindex -l -@opindex --lines +@optItem{split,-l,@w{ }@var{lines}} +@optItemx{split,--lines,=@var{lines}} Put @var{lines} lines of @var{input} into each output file. If @option{--separator} is specified, then @var{lines} determines the number of records. @@ -3474,17 +3281,13 @@ For compatibility @command{split} also supports an obsolete option syntax @option{-@var{lines}}. New scripts should use @option{-l @var{lines}} instead. -@item -b @var{size} -@itemx --bytes=@var{size} -@opindex -b -@opindex --bytes +@optItem{split,-b,@w{ }@var{size}} +@optItemx{split,--bytes,=@var{size}} Put @var{size} bytes of @var{input} into each output file. @multiplierSuffixes{size} -@item -C @var{size} -@itemx --line-bytes=@var{size} -@opindex -C -@opindex --line-bytes +@optItem{split,-C,@w{ }@var{size}} +@optItemx{split,--lines-bytes,=@var{size}} Put into each output file as many complete lines of @var{input} as possible without exceeding @var{size} bytes. Individual lines or records longer than @var{size} bytes are broken into multiple files. @@ -3492,8 +3295,7 @@ longer than @var{size} bytes are broken into multiple files. If @option{--separator} is specified, then @var{lines} determines the number of records. -@item --filter=@var{command} -@opindex --filter +@optItem{split,--filter,=@var{command}} With this option, rather than simply writing to each output file, write through a pipe to the specified shell @var{command} for each output file. @var{command} should use the $FILE environment variable, which is set @@ -3511,11 +3313,8 @@ xz -dc BIG.xz | split -b200G --filter='xz > $FILE.xz' - big- Assuming a 10:1 compression ratio, that would create about fifty 20GiB files with names @file{big-aa.xz}, @file{big-ab.xz}, @file{big-ac.xz}, etc. -@item -n @var{chunks} -@itemx --number=@var{chunks} -@opindex -n -@opindex --number - +@optItem{split,-n,@w{ }@var{chunks}} +@optItemx{split,--number,=@var{chunks}} Split @var{input} to @var{chunks} output files where @var{chunks} may be: @macro Stdout @@ -3552,20 +3351,16 @@ cannot easily be determined, there is no trouble for @samp{r} mode because the size of the input is irrelevant. For other modes, such an input is first copied to a temporary to determine its size. -@item -a @var{length} -@itemx --suffix-length=@var{length} -@opindex -a -@opindex --suffix-length +@optItem{split,-a,@w{ }@var{length}} +@optItemx{split,--suffix-length,=@var{length}} Use suffixes of length @var{length}. If a @var{length} of 0 is specified, this is the same as if (any previous) @option{-a} was not specified, and thus enables the default behavior, which starts the suffix length at 2, and unless @option{-n} or @option{--numeric-suffixes=@var{from}} is specified, will auto increase the length by 2 as required. -@item -d -@itemx --numeric-suffixes[=@var{from}] -@opindex -d -@opindex --numeric-suffixes +@optItem{split,-d} +@optItemx{split,--numeric-suffixes,[=@var{from}]} Use digits in suffixes rather than lower-case letters. The numerical suffix counts from @var{from} if specified, 0 otherwise. @@ -3577,31 +3372,24 @@ suffixes beyond @samp{99}. If option @option{--number} is specified and the number of files is less than @var{from}, a single run is assumed and the minimum suffix length required is automatically determined. -@item -x -@itemx --hex-suffixes[=@var{from}] -@opindex -x -@opindex --hex-suffixes +@optItem{split,-x} +@optItemx{split,--hex-suffixes,[=@var{from}]} Like @option{--numeric-suffixes}, but use hexadecimal numbers (in lower case). -@item --additional-suffix=@var{suffix} -@opindex --additional-suffix +@optItem{split,--additional-suffix,=@var{suffix}} Append an additional @var{suffix} to output file names. @var{suffix} must not contain slash. -@item -e -@itemx --elide-empty-files -@opindex -e -@opindex --elide-empty-files +@optItem{split,-e} +@optItemx{split,--elide-empty-files} Suppress the generation of zero-length output files. This can happen with the @option{--number} option if a file is (truncated to be) shorter than the number requested, or if a line is so long as to completely span a chunk. The output file sequence numbers, always run consecutively even when this option is specified. -@item -t @var{separator} -@itemx --separator=@var{separator} -@opindex -t -@opindex --separator +@optItem{split,-t,@w{ }@var{separator}} +@optItemx{split,--separator,=@var{separator}} @cindex line separator character @cindex record separator character Use character @var{separator} as the record separator instead of the default @@ -3609,15 +3397,12 @@ newline character (ASCII LF). To specify ASCII NUL as the separator, use the two-character string @samp{\0}, e.g., @samp{split -t '\0'}. -@item -u -@itemx --unbuffered -@opindex -u -@opindex --unbuffered +@optItem{split,-u} +@optItemx{split,--unbuffered} Immediately copy input to output in @option{--number r/@dots{}} mode, which is a much slower mode of operation. -@item --verbose -@opindex --verbose +@optItem{split,--verbose} Write a diagnostic just before each output file is opened. @end table @@ -3758,17 +3543,13 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -f @var{prefix} -@itemx --prefix=@var{prefix} -@opindex -f -@opindex --prefix +@optItem{csplit,-f,@w{ }@var{prefix}} +@optItemx{csplit,--prefix,=@var{prefix}} @cindex output file name prefix Use @var{prefix} as the output file name prefix. -@item -b @var{format} -@itemx --suffix-format=@var{format} -@opindex -b -@opindex --suffix-format +@optItem{csplit,-b,@w{ }@var{format}} +@optItemx{csplit,--suffix-format,=@var{format}} @cindex output file name suffix Use @var{format} as the output file name suffix. When this option is specified, the suffix string must include exactly one @@ -3783,29 +3564,22 @@ entire @var{format} is given (with the current output file number) to individual output files in turn. If this option is used, the @option{--digits} option is ignored. -@item -n @var{digits} -@itemx --digits=@var{digits} -@opindex -n -@opindex --digits +@optItem{csplit,-n,@w{ }@var{digits}} +@optItemx{csplit,--digits,=@var{digits}} Use output file names containing numbers that are @var{digits} digits long instead of the default 2. -@item -k -@itemx --keep-files -@opindex -k -@opindex --keep-files +@optItem{csplit,-k} +@optItemx{csplit,--keep-files} Do not remove output files when errors are encountered. -@item --suppress-matched -@opindex --suppress-matched +@optItem{csplit,--suppress-matched} Do not output lines matching the specified @var{pattern}. I.e., suppress the boundary line from the start of the second and subsequent splits. -@item -z -@itemx --elide-empty-files -@opindex -z -@opindex --elide-empty-files +@optItem{csplit,-z} +@optItemx{csplit,--elide-empty-files} Suppress the generation of zero-length output files. (In cases where the section delimiters of the input file are supposed to mark the first lines of each of the sections, the first output file will generally be a @@ -3813,14 +3587,10 @@ zero-length file unless you use this option.) The output file sequence numbers always run consecutively starting from 0, even when this option is specified. -@item -s -@itemx -q -@itemx --silent -@itemx --quiet -@opindex -s -@opindex -q -@opindex --silent -@opindex --quiet +@optItem{csplit,-s} +@optItemx{csplit,-q} +@optItemx{csplit,--silent} +@optItemx{csplit,--quiet} Do not print counts of output file sizes. @end table @@ -3972,23 +3742,17 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -c -@itemx --bytes -@opindex -c -@opindex --bytes +@optItem{wc,-c} +@optItemx{wc,--bytes} Print only the byte counts. -@item -m -@itemx --chars -@opindex -m -@opindex --chars +@optItem{wc,-m} +@optItemx{wc,--chars} Print only the character counts, as per the current locale. Encoding errors are not counted. -@item -w -@itemx --words -@opindex -w -@opindex --words +@optItem{wc,-w} +@optItemx{wc,--words} Print only the word counts. A word is a nonempty sequence of non white space delimited by white space characters or by start or end of input. The current locale determines which characters are white space. @@ -4001,30 +3765,24 @@ space even if the current locale does not: U+00A0 NO-BREAK SPACE, U+2007 FIGURE SPACE, U+202F NARROW NO-BREAK SPACE, and U+2060 WORD JOINER. -@item -l -@itemx --lines -@opindex -l -@opindex --lines +@optItem{wc,-l} +@optItemx{wc,--lines} Print only the newline character counts. If a file ends in a non-newline character, its trailing partial line is not counted. -@item --debug -@opindex --debug +@optItem{wc,--debug} Output extra information to standard error. Currently; print the line count acceleration implementation being used. -@item -L -@itemx --max-line-length -@opindex -L -@opindex --max-line-length +@optItem{wc,-L} +@optItemx{wc,--max-line-length} Print only the maximum display widths. Tabs are set at every 8th column. Display widths of wide characters are considered. Non-printable characters are given 0 width. -@item --total=@var{when} -@opindex --total=@var{when} +@optItem{wc,--total} Control when and how the final line with cumulative counts is printed. @var{when} is one of: @itemize @bullet @@ -4047,8 +3805,7 @@ to simplify subsequent processing. @end itemize @macro filesZeroFromOption{cmd,withTotalOption,subListOutput} -@item --files0-from=@var{file} -@opindex --files0-from=@var{file} +@optItem{\cmd\,--files0-from,=@var{file}} @c This is commented out to avoid a texi2dvi failure. @c texi2dvi (GNU Texinfo 4.11) 1.104 @c @cindex including files from @command{\cmd\} @@ -4108,17 +3865,14 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -r -@opindex -r +@optItem{sum,-r} @cindex BSD @command{sum} Use the default (BSD compatible) algorithm. This option is included for compatibility with the System V @command{sum}. Unless @option{-s} was also given, it has no effect. -@item -s -@itemx --sysv -@opindex -s -@opindex --sysv +@optItem{sum,-s} +@optItemx{sum,--sysv} @cindex System V @command{sum} Compute checksums using an algorithm compatible with System V @command{sum}'s default, and print file sizes in units of 512-byte blocks. @@ -4216,10 +3970,8 @@ escape sequences are reserved for future use. @table @samp -@item -a -@itemx --algorithm -@opindex -a -@opindex --algorithm +@optItem{cksum,-a,@w{ }@var{type}} +@optItemx{cksum,--algorithm,=@var{type}} @cindex digest algorithm Compute checksums using the specified digest algorithm. @@ -4250,8 +4002,7 @@ produce the same checksum: @samp{blake2b} equivalent to @command{b2sum} @end example -@item --base64 -@opindex --base64 +@optItem{cksum,--base64} @cindex base64 checksum encoding Print base64-encoded digests not hexadecimal. This option is ignored with @option{--check}. @@ -4264,16 +4015,14 @@ modulo 3, and the @option{--check} parser requires precisely the same input digest string as what is output. I.e., removing or adding any @samp{=} padding renders a digest non-matching. -@item --debug -@opindex --debug +@optItem{cksum,--debug} Output extra information to standard error, like the checksum implementation being used. -@item -l -@itemx --length -@opindex -l -@opindex --length +@optItem{cksum,-l,@w{ }@var{bits}} +@optItemx{cksum,--length,=@var{bits}} @cindex BLAKE2 hash length +@cindex SHA-2 hash length @cindex SHA-3 hash length Specify the digest size used with @option{-a sha2, sha3, or blake2b}. For @samp{blake2b} this is optional, with 512 being the default. If the @@ -4283,8 +4032,7 @@ option is required, and the @var{length} must be one of 224, 256, 384, or 512. This option is ignored when @option{--check} is specified, as the length is automatically determined when checking. -@item --raw -@opindex --raw +@optItem{cksum,--raw} @cindex raw binary checksum Print only the unencoded raw binary digest for a single input. Do not output the file name or anything else. @@ -4294,8 +4042,7 @@ This option works only with a single input. Unlike other output formats, @command{cksum} provides no way to @option{--check} a @option{--raw} checksum. -@item --untagged -@opindex --untagged +@optItem{cksum,--untagged} Output using the original Coreutils format used by the other standalone checksum utilities like @command{md5sum} for example. This format has the checksum at the start of the line, and may be @@ -4310,10 +4057,8 @@ This does not identify the digest algorithm used for the checksum. @table @samp -@item -b -@itemx --binary -@opindex -b -@opindex --binary +@optItem{cksum,-b} +@optItemx{cksum,--binary} @cindex binary input files Treat each input file as binary, by reading it in binary mode and outputting a @samp{*} flag. This is the inverse of @option{--text}. @@ -4329,8 +4074,8 @@ of the legacy standalone checksumming utilities. @end macro @cksumTextMode -@item -c -@itemx --check +@optItem{cksum,-c} +@optItemx{cksum,--check} Read file names and checksum information (not data) from each @var{file} (or from standard input if no @var{file} was specified) and report whether the checksums match the contents of the named files. @@ -4371,16 +4116,14 @@ a checksum inconsistent with the associated file, or if no valid line is found, @command{cksum} exits with nonzero status. Otherwise, it exits successfully. -@item --ignore-missing -@opindex --ignore-missing +@optItem{cksum,--ignore-missing} @cindex verifying checksums This option is useful only when verifying checksums. When verifying checksums, don't fail or report any status for missing files. This is useful when verifying a subset of downloaded files given a larger list of checksums. -@item --quiet -@opindex --quiet +@optItem{cksum,--quiet} @cindex verifying checksums This option is useful only when verifying checksums. When verifying checksums, don't generate an 'OK' message per successfully @@ -4388,8 +4131,7 @@ checked file. Files that fail the verification are reported in the default one-line-per-file format. If there is any checksum mismatch, print a warning summarizing the failures to standard error. -@item --status -@opindex --status +@optItem{cksum,--status} @cindex verifying checksums This option is useful only when verifying checksums. When verifying checksums, don't generate the default one-line-per-file @@ -4400,8 +4142,7 @@ If all listed files are readable and are consistent with the associated checksums, exit successfully. Otherwise exit with a status code indicating there was a failure. -@item --tag -@opindex --tag +@optItem{cksum,--tag} @cindex BSD output Output BSD style checksums, which indicate the checksum algorithm used. As a GNU extension, if @option{--zero} is not used, file names with problematic @@ -4413,10 +4154,8 @@ the output format, while providing little benefit. @xref{cksum output modes} for details of this format. The @command{cksum} command, uses @option{--tag} as its default output format. -@item -t -@itemx --text -@opindex -t -@opindex --text +@optItem{cksum,-t} +@optItemx{cksum,--text} @cindex text input files Treat each input file as text, by reading it in text mode and outputting a @samp{ } flag. This is the inverse of @option{--binary}. @@ -4426,23 +4165,20 @@ the default for reading standard input when standard input is a terminal. This mode is never defaulted to if @option{--tag} is used. @cksumTextMode -@item -w -@itemx --warn -@opindex -w -@opindex --warn +@optItem{cksum,-w} +@optItemx{cksum,--warn} @cindex verifying checksums When verifying checksums, warn about improperly formatted checksum lines. This option is useful only if all but a few lines in the checked input are valid. -@item --strict -@opindex --strict +@optItem{cksum,--strict} @cindex verifying checksums When verifying checksums, if one or more input line is invalid, exit nonzero after all warnings have been issued. -@optZero +@optZero{cksum} Also file name escaping is not used. @end table @@ -4513,10 +4249,8 @@ In addition @command{b2sum} supports the following options. @table @samp -@item -l -@itemx --length -@opindex -l -@opindex --length +@optItem{b2sum,-l,@w{ }@var{bits}} +@optItemx{b2sum,--length,=@var{bits}} @cindex BLAKE2 hash length Specify the digest size used by the algorithm. This option is optional. By default a 512 bit digest will be used. If the option is given it @@ -4652,11 +4386,9 @@ mode: @table @samp -@item -c -@itemx --check +@optItem{sort,-c} +@optItemx{sort,--check} @itemx --check=diagnose-first -@opindex -c -@opindex --check @cindex checking whether a file is sorted Check whether the given file is already sorted: if it is not all sorted, print a diagnostic containing the first out-of-order line and @@ -4664,10 +4396,9 @@ exit with a status of 1. Otherwise, exit successfully. At most one input file can be given. -@item -C +@optItem{sort,-C} @itemx --check=quiet @itemx --check=silent -@opindex -c @opindex --check @cindex checking whether a file is sorted Exit successfully if the given file is already sorted, and @@ -4675,10 +4406,8 @@ exit with status 1 otherwise. At most one input file can be given. This is like @option{-c}, except it does not print a diagnostic. -@item -m -@itemx --merge -@opindex -m -@opindex --merge +@optItem{sort,-m} +@optItemx{sort,--merge} @cindex merging sorted files Merge the given files by sorting them as a group. Each input file must always be individually sorted. It always works to sort instead of @@ -4712,10 +4441,8 @@ so portable shell scripts should specify global options first. @table @samp -@item -b -@itemx --ignore-leading-blanks -@opindex -b -@opindex --ignore-leading-blanks +@optItem{sort,-b} +@optItemx{sort,--ignore-leading-blanks} @cindex blanks, ignoring leading @vindex LC_CTYPE Ignore leading blanks when finding sort keys in each line. @@ -4724,10 +4451,8 @@ can change this. Blanks may be ignored by your locale's collating rules, but without this option they will be significant for character positions specified in keys with the @option{-k} option. -@item -d -@itemx --dictionary-order -@opindex -d -@opindex --dictionary-order +@optItem{sort,-d} +@optItemx{sort,--dictionary-order} @cindex dictionary order @cindex phone directory order @cindex telephone directory order @@ -4737,10 +4462,8 @@ letters, digits and blanks when sorting. By default letters and digits are those of ASCII and a blank is a space or a tab, but the @env{LC_CTYPE} locale can change this. -@item -f -@itemx --ignore-case -@opindex -f -@opindex --ignore-case +@optItem{sort,-f} +@optItemx{sort,--ignore-case} @cindex ignoring case @cindex case folding @vindex LC_CTYPE @@ -4752,12 +4475,9 @@ thrown away. (There is currently no way to throw away the upper case equivalent instead. (Any @option{--reverse} given would only affect the final result, after the throwing away.)) -@item -g -@itemx --general-numeric-sort -@itemx --sort=general-numeric -@opindex -g -@opindex --general-numeric-sort -@opindex --sort +@optItem{sort,-g} +@optItemx{sort,--general-numeric-sort} +@optItemx{sort,--sort,=general-numeric} @cindex general numeric sort @vindex LC_NUMERIC Sort numerically, converting a prefix of each line to a long @@ -4789,11 +4509,9 @@ or of varying case. However for hex numbers of consistent case, and left padded with @samp{0} to a consistent width, a standard lexicographic sort will be faster. -@item -h -@itemx --human-numeric-sort +@optItem{sort,-h} +@optItemx{sort,--human-numeric-sort} @itemx --sort=human-numeric -@opindex -h -@opindex --human-numeric-sort @opindex --sort @cindex human numeric sort @vindex LC_NUMERIC @@ -4812,10 +4530,8 @@ option; the SI suffix must immediately follow the number. To sort more accurately, you can use the @command{numfmt} command to reformat numbers to human format @emph{after} the sort. -@item -i -@itemx --ignore-nonprinting -@opindex -i -@opindex --ignore-nonprinting +@optItem{sort,-i} +@optItemx{sort,--ignore-nonprinting} @cindex nonprinting characters, ignoring @cindex unprintable characters, ignoring @vindex LC_CTYPE @@ -4824,11 +4540,9 @@ The @env{LC_CTYPE} locale determines character types. This option has no effect if the stronger @option{--dictionary-order} (@option{-d}) option is also given. -@item -M -@itemx --month-sort +@optItem{sort,-M} +@optItemx{sort,--month-sort} @itemx --sort=month -@opindex -M -@opindex --month-sort @opindex --sort @cindex months, sorting by @vindex LC_TIME @@ -4840,11 +4554,9 @@ category determines the month spellings. By default a blank is a space or a tab, but the @env{LC_CTYPE} locale can change this. -@item -n -@itemx --numeric-sort +@optItem{sort,-n} +@optItemx{sort,--numeric-sort} @itemx --sort=numeric -@opindex -n -@opindex --numeric-sort @opindex --sort @cindex numeric sort @vindex LC_CTYPE @@ -4867,28 +4579,24 @@ Neither a leading @samp{+} nor exponential notation is recognized. To compare such strings numerically, use the @option{--general-numeric-sort} (@option{-g}) option. -@item -V -@itemx --version-sort -@opindex -V -@opindex --version-sort +@optItem{sort,-V} +@optItemx{sort,--version-sort} +@itemx --sort=version +@opindex --sort @cindex version number sort Sort by version name and number. It behaves like a standard sort, except that each sequence of decimal digits is treated numerically as an index/version number. (@xref{Version sort ordering}.) -@item -r -@itemx --reverse -@opindex -r -@opindex --reverse +@optItem{sort,-r} +@optItemx{sort,--reverse} @cindex reverse sorting Reverse the result of comparison, so that lines with greater key values appear earlier in the output instead of later. -@item -R -@itemx --random-sort +@optItem{sort,-R} +@optItemx{sort,--random-sort} @itemx --sort=random -@opindex -R -@opindex --random-sort @opindex --sort @cindex random sort Sort by hashing the input keys and then sorting the hash values. @@ -4911,7 +4619,7 @@ Other options are: @table @samp -@item --compress-program=@var{prog} +@optItem{sort,--compress-program,@w{ }@var{prog}} Compress any temporary files with the program @var{prog}. With no arguments, @var{prog} must compress standard input to standard @@ -4929,10 +4637,8 @@ White space and the backslash character should not appear in @filesZeroFromOption{sort,,sorted output} -@item -k @var{pos1}[,@var{pos2}] -@itemx --key=@var{pos1}[,@var{pos2}] -@opindex -k -@opindex --key +@optItem{sort,-k,@w{ }@var{pos1}[@comma{}@var{pos2}]} +@optItemx{sort,--key,=@var{pos1}[@comma{}@var{pos2}]} @cindex sort field Specify a sort field that consists of the part of the line between @var{pos1} and @var{pos2} (or the end of the line, if @var{pos2} is @@ -4961,12 +4667,11 @@ Example: To sort on the second field, use @option{--key=2,2} See also the @option{--debug} option to help determine the part of the line being used in the sort. -@item --debug +@optItem{sort,--debug} Highlight the portion of each line used for sorting. Also issue warnings about questionable usage to standard error. -@item --batch-size=@var{nmerge} -@opindex --batch-size +@optItem{sort,--batch-size,=@var{nmerge}} @cindex number of inputs to merge, nmerge Merge at most @var{nmerge} inputs at once. @@ -4992,10 +4697,8 @@ the operating system has other limits on the number of open files. If the value of @var{nmerge} exceeds the resource limit, @command{sort} silently uses a smaller value. -@item -o @var{output-file} -@itemx --output=@var{output-file} -@opindex -o -@opindex --output +@optItem{sort,-o,@w{ }@var{output-file}} +@optItemx{sort,--output,=@var{output-file}} @cindex overwriting of input, allowed Write output to @var{output-file} instead of standard output. Normally, @command{sort} reads all input before opening @@ -5015,17 +4718,14 @@ On newer systems, @option{-o} cannot appear after an input file if scripts should specify @option{-o @var{output-file}} before any input files. -@item --random-source=@var{file} -@opindex --random-source +@optItem{sort,--random-source,=@var{file}} @cindex random source for sorting Use @var{file} as a source of random data used to determine which random hash function to use with the @option{-R} option. @xref{Random sources}. -@item -s -@itemx --stable -@opindex -s -@opindex --stable +@optItem{sort,-s} +@optItemx{sort,--stable} @cindex sort stability @cindex sort's last-resort comparison @@ -5033,10 +4733,8 @@ Make @command{sort} stable by disabling its last-resort comparison. This option has no effect if no fields or global ordering options other than @option{--reverse} (@option{-r}) are specified. -@item -S @var{size} -@itemx --buffer-size=@var{size} -@opindex -S -@opindex --buffer-size +@optItem{sort,-S,@w{ }@var{size}} +@optItemx{sort,--buffer-size,=@var{size}} @cindex size for main memory sorting Use a main-memory sort buffer of the given @var{size}. By default, @var{size} is in units of 1024 bytes. Appending @samp{%} causes @@ -5054,10 +4752,8 @@ However, this option affects only the initial buffer size. The buffer grows beyond @var{size} if @command{sort} encounters input lines larger than @var{size}. -@item -t @var{separator} -@itemx --field-separator=@var{separator} -@opindex -t -@opindex --field-separator +@optItem{sort,-t,@w{ }@var{separator}} +@optItemx{sort,--field-separator,=@var{separator}} @cindex field separator character Use character @var{separator} as the field separator when finding the sort keys in each line. By default, fields are separated by the empty @@ -5077,10 +4773,8 @@ retain the field separators present between the endpoints of the range. To specify ASCII NUL as the field separator, use the two-character string @samp{\0}, e.g., @samp{sort -t '\0'}. -@item -T @var{tempdir} -@itemx --temporary-directory=@var{tempdir} -@opindex -T -@opindex --temporary-directory +@optItem{sort,-T,@w{ }@var{tempdir}} +@optItemx{sort,--temporary-directory,=@var{tempdir}} @cindex temporary directory @vindex TMPDIR Use directory @var{tempdir} to store temporary files, overriding the @@ -5090,8 +4784,7 @@ have a large sort or merge that is I/O-bound, you can often improve performance by using this option to specify directories on different file systems. -@item --parallel=@var{n} -@opindex --parallel +@optItem{sort,--parallel,=@var{n}} @cindex multithreaded sort Set the number of sorts run in parallel to @var{n}. By default, @var{n} is set to the number of available processors, but limited @@ -5099,10 +4792,8 @@ to 8, as performance gains diminish after that. Using @var{n} threads increases the memory usage by a factor of log @var{n}. Also see @ref{nproc invocation}. -@item -u -@itemx --unique -@opindex -u -@opindex --unique +@optItem{sort,-u} +@optItemx{sort,--unique} @cindex uniquifying output Normally, output only the first of a sequence of lines that compare @@ -5117,7 +4808,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}. -@optZeroTerminated +@optZeroTerminated{sort} @macro newlineFieldSeparator With @option{-z} the newline character is treated as a field separator. @end macro @@ -5363,17 +5054,13 @@ input. The following options change the operation mode: @table @samp -@item -e -@itemx --echo -@opindex -c -@opindex --echo +@optItem{shuf,-e} +@optItemx{shuf,--echo} @cindex command-line operands to shuffle Treat each command-line operand as an input line. -@item -i @var{lo}-@var{hi} -@itemx --input-range=@var{lo}-@var{hi} -@opindex -i -@opindex --input-range +@optItem{shuf,-i,@w{ }@var{lo}-@var{hi}} +@optItemx{shuf,--input-range,=@var{lo}-@var{hi}} @cindex input range to shuffle Act as if input came from a file containing the range of unsigned decimal integers @var{lo}@dots{}@var{hi}, one per line. @@ -5385,34 +5072,27 @@ operation modes: @table @samp -@item -n @var{count} -@itemx --head-count=@var{count} -@opindex -n -@opindex --head-count +@optItem{shuf,-n,@w{ }@var{count}} +@optItemx{shuf,--head-count,=@var{count}} @cindex head of output Output at most @var{count} lines. By default, all input lines are output. -@item -o @var{output-file} -@itemx --output=@var{output-file} -@opindex -o -@opindex --output +@optItem{shuf,-o,@w{ }@var{output-file}} +@optItemx{shuf,--output,=@var{output-file}} @cindex overwriting of input, allowed Write output to @var{output-file} instead of standard output. @command{shuf} reads all input before opening @var{output-file}, so you can safely shuffle a file in place by using commands like @code{shuf -o F