Rev 6036: (jelmer) Document the behaviour with regards to special characters in URLs. in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

[Canonical.com Patch Queue Manager]

At file:///home/pqm/archives/thelove/bzr/%2Btrunk/

------------------------------------------------------------
revno: 6036 [merge]
revision-id: pqm at pqm.ubuntu.com-20110721103418-isfx9a31sy79q2tu
parent: pqm at pqm.ubuntu.com-20110721075122-l9d0n4d3pk4p3hfg
parent: jelmer at samba.org-20110721093122-n0tejaaelntt8ayt
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Thu 2011-07-21 10:34:18 +0000
message:
  (jelmer) Document the behaviour with regards to special characters in URLs.
   (Jelmer Vernooij)
added:
  bzrlib/help_topics/en/url-special-chars.txt urlspecialchars.txt-20110630155852-mod387qhw2i2gdzp-1
modified:
  bzrlib/help_topics/__init__.py help_topics.py-20060920210027-rnim90q9e0bwxvy4-1
=== modified file 'bzrlib/help_topics/__init__.py'
--- a/bzrlib/help_topics/__init__.py	2011-05-28 13:46:51 +0000
+++ b/bzrlib/help_topics/__init__.py	2011-06-30 16:47:06 +0000
@@ -270,8 +270,8 @@
 
 would refer to ``/home/remote/myproject/trunk``.
 
-Many commands that accept URLs also accept location aliases too.  See
-::doc:`location-alias-help`.
+Many commands that accept URLs also accept location aliases too.
+See :doc:`location-alias-help` and :doc:`url-special-chars-help`.
 """
 
     return out
@@ -778,6 +778,8 @@
                         'Aliases for remembered locations')
 topic_registry.register('log-formats', _load_from_file,
                         'Details on the logging formats available')
+topic_registry.register('url-special-chars', _load_from_file,
+                        'Special character handling in URLs')
 
 
 # Register concept topics.
@@ -898,6 +900,6 @@
         elif line.endswith('::'):
             line = line[:-1]
         # Map :doc:`xxx-help` to ``bzr help xxx``
-        line = re.sub(":doc:`(.+)-help`", r'``bzr help \1``', line)
+        line = re.sub(":doc:`(.+?)-help`", r'``bzr help \1``', line)
         result.append(line)
     return "\n".join(result) + "\n"

=== added file 'bzrlib/help_topics/en/url-special-chars.txt'
--- a/bzrlib/help_topics/en/url-special-chars.txt	1970-01-01 00:00:00 +0000
+++ b/bzrlib/help_topics/en/url-special-chars.txt	2011-07-21 09:31:22 +0000
@@ -0,0 +1,41 @@
+Special character handling in URLs
+==================================
+
+Bazaar allows locations to be specified in multiple ways, either:
+
+ * Fully qualified URLs
+
+ * File system paths, relative or absolute
+
+Internally bzr treats all locations as URLs. For any file system paths
+that are specified it will automatically determine the appropriate URL
+representation, and escape special characters where necessary.
+
+There are a few characters which have special meaning in URLs and need careful
+handling to avoid ambiguities. Characters can be escaped with a % and a hex
+value in URLs. Any non-ASCII characters in a file path will automatically be
+urlencoded when the path is converted to a URL.
+
+URLs represent non-ASCII characters in an encoding defined by the server, but
+usually UTF-8.  The % escapes should be of the UTF-8 bytes.  Bazaar tries to be
+generous in what it accepts as a URL and to print them in a way that
+will be readable.
+
+For example, if you have a directory named '/tmp/%2False' these are all valid
+ways of accessing the content (0x2F, or 47, is the ASCII code for forward slash)::
+
+  cd /tmp
+  bzr log /tmp/%2False
+  bzr log %2False
+  bzr log file:///tmp/%252False
+  bzr log file://localhost/tmp/%252False
+  bzr log file:%252False
+
+These are valid but do not refer to the same file::
+
+  bzr log file:///tmp/%2False (refers to a file called /tmp/\/alse)
+  bzr log %252False (refers to a file called /tmp/%252False)
+
+Comma also has special meaning in URLs, because it denotes `segment parameters`_
+
+_`segment parameters`: http://www.ietf.org/rfc/rfc3986.txt (section 3.3)