[MERGE] bzr help locationspec

[Alexander Belchenko]

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

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.

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?

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.

> # Bazaar revision bundle v0.8
> #
> # message:
> #   Add a help topic for location specifiers.
> #   
> # committer: Marius Gedminas <mgedmin at b4net.lt>
> # date: Tue 2007-01-16 00:12:41.658999920 +0200
> 
> === modified file bzrlib/help_topics.py
> --- bzrlib/help_topics.py
> +++ bzrlib/help_topics.py
> @@ -100,6 +100,30 @@
>      return ''.join(out)
>  

v-- title of your topic looks like valid RSTX title.
So you could remove colon from title.

>  
> +_help_on_locationspec = """
> +Location specifier:
> +-------------------
> +
> +A location is either a local path name (which can be absolute or relative),
> +or a URL using one of the following schemes:

v-- From readability point it's better to align descriptions by the same column.
    In case of providing valid RSTX output you could format these definitions
    as table.

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

> +
> +
>  _basic_help= \
>  """Bazaar -- a free distributed version-control tool
>  http://bazaar-vcs.org/
> @@ -129,6 +153,8 @@
>  
>  topic_registry.register("revisionspec", _help_on_revisionspec,
>                          "Explain how to use --revision")
> +topic_registry.register("locationspec", _help_on_locationspec,
> +                        "Explain how to specify LOCATIONs")
>  topic_registry.register('basic', _basic_help, "Basic commands")
>  topic_registry.register('topics', _help_on_topics, "Topics list")
>  def get_format_topic(topic):
> 
> === modified directory  // last-changed:mgedmin at b4net.lt-20070115221241-grt4oyq
> ... 0h73ql027
> # revision id: mgedmin at b4net.lt-20070115221241-grt4oyq0h73ql027
> # sha1: c1d10fb06723865c7d0a18578dbe32ba49cef38a
> # inventory sha1: 68e28347cc08d0bb759cd2bf6eda5959548c21d0
> # parent ids:
> #   pqm at pqm.ubuntu.com-20070115033134-6f456e8e9cc87f35
> # base id: pqm at pqm.ubuntu.com-20070115033134-6f456e8e9cc87f35
> # properties:
> #   branch-nick: bzr.dev
> 

- --
Alexander
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.6 (MingW32)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iD8DBQFFrEoszYr338mxwCURAlycAJ45N4qYxtU2mWJwzAl3MAPL3FLHCACfXOKk
cmc0v/59wtclR0Wy6rLLdn4=
=bjj0
-----END PGP SIGNATURE-----