Re: What have the Romans done for us? (Bazaar)

[Chad Brown <yandros@MIT.EDU>]

[-- Attachment #1: Type: text/plain, Size: 1570 bytes --]


On Apr 6, 2010, at 7:31 AM, Alan Mackenzie wrote:
> 
>> ?  http://doc.bazaar.canonical.com/en/ points to plenty of downloadable
>> documentation, in HTML, CHM, and PDF formats.
> 
> They all lack hyperlinks or are non-searchable.  (BTW, I'll need to find
> out what CHM is).

It's an acronym for `Compiled Help file (Microsoft)' -- does that tell you 
everything you need to know? :-)

It's a format used to make HTML help file bundles for MS's `help viewer'.
You almost certainly don't care.

>  But worst of all is the low quality of the reference
> docs.  For example, 'bzr help merge' doesn't say with any specificity
> what is being merged or where the result is written.  It talks about
> "merging a branch", which makes as much sense as "the difference between
> a file" does.  This vagueness is prevalent over much or all of 'bzr help
> <cmd>'.  Is it too much to expect these man pages (in effect) to be
> precise?

I don't disagree at all, but you might find it helpful to spend an hour or so
digging through

	http://wiki.bazaar.canonical.com/BzrGlossary/

In general, the docs seem to assume that you're either already familiar with
vcs concepts and are just looking for the bzr keywords, or that you don't 
care at all and are just looking for the right set of magic words to say to 
avoid angering the wizards.  I suspect that the aim to cater to as many 
different `methodologies' (what we've been calling workflows on this list) 
has encouraged a doc style that's so detail-agnostic that it's hard to ever 
find useful content.

I hope that helps,
*Chad

[-- Attachment #2: Type: text/html, Size: 2445 bytes --]