[MERGE] bzr help locationspec

[Martin Pool]

On 16 Jan 2007, Alexander Belchenko <bialix at ukr.net> wrote:
> Marius Gedminas �����:
> > I was reading bzr help push today, and I wondered how I could push the
> > branch to a remote server if I have an ssh account there.  I could not
> > find the answer in bzr's help topics.
> > 
> > Here's a patch that adds a help topic explaining what sorts of URL
> > schemes are supported by bzr.
> > 
> > Since bzr's transports are pluggable, a better solution would be to do
> > what bzr help revisionspec does -- loop through registered transports
> > and collect documentation from the interesting ones.  (I do not think
> > end-users are interested in transports like 'memory+' or 'vfat+'.) That
> > seemed to be a bit too much work for a first-time bzr drive-by-patcher
> > like me.  IMHO an incomplete help topic is better than no topic at all.

Hi Marius,

I agree, adding this now is better than nothing, and we can do more
later.  So +1
 
> I like this in general, but have some notes.
> Some bzr commands use LOCATION argument, some BRANCH.
> I think this help need to mention all situation.
> Maybe it's better to call this topic 'urlspec' (URL specifier)
> to cover more cases?

Or really just 'url' would be easier to guess, though strictly that
doesn't include local paths.

Where there are synonyms we should add them to the help system too.

Commands that take a url should then say 'see also: url'

> Also it's good to see this topic in general bzr documentation,
> see documents in bzr source tree doc/ subdirectory. We even could
> auto-generate corresponding document based on output of
> bzr help locationspec
> but in this case you need provide valid RSTX syntax.

Could we instead move all of these into the help system, and have the
html generator take them from there?  That seems to have several
advantages:

 * users can find everything through the help command, without needing
   to search around for the external docs

 * "same things together"

 * they can be up-to-date with things provided by plugins

> > +  file: Local file access (the file:// prefix is optional).
> > +  http: Read-only access of branches exported on the web.
> > +  https: Read-only access of branches exported on the web using SSL.
> > +  sftp: Access using SFTP (most SSH servers provide SFTP).
> > +  ftp: Access using passive FTP.
> > +  aftp: Access using active FTP.
> > +  bzr: Fast access using the Bazaar smart server.
> > +  bzr+http: Fast access using the Bazaar smart server over HTTP.
> > +  bzr+ssh: Fast access using the Bazaar smart server over SSH.
> > +
> > +Schemes that use the Bazaar smart server require it to be installed on
> > +the remote machine.
> > +
> > +Plugins can add support for more URL schemes.
> > +"""
> 
> How we could collect URL schemes from plugins?
> May be something similar to bzr commands?
> Each URL schemes defined as class, docstring of class used to generate help,
> attribute 'hidden' could be used to hide those schemes that used for testing.
> 
> How about this idea, guys?

Sounds good.
-- 
Martin