[bitbake-devel] [PATCH] bitbake-user-manual-fetching.xml: note about URLs with semi-colons

[Juro Bystricky]

Some URLs contain semi-colons. Unfortunatelly, bitbake uses semi-colons in SRC_URI
as delimiters for various parameters.
It may still be possible to use such URLs, providing the user replaces semi-colons ';'
with '&' characters.

For example:

   http://abc123.com/git/?p=gcc/gcc.git;a=snapshot;h=a5dd47

 and

   http://abc123.com/git/?p=gcc/gcc.git&a=snapshot&h=a5dd47

should be equivalent, as W3C recommends treating ';' in queries identically to '&'.

See http://www.w3.org/TR/1999/REC-html401-19991224/appendix/notes.html#h-B.2.2

Kudos to Olof Johansson

Signed-off-by: Juro Bystricky <juro.bystricky at intel.com>
---
 .../bitbake-user-manual-fetching.xml                  | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml
index b37b2ae..f168cfa 100644
--- a/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml
+++ b/bitbake/doc/bitbake-user-manual/bitbake-user-manual-fetching.xml
@@ -325,6 +325,25 @@
      SRC_URI = "ftp://you@oe.handhelds.org/home/you/secret.plan"
                 </literallayout>
             </para>
+            <note>
+               Because URL parameters are delimited by semi-colons, this can
+               introduce ambiguity when parsing URLs that also contain semi-colons,
+               for example:
+                <literallayout class='monospaced'>
+     SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git;a=snapshot;h=a5dd47"
+                </literallayout>
+               Such URLs should should be modified by replacing semi-colons with '&amp;' characters:
+               <literallayout class='monospaced'>
+     SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&amp;a=snapshot&amp;h=a5dd47"
+                </literallayout>
+                In most cases this should work. Treating semi-colons and '&amp;' in queries
+                identically is recommended by the World Wide Web Consortium (W3C).
+                Note that due to the nature of the URL, you may have to specify the name
+                of the downloaded file as well:
+              <literallayout class='monospaced'>
+     SRC_URI = "http://abc123.org/git/?p=gcc/gcc.git&amp;a=snapshot&amp;h=a5dd47;downloadfilename=myfile.bz2"
+                </literallayout>
+            </note>
         </section>
 
         <section id='cvs-fetcher'>
-- 
1.9.1