[MERGE] improved help on storage formats

[Matthew D. Fuller]

On Thu, Dec 11, 2008 at 06:10:18PM +1000 I heard the voice of
Ian Clatworthy, and lo! it spake thus:
>
> This patch improves the help by:

This is a very good and necessary thing to do.  However...

> * including a decision tree (based on some emails by
>   Robert Collins)

I'm not sure this belongs exactly here.  I now have to go 35 lines
into the formats help before I find the formats list, which is what I
want to see when I look at the help.  IMO, we put way too much in the
online help...  but if this is there, it should have its own topic.
`bzr help choosing-format` or something.


> * including some suggestions from John Arbash Meinel,
>   e.g. moving knit-based repositories into the
>   deprecated list.

This doesn't go far enough.  I think deprecated and experimental
formats need their own help topics, as would the above decision tree
if it were to be in the online help.  The formats help itself should
just list the "currently important" formats, with enough description
to eyeball what they are.  Otherwise it's just too big:

% ./bzr help formats | wc
     107     491    3580

That's huge.  It's the sorta thing you see from something with Too
Damn Many Formats.


I envision `help formats` looking more like:
--------------------------------
Current Storage Formats

pack-0.92:
    (native) (default) New in 0.92: Pack-based format with data
    compatible with dirstate-tags format repositories. Interoperates
    with bzr repositories before 0.92 but cannot be read by bzr <
    0.92. Previously called knitpack-experimental.  For more
    information, see http://doc.bazaar-
    vcs.org/latest/developers/packrepo.html.

rich-root-pack:
    (native) New in 1.0: A variant of pack-0.92 with rich-root
    support.

1.6:
    (native) A branch and pack based repository that supports
    stacking.

1.6.1-rich-root:
    (native) A variant of 1.6 with rich-root support.

1.9:
    (native) A branch and pack based repository that uses btree
    indexes.

1.9-rich-root:
    (native) A variant of 1.9 with rich-root support.


See ``bzr help deprecated-formats`` for older formats.
See ``bzr help experimental-formats`` for experimental formats.
--------------------------------

(It sure is annoying how URL's get split across lines...  and what the
heck does "A branch and pack based repository" mean, anyway?)

That's still 27 lines, which is already pretty long.  Of course,
hopefully pack-0.92 (along with rich-root-pack) will move to the 'old'
list in a couple versions, and please $DEITY soon we won't be carrying
around two versions of every format, both of which will chop it down
nicely.

Notable changes:

1) Ordering was almost right, except for r-r-p ending up way the heck
   away from the format it's related to.  I realize this is harder to
   control since the help is all autogenerated.  This may call for
   revisitation.

   Similarly, the ordering in deprecated could use rework too.  It
   seems to me they should be in age order (whether newest-first or
   oldest-first, there are points either way), rather than the current
   lexical ordering which gives you hardly any indication of how they
   relate.

2) It's kinda annoying for the rich-root variants to repeat the whole
   description of their counterpart just to add "and rich root data"
   to the end.  Just point at it.



-- 
Matthew Fuller     (MF4839)   |  fullermd at over-yonder.net
Systems/Network Administrator |  http://www.over-yonder.net/~fullermd/
           On the Internet, nobody can hear you scream.