1 % The UCW Macro Collection: Destinations and links
2 % Written by Martin Mares <mj@ucw.cz> in 2018 and placed into public domain
3 % -------------------------------------------------------------------------
7 % Should clickable links be produced?
15 % Common style of all clickable links
17 \def\commonlinkargs{height \the\dimexpr\ht\strutbox-0.5pt\relax depth \the\dimexpr\dp\strutbox-0.5pt\relax attr {/C [0 0 0.5] /Border [0 0 2]}}
19 % Define a PDF destination for the current position at the page
20 \def\destpos#1{\ifclickable\pdfdest name {#1} xyz\relax\fi}
22 % Define a PDF destination for the current page
23 \def\destpage#1{\ifclickable\pdfdest name {#1} fit\relax\fi}
25 % Typeset a clickable link to the given destination
29 \pdfstartlink\commonlinkargs goto name {#1}\relax
37 % Typeset a clickable link to the given page number
38 % (This does not use named destinations. We use it in tables of contents and indices,
39 % where absolute page numbers are known from other sources.)
40 % \linkpage{page}{text}
41 \def\linkpage#1#2{\ifclickable\pdfstartlink\commonlinkargs goto page #1 {/Fit}\relax #2\pdfendlink\else #2\fi}
43 % Typesetting of URLs is tricky:
45 % - They can contain various characters considered special by TeX.
46 % - We want to adjust appearance of "//", "_", "~" according to font.
47 % - We want to insert a breakpoint after "/", "?", "&".
48 % - We need the raw form of the URL for PDF links.
49 % - We cannot rely purely on changing catcodes, as we sometimes need
50 % to parse URLs given as arguments of macros.
51 % - Sometimes, it is useful to insert a manual line break to the URL.
55 % - In our front-end macros (\url, \linkurl) we switch catcodes
56 % to accept '%' and '#' as normal characters; if the macros are
57 % called indirectly, these characters must be escaped as '\%' and '\#'.
58 % - The URL is preprocessed: special characters (with their original
59 % catcode) are replaced by calls of auxiliary macros.
60 % - When producing PDF links, the auxiliary macros expand to ordinary
62 % - When typesetting the URL, the auxiliary macros expand differently.
63 % Furthermore, they can be temporarily re-defined in the \urlprefix macro.
64 % - "\\" (which is usually called to produce a line break) disappears in PDF links.
65 % - If you call a custom macro in the URL, you can modify its definition
66 % for typesetting in \urlprefix and for PDF links by appending to \urlplainascii.
68 % Typeset a clickable URL
69 % \url{http://example.com/}
70 \def\url{\begingroup\begingroup\allowurlchars\urlaux}
71 \def\urlaux#1{\urlauxarg{#1}\linkurlauxB{\displayurl}}
73 % Typeset a clickable link to the given URL
74 % \linkurl{http://example.com/}{text}
75 \def\linkurl{\begingroup\begingroup\allowurlchars\linkurlaux}
76 \def\linkurlaux#1{\urlauxarg{#1}\linkurlauxB}
82 \pdfstartlink\commonlinkargs user {/Subtype/Link /A << /Type/Action /S/URI /URI(\tmpb) >>}\relax
89 \endgroup % opened in \url or \linkurl
92 % Catcode '%' and '#' to 'other'
93 \def\allowurlchars{\catcode`\%=12\catcode`\#=12\relax}
96 \endgroup % opened in \url or \linkurl
97 \toks0={#1}\edef\tmpb{\the\toks0}%
98 \replacestrings{//}{\urlslashslash}%
99 \replacestrings{_}{\urlunderscore}%
100 \replacestrings{~}{\urltilde}%
101 \replacestrings{/}{\urlslash}%
102 \replacestrings{?}{\urlquestion}%
103 \replacestrings{&}{\urlamp}%
104 \replacestrings{=}{\urlequal}%
107 % Style switches at the beginning/end of an URL (feel free to re-define them)
111 % Default appearance of characters special in URLs
112 \def\urlslashslash{/\kern\urlinterslashkern/}
113 \def\urlunderscore{\_}
114 \def\urltilde{{\tt\char126}}
115 \def\urlslash{/\penalty100\relax}
116 \def\urlquestion{?\penalty100\relax}
117 \def\urlamp{\&\penalty100\relax}
118 \def\urlequal{=\penalty100\relax}
120 % Kern to place between "//" in an URL
121 \newdimen\urlinterslashkern
122 \urlinterslashkern=-0.1em
124 % Switch auxiliary macros, so special characters expand to plain ASCII characters
125 % (since we need to replace them in the expand processor, we cannot use \let for that)
126 % If you want to modify expansion of your macros, extend \urlplainascii using \appendef.
133 \lowercase{\gdef\urlplainascii{%
134 \def\urlslashslash{//}%
135 \def\urlunderscore{A}%
146 % Typeset the URL stored in \tmpb. In most cases, this is used internally by \url,
147 % but you can call it explicity from the second argument of \linkurl to typeset the current URL.
148 \def\displayurl{{\urlprefix\tmpb\urlsuffix}}