[MERGE] Add Bazaar Zen section to the User Guide

[John Yates]

Robert Collins wrote:

> Revision Identifiers are globally unique identifiers for an individual

> revision in bzr. They are long, cumbersome to type and are not 
> comparable to each other in any way. Revision id's are generated at 
> commit time (or for imports from other systems, at the time of the 
> import).
> 
> Bzr provides a much shorter identifier for revisions call a "revision 
> number'. Revision numbers are dotted decimal identifiers that trace a 
> path through the revision graph for a branch. Revision numbers are 
> generally shorter than revision ids, and (within a single branch) can 
> be compared with each other to get a sense of their graph
relationship.
> Revision Numbers are generated on the fly when 'log' or other commands

> are executing, because they depend on the current branch tip.

I think that the important difference in stability is too hidden.  How
about something like this:

  Revision Identifiers are _immutable_, globally unique references to
  individual revisions in bzr.  They are long, cumbersome to type and
  are not comparable to each other in any way. Revision identifiers are
  assigned at commit time (or for imports from other systems, at the
  time of the import).

  Revision Numbers are a much shorter though less stable way to
reference
  revisions.  A revision number is a dotted decimal sequence encoding a
  path between a revision and the branch tip.  Revision numbers change
  anytime the tip changes (e.g. commit).  Nonetheless they are
especially
  convenient during historical inspections.  This is because revision
  numbers are invariably shorter than revision identifiers, and (within
a
  single branch) can be compared with each other to get a sense of their
  graph relationships.

/john