From e902f9b88d69df6419300d68f03a8bfd8ef485cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A1draig=20Brady?= Date: Tue, 15 Nov 2022 11:54:58 +0000 Subject: [PATCH] maint: avoid misquoting of some --long-options in texi * cfg.mk (sc_texi_long_option_escaped): A new check to avoid future instances of this. * doc/coreutils.texi (Common options): Rearrange this menu to be less repetitive in each description, and avoid long lines. Addresses https://bugs.gnu.org/59262 --- cfg.mk | 8 +++ doc/coreutils.texi | 166 +++++++++++++++++++++++---------------------- 2 files changed, 94 insertions(+), 80 deletions(-) diff --git a/cfg.mk b/cfg.mk index 8957cca34..99a9ad4d3 100644 --- a/cfg.mk +++ b/cfg.mk @@ -366,6 +366,14 @@ sc_option_desc_uppercase: $(ALL_MANS) @grep '^\\fB\\-' -A1 man/*.1 | LC_ALL=C grep '\.1.[A-Z][a-z]' \ && { echo 1>&2 '$@: found initial capitals in --help'; exit 1; } || : +# Option descriptions should not start with a capital letter. +# One could grep source directly as follows: +# grep -E " {2,6}-.*[^.] [A-Z][a-z]" $$($(VC_LIST_EXCEPT) | grep '\.c$$') +# but that would miss descriptions not on the same line as the -option. +sc_texi_long_option_escaped: doc/coreutils.info + @grep ' –[^ ]' '$<' \ + && { echo 1>&2 '$@: found unquoted --long-option'; exit 1; } || : + # Ensure all man/*.[1x] files are present. sc_man_file_correlation: check-x-vs-1 check-programs-vs-x diff --git a/doc/coreutils.texi b/doc/coreutils.texi index ebd096cda..9121f48b7 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -792,51 +792,28 @@ otherwise specified, a @samp{-} can appear as any operand that requires a file name. @menu -* Exit status:: Indicating program success or failure. -* Backup options:: @option{-b} @option{-S}, in some programs. -* Block size:: BLOCK_SIZE and @option{--block-size}, in some programs. -* Floating point:: Floating point number representation. -* Signal specifications:: Specifying signals using @option{--signal}. +Items shared between some programs: + +* Backup options:: @option{-b} @option{-S}. +* Block size:: BLOCK_SIZE and @option{--block-size}. +* Signal specifications:: Specifying signals with @option{--signal}. * Disambiguating names and IDs:: chgrp, chown, chroot, id: user and group syntax -* Random sources:: @option{--random-source}, in some programs. -* Target directory:: Specifying a target directory, in some programs. -* Trailing slashes:: @option{--strip-trailing-slashes}, in some programs. -* Traversing symlinks:: @option{-H}, @option{-L}, or @option{-P}, in some programs. -* Treating / specially:: @option{--preserve-root} and @option{--no-preserve-root}. -* Special built-in utilities:: @command{break}, @command{:}, @dots{} -* Standards conformance:: Conformance to the POSIX standard. -* Multi-call invocation:: Multi-call program invocation. +* Random sources:: @option{--random-source}. +* Target directory:: Specifying a target directory. +* Trailing slashes:: @option{--strip-trailing-slashes}. +* Traversing symlinks:: @option{-H}, @option{-L}, or @option{-P}. +* Treating / specially:: @option{--preserve-root} and the converse. +* Special built-in utilities:: @command{break}, @command{:}, @dots{} + +Items applicable to all programs: + +* Exit status:: Indicating program success or failure. +* Floating point:: Floating point number representation. +* Standards conformance:: Conformance to the POSIX standard. +* Multi-call invocation:: Multi-call program invocation. @end menu -@node Exit status -@section Exit status - -@macro exitstatus -An exit status of zero indicates success, -and a nonzero value indicates failure. -@end macro - -Nearly every command invocation yields an integral @dfn{exit status} -that can be used to change how other commands work. -For the vast majority of commands, an exit status of zero indicates -success. Failure is indicated by a nonzero value---typically -@samp{1}, though it may differ on unusual platforms as POSIX -requires only that it be nonzero. - -However, some of the programs documented here do produce -other exit status values and a few associate different -meanings with the values @samp{0} and @samp{1}. -Here are the exceptions: -@c You can generate the following list with: -@c grep initialize_exit_failure src/*.c | cut -f1 -d: | -@c sed -n 's|src/\(.*\)\.c|@command{\1},|p' | sort | fmt -@command{chroot}, @command{env}, @command{expr}, @command{ls}, -@command{nice}, @command{nohup}, @command{numfmt}, @command{printenv}, -@command{runcon}, @command{sort}, @command{stdbuf}, @command{test}, -@command{timeout}, @command{tty}. - - @node Backup options @section Backup options @@ -1084,42 +1061,6 @@ equivalent to @option{--block-size=si}. Note for @command{ls} the @option{-k} option does not control the display of the apparent file sizes, whereas the @option{--block-size} option does. -@node Floating point -@section Floating point numbers -@cindex floating point -@cindex IEEE floating point - -Commands that accept or produce floating point numbers employ the -floating point representation of the underlying system, and suffer -from rounding error, overflow, and similar floating-point issues. -Almost all modern systems use IEEE-754 floating point, and it is -typically portable to assume IEEE-754 behavior these days. IEEE-754 -has positive and negative infinity, distinguishes positive from -negative zero, and uses special values called NaNs to represent -invalid computations such as dividing zero by itself. For more -information, please see David Goldberg's paper -@uref{https://@/docs.oracle.com/@/cd/@/E19957-01/@/806-3568/@/ncg_goldberg.html, -What Every Computer Scientist Should Know About Floating-Point Arithmetic}. - -Commands that accept floating point numbers as options, operands or -input use the standard C functions @code{strtod} and @code{strtold} to -convert from text to floating point numbers. These floating point -numbers therefore can use scientific notation like @code{1.0e-34} and -@code{-10e100}. Commands that parse floating point also understand -case-insensitive @code{inf}, @code{infinity}, and @code{NaN}, although -whether such values are useful depends on the command in question. -Modern C implementations also accept hexadecimal floating point -numbers such as @code{-0x.ep-3}, which stands for @minus{}14/16 times -@math{2^-3}, which equals @minus{}0.109375. @xref{Parsing of -Floats,,, libc, The GNU C Library Reference Manual}. - -@vindex LC_NUMERIC -Normally the @env{LC_NUMERIC} locale determines the decimal-point -character. However, some commands' descriptions specify that they -accept numbers in either the current or the C locale; for example, -they treat @samp{3.14} like @samp{3,14} if the current locale uses -comma as a decimal point. - @node Signal specifications @section Signal specifications @cindex signals, specifying @@ -1538,6 +1479,71 @@ special built-in utilities like @command{history}, and @command{suspend}, and with Bash the command @samp{nice suspend} generates an error message instead of suspending. + +@node Exit status +@section Exit status + +@macro exitstatus +An exit status of zero indicates success, +and a nonzero value indicates failure. +@end macro + +Nearly every command invocation yields an integral @dfn{exit status} +that can be used to change how other commands work. +For the vast majority of commands, an exit status of zero indicates +success. Failure is indicated by a nonzero value---typically +@samp{1}, though it may differ on unusual platforms as POSIX +requires only that it be nonzero. + +However, some of the programs documented here do produce +other exit status values and a few associate different +meanings with the values @samp{0} and @samp{1}. +Here are the exceptions: +@c You can generate the following list with: +@c grep initialize_exit_failure src/*.c | cut -f1 -d: | +@c sed -n 's|src/\(.*\)\.c|@command{\1},|p' | sort | fmt +@command{chroot}, @command{env}, @command{expr}, @command{ls}, +@command{nice}, @command{nohup}, @command{numfmt}, @command{printenv}, +@command{runcon}, @command{sort}, @command{stdbuf}, @command{test}, +@command{timeout}, @command{tty}. + +@node Floating point +@section Floating point numbers +@cindex floating point +@cindex IEEE floating point + +Commands that accept or produce floating point numbers employ the +floating point representation of the underlying system, and suffer +from rounding error, overflow, and similar floating-point issues. +Almost all modern systems use IEEE-754 floating point, and it is +typically portable to assume IEEE-754 behavior these days. IEEE-754 +has positive and negative infinity, distinguishes positive from +negative zero, and uses special values called NaNs to represent +invalid computations such as dividing zero by itself. For more +information, please see David Goldberg's paper +@uref{https://@/docs.oracle.com/@/cd/@/E19957-01/@/806-3568/@/ncg_goldberg.html, +What Every Computer Scientist Should Know About Floating-Point Arithmetic}. + +Commands that accept floating point numbers as options, operands or +input use the standard C functions @code{strtod} and @code{strtold} to +convert from text to floating point numbers. These floating point +numbers therefore can use scientific notation like @code{1.0e-34} and +@code{-10e100}. Commands that parse floating point also understand +case-insensitive @code{inf}, @code{infinity}, and @code{NaN}, although +whether such values are useful depends on the command in question. +Modern C implementations also accept hexadecimal floating point +numbers such as @code{-0x.ep-3}, which stands for @minus{}14/16 times +@math{2^-3}, which equals @minus{}0.109375. @xref{Parsing of +Floats,,, libc, The GNU C Library Reference Manual}. + +@vindex LC_NUMERIC +Normally the @env{LC_NUMERIC} locale determines the decimal-point +character. However, some commands' descriptions specify that they +accept numbers in either the current or the C locale; for example, +they treat @samp{3.14} like @samp{3,14} if the current locale uses +comma as a decimal point. + + @node Standards conformance @section Standards conformance @@ -7610,9 +7616,9 @@ or any of the following options is in effect: @opindex --group-directories-first Group all the directories before the files and then sort the directories and the files separately using the selected sort key -(see --sort option). +(see @option{--sort} option). That is, this option specifies a primary sort key, -and the --sort option specifies a secondary key. +and the @option{--sort} option specifies a secondary key. However, any use of @option{--sort=none} (@option{-U}) disables this option altogether. @@ -12386,7 +12392,7 @@ are often symbolic links. @opindex -d @var{depth} @opindex --max-depth=@var{depth} @cindex limiting output of @command{du} -Show the total for each directory (and file if --all) that is at +Show the total for each directory (and file if @option{--all}) that is at most MAX_DEPTH levels down from the root of the hierarchy. The root is at level 0, so @code{du --max-depth=0} is equivalent to @code{du -s}. -- 2.26.2