Review of Chapter 4: Branching and Merging

[Ben Collins-Sussman]

Here are my feelings.

I think our goal should be to have our readers gain an awareness of
*both* long and short forms.  The long forms are great for clarity
when explaining things, and great for initial learning.  But if you
use Subversion for than a few days, the long forms get really
annoying.  Real users graduate to short forms relatively quickly.

So I think that a rule of "always long switches, everywhere" is bad
for our readers.  Someone who diligently works their way through the
book should not be stuck in an ivory tower of theoretical long forms;
they should at least have normal exposure to short forms, and not be
surprised when they see others using them.  It's all about balacing
theory with practical skills.

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.


On 2/24/07, Brian W. Fitzpatrick <fitz at red-bean.com> wrote:
> On 2/24/07, Ben Collins-Sussman <sussman at red-bean.com> wrote:
> > I'm confused;  this chapter has had '-r' running through it for years and years.
> >
> > What exactly is our policy on options again?  I keep losing track, it
> > seems like it changes.
> >
> > I seem to recall that first we used a mixture of short and long forms,
> > then went super-militant and decided to ban all short forms
> > completely.  Then later, we backed off and found a middle ground where
> > we decided that we'd use long forms when talking about option names
> > within paragraphs of text, but console examples could still be free to
> > use short-form.
> >
> > Am I remembering incorrectly?  At the moment, I see a mixture of short
> > and long options within examples throughout the whole book (including
> > your chapter, fitz!)
>
> I thought our rule was "always long switches".  Let's decide now once
> and for all and I'll put it in HACKING (there's already a note about
> using long subcommands).
>
> -Fitz
>