[RFC] branch --bind

[Eli Zaretskii]

> From: "Stephen J. Turnbull" <stephen at xemacs.org>
> Date: Fri, 08 Jan 2010 20:30:05 +0900
> Cc: Martin Pool <mbp at canonical.com>,
> 	"Matthew D. Fuller" <fullermd at over-yonder.net>,
> 	Ian Clatworthy <ian.clatworthy at canonical.com>,
> 	bazaar <bazaar at lists.canonical.com>
> 
> Long lists of tersely (even obscurely) documented options is a common
> complaint on emacs-devel.  Probably 70% come from one developer, Eli,
> but Eli is also producing about 70% of the testing of various
> workflows that have been proposed, so it seems more or less
> proportionate to the work he's doing (ie, not just a single cranky
> individual).

Maybe also because this old fart is used to placing a lot of faith in
documentation.  And indeed, as Stephen says, quite a few portions of
Bazaar documentation leave me bewildered.  I think the main problem is
that they use obscure phrases or terminology that is not explained
where it is used, sometimes not explained anywhere.  And even if it is
explained somewhere else, there are no cross-references there.

Just two random examples:

 bzr add

    --file-ids-from=ARG 
      Lookup file ids from this tree.
      ...
      -file-ids-from will try to use the file ids from the supplied
      path.

Huh? what are file ids?

 bzr merge

    --uncommitted Apply uncommitted changes from a working copy,
      instead of branch changes.

What are ``branch changes''? what branch is it talking about?

Etc., etc.

It doesn't help that the user manual doesn't have an index, and one is
forced to use simple text searches -- which doesn't seem to work well
when I want to search for a phrase, as opposed to a single word.  Text
searches are much less efficient than index search, because the person
who indexed the manual usually thinks about phrases that someone who
searches would think about.  By contrast, the text of the manual does
not necessarily include those phrases verbatim.

Now, take the last discussion about "branch --bind": the name of the
option already puts an unwarranted mental pressure on the user.  Why
"bind"?  We are asking bzr to create a bound branch, so why not
"branch --bound"?  At least to me, that would make it far easier to
remember the option.  IOW, when you pick up a name of a command or an
option, please think about making it easy to remember.

Thank you for your attention.