[MERGE] bzr help disambiguation and bzr help PLUGINNAME

[James Westby]

On (20/04/07 15:49), Robert Collins wrote:
> This adds support for bzr help to identify when topics from areas like
> 'registered topics' and 'plugins' and 'commands' overlap, and report
> this to the user.

I like the general idea. It allows much more information to be provided,
even if there isn't going to be that much yet.

> +def _get_cmd_object(cmd_name, plugins_override=True):
> +    """Worker for get_cmd_object which raises KeyError rather than BzrCommandError."""

Long line?

> +        if doc is None:
> +            raise NotImplementedError("sorry, no detailed help yet for %r" % self.name())

Another long line.

I hit this the other day with a plugin. It means you get a traceback if
there is no help provided, which is quite ugly, and perhaps a little
over the top. On the other hand it may provide more incentive to
actually provide some help.

> +        see_also = self.get_see_also(additional_see_also)
> +        if see_also:
> +            result += '\nSee also: '
> +            result += ', '.join(see_also)
> +            result += '\n'
> +        return result

One thing this does is make all references appear to have the same relevance,
one because they are sorted, the other because you removed direct
references to use this system.

While it is probably a small thing I think in some cases it makes
things slightly non-obvious. For instance the checkouts help topic
attempts to explain what a checkout is and how it differs from a branch.
With this patch 'bzr help checkout' shows

  usage:bzr checkout [BRANCH_LOCATION] [TO_LOCATION]
  aliases:
  co
  
  Create a new checkout of an existing branch.

  ...

  See also: branch, checkouts

It is not clear to me that checkouts is a help topic, and if a user is
asking "what the hell is a checkout" it's not clear that this one word
right at the very end will attempt to explain it to them.

There could be a couple of possible solutions. We could add the prefixes
to the 'See also:' line, so at least you know whether it is a topic or
command, or whatever. The other could be to add back in some manual
reference text for the cases that could be highlighted.

> +
> +class NoHelpTopic(BzrError):
> +
> +    _fmt = ("No help could be found for '%(topic)s'. "
> +        "Please use 'bzr help topics' to obtain a list of topics.")
> +

I feel this should perhaps mention commands. If the user is aiming to
get the help for a command and mistypes it might be a little cryptic.
However having the error might be enough to prompt them to check.

Overall I think it is a good change, so I'm +1 on the idea, if that
counts for anything.

Thanks,

James

-- 
  James Westby   --    GPG Key ID: B577FE13    --     http://jameswestby.net/
  seccure key - (3+)k7|M*edCX/.A:n*N!>|&7U.L#9E)Tu)T0>AM - secp256r1/nistp256