[MERGE] Bazaar User Reference

[Ian Clatworthy]

James Westby wrote:
> On (06/08/07 20:48), Ian Clatworthy 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.
> 
> This looks good.

Thanks. Latest version given the feedback from Alexander and yourself
has been uploaded now.

>> -     Supported formats       Autodetected by extension
>> -     -----------------       -------------------------
>> +      =================       =========================
>> +      Supported formats       Autodetected by extension
>> +      =================       =========================
>>           dir                            -
> 
> This leads to an artefact in the generated output above. Perhaps there
> is another character that would go here, or perhaps "(none)" or similar.

Fixed. (none) sounded good to me.

>> +_env_variables = \
>> +"""Environment Variables
>> +
>> +:BZRPATH:         Path where bzr is to look for shell plugin external commands
>> +:BZR_EMAIL:       E-Mail address of the user. Overrides default user config.
> 
> Overrides EMAIL.
> 
>> +:EMAIL:           E-Mail address of the user. Overrides default user config.
>> +:BZR_EDITOR:      Editor for editing commit messages
> 
> Overrides EDITOR.

Done.

>> +:EDITOR:          Editor for editing commit messages
>> +:BZR_PLUGIN_PATH: Paths where bzr should look for plugins
> 
> This formats strangely in the posted output.

This looks like a nuance of how reST formats things if a field name gets
too big so I've gone with a table instead.

>> +:BZR_HOME:        Home directory for bzr
> 
> Overrides HOME?

Looking at the code, it indeed does. Though the story on Win32 is
slightly more complicated. I've updated the text accordingly.

> There is also inconsistency in ending the items with full-stops.

Fixed.

>> -    return bzrdir.format_registry.help_topic(topic)
>> +    return "Storage Formats\n\n" + bzrdir.format_registry.help_topic(topic)
> 
> This leads to incorrect formatting for the dirstate/default entry in the
> posted output.

Once again, a reST nuance when a field name is too long I think. I
changed the formatting to put the "default" marker in the text instead
of the label and this now looks better.

> It would be great if the cross-references could be hyper-linked, but I
> guess that might be tricky, it is not needed for this to be merged.

Nice idea. Another time though.

Ian C.