[PATCH] 'svn propset' help doc fix

[Alexander Thomas <kc...@gmail.com>]

Here's the patch to fix inconsistency between 'svn propset' behavior and 
its command line help doc.

Present 'svn propset' help doc says that "PROPVAL or -F VALFILE" is 
optional. But actually
'svn ps' takes a mandatory PROPVAL as the first argument, if "-F 
VALFILE" is not specified.
Also unversioned propchange on repos takes a optional URL or PATH as the 
second argument.
Now PATH is undocumented.

-AT

Re: [PATCH] 'svn propset' help doc fix

[Julian Foad <ju...@btopenworld.com>]

Alexander Thomas wrote:
> 
> Here's the patch to fix inconsistency between 'svn propset' behavior and 
> its command line help doc.
> 
> Present 'svn propset' help doc says that "PROPVAL or -F VALFILE" is 
> optional. But actually
> 'svn ps' takes a mandatory PROPVAL as the first argument, if "-F 
> VALFILE" is not specified.
> Also unversioned propchange on repos takes a optional URL or PATH as the 
> second argument.
> Now PATH is undocumented.

Thanks for these patches (this and the one for "propdel").

(Looking through all of the on-line help, I think a bit of an overhaul to make 
it all a bit more consistent would be a good idea.)


> ------------------------------------------------------------------------
> 
> Fix for inconsistency between 'svn propset' help doc and behavior.
> 
> * subversion/clients/cmdline/main.c
>   (svn_cl__cmd_table): Modified command line help doc.
> 
> 
> ------------------------------------------------------------------------
> 
> Index: subversion/clients/cmdline/main.c
> ===================================================================
> --- subversion/clients/cmdline/main.c	(revision 17512)
> +++ subversion/clients/cmdline/main.c	(working copy)
> @@ -559,13 +559,18 @@
>  
>    { "propset", svn_cl__propset, {"pset", "ps"},
>      N_("Set PROPNAME to PROPVAL on files, dirs, or revisions.\n"
> -       "usage: 1. propset PROPNAME [PROPVAL | -F VALFILE] PATH...\n"
> -       "       2. propset PROPNAME --revprop -r REV [PROPVAL | -F VALFILE] "
> -       "[URL]\n"
> +       "usage: 1. propset PROPNAME PROPVAL PATH...\n"

Yes.  Perhaps the writer intended the brackets to mean grouping rather than 
"optional", and one could argue that "PROPVAL" is optional because it doesn't 
have to be given (if "-F VALFILE" is given instead), but your fix makes it 
consistent with "svn add PATH..." where PATH can be replaced with "--targets FILE".

> +       "       2. propset PROPNAME --revprop -r REV PROPVAL [URL | PATH]\n"

Instead of "[URL | PATH]" I'll write "[TARGET]" as we do in all the other commands.

>         "\n"
>         "  1. Creates a versioned, local propchange in working copy.\n"
>         "  2. Creates an unversioned, remote propchange on repos revision.\n"
> +       "     If both URL and PATH is omitted, current directory is taken\n"
> +       "     as PATH.

"are omitted".

We are very inconsistent in whether we say that and how we say it.  It is 
mentioned as a general rule in the "svn help" output, though I wouldn't 
necessarily go looking for it there if I wanted to know.  I don't think I'll 
add it here.  It would apply also to case 2 of "propedit" and cases 1 and 2 of 
"propdel" and "propget" and "proplist".

> +       If PATH is a working copy path, the corresponding\n"
> +       "     repository URL will be used.\n"

That's true, but I felt it more useful to say that the path or URL does not 
have any meaning except for determining which repository to access, which 
implies what you said.

>         "\n"
> +       "  A property value must be provided either with PROPVAL or with\n"
> +       "  -F VALFILE, where VALFILE is file containg the property value.\n"
> +       "\n"

"is a file" and "containing", but I'll fix those typos.  I felt "--file" was 
better than "-F" and consistent with "commit", but generally we're inconsistent 
about long and short option names in help text.


I have committed a combination of your syntax corrections with my wording in 
r17521.  I hope that's OK.

- Julian

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