[RFC] Bazaar Complete Reference

Ian Clatworthy ian.clatworthy at internode.on.net
Mon Jul 23 09:31:21 BST 2007

#3 on my doc review hit list: a *complete* reference to all things
related to Bazaar. Firstly, I'd like to propose what the final document
ought to contain. Secondly, I'd like to suggest some ways of generating
it. If you have opinions on either of these, please see below and respond.

In terms of content, the man page is a step in the right direction but I
want more information and 2 levels in the TOC. (I want a reference that
will work really well in numerous mediums including paper, web, GNOME
help, KDE help, Windows help, etc.) Here's my suggested TOC assuming
that the file is automatically (but smartly) generated from the current
online help topics (90% complete IMO) together with some new ones:

    Working Trees
    Bug Trackers
    Configuration Settings
    Environment Variables
    Global Options
    Hooks (?)
    Revision Identifiers
    Status Flags
    URL Identifiers
Core Plug-ins

Anything missing?

That leaves out 'basic-commands', 'commands' and 'hidden-commands'. The
basic stuff is covered in the mini-tutorial and tutorial, 'commands' is
kind of covered by the Complete Reference TOC (but could go in Lists if
we wanted) and 'hidden-commands' ought to be left out IMO.

So if that sounds OK conceptually, we need to consider implementation
options. My preference is to add meta-data to topics saying whether they
are a concept, list, core plug-in, or hidden. We can easily generate the
complete reference (and extended man page) from there, adding to it over

In summary, I want everything available via the built-in online help but
nicely available in a single good looking printed doc and searchable in
OS help systems.


Ian C.

More information about the bazaar mailing list