[MERGE] [1.0] Move material out of User Guide into User Reference
Alexander Belchenko
bialix at ukr.net
Tue Dec 11 07:58:52 GMT 2007
bb:tweak -- see comments below.
Ian Clatworthy пишет:
> Aaron Bentley wrote:
>> Ian Clatworthy wrote:
>> 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.)
Because in the osutils code related to loading text file you call it
"package", but use simple directory layout (without __init__.py) it
seems a bit misleading. I think it's time to move bzrlib/help_topics.py
to bzrlib/help_topics/__init__.py to make code match comments.
>> 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.
>
=== modified file 'bzrlib/help_topics.py'
--- bzrlib/help_topics.py 2007-12-07 03:30:29 +0000
+++ bzrlib/help_topics.py 2007-12-11 06:18:55 +0000
@@ -128,6 +134,15 @@
return ''.join(out)
+def _load_from_file(topic_name):
+ """Load help from a file.
+
+ Topics are expected to be txt files in bzrlib.help_topics.
+ """
+ resource_name = "en/%s.txt" % (topic_name,)
+ return osutils.resource_string('bzrlib.help_topics', resource_name)
^-- In the text you say now texts live in help_topics/en/, but in the
code you're using just help_topics, and resourse_string does not seems
to append 'en' part oneself. So, it wont work, IIUC.
+
+
def _help_on_revisionspec(name):
"""Generate the help for revision specs."""
import re
More information about the bazaar
mailing list