+% Typesetting of URLs is tricky:
+%
+% - They can contain various characters considered special by TeX.
+% - We want to adjust appearance of "//", "_", "~" according to font.
+% - "--" should not produce a ligature.
+% - We want to insert a breakpoint after "/", "?", "&".
+% - We need the raw form of the URL for PDF links.
+% - We cannot rely purely on changing catcodes, as we sometimes need
+% to parse URLs given as arguments of macros.
+% - Sometimes, it is useful to insert a manual line break or another
+% typesetting hack to the URL.
+%
+% Therefore:
+%
+% - In our front-end macros (\url, \linkurl) we switch catcodes
+% to accept '%' and '#' as normal characters; if the macros are
+% called indirectly, these characters must be escaped as '\%' and '\#'.
+% - The URL is preprocessed: special characters (with their original
+% catcode) are replaced by calls of auxiliary macros.
+% - When producing PDF links, the auxiliary macros expand to ordinary
+% ASCII characters.
+% - When typesetting the URL, the auxiliary macros expand differently.
+% Furthermore, they can be temporarily re-defined in the \urlprefix macro.
+% - "\\" (which is usually called to produce a line break) disappears in PDF links.
+% - If you use \urlhack{X} in the URL, it is typeset as X, but it disappears
+% in PDF links.
+% - If you call a custom macro in the URL, you can modify its definition
+% for typesetting in \urlprefix and for PDF links by appending to \urlplainascii.
+