diff options
Diffstat (limited to 'macros/luatex/optex/hyperlinks.opm')
-rw-r--r-- | macros/luatex/optex/hyperlinks.opm | 134 |
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>`. |