[MERGE] [1.0] Move material out of User Guide into User Reference

[Ian Clatworthy]

Aaron Bentley wrote:
> Ian Clatworthy wrote:
>> Alexander Belchenko wrote:
> 
>>> Looks good for me.
>>> bb:approve. (Probably someone else should approve this as well).
>> I agree. Perhaps Aaron or John could have a look?
> 
> bb:comment
> 
> Well, to me it seems strange to be moving documentation out of the doc
> directory.  That makes it less discoverable.  Also, it was formerly
> specified as "doc/en", and now no language is specified.

Thanks for the feedback and chat on IRC today re this. Updated patch
attached.

The files are now in bzrlib/help_topics/en. I think that makes them
discoverable enough. (All help topics are either in
bzrlib/help_topics.py or bzrlib/help_topics/ - basically right next to
each other.)

> We also might want to consider using pkg_resources rather than brewing
> this ourselves.

As discussed on IRC, I'm not keen at this point to make setuptools a
dependency or to repackage part of it within bzr right now. So I've used
a compatible API (as suggested) and added a lightweight implementation
to osutils, together with a test. osutils looks as good a place as any
given we tweak the lookup algorithm for the Windows installer.

> And I fear that we're introducing too many ReST-isms into what's
> supposed to be plaintext docs.  The headings are fine, but the links are
> a problem.  I don't think Bazaar users should be forced to interpret
> "See also `Using Hooks <../user-guide/index.html#using-hooks>`_." when
> they run "bzr help hooks"

I've improved the readability of this as suggested by John. I'm not
currently stripping out ReST directives. If it proves an issue in
practice, I think we should address it separately, e.g. by hiding the
topic altogether in the online system or by coming up with some bigger
ReST help strategy.

Ian C.

PS: This has probably missed the rc3 cut-off. I've leave it to poolie to
decide whether it should therefore be considered for 1.0 or not.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: move-stuff-from-guide-to-reference-4.patch
Type: text/x-patch
Size: 31065 bytes
Desc: not available
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20071211/640cd481/attachment-0001.bin