summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/tex/optex/base/hyperlinks.opm
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/tex/optex/base/hyperlinks.opm')
-rw-r--r--Master/texmf-dist/tex/optex/base/hyperlinks.opm157
1 files changed, 157 insertions, 0 deletions
diff --git a/Master/texmf-dist/tex/optex/base/hyperlinks.opm b/Master/texmf-dist/tex/optex/base/hyperlinks.opm
new file mode 100644
index 00000000000..5fc8a32233b
--- /dev/null
+++ b/Master/texmf-dist/tex/optex/base/hyperlinks.opm
@@ -0,0 +1,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 \ No newline at end of file