[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

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

From: Julian Foad <julianfoad_at_btopenworld.com>
Date: 2005-11-26 17:27:45 CET

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
Received on Sat Nov 26 17:28:45 2005

This is an archived mail posted to the Subversion Dev mailing list.