[RFC] Bazaar Complete Reference

[Martin Pool]

That looks good. We also need a section on plugins. +1 to add a
section attribute to help topics. We need to review the help topics
both individually and when turned into a combined doc.

On 7/23/07, Ian Clatworthy <ian.clatworthy at internode.on.net> wrote:
> #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:
>
> Concepts
>     Checkouts
>     Repositories
>     Working Trees
> Lists
>     Bug Trackers
>     Configuration Settings
>     Environment Variables
>     Files
>     Formats
>     Global Options
>     Hooks (?)
>     Revision Identifiers
>     Status Flags
>     URL Identifiers
> Commands
>     add
>     ..
>     whoami
> Core Plug-ins
>     Launchpad
>
> 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
> time.
>
> 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.
>
> Thoughts?
>
> Ian C.
>
>


-- 
Martin