docutils/test/functional/input/data/urls.txt

   1 External references
   2 -------------------
   3
   4 Long URLs should be wrapped in the PDF.
   5 This can be achieved with the \url command which is used by the LaTeX writer
   6 whenever the content (name) of a reference node equals the link URL.
   7
   8 Example:
   9   a long URL that should wrap in the output
  10   http://docutils.sourceforge.net/docs/user/latex.html#id79
  11
  12
  13 If the argument contains any "%", "#", or "^^", or ends with ``\``, it can't
  14 be used in the argument to another command. The argument must not contain
  15 unbalanced braces.
  16
  17 The characters ^, {, }, and ``\`` are invalid in a "http:" or "ftp:" URL
  18 and 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
  24 They can, however be used in paths and/or filenames.
  25
  26 Handling 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}>`__