summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/tex/luatex/optex/base/hyperlinks.opm
blob: 5fc8a32233bcfe35d2009cda43e405234387f94b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
%% This is part of the OpTeX project, see http://petr.olsak.net/optex

\_codedecl \ulink {Hyperlinks <2021-01-27>} % preloaded in format

   \_doc ----------------------------
   \`\dest``[<type>:<spec>]` creates a destination of internal links. The
   destination is declared in the format `<type>:<spec>`. If the \^`\hyperlinks`
   command in not used, then `\dest` does nothing else it is set to `\_destactive`.
   The \`\_destactive` is implemented by `\_pdfdest` primitive. It creates a box
   in which the destination is shifted by \`\_destheight`. The reason is that
   the destination is exactly at the top border of the PDF viewer but we want to see
   the line where the destination is. The destination box is positioned by a
   different way dependent on the current vertical or horizontal mode.
   \_cod ----------------------------

\_def\_destheight{1.4em}
\_def\_destactive[#1:#2]{\_if$#2$\_else\_ifvmode
      \_tmpdim=\_prevdepth \_prevdepth=-1000pt
      \_destbox[#1:#2]\_prevdepth=\_tmpdim
   \_else \_destbox[#1:#2]%
   \_fi\_fi
}
\_def\_destbox[#1]{\_vbox to\_zo{\_kern-\_destheight \_pdfdest name{#1} xyz\_vss}}
\_def\_dest[#1]{}
\_public \dest ;

   \_doc ----------------------------
   \`\link``[<type>:<spec>]{<color>}{<text>}` creates an internal link to \^`\dest`
   with the same `<type>:<spec>`. You can have more links with the same
   `<type>:<spec>` but only one `\dest` in the document. If \^`\hyperlinks`
   command is not used, then `\link` only prints `<text>` else it is set to
   `\_linkactive`.
   The \`\_linkactive` is implemented by `\_pdfstartlink...\_pdfendlink`
   primitives.
   \nl
   \`\ilink``[<type>:<spec>]{<text>}` is equivalent to `\_link` but
   the `<color>` is used from \^`\hyperlinks` declaration.
   \_cod ----------------------------

\_protected\_def\_linkactive[#1:#2]#3#4{\_leavevmode\_pdfstartlink height.9em depth.3em
      \_pdfborder{#1} goto name{#1:#2}\_relax {#3#4}\_pdfendlink
}
\_protected\_def\_link[#1]#2#3{\_leavevmode{#3}}
\_protected\_def\_ilink[#1]#2{\_leavevmode{#2}}
\_public \ilink \link ;

   \_doc ----------------------------
   \`\ulink``[<url>]{<text>}` creates external link. It prints only the `<text>` by default but
   the \^`\hyperlinks` declaration defines it as \`\_urlactive``[url:<url>]{<text>}`.
   The external link is created by the `\_pdfstartlink...\pdfendlink` primitives.
   The `<url>` is detokenized with `\escapechar=-1` before it is used, so
   `\%`, `\#` etc. can be used in the `<url>`.
   \_cod ----------------------------

\_protected\_def\_urlactive[#1:#2]#3#4{\_leavevmode{\_escapechar=-1
   \_pdfstartlink height.9em depth.3em \_pdfborder{#1}%
      user{/Subtype/Link/A <</Type/Action/S/URI/URI(\_detokenize{#2})>>}\_relax
      {#3#4}\_pdfendlink}%
}
\_def\_ulink[#1]#2{\_leavevmode{#2}}
\_def\_urlcolor{}
\_public \ulink ;

   \_doc ----------------------------
   The `\_pdfstartlink` primitive uses `\_pdfborder{<type>}` in its parameter
   (see \^`\_linkactive` or \^`\_urlactive` macros). The \`\_pdfborder``{<type>}`
   expands to `attr{/C[? ? ?] /Border[0 0 .6]}` if the
   `\_<type>border` (i.e.\ \`\_refborder`, \`\_citeborder`, \`\_tocborder`,
   \`\_pgborder`, \`\_urlborder`, \`\_fntborder` or \`\_fnfborder`)
   is defined. Users can define it in
   order to create colored frames around active links. For example
   `\def\_tocborder{1 0 0}` causes red frames in TOC (not printed, only visible
   in PDF viewers).
   \_cod ----------------------------

\_def\_pdfborder#1{\_ifcsname _#1border\_endcsname
       attr{/C[\_csname _#1border\_endcsname] /Border[0 0 .6]}%
   \_else attr{/Border[0 0 0]}\_fi
}

   \_doc ----------------------------
   \`\hyperlinks``{<ilink_color>}{<ulink_color>}` activates `\dest`, `\link`,
   `\ilink`, `\ulink` in order they create links. These macros are redefined
   here to their \"active" version.
   \_cod ----------------------------

\_def\_hyperlinks#1#2{%
   \_let\_dest=\_destactive \_let\_link=\_linkactive
   \_def\_ilink[##1]##2{\_link[##1]{\_localcolor#1}{##2}}%
   \_def\_ulink[##1]##2{\_urlactive[url:##1]{\_localcolor#2}{##2}}%
   \_public \dest \ilink \ulink \link ;%
}
\_public \hyperlinks ;

   \_doc ----------------------------
   \`\url``{<url>}` does approximately the same as \^`\ulink``[<url>]{<url>}`, but
   more work is done before the `\ulink` is processed. The link-version of <url>
   is saved to `\_tmpa` and the printed version in `\_tmpb`. The printed
   version is modified in order to set breakpoints to special places of the
   `<url>`. For example `//` is replaced by `\_urlskip/\_urlskip/\_urlbskip`
   where `\urlskip` adds a small nonbreakable glue between these two slashes and
   before them and `\_urlbskip` adds a breakable glue after them.
   \nl
   The text version of the `<url>` is printed in \`\_urlfont`.
   \_cod ----------------------------

\_def\_url#1{{%
   \_def\_tmpa{#1}\_replstring\_tmpa {\|}{}%
   {\_escapechar=-1 \_ea}\_ea\_edef\_ea\_tmpa\_ea{\_detokenize\_ea{\_tmpa}}%
   \_def\_tmpb{#1}\_replstring\_tmpb {\|}{\_urlbskip}%
   \_replstring\_tmpb {//} {{\_urlskip\_urlslashslash\_urlbskip}}%
   \_replstring\_tmpb {/}  {{\_urlskip/\_urlbskip}}%
   \_replstring\_tmpb {.}  {{\_urlskip.\_urlbskip}}%
   \_replstring\_tmpb {?}  {{\_urlskip?\_urlbskip}}%
   \_replstring\_tmpb {=}  {{\_urlskip=\_urlbskip}}%
   \_ea\_replstring\_ea\_tmpb \_ea{\_string &} {{\_urlbskip\_char`\& \_urlskip}}%
   \_ea\_replstring\_ea\_tmpb \_ea{\_bslash|}  {{\_penalty0}}%
   \_ea\_ulink \_ea[\_tmpa] {\_urlfont\_tmpb\_null}%
}}
\_def\_urlfont{\_tt}
\_def\_urlskip{\_null\_nobreak\_hskip0pt plus0.05em\_relax}
\_def\_urlbskip{\_penalty100 \_hskip0pt plus0.05em\_relax}
\_def\_urlslashslash{/\_urlskip/}

\_public \url ;

\_endcode % ----------------------------------------


There are four types of internal links and one type of external link:

\begitems
* `ref:<label>`     -- the destination is created when `\label[<label>]` is used,
                       see also the section \ref[references].
* `toc:<tocrefnum>` -- the destination is created at chap/sec/secc titles,
                       see also the section \ref[maketoc].
* `pg:<gpageno>`    -- the destination is created at beginning of each page,
                       see also the section \ref[output].
* `cite:<bibnum>`   -- the destination is created in bibliography reference,
                       see also the section \ref[bib].
* `url:<url>`       -- used by `\url` or `\ulink`,
                       see also the end of this section.
\enditems

The `<tocrefnum>`, `<gpageno>`, and `<bibnum>` are numbers starting from one and
globally incremented by one in the whole document. The registers \^`\tocrefnum`,
\^`\gpageno` and \^`\bibnum` are used for these numbers.

When a chap/sec/secc title is prefixed by `\label[<label>]`, then both types
of internal links are created at the same destination place:
`toc:<tocrefnum>` and `ref:<label>`.

\_endinput

2021-01-27 \public \link added to \hyperlinks, bug fixed.
2020-04-22 \| in \url: bug fixed
2020-03-15 introduced