[MERGE/RFC] Checkouts help topic.

[James Westby]

On (08/02/07 15:05), John Arbash Meinel wrote:
> John Yates wrote:
> > The more you chop up the help namespace the harder it will be
> > for novices to locate the help they seek.  This feels simple
> > and moves topics out of the command namespace:
> > 
> > bzr help
> >   enumerate commands including mention of the topic command
> > 
> > bzr help COMMAND
> >   describe the specifics of command COMMAND
> > 
> > bzr topic
> >   enumerate non-command-specific help topics
> > 
> > bzr topic TOPIC
> >   display help for TOPIC

I like this approach actually. It looks clean, but again it is subject
to exploding the number of commands if we want things like the plugin
help.

> 
> Well, we have 'bzr help topics'. And we also would like a way to do "bzr
> help PLUGIN". Like "bzr help bzrtools".

This was one I was thinking of adding, but to core rather than bzrtools
itself. So that it could say "bzrtools is great, it can do thigs like
this and this, lot's of people install it, but you can live without it
if you are only doing standard things." Bzrtools could then override this
when installed to say something like "You have bzrtools installed, these
are the commands that you now have that are provided by bzrtools." It
could also be mentioned about the need to keep plugins updated etc.

> And many plugins have the same name as their command. So we would
> probably also want "bzr help plugin X" or maybe just 'bzr help-plugin X'.
> 
> So whatever mechanism we use for topics could also be used for topics.
> 
> I would prefer "bzr help topic foo" or "bzr help-topic foo", to using a
> namespace scheme. But 'bzr help plugin:foo" could work.
> 

I think the plugin one is a good idea. The first time I installed
bzr-svn I didn't anticipate that it would be so seemless, and so spent
ages looking in help commands for the bzr-svn commands, and ended up
doing svnimport when a simple bzr branch would have sufficed. If help
would have been available (and I knew it was there and how to get it),
then I would have understood how great the plugin is and just branched
the repo in question.

I think SVN may be worthy of a help topic, to say that interoperability
is well supported and if people want that then they should install
bzr-svn.

I realise that I am suggesting a lot of help topics, I like the idea of
them and think there are plenty of things that would be useful there.
Also I think a system like that is on;y going to be useful if it is
known as a source of plenty of good information, if a user looks there
and sees that there isn't much then they might not think to go there to
read up on something later.

Are people happy with using the topics like this? Some of the ones that
I would like to see (and I am willing to write them all, it might just
take me a while) are:

  repositories - often misunderstood by users, and unknown as well, the
                 performance benefits are worth the emphasis I think.
                 Also explaining trees/no-trees might save a lot of
                 confusion. Explain how it differs from repos in other
                 projects.
  branches - background on what a branch is, and what can be done with
             it. This one was more mainly for the terminology.
  working-tree - I didn't understand the distinction for a while, and
                 getting that is crucial for understanding some of the
                 other concepts and using some commands correctly.
  merging - explain what it is and when you would do it, and when you
            wouldn't. Mention conflicts as well (maybe that deserves one
            of its own).
  getting-changes-to-another-branch - the name needs some work, but
                                      quite often people ask "I've
                                      commited here, how do I get my
                                      work over there"
  tags - when they are finalised and I get the concept myself it would
         be good to explain them.
  configuration - the main options to set and the files for them. The
                  preference order, and policies.

There's quite a lot there, and a couple have slipped my mind, and maybe
a couple of them aren't worth it, and I want to avoid feeling like there
is a need for some explanations of how to find stuff in all of these
topics.

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