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