On 01/31/2012 11:16 AM, Jim Meyering wrote: > Pádraig Brady wrote: >> I notice that `pr -S` takes an optional arg, >> but the docs say it's required. >> Should I fix the docs or the code? > > Thanks for checking, and good point. > The "Mandatory arguments to long options are mandatory for short options too." > statement doesn't apply to optional arguments. > > --help implies it's optional with the long-named option, > "--sep-string[=STRING]": > > -SSTRING, --sep-string[=STRING] > separate columns by STRING, > without -S: Default separator <TAB> with -J and <space> > otherwise (same as -S" "), no effect on column options > > coreutils.texi says this: > > `-SSTRING' > `--sep-string[=STRING]' > Use STRING to separate output columns. The `-S' option doesn't > affect the `-W/-w' option, unlike the `-s' option which does. It > does not affect line truncation or column alignment. Without > `-S', and with `-J', `pr' uses the default output separator, TAB. > Without `-S' or `-J', `pr' uses a `space' (same as `-S" "'). > `--sep-string' with no `=STRING' is equivalent to > `--sep-string=""'. > > You're welcome to make it clearer that the -S option arg is also optional. >
Cool. I'm pushing the attached. cheers, Pádraig.
>From 285b19210bb6fc4112478e9addc6c87d8b87cdc0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email protected]> Date: Mon, 30 Jan 2012 11:59:04 +0000 Subject: [PATCH] doc: clarify --help output for some optional arguments * src/pr.c (usage): Fix the -S description to indicate that the argument is optional for the short option. * doc/coreutils.texi (pr invocation): Likewise. * src/od.c (usage): Fix the -S description to indicate that the argument is required for the short option. Clarify -w takes an argument and that it is optional. --- doc/coreutils.texi | 6 +++--- src/od.c | 4 ++-- src/pr.c | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/coreutils.texi b/doc/coreutils.texi index 6f24dd3..52838e7 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -2518,7 +2518,7 @@ three column options (@option{-COLUMN}|@option{-a -COLUMN}|@option{-m}) unless @option{-w} is set. This is a @acronym{POSIX}-compliant formulation. -@item -S@var{string} +@item -S[@var{string}] @itemx --sep-string[=@var{string}] @opindex -S @opindex --sep-string @@ -2528,8 +2528,8 @@ does not affect line truncation or column alignment. Without @option{-S}, and with @option{-J}, @command{pr} uses the default output separator, TAB@. Without @option{-S} or @option{-J}, @command{pr} uses a @samp{space} -(same as @option{-S"@w{ }"}). @option{--sep-string} with no -@samp{=@var{string}} is equivalent to @option{--sep-string=""}. +(same as @option{-S"@w{ }"}). +If no @samp{@var{string}} argument is specified, @samp{""} is assumed. @item -t @itemx --omit-header diff --git a/src/od.c b/src/od.c index 2da2825..7593796 100644 --- a/src/od.c +++ b/src/od.c @@ -313,10 +313,10 @@ All arguments to long options are mandatory for short options.\n\ "), stdout); fputs (_("\ -N, --read-bytes=BYTES limit dump to BYTES input bytes\n\ - -S, --strings[=BYTES] output strings of at least BYTES graphic chars\n\ + -S BYTES, --strings[=BYTES] output strings of at least BYTES graphic chars\n\ -t, --format=TYPE select output format or formats\n\ -v, --output-duplicates do not use * to mark line suppression\n\ - -w, --width[=BYTES] output BYTES bytes per output line\n\ + -w[BYTES], --width[=BYTES] output BYTES bytes per output line\n\ --traditional accept arguments in traditional form\n\ "), stdout); fputs (HELP_OPTION_DESCRIPTION, stdout); diff --git a/src/pr.c b/src/pr.c index 4f949de..f1e310f 100644 --- a/src/pr.c +++ b/src/pr.c @@ -250,7 +250,7 @@ compliant formulation. The source code translates -s into the new options -S and -J, also -W if required. - -S STRING, --sep-string[=STRING] + -S[STRING], --sep-string[=STRING] Separate columns by any string STRING. The -S option doesn't react upon the -W/-w option (unlike -s option does). It defines a separator nothing else. @@ -2842,7 +2842,7 @@ Mandatory arguments to long options are mandatory for short options too.\n\ options (-COLUMN|-a -COLUMN|-m) except -w is set\n\ "), stdout); fputs (_("\ - -SSTRING, --sep-string[=STRING]\n\ + -S[STRING], --sep-string[=STRING]\n\ separate columns by STRING,\n\ without -S: Default separator <TAB> with -J and <space>\n\ otherwise (same as -S\" \"), no effect on column options\n\ -- 1.7.6.4
