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 2003/06/25 21:51:33 UTC
PATCH: help text: presentation of optionally-repeated arguments
These usage messages all specify an argument that can be repeated:
usage: cat TARGET [TARGET [TARGET ... ]]
usage: list URL [URL ... ]
usage: svnadmin rmtxns REPOS_PATH TXN_NAME [TXN_NAME2 ...]
They all specify the repeatable argument in slightly different and long-winded ways. I propose to change the specification of repeatable arguments to this form:
usage: cat TARGET...
Users familiar with this sort of notation will not be troubled. Inexperienced users may at first be less sure (compared with the current message) whether that TARGET has to be specified at least once, but as soon as they see the alternative form "[TARGET]..." used in a different command, they should then be sure.
This is the way the GNU core utilities do it. Of course there's no particular reason why we should match the GNU utilities; I'm just pointing out that I didn't make up this convention myself. For an optional repeated argument my first thought was to put the ellipsis inside the brakets - [SUBCOMMAND...] - but there may be a good reason not to, such as being able to have spaces in the repeated part, as in "[-D SYMBOL]...". So I would change
usage: help [SUBCOMMAND [SUBCOMMAND ... ]]
to
usage: help [SUBCOMMAND]...
The patch below (against revision 6346) does this (and also fixes the names that the three utility programs present in their "help help" output).
I believe this will make the messages clearer. Comments? (I'll split the patch if you want.)
- Julian
Log message: ------------------------------------------------------------------]
Two improvements to the help text of the command-line client and utilities:
1. To reduce inconsistency and repetition, simplify the specification of
arguments that can be repeated, by writing
"TARGET..." instead of things like "TARGET [TARGET [TARGET ... ]]" and
"[TARGET]..." instead of things like "[TARGET [TARGET ... ]]".
2. In the usage message for the "help" command (which is displayed when the
two arguments "help help" are given), the three utilities were all referring
to themselves as "svn". Fixed them to say "svnlook" etc. as appropriate.
* subversion/svnadmin/main.c
* subversion/svnlook/main.c
* subversion/svndumpfilter/main.c
(cmd_table): Simplify the specification of repeated arguments.
Fix the program name in the "help help" usage message.
* subversion/clients/cmdline/main.c
(svn_cl__cmd_table): Simplify the specification of repeated arguments.
Re: PATCH: help text: presentation of optionally-repeated arguments
Posted by Julian Foad <ju...@btopenworld.com>.
Greg Hudson wrote:
> On Thu, 2003-06-26 at 13:06, Julian Foad wrote:
>
>>I don't see that "[OPTION]..." is ambiguous. Do you read it as
>>"brackets mean zero or more; dots mean one or more" mean that
>
> I read brackets as "zero or one" and dots as "one or more". In extended
> regexp notation, "(foo?)+" is an ambiguous grammar--because any number
> of empty strings matching "(foo?)" can be inserted into the
> sequence--while "(foo+)?" is not. (As I said before, I think some
> people find unambiguous grammars more intuitive, all other things being
> equal.)
OK, I see now what you mean by "ambiguous", and I agree.
> Thanks for rewriting the patch to my preference.
OK, but I messed up a bit as cmpilato pointed out.
>>My example of a possible reason was that it provides (as a free bonus)
>>a convenient way to specify that a group of words may be repeated.
>>However, this syntax cannot directly specify a group of words that may
>>be repeated ONE OR MORE times. In that case I would need to write
>>something like:
>>
>> cc -D SYMBOL [-D SYMBOL]...
>
> Understood. I don't think that will ever be a concern for us.
I see no reason why we shouldn't ever have a command with this sort of syntax, but it may well be acceptable to document it in this way with part of it mentioned twice.
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: PATCH: help text: presentation of optionally-repeated arguments
Posted by Greg Hudson <gh...@MIT.EDU>.
On Thu, 2003-06-26 at 13:06, Julian Foad wrote:
> I don't see that "[OPTION]..." is ambiguous. Do you read it as
> "brackets mean zero or more; dots mean one or more" mean that
I read brackets as "zero or one" and dots as "one or more". In extended
regexp notation, "(foo?)+" is an ambiguous grammar--because any number
of empty strings matching "(foo?)" can be inserted into the
sequence--while "(foo+)?" is not. (As I said before, I think some
people find unambiguous grammars more intuitive, all other things being
equal.)
Thanks for rewriting the patch to my preference.
> My example of a possible reason was that it provides (as a free bonus)
> a convenient way to specify that a group of words may be repeated.
> However, this syntax cannot directly specify a group of words that may
> be repeated ONE OR MORE times. In that case I would need to write
> something like:
>
> cc -D SYMBOL [-D SYMBOL]...
Understood. I don't think that will ever be a concern for us.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: PATCH: help text: presentation of optionally-repeated arguments
Posted by Julian Foad <ju...@btopenworld.com>.
Julian Foad wrote:
>
> The attached patch now includes the corresponding modifications to
> expected test results, and passes at least the first 22 groups of tests
> (which includes getopt_tests.py and goes up to diff_tests.py).
I can now confirm that it passes all 29 groups of tests that are executed by "make check" on my system.
- Julian
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: PATCH: help text: presentation of optionally-repeated arguments
Posted by Julian Foad <ju...@btopenworld.com>.
cmpilato@collab.net wrote:
> Julian Foad <ju...@btopenworld.com> writes:
>
>>Well, I don't mind either way. Here is the patch the way you prefer it.
>
> Now, perhaps try one more time, the way *I* prefer it.
>
> a) with a log message, and
Oops... I forgot that. Here it is, adjusted to match the "dots inside" version of the patch.
Log message: ------------------------------------------------------------------]
Two improvements to the help text of the command-line client and utilities:
1. To reduce inconsistency and repetition, simplify the specification of
arguments that can be repeated, by writing
"TARGET..." instead of things like "TARGET [TARGET [TARGET ... ]]" and
"[TARGET...]" instead of things like "[TARGET [TARGET ... ]]".
2. In the usage message for the "help" command (which is displayed when the
two arguments "help help" are given), the three utilities were all referring
to themselves as "svn". Fixed them to say "svnlook" etc. as appropriate.
* subversion/svnadmin/main.c
* subversion/svnlook/main.c
* subversion/svndumpfilter/main.c
(cmd_table): Simplify the specification of repeated arguments.
Fix the program name in the "help help" usage message.
* subversion/clients/cmdline/main.c
(svn_cl__cmd_table): Simplify the specification of repeated arguments.
> b) not causing some of the getopt_test.py tests to fail.
Good grief. I didn't think the usage messages would be tested. Note to self: DON'T THINK; JUST RUN THE TESTS.
The attached patch now includes the corresponding modifications to expected test results, and passes at least the first 22 groups of tests (which includes getopt_tests.py and goes up to diff_tests.py).
Thanks for your patience.
- Julian
Re: PATCH: help text: presentation of optionally-repeated arguments
Posted by cm...@collab.net.
Julian Foad <ju...@btopenworld.com> writes:
> > I don't understand this reasoning. I think "[SUBCOMMAND...]" makes
> > more
> > sense because it specifies a non-ambiguous grammar, which for some
> > people is more intuitive.
>
> Well, I don't mind either way. Here is the patch the way you prefer it.
Now, perhaps try one more time, the way *I* prefer it.
a) with a log message, and
b) not causing some of the getopt_test.py tests to fail.
:-)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: PATCH: help text: presentation of optionally-repeated arguments
Posted by Julian Foad <ju...@btopenworld.com>.
Greg Hudson wrote:
> A big +1 here, with a nitpick:
>
> On Wed, 2003-06-25 at 17:51, Julian Foad wrote:
>
>>For an optional repeated argument my first thought was to put the
>>ellipsis inside the brakets - [SUBCOMMAND...] - but there may be a
>>good reason not to, such as being able to have spaces in the repeated
>>part, as in "[-D SYMBOL]...". So I would change
>
> I don't understand this reasoning. I think "[SUBCOMMAND...]" makes more
> sense because it specifies a non-ambiguous grammar, which for some
> people is more intuitive.
Well, I don't mind either way. Here is the patch the way you prefer it.
To address your comment, my reasoning was that people writing some (but by no means all) GNU programs have chosen to put the ellipsis outside the brackets, and there is a fair chance that they may have had a good reason for doing so, and therefore I would match what they did without knowing the reason. E.g.
> rm --help
Usage: rm [OPTION]... FILE...
I don't see that "[OPTION]..." is ambiguous. Do you read it as "brackets mean zero or more; dots mean one or more" mean that
My example of a possible reason was that it provides (as a free bonus) a convenient way to specify that a group of words may be repeated. However, this syntax cannot directly specify a group of words that may be repeated ONE OR MORE times. In that case I would need to write something like:
cc -D SYMBOL [-D SYMBOL]...
which puts the dots outside the brackets anyway. So far we don't need multi-word repetitions, so I still think either version is just about as good as the other.
- Julian
Re: PATCH: help text: presentation of optionally-repeated arguments
Posted by Greg Hudson <gh...@MIT.EDU>.
A big +1 here, with a nitpick:
On Wed, 2003-06-25 at 17:51, Julian Foad wrote:
> For an optional repeated argument my first thought was to put the
> ellipsis inside the brakets - [SUBCOMMAND...] - but there may be a
> good reason not to, such as being able to have spaces in the repeated
> part, as in "[-D SYMBOL]...". So I would change
I don't understand this reasoning. I think "[SUBCOMMAND...]" makes more
sense because it specifies a non-ambiguous grammar, which for some
people is more intuitive.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: PATCH: help text: presentation of optionally-repeated arguments
Posted by Paul L Lussier <pl...@lanminds.com>.
In a message dated: Sat, 28 Jun 2003 22:33:18 +0200
Sander Roobol said:
>On Fri, Jun 27, 2003 at 10:33:22AM -0400, Paul L Lussier wrote:
>>
>> Filed as issue 1377 here:
>>
>> http://subversion.tigris.org/issues/show_bug.cgi?id=1377
>
>Whoah, I guess you live faster than most of us :)
Nahh, I decided 'Friday is patch issue day' :)
>In my timeframe less than a day has passed since Julian Foad posted the
>second version of the patch. It might be better to wait a while and give
>the developers a chance to review the patches so the issue tracker
>doesn't get cluttered unnecesary.
Yeah, I know. I only meant to enter an issue on 2 submitted patches,
but I got ahead of myself :)
>Also, the issue you filed looks fine but it seems you forgot to add the
>author of the patch to the cc list.
Oh, good idea! I'll do that as well.
>And it might be nice to state more clearly who made the patch.
>I just wrote 'patch by ...'
Will do!
>but actually I like your idea of adding the complete log message to the issue.
Well, I figured the log message was (should be) a good 'description'
of what the patch actually does :)
> please combine the best of those two ways :)
Okay.
>Apart from the nitpicking I must say thanks for doing this! I'll post my
>current list of patches tomorrow...
You're welcome, and please continue picking these nits, I seem to be
covered in them. Until they're all gone, I still have a lot to learn ;)
--
Seeya,
Paul
--
Key fingerprint = 1660 FECC 5D21 D286 F853 E808 BB07 9239 53F1 28EE
It may look like I'm just sitting here doing nothing,
but I'm really actively waiting for all my problems to go away.
If you're not having fun, you're not doing it right!
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: PATCH: help text: presentation of optionally-repeated arguments
Posted by Sander Roobol <ph...@wanadoo.nl>.
On Fri, Jun 27, 2003 at 10:33:22AM -0400, Paul L Lussier wrote:
>
> Filed as issue 1377 here:
>
> http://subversion.tigris.org/issues/show_bug.cgi?id=1377
Whoah, I guess you live faster than most of us :)
In my timeframe less than a day has passed since Julian Foad posted the
second version of the patch. It might be better to wait a while and give
the developers a chance to review the patches so the issue tracker
doesn't get cluttered unnecesary.
Also, the issue you filed looks fine but it seems you forgot to add the
author of the patch to the cc list. And it might be nice to state more
clearly who made the patch. I just wrote 'patch by ...' but actually I
like your idea of adding the complete log message to the issue. Well,
please combine the best of those two ways :)
Apart from the nitpicking I must say thanks for doing this! I'll post my
current list of patches tomorrow...
Sander
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: PATCH: help text: presentation of optionally-repeated arguments
Posted by Paul L Lussier <pl...@lanminds.com>.
Filed as issue 1377 here:
http://subversion.tigris.org/issues/show_bug.cgi?id=1377
--
Seeya,
Paul
--
Key fingerprint = 1660 FECC 5D21 D286 F853 E808 BB07 9239 53F1 28EE
It may look like I'm just sitting here doing nothing,
but I'm really actively waiting for all my problems to go away.
If you're not having fun, you're not doing it right!
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org