Review of Chapter 4: Branching and Merging
C. Michael Pilato
cmpilato at red-bean.com
Sat Feb 24 15:49:31 CST 2007
Ben Collins-Sussman wrote:
> So I advocate these rules:
>
> * When discussing an option in a paragraph, always use the long
> form, and optionally display the short form too (so as to make a
> connection between them.) For example, "you can use the --revision
> (-r) option to specify a revision number." This always highlights the
> option's true name.
>
> * In console examples, I think we should use the short forms, since
> that's what users really use. This will keep users exposed to
> real-life examples, and allow them to feel free to use short options
> themselves.
My recollection was that we said short-form options were fine, but never
use subcommand aliases.
So, +1 on making a clear rule in HACKING, and +1 on these particular
rules. Though, I'd say that in the first rule, showing the short form
shouldn't be an option -- tying the prose to the examples is pretty key
to comprehension. You wouldn't want:
Use the --revision option to checkout an old revision:
$ svn co -r 45 http://...
--
C. Michael Pilato <cmpilato at red-bean.com>
"The Christian ideal has not been tried and found wanting. It has
been found difficult; and left untried." -- G. K. Chesterton
More information about the svnbook-dev
mailing list