summaryrefslogtreecommitdiff
path: root/macros/luatex/optex/hyperlinks.opm
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/optex/hyperlinks.opm')
-rw-r--r--macros/luatex/optex/hyperlinks.opm134
1 files changed, 74 insertions, 60 deletions
diff --git a/macros/luatex/optex/hyperlinks.opm b/macros/luatex/optex/hyperlinks.opm
index 891ae41f49..1cf48ac945 100644
--- a/macros/luatex/optex/hyperlinks.opm
+++ b/macros/luatex/optex/hyperlinks.opm
@@ -1,8 +1,19 @@
%% This is part of OpTeX project, see http://petr.olsak.net/optex
-\_codedecl \urllink {references <2020-02-22>}
+\_codedecl \ulink {Hyperlinks <2020-02-22>}
-%> \dest
+\_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
@@ -15,7 +26,17 @@
\_def\_dest[#1]{}
\_public \dest ;
-%> \_link, \ilink
+ \_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
@@ -24,7 +45,13 @@
\_protected\_def\_ilink[#1]#2{\_leavevmode{#2}}
\_public \ilink ;
-%> \ulink
+ \_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}%
@@ -35,7 +62,15 @@
\_def\_urlcolor{}
\_public \ulink ;
-%> \_pdfborder
+ \_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
@@ -43,7 +78,11 @@
\_else attr{/Border[0 0 0]}\_fi\_fi
}
-%> \hyperlinks
+ \_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
@@ -53,7 +92,15 @@
}
\_public \hyperlinks ;
-%> \url
+ \_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 {\|}{}%
@@ -76,62 +123,29 @@
\_public \url ;
-\_endcode % -------------------------------------
-
-\%> \dest
-
-`\dest[<type>:<label>]` creates a destination of internal links. The
-destination is declared by `<type>:<label>`. 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.
-
-\%> \_link \ilink
-
-`\_link[<type>:<label>]{<color>}{<text>}` creates an internal link to `\dest`
-with the same `<type>:<label>`. You can have more links with the same
-`<type>:<label>` but only one `\dest` in the document. If `\hyperlinks` are
-not declared, then `\link` only prints <text> else it is set to `\_linkactive`.
-The `\_linktactive` is implemented by `\_pdfstartlink...\_pdfendlink`
-primitives.
-
-`\ilink[<type>:<label>]{<text>}` is equivalent to `\_link` but <color> is
-used from `\hyperlinks` decaration.
-
-\%> \ulink
-
-`\ulink[<url>]{<text>}` creates external link. It 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>.
-
-\%> \_pdfborder
+\_endcode % ----------------------------------------
-The `\_pdfstartink` 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).
-\%> \hyperlinks
+There are four types of the internal links and one type of external link:
-`\hyperlinks{<ilink_color>}{<ulink_color>}` activates `\dest`, `\link`,
-`\ilink`, `\ulink` in order they create links. These macros are redefined
-here to their \"active" version.
+\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
-\%> \url
+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.
-`\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.
+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>`.