You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Julian Foad <ju...@btopenworld.com> on 2006/07/02 23:12:05 UTC

Re: svn commit: r20301 - in trunk/subversion: svn svnadmin svndumpfilter svnlook svnsync tests/cmdline tests/cmdline/getopt_tests_data

Malcolm Rowe wrote:
> On Thu, Jun 29, 2006 at 04:28:10PM -0700, julianfoad@tigris.org wrote:
> 
>>Describe "--version" in the main help display rather than as an option to
>>the "help" subcommand, for logical correctness and so users can reasonably
>>find it.  Remove "--version" and "--quiet" options from the "help" command.
>>Do not allow "--version" to be combined with "help" or any other arguments
>>or options.
> 
> Hmm, I'm not sure if we care too much, but there's now no documentation
> of the 'svn --version --quiet' combination.

Of its meaning?  You're right.  Its existence and syntax is documented:

> usage: svn <subcommand> [options] [args]
>        svn --version [--quiet]

... but not the meaning.  The old documentation was pretty useless even when 
one found it:

> $ svn help help
> help (?, h): Describe the usage of this program or its subcommands.
> usage: help [SUBCOMMAND...]
> 
> Valid options:
>   --version                : print client version info
>   -q [--quiet]             : print as little as possible

It wasn't at all obvious that "--quiet" would have an effect in conjunction 
with "--version" and not with "help".  I figured there was no sense in 
retaining that degree of helpfulness, and no great need to provide a proper 
description although the logical side of me would rather like the description 
to be there.  We could say something like:

   Type 'svn --version' to see the program version and RA modules
     or 'svn --version --quiet' to see just the version number.

That seems better.

Then, if we're going to have this full prose description of "--version" usage, 
we don't need the usage line, and taking into account Nori's suggestion to 
document even svndumpfilter's "--version" option in prose, the additional usage 
line for it in each program is then unnecessary.  We didn't have a usage line 
for the other global option ("--help") so it was a bit inconsistent anyway.

I'll do that: provide descriptions and remove "usage" lines.

Finally, in "svnserve" and "svnversion" the help is in a different style. 
Those programs don't have subcommands, and the general help lists all available 
options with descriptions.  The description of "--version":

   --version                : show version information

is ambiguous in "svnversion", as it is a program whose purpose is to show 
version information anyway, so I'll tweak that to "show program version 
information".  I will make the same change in all programs for consistency (so 
the translators only have one such string to translate), though it will not now 
be visible to the user in any programs other than "svnserve" and "svnversion".

See r20353.

Thanks for the comments.

- Julian

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org

Re: svn commit: r20301 - in trunk/subversion: svn svnadmin svndumpfilter svnlook svnsync tests/cmdline tests/cmdline/getopt_tests_data

Posted by Malcolm Rowe <ma...@farside.org.uk>.
On Mon, Jul 03, 2006 at 12:12:05AM +0100, Julian Foad wrote:
> >Hmm, I'm not sure if we care too much, but there's now no documentation
> >of the 'svn --version --quiet' combination.
> 
> Of its meaning?  You're right.  Its existence and syntax is documented:
> 
> >usage: svn <subcommand> [options] [args]
> >       svn --version [--quiet]
> 

Oh!  For some reason, I didn't see that.

That's all I meant, but the changes you made in r20353 are great anyway
- thanks!

Regards,
Malcolm

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org