[MERGE] bzr help locationspec

[John Arbash Meinel]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Martin Pool wrote:

...

>>> 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

This is a little bit of what Registry was meant to help with. So that we
can change the Transport registry, and at registration time, we could
possibly include a 'hidden' or 'internal-only' flag.

One other thing is that http+urllib and http+pycurl are probably useful,
though maybe only as debugging... I'm not really sure.

Internally all these are transports, so we *could* do "bzr help
transports". But that could be too much of an implementation detail
versus 'bzr help urls'. Maybe 'bzr help supported-protocols' or 'bzr
help protocols'?  Because it isn't really the whole url that we are
talking about, just the protocol portion.

...

>> 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

I agree, when possible we should create documentation from the internal
help rather than having 2 sets of internal and external help.

Though someone (fullermd?) had a good point about online versus offline
documenation. Which is that online (bzr help) is really just meant as a
reminder, versus offline (doc/*) is meant to be a verbose discussion of
the tradeoffs between different styles, etc.

So where the documentation would be the same, I would like to see it
come from reprocessed internal help. Where we want to expand, it
probably would be external.

> 
>>> +  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.

Well, technically you can iterate over
bzrlib.transport._protocol_handlers. But that isn't a very good api. And
I'd really rather have a:
bzrlib.transport.transport_registry.keys() call to give you back all of
the names of registered protocols.

So I'm +1 on the documentation improvements, but I would like us to
finalize what help topic it falls under, just so it doesn't have to move
around much afterwards.

Current suggestions are:

  locationspec
  url
  urls
  protocol
  protocols
  transport
  transports

I would probably vote for 'protocols' as my favorite. Though we also
would need to decide on plural form versus singular.

I suppose if we standardized on something like "LOCATION" as the name of
the parameter, then we could just switch to "bzr help location".

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.3 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFFrPhEJdeBCYSNAAMRAtmMAKCa076b6fwtAV+2nX1j/qBUH4y1KgCg0gzY
8KSeuAFl1g+2Ri1ytxYCOCw=
=1s7c
-----END PGP SIGNATURE-----