Help issues

[James Blackwell]

On Fri, Feb 03, 2006 at 12:04:02PM -0500, Aaron Bentley wrote:
> 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."

back up a backup, eh? Fair point.

> 
> >   bzr help list      Get information on extended help.
> 
> I think we should also have:
> 
> bzr help commands   List all available commands with summaries

Sure, so long as when you get back to a prompt you can see the previous
prompt. Thats important so that its clear that nothing has scrolled off
the screen.

> 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 suspect we disagree on what signifies prominance. I see the lines that
are closest to the returned prompt as more prominant. I'm happy any which
way they are and was just playing for fun.

If top-is-prominent, then we should consider moving the first three lines
to the bottom: 
====
Bazaar-NG -- a free distributed version-control tool
http://bazaar-ng.org/

====

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

Both suggestions sound good to me.


> >   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.
> > 
> >  bzr help [plugin]    - Get help for a specific plugin.
> >  bzr help plugins     - Get list all all plugins.
> 
> This is inaccurate.  Help lists all commands, not just builtins.  Or
> were you planning to change that?
> 
> This lists plugins, where bzrtools is one plugin.  Is this what you intend?

I'm a bit of a purist in this department. I like to know what comes with
standard, and what is bolted on. Thus I generally prefer the official list
of commands is just official commands and that added on commands are list
as added on.

I was hellaconfused when I installed bzrtools plugin and couldn't figure
out the new commands. I imagine this process: 

$ bzr help commands
[get builtins]
$ install bzrtools
$ bzr help bzrtools

 This is bzrtools. Bzrtools does awesome things like rsync push and shelve
 and unshelve.
 Added commands   Modified commands
 shelve           push
 unshelve         whatever

$ bzr help shelve

 The builtin help for bzrtool's shelve

$ bzr help push

 This is the push supplied by bzrtools. It does push in the standard ways
 and provides support for sync as well.


Something like that.

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

If you like. I'd probably go with adding another line for "bzr help
configuration" instead of putting it into environment or globalops.


-- 
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/3462e035/attachment.pgp