summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/tex/luatex/optex/hyperlinks.opm
blob: 02b33600bd594db7bd87bf55f926257249a5a33b (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
%% This is part of OpTeX project, see http://petr.olsak.net/optex

\_codedecl \ulink {Hyperlinks <2020-03-15>} % preloaded in format 

\_newcount \_tocrefnum

   \_doc ----------------------------
   `\dest[<type>:<spec>]` creates a destination of internal links. The
   destination is declared by `<type>:<spec>`. If `\hyperlinks` are not
   declared, 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 top border of the PDF viewer but we want to se
   the line where destination is. The destination box is positioned by
   different way dependent on 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 to0pt{\_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` are
   not declared, then `\link` only prints <text> else it is set to `\_linkactive`.
   The `\_linkactive` is implemented by `\_pdfstartlink...\_pdfendlink`
   primitives.

   `\ilink[<type>:<spec>]{<text>}` is equivalent to `\_link` but <color> is
   used from `\hyperlinks` decaration.
   \_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 ;

   \_doc ----------------------------
   `\ulink[<url>]{<text>}` creates external link. It prints only <text> by default but
   the `\hyperlinks` declaration defines it as `\_urlactive[url:<url>]{<text>}`.
   The external link is created by `\_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 `\_pdfbordef{<type>}` 
   expands to `attr{/C[? ? ?] /Border[0 0 .6]}` if the 
   `\<type>border` is defined. User 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{\_if^#1^\_else \_isdefined{#1border}\_iftrue
   \_if^\_csname #1border\_endcsname^\_else 
      attr{/C[\_csname #1border\_endcsname] /Border[0 0 .6]}\_fi
   \_else attr{/Border[0 0 0]}\_fi\_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 ;%
}
\_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 a breakpoints in special places of the
   <url>. For example `//` is replaced by `\_urlskip/\_urlskip/\_urlbskip` 
   where `\urlskip` adds a small nobreakable glue between these two slashes and
   before them and `\_urlbskip` adds a breakable glue after them.
   \_cod \_fin ----------------------

\_def\_url#1{{%
   \_def\_tmpa{#1}\_replstring\_tmpa {\|}{}%
   \_def\_tmpb{#1}\_replstring\_tmpb {\|}{\\|}%
   {\_escapechar=-1 \_ea}\_ea\_edef\_ea\_tmpb\_ea{\detokenize\_ea{\_tmpb}}%
   \_let\_tmpa=\_tmpb
   \_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 the 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 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>`.