Help issues

[Aaron Bentley]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

James Blackwell wrote:
> Well formed paragraphs a few rules.

Irony?

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

In my experience, 'backup' and 'setup' are nouns, while 'back up' and
'set up' are verbs.  E.g. "I backed up my setup." or "I set up my backup."

>   bzr help list      Get information on extended help.

I think we should also have:

bzr help commands   List all available commands with summaries

Many people have not noticed it at the bottom of the listing, and it is
vital information.

>   bzr check          Validate consistancy for a branch.

You consider this an essential basic, and would make it more prominent
than init, add, commit, branch?

I would suggest the following order:
1. commands that you need to know to get started
2. commands that you will use frequently once started
3. commands that you will not use routinely, but are critical to know about

>   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 add dirname" also makes a directory version controlled, so I think
this is too vague.

>   bzr branch         Make a copy of a branch.

> $ 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.

This is inaccurate.  Help lists all commands, not just builtins.  Or
were you planning to change that?

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

This lists plugins, where bzrtools is one plugin.  Is this what you intend?

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

How about bzr help configuration, instead?  Then we can point at config
files as well as environment vars.

Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFD440C0F+nu1YWqI0RAnWDAJ9aXq+yebHY8vS7sp9tiXo7GI5YvgCeL6By
L27sOG/mTTvkcOgU6KVqlBU=
=OvAv
-----END PGP SIGNATURE-----