[MERGE] Bazaar User Reference

[Martin Pool]

On 8/6/07, Ian Clatworthy <ian.clatworthy at internode.on.net> wrote:
> A patch to generate a "complete" User Reference from online help is
> attached. If you're only interested in seeing the end result rather than
> the code, a sample output can be found here:
> http://people.ubuntu.com/~ianc/doc/bzr_man.htm.

That looks good.  It prints (well, to pdf) ok in Safari so I'd suspect
an IE-specific problem.

> Compared to what I proposed earlier
> (https://lists.ubuntu.com/archives/bazaar/2007q3/028509.html), there are
> still some important sections missing, particularly Configuration
> Settings. That content can come in follow-up patches either done by
> myself or anyone else keen to help. The Files section needs some work
> when that content is merged as well. (At the moment, it is the same
> content as provided in the man page so it's not complete but no worse
> than our current doc.)
>
> Quite a few things needed to be tweaked to make this all come together.
> The major change was explicitly supporting limited reStructuredText in
> topics and command help, particularly literal blocks and field lists. To
> ensure that the online help and man page still render correctly, some
> very basic rules are applied to the text to remove unwanted reST markup,
> namely:
>
> 1. A trailing :: is replaced with a single :
> 2. A leading : (no whitespace before it) is removed.
>
> That does the trick without needing to make docutils a dependency.

It might be good to render this from make check to catch any changes
that would break rendering.

I haven't read the diff as it's so large and presumably mostly
mechanical, and others seem to have read it.  BB missed it for some
reason.   I think you can go ahead and merge if you're happy.

-- 
Martin