[MERGE] bzr help disambiguation and bzr help PLUGINNAME

[James Westby]

On (21/04/07 14:50), Robert Collins wrote:
> On Fri, 2007-04-20 at 17:29 +0100, James Westby wrote:
> > Long line?
> 
> Yes. as PEP8 says pragmatism first; The first line should be a complete
> sentence, and can't be split because summaries no longer show right. 

Ah, maybe I should read PEP8 again, thanks.

> > 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.
> 
> That I actually think should be deleted. I think we should do what I do
> for plugins with no docstring: explain that there is no help and hint at
> how it can be added.

That sounds good to me.

> > 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.
> 
> I agree. I didn't remove all manual cross references for this reason. Do
> you think we should add this particular one back? I'm not inclined to
> add typing of references at this point.

Ah, I wasn't sure that you had removed them all, this was just the first
on I looked at. I think this case is a candidate for a manual reference.
I can always submit patches later to add any more that seem like a good
idea.

> > 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.
> 
> I could go either way. But I think pathologically we end up listing
> everything there. The basic issue is that for a simple term like 'foo'
> we cannot tell what index the user was hoping to look in. If the user
> says 'commands/foo' then we do know - and thats actually a good future
> improvement: If the user provides a qualified search, give a qualified
> error.

A qualified error would be good once people start using the qualified
search.

I was just concerned that someone tried to get help on a command and
then had to do 'bzr help topics', then 'bzr help commands' to see that
they had the spelling wrong, but it is probably no great deal. Also I'm
a fan of topics, and maybe advertising them a bit more is a good thing.

> It does - thanks for the review.
> 

Thanks for the patch,

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