ucw-link.tex

   1 % The UCW Macro Collection: Destinations and links
   2 % Written by Martin Mares <mj@ucw.cz> in 2018 and placed into public domain
   3 % -------------------------------------------------------------------------
   4
   5 \ucwdefmodule{link}
   6
   7 % Should clickable links be produced?
   8 \newif\ifclickable
   9 \ifpdf
  10         \clickabletrue
  11 \else
  12         \clickablefalse
  13 \fi
  14
  15 % Common style of all clickable links
  16 \pdflinkmargin=1pt
  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]}}
  18
  19 % Define a PDF destination for the current position at the page
  20 \def\destpos#1{\ifclickable\pdfdest name {#1} xyz\relax\fi}
  21
  22 % Define a PDF destination for the current page
  23 \def\destpage#1{\ifclickable\pdfdest name {#1} fit\relax\fi}
  24
  25 % Typeset a clickable link to the given destination
  26 % \link{dest}{text}
  27 \def\link#1#2{%
  28         \ifclickable
  29                 \pdfstartlink\commonlinkargs goto name {#1}\relax
  30                 #2%
  31                 \pdfendlink\relax
  32         \else
  33                 #2%
  34         \fi
  35 }
  36
  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}
  42
  43 % Typesetting of URLs is tricky:
  44 %
  45 %   - They can contain various characters considered special by TeX.
  46 %   - We want to adjust appearance of "//", "_", "~" according to font.
  47 %   - "--" should not produce a ligature.
  48 %   - We want to insert a breakpoint after "/", "?", "&".
  49 %   - We need the raw form of the URL for PDF links.
  50 %   - We cannot rely purely on changing catcodes, as we sometimes need
  51 %     to parse URLs given as arguments of macros.
  52 %   - Sometimes, it is useful to insert a manual line break or another
  53 %     typesetting hack to the URL.
  54 %
  55 % Therefore:
  56 %
  57 %   - In our front-end macros (\url, \linkurl) we switch catcodes
  58 %     to accept '%' and '#' as normal characters; if the macros are
  59 %     called indirectly, these characters must be escaped as '\%' and '\#'.
  60 %   - The URL is preprocessed: special characters (with their original
  61 %     catcode) are replaced by calls of auxiliary macros.
  62 %   - When producing PDF links, the auxiliary macros expand to ordinary
  63 %     ASCII characters.
  64 %   - When typesetting the URL, the auxiliary macros expand differently.
  65 %     Furthermore, they can be temporarily re-defined in the \urlprefix macro.
  66 %   - "\\" (which is usually called to produce a line break) disappears in PDF links.
  67 %   - If you use \urlhack{X} in the URL, it is typeset as X, but it disappears
  68 %     in PDF links.
  69 %   - If you call a custom macro in the URL, you can modify its definition
  70 %     for typesetting in \urlprefix and for PDF links by appending to \urlplainascii.
  71
  72 % Typeset a clickable URL
  73 % \url{http://example.com/}
  74 \def\url{\begingroup\begingroup\allowurlchars\urlaux}
  75 \def\urlaux#1{\urlauxarg{#1}\linkurlauxB{\displayurl}}
  76
  77 % Typeset a clickable link to the given URL
  78 % \linkurl{http://example.com/}{text}
  79 \def\linkurl{\begingroup\begingroup\allowurlchars\linkurlaux}
  80 \def\linkurlaux#1{\urlauxarg{#1}\linkurlauxB}
  81 \def\linkurlauxB#1{%
  82         \leavevmode
  83         \ifclickable
  84                 {%
  85                         \urlplainascii
  86                         \pdfstartlink\commonlinkargs user {/Subtype/Link /A << /Type/Action /S/URI /URI(\tmpb) >>}\relax
  87                 }%
  88         \fi
  89         #1%
  90         \ifclickable
  91                 \pdfendlink
  92         \fi
  93         \endgroup               % opened in \url or \linkurl
  94 }
  95
  96 % Catcode '%' and '#' to 'other'
  97 \def\allowurlchars{\catcode`\%=12\catcode`\#=12\relax}
  98
  99 \def\urlauxarg#1{%
 100         \endgroup               % opened in \url or \linkurl
 101         \toks0={#1}\edef\tmpb{\the\toks0}%
 102         \replacestrings{//}{\urlslashslash}%
 103         \replacestrings{_}{\urlunderscore}%
 104         \replacestrings{~}{\urltilde}%
 105         \replacestrings{/}{\urlslash}%
 106         \replacestrings{?}{\urlquestion}%
 107         \replacestrings{&}{\urlamp}%
 108         \replacestrings{=}{\urlequal}%
 109         \replacestrings{-}{\urlminus}%
 110 }
 111
 112 % Style switches at the beginning/end of an URL (feel free to re-define them)
 113 \let\urlprefix\it
 114 \let\urlsuffix\/
 115
 116 % Default appearance of characters special in URLs
 117 \def\urlslashslash{/\kern\urlinterslashkern/}
 118 \def\urlunderscore{\_}
 119 \def\urltilde{{\tt\char126}}
 120 \def\urlslash{/\penalty100\relax}
 121 \def\urlquestion{?\penalty100\relax}
 122 \def\urlamp{\&\penalty100\relax}
 123 \def\urlequal{=\penalty100\relax}
 124 \def\urlminus{\hbox{-}}
 125 \def\urlhack#1{#1}
 126
 127 % Kern to place between "//" in an URL
 128 \newdimen\urlinterslashkern
 129 \urlinterslashkern=-0.1em
 130
 131 % Switch auxiliary macros, so special characters expand to plain ASCII characters
 132 % (since we need to replace them in the expand processor, we cannot use \let for that)
 133 % If you want to modify expansion of your macros, extend \urlplainascii using \appendef.
 134 {
 135 \lccode`A=`\_
 136 \lccode`B=`\~
 137 \lccode`C=`\&
 138 \lccode`D=`\%
 139 \lccode`E=`\#
 140 \lowercase{\gdef\urlplainascii{%
 141         \def\urlslashslash{//}%
 142         \def\urlunderscore{A}%
 143         \def\urltilde{B}%
 144         \def\urlslash{/}%
 145         \def\urlquestion{?}%
 146         \def\urlamp{C}%
 147         \def\urlequal{=}%
 148         \def\urlminus{-}%
 149         \def\%{D}%
 150         \def\#{E}%
 151         \def\\{}%
 152         \def\urlhack##1{}%
 153 }}}
 154
 155 % Typeset the URL stored in \tmpb. In most cases, this is used internally by \url,
 156 % but you can call it explicity from the second argument of \linkurl to typeset the current URL.
 157 \def\displayurl{{\urlprefix\tmpb\urlsuffix}}