Help issues

[James Blackwell]

On Fri, Feb 03, 2006 at 09:27:25AM -0500, Aaron Bentley wrote:
> James Blackwell wrote:
> > On Wed, Feb 01, 2006 at 05:36:41PM +1100, Martin Pool wrote:
> > 
> >>Any comments on this doc change?
> > 
> > 

+    If the global option '--no-plugins' is given, plugins are not loaded
+    before running the selftests.  This has two effects: features
+    provided or modified by plugins will not be tested, and tests provided
+    by plugins will not be run.

> > The instructions imply to me that --no-plugins only works when selftest is
> > run. A quick test implies that --no-plugins works all the time.
> 
> The term 'global' is meant to imply that this option works all the time.
>  How can we express this better?

By creating a section of builtin help that is concerned with global
options. One feature would be to describe a what a global option is within
the context of Bazaar-NG (ex. Can modules use global options? What if a
global option is in conflict with a local option?). Another feature would
be to list the global options.

Well formed paragraphs a few rules. One rule is that a paragraph only has
one subject. Another rule is that all sentences support the single
subject. A third rule is that when possible the first sentence of a
paragraph should clearly state the subject of the paragraph.

The "If the global option '--no-plugins is given..'" paragraph teaches the
relationship of how --no-plugins affects selftesting. In this context the 
reader is learning about testing, not about running Bazaar-NG. The reader 
is thus likely to disregard the "global option" part as insignificant to
what they are reading. If he doesn't, he is unlikely to remember anyways
because the association was built in the improper context.

I wrote the following for fun. While I was enjoying myself I made a few other
changes -- also just for fun.  

$ bzr help
  Bazaar-NG -- Free decentralized RCS  -- http://bazaar-ng.og
  *NOTE* Development version. Please backup branches *NOTE*
  bzr help list      Get information on extended help.

  bzr check          Validate consistancy for a branch.

  bzr log            Show history of changes for a branch.
  bzr status         Summarize changes in working copy.
  bzr diff           Show detailed diffs for a working tree.

  bzr init           Make a directory version controlled.
  bzr branch         Make a copy of a branch.

  bzr merge          Pull in changes from another branch.
  bzr commit         Create snapshot revision with optional limits.

  bzr add            Make files or directories versioned.
  bzr ignore         Ignore a file or pattern in a working tree.
  bzr mv             Move or rename a versioned file.

$ bzr help list
Bazaar-NG -- Free decentralized RCS http://bazaar-ng.og
*NOTE* Development version. Please backup branches *NOTE*

 bzr help [command]   - Get lengthy help for a specific command.
 bzr help commands    - Get list of all builtin commands.

 bzr help [plugin]    - Get help for a specific plugin.
 bzr help plugins     - Get list all all plugins.

 bzr help globalops   - Get info on all global options.
 bzr help environment - Get list and info on environment variables used.
 

-- 
My home page:   <a href="http://jblack.linuxguru.net">James Blackwell</a>
Gnupg 06357400  F-print AAE4 8C76 58DA 5902 761D  247A 8A55 DA73 0635 7400
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : https://lists.ubuntu.com/archives/bazaar/attachments/20060203/c0ed6aec/attachment.pgp