[MERGE] improved help on storage formats

[Ian Clatworthy]

Martin Pool wrote:

> The following needn't block merges:

As discussed on IRC, I'll treat that as bb:tweak and go ahead and merge.

> Incidentally for reviews like this it may help to include the output in
> your mail.

See http://people.ubuntu.com/~ianc/doc/en/user-reference/bzr_man.html.
The interesting sections are:

* "Storage Formats" (under Concepts)
* "Current Storage Formats" and "Other Storage Formats" (under Lists).

> +If some of your developers are unable to use the most recent
> +version of Bazaar (due to corporate policy say), be sure to
> +adjust the guidelines above accordingly. For example, you may
> +need to select 1.6 instead of 1.9 if your company has standardized
> +on Bazaar 1.7.
> 
> This sounds a bit corporate, and it doesn't need to be: people might be
> waiting for e.g. a distro package update, and I'd change
> /company/project/ in the latter to be more precise.

Fixed.

> The updates to format descriptions are good, but many are now described
> by backward references, e.g. from 1.9 to 1.6.  I don't know if this
> means much to readers: it's true they may have code or subcomponents in
> common but at the user level they're opaque.  Readers want to
> know what interoperability, feature or performance implications there
> would be in upgrading.  So:
> 
>  format_registry.register_metadir('1.9',
>      'bzrlib.repofmt.pack_repo.RepositoryFormatKnitPack6',
> -    help='A branch and pack based repository that uses btree indexes.
>      ',
> +    help='An enhancement to 1.6 that introduces btree indexes. These indexes '
> +         'are smaller in size, have smarter caching and provide faster '
> +         'performance for most operations.',
> 
> Maybe just "A repository format with B+tree indexes..."

Fixed.

> +    deprecated=True)
> 
> Will this cause these formats to generate warnings to make an upgrade?
> 

Yes. I believe they do anyway as the repo format is deprecated.

Ian C.