bitbake: bitbake-user-manual-fetching.xml: note about URLs with semi-colons

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

(Bitbake rev: d8953c16c52c6e5de879f4a32ec8aeee396bb410)

Signed-off-by: Juro Bystricky <juro.bystricky@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

1 files changed, 19 insertions, 0 deletions

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 b37b2ae42c..f168cfa686 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'>