[RFC] Concise vs comprehensive help - do we need both?

[Martin Pool]

2009/1/31 Ian Clatworthy <ian.clatworthy at internode.on.net>:
> So, I'd like to propose that:
>
> * We continue to keep the User Reference and online help
>  in sync
>
> * "bzr help xxx" and "bzr xxx -h" give comprehensive help
>
> * "bzr help -?" be supported & it should show just the one line
>  summary and list the options.

I agree that the reference-type documentation -- all the documentation
that directly corresponds to technical features of the program like
formats or commands -- should be in the tree, accessible through help,
and from there generated into other forms.

Possibly the most useful tool to keep help topics reasonably small is
to break them into multiple parts and put in 'see also' links between
them, as you did with formats.  I like this because we can make the
separation into subtopics that are individually useful, and it means
the addressing is all within one namespace, the help topic name.

Having a feature that can only be reached by -? seems like asking for
trouble with shell metacharacters.  Not so much that people might have
files called -a (though they might) but also some shells error on
globs that don't match (like 'setopt bad_pattern' in zsh.)

There is a precedent however in some tools (that use popt?) where
--usage gives you just a list of all the arguments in terse form,
enough to remind you of the purpose:

mbp at grace% rpm --usage
Usage: rpm [-afgpWcdlsKiv?] [-a|--all] [-f|--file] [-g|--group] [-p|--package]
        [-W|--ftswalk] [--pkgid] [--hdrid] [--fileid] [--specfile]
[--triggeredby]
        [--whatrequires] [--whatprovides] [--nomanifest] [-c|--configfiles]
        [-d|--docfiles] [--dump] [-l|--list]
[--queryformat=QUERYFORMAT] [-s|--state]
        ....

(already nearly 25 lines in this case)

and it could be readable to also give the one-sentence purpose of the
command and the form of the arguments.


-- 
Martin <http://launchpad.net/~mbp/>