You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by "Nicolai, Johannes" <Jo...@student.hpi.uni-potsdam.de> on 2007/11/03 05:11:18 UTC
Inconsistencies in switch descriptions in online help
After going through the whole online help of Subversion, I had the feeling that it was intentionally planned, that a switch always has the same description, no matter for which command you use it. If necessary, the description of the command specifies the exact behaviour of the switch.
The big advantage of this approach is, that you can describe the general semantic of a switch without naming any commands.
I am currently preparing a cheat sheet for Subversion, that is designed like a big matrix with all the switches, its descriptions and its applicable commands, that would rely on that general rule.
However, there is one exception from this general rule: svn lock's -m and -F switches differ from all other -m and -F switches:
-m [--message] ARG : specify lock comment ARG
-F [--file] ARG : read lock comment from file ARG
differs from
-m [--message] ARG : specify log message ARG
-F [--file] ARG : read log message from file ARG
On the other hand, the description of the --force-log option, that is applicable to svn lock as well, always refers to log messages
--force-log : force validity of log message source
That might confuse users of the online help, because it is not clear which log message is meant in this context (above it was only spoken of lock messages).
Should the description of the --force-log message be changed for svn lock as well or should the -m and -F switch description be defined globally (and svn help lock will have an introducing sentence about the meaning of the -m and -F option)?
Regards
Johannes
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Inconsistencies in switch descriptions in online help
Posted by David Glasser <gl...@davidglasser.net>.
On 11/2/07, Nicolai, Johannes
<Jo...@student.hpi.uni-potsdam.de> wrote:
>
> After going through the whole online help of Subversion, I had the feeling that it was intentionally planned, that a switch always has the same description, no matter for which command you use it. If necessary, the description of the command specifies the exact behaviour of the switch.
> The big advantage of this approach is, that you can describe the general semantic of a switch without naming any commands.
> I am currently preparing a cheat sheet for Subversion, that is designed like a big matrix with all the switches, its descriptions and its applicable commands, that would rely on that general rule.
>
> However, there is one exception from this general rule: svn lock's -m and -F switches differ from all other -m and -F switches:
>
> -m [--message] ARG : specify lock comment ARG
> -F [--file] ARG : read lock comment from file ARG
>
> differs from
>
> -m [--message] ARG : specify log message ARG
> -F [--file] ARG : read log message from file ARG
>
> On the other hand, the description of the --force-log option, that is applicable to svn lock as well, always refers to log messages
>
> --force-log : force validity of log message source
>
> That might confuse users of the online help, because it is not clear which log message is meant in this context (above it was only spoken of lock messages).
>
> Should the description of the --force-log message be changed for svn lock as well or should the -m and -F switch description be defined globally (and svn help lock will have an introducing sentence about the meaning of the -m and -F option)?
Good call. See r27580.
--dave
--
David Glasser | glasser@davidglasser.net | http://www.davidglasser.net/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Inconsistencies in switch descriptions in online help
Posted by David Glasser <gl...@davidglasser.net>.
On 11/2/07, Nicolai, Johannes
<Jo...@student.hpi.uni-potsdam.de> wrote:
>
> After going through the whole online help of Subversion, I had the feeling that it was intentionally planned, that a switch always has the same description, no matter for which command you use it. If necessary, the description of the command specifies the exact behaviour of the switch.
For the record, it *is* intentionally planned that options always take
the same number of arguments (so you can even use them before the
subcommand); in a small number of cases the meaning varies, though.
Take a look at the commands table in subversion/svn/main.c for all the details.
--dave
--
David Glasser | glasser@davidglasser.net | http://www.davidglasser.net/
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org