[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