1External references
2-------------------
3
4Long URLs should be wrapped in the PDF. This can be achieved with the
5``\url`` command which is used by the LaTeX writer whenever the content
6(name) of a reference node equals the link URL.
7
8Example:
9  a long URL that should wrap in the output
10  http://docutils.sourceforge.net/docs/user/latex.html#id79
11
12
13If the argument contains any "%", "#", or "^^", or ends with ``\``, it can't
14be used in the argument to another command. The argument must not contain
15unbalanced braces.
16
17The characters ^, {, }, and ``\`` are invalid in a "http:" or "ftp:" URL
18and not recognized as part of it:
19
20| http://www.example.org/strange^^name
21| http://www.example.org\\using\\DOS\\paths\\
22| http://www.example.org/XML/strange{n}ame
23
24They can, however be used in paths and/or filenames.
25
26Handling by the LaTeX writer:
27
28* ``#``, ``\`` and ``%`` are escaped:
29
30  | `URL with # <http://www.w3.org/XML/Schema#dev>`__
31    http://www.w3.org/XML/Schema#dev
32  | `URL with % <http://www.w3.org/XML/Schema%dev>`__
33    http://example.org/Schema%dev
34  | `file with DOS path`__ `A:DOS\\path\\`__
35
36  .. note:: These URLs are typeset inside a LaTeX command without error.
37
38    | http://www.w3.org/XML/Schema#dev
39    | http://example.org/Schema%dev
40    | `A:DOS\\path\\`__
41
42__
43__
44__ A:DOS\\path\\
45
46
47* ``^^`` LaTeX's special syntax for characters results in "strange" replacements
48  (both with ``\href`` and ``\url``). A warning is given.
49
50  `file with ^^ <../strange^^name>`__:
51  `<../strange^^name>`__
52
53* Unbalanced braces, { or }, will fail (both with ``\href`` and ``\url``)::
54
55    `file with { <../strange{name>`__
56    `<../strange{name>`__
57
58  while balanced braces are suported:
59
60  | `<../strange{n}ame>`__
61  | `<../st{r}ange{n}ame>`__
62  | `<../{st{r}ange{n}ame}>`__
63