Review of Chapter 4: Branching and Merging

[Brian W. Fitzpatrick]

On 2/24/07, C. Michael Pilato <cmpilato at red-bean.com> wrote:
> 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://...

OK.  I'll put this in hacking when I get back home.

-Fitz