From a5ae129f3aa3a3a0aeaa21c55b75a1d543fe4111 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Fri, 4 Jun 2021 03:02:48 +0000 Subject: CTAN sync 202106040302 --- macros/optex/base/hyperlinks.opm | 203 ++++++++++++++++++++++++--------------- 1 file changed, 124 insertions(+), 79 deletions(-) (limited to 'macros/optex/base/hyperlinks.opm') diff --git a/macros/optex/base/hyperlinks.opm b/macros/optex/base/hyperlinks.opm index 95fae3846b..ef205f3aa2 100644 --- a/macros/optex/base/hyperlinks.opm +++ b/macros/optex/base/hyperlinks.opm @@ -1,6 +1,6 @@ %% This is part of the OpTeX project, see http://petr.olsak.net/optex -\_codedecl \ulink {Hyperlinks <2021-04-17>} % preloaded in format +\_codedecl \ulink {Hyperlinks <2021-05-14>} % preloaded in format \_doc ---------------------------- \`\dest``[:]` creates a destination of internal links. The @@ -25,78 +25,81 @@ \_public \dest ; \_doc ---------------------------- - \`\link``[:]{}{}` creates an internal link to \^`\dest` - with the same `:`. You can have more links with the same - `:` but only one `\dest` in the document. If \^`\hyperlinks` - command is not used, then `\link` only prints `` else its meaning is set to - `\_linkactive`. - The \`\_linkactive` is implemented by `\_pdfstartlink...\_pdfendlink` - primitives. The `` is the color of the link text generated by - the `\_linkactive` macro. - The `` parameter can be overwritten by definition of - `\_linkcolor`. For example `\def\_toclinkcolor{\Red}` means that - links from table of contents are in red. This is similar concept as - `\_def\_tocborder`. + Each hyperlink is created internally by \`\_xlink``{}{}{}{}`. + This macro expands to `\_quitvmode{}` by default, i.e.\ no active + hyperlink is created, only is printed in horizontal mode. + If \^`\hyperlinks` is used, then `\_xlink` gets meaning of + \`\_xlinkactive` and hyperlinks are created using `\pdfstartlink`, + `\pdfendlink` primitives. The has given only when + hyperlink is created. But if `\_linkcolor` is defined, it has + precedence. \nl - \`\ilink``[:]{}` is equivalent to `\_link` but - the `` is used from \^`\hyperlinks` declaration - (or it is overwriten by `\def\_linkcolor`). + The \`\_linkdimens` macro declares the dimensions of link area. \nl - \`\_linkdimens` are default dimensions of the link area. - \_cod ---------------------------- + A specific action can be defined for each link by the macro + `\_action{}`. \OpTeX/ defines only \`\_urlaction``{}`. + The default link action (when `\_action` is not defined) is + `goto mame{:}` (creates an internal link). It is declared in the + \`\_linkactions``{}{}` macro. + \nl + The `\_pdfstartlink` primitive uses `attr{\_pdfborder{}}`. The + \`\_pdfborder``{}` macro expands to `/C[? ? ?] /Border[0 0 .6]` if the + `\_border` macro (i.e.\ \`\_refborder`, \`\_citeborder`, \`\_tocborder`, + \`\_pgborder`, \`\_urlborder`, \`\_fntborder` or \`\_fnfborder`) + is defined. + \_cod -\_protected\_def\_linkactive[#1:#2]#3#4{\_leavevmode\_pdfstartlink \_linkdimens - attr{\_pdfborder{#1}} goto name{#1:#2}\_relax - {\_localcolor\_trycs{_#1linkcolor}{#3}#4}\_pdfendlink +\_protected\_def\_xlinkactive#1#2#3#4{\_quitvmode + \_pdfstartlink \_linkdimens attr{\_pdfborder{#1}}\_linkactions{#1}{#2}\_relax + {\_localcolor\_trycs{_#1linkcolor}{#3}#4}\_pdfendlink } -\_protected\_def\_link[#1]#2#3{\_leavevmode{#3}} -\_def\_ilink[#1]#2{\_link[#1]{}{#2}} +\_protected\_def\_xlink#1#2#3#4{\_quitvmode{#4}} + \_def\_linkdimens{height.9em depth.3em} -\_public \ilink \link ; - \_doc ---------------------------- - \`\ulink``[]{}` creates external link. It prints only the `` by default but - the \^`\hyperlinks` declaration defines it as \`\_urlactive``[url:]{}`. - The external link is created by the `\_pdfstartlink...\pdfendlink` primitives. - The `` is detokenized with `\escapechar=-1` before it is used, so - `\%`, `\#` etc. can be used in the ``. - \_cod ---------------------------- +\_def\_linkactions#1#2{\_ifcsname _#1action\_endcsname + \_lastnamedcs{#2}\_else goto name{#1:#2}\_fi} +\_def\_urlaction #1{user{/Subtype/Link/A <>}} -\_protected\_def\_urlactive[#1:#2]#3#4{\_leavevmode{\_escapechar=-1 - \_pdfstartlink \_linkdimens attr{\_pdfborder{#1}}% - user{/Subtype/Link/A <>}\_relax - {\_localcolor\_trycs{_#1linkcolor}{#3}#4}\_pdfendlink}% +\_def\_pdfborder#1{\_ifcsname _#1border\_endcsname + /C [\_csname _#1border\_endcsname] /Border [0 0 .6]\_else /Border [0 0 0]\_fi } -\_def\_ulink[#1]#2{\_leavevmode{#2}} -\_public \ulink ; - \_doc ---------------------------- - The `\_pdfstartlink` primitive uses `attr{\_pdfborder{}}` in its parameter - (see \^`\_linkactive` or \^`\_urlactive` macros). The \`\_pdfborder``{}` - macro expands to `/C[? ? ?] /Border[0 0 .6]` if the - `\_border` macro (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). + \_doc ------------------------------ + \`\link``[:]{}{}` creates a link. It is + kept here for backward compatibility and it is + equivalent to \^`\_xlink{}{}{}{}`. + If `\_action` is not defined then + `\link` creates internal link do the \^`\dest[:]`. + You can have more links with the same `:` but only one \^`\dest` + in the document. + \nl + \`\ilink``[:]{}` is equivalent to \^`\link` but + the `` is used from \^`\hyperlinks` declaration + (or it is overwriten by `\def\_linkcolor`). + \nl + \`\ulink``[]{}` creates external link. + The `` is detokenized with `\escapechar=-1` before it is used, so + `\%`, `\#` etc. can be used in the ``. \_cod ---------------------------- -\_def\_pdfborder#1{\_ifcsname _#1border\_endcsname - /C [\_csname _#1border\_endcsname] /Border [0 0 .6]\_else /Border [0 0 0]\_fi -} +\_def\_link[#1:#2]{\_xlink{#1}{#2}} +\_def\_ilink[#1:#2]#3{\_xlink{#1}{#2}\_ilinkcolor{#3}} +\_def\_ulink[#1]#2{{\_escapechar=-1 \_ea}\_expanded + {\_noexpand\_xlink{url}{\_detokenize{#1}}}\_elinkcolor{#2}} + +\_public \ilink \ulink \link ; \_doc ---------------------------- - \`\hyperlinks``{}{}` activates `\dest`, `\link`, - `\ilink`, `\ulink` in order they create links. These macros are redefined - here to their \"active" version. + \`\hyperlinks``{}{}` activates `\dest`, `\xlink`, + in order they create links. \_cod ---------------------------- \_def\_hyperlinks#1#2{% - \_let\_dest=\_destactive \_let\_link=\_linkactive - \_def\_ilink[##1]##2{\_link[##1]{#1}{##2}}% - \_def\_ulink[##1]##2{\_urlactive[url:##1]{#2}{##2}}% - \_public \dest \ilink \ulink \link ;% + \_let\_dest=\_destactive \_let\_xlink=\_xlinkactive + \_let\_ilinkcolor=#1% + \_let\_elinkcolor=#2% + \_public \dest \xlink ;% } \_public \hyperlinks ; @@ -104,38 +107,64 @@ \`\url``{}` does approximately the same as \^`\ulink``[]{}`, but more work is done before the `\ulink` is processed. The link-version of 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 - ``. 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. + version is processed in four steps: 1.~the `\|` are replaced by `[||]` (we + suppose that such string does not exist in any URL). 2.~it is detokenized with + `\escapechar=-1`. 3.~muti-strings and spaces are replaced by strings in + braces `{...}`. 4.~internal penalties and skips are put between characters + using \`\_urlA`, \`\_urlB` and \`\_urlC`. The step~4 do following: + The \`\_urlxskip` is inserted between each pair of \"normal characters", + i.e.\ characters not declared by `\sdef{_ur:}`. + The special characters declared by `\sdef{_ur:}` are replaced + by the body of their corresponding macro. + The \`\_urlskip`, \`\_urlbskip`, \`\_urlgskip` + are typical skips used for special characters, their meaning is + documented in the code below. You can change them. + Default values: penalty 9990 is inserted between each pair of normal + chararacters, penalty 100 is inserted after special charcters, nobreak before special + characters. The URL can be broken at any place using these default + values. If you want to disable breaking between normal characters, say + `\let\_urlxskip=\nobreak`. \nl The text version of the `` 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\_tmpb{#1}\_replstring\_tmpb {\|}{[||]}% + {\_escapechar=-1 \_ea}\_ea\_edef\_ea\_tmpb\_ea{\_detokenize\_ea{\_tmpb}}% + \_replstring\_tmpb{[||]}{{gb|}}% + \_replstring\_tmpb{ }{{ }}% + \_replstring\_tmpb{://}{{://}}% + \_ea\_ulink \_ea[\_ea{\_tmpa}] {\_urlfont \_ea\_urlA\_tmpb\_end}% }} -\_def\_urlfont{\_tt} -\_def\_urlskip{\_null\_nobreak\_hskip0pt plus0.05em\_relax} -\_def\_urlbskip{\_penalty100 \_hskip0pt plus0.05em\_relax} -\_def\_urlslashslash{/\_urlskip/} +\_def\_urlA#1{\_ifx\_end#1\_else \_urlC{}{#1}\_fi} +\_def\_urlB#1{\_ifx\_end#1\_else \_urlC{\_urlxskip}{#1}\_fi} +\_def\_urlC#1#2{% + \_ifcsname _ur:#2\_endcsname \_lastnamedcs \_ea\_ea\_ea \_urlA + \_else #1#2\_ea\_ea\_ea \_urlB \_fi +} +\_sdef{_ur:://}{\_urlskip:\_urlskip/\_urlskip/\_urlbskip} +\_sdef{_ur:/}{\_urlskip/\_urlbskip} +\_sdef{_ur:.}{\_urlskip.\_urlbskip} +\_sdef{_ur:?}{\_urlskip?\_urlbskip} +\_sdef{_ur:=}{\_urlskip=\_urlbskip} +\_sdef{_ur:-}{\_urlskip-\_urlbskip} +\_sdef{_ur:&}{\_urlskip\_char`\&\_urlbskip} +\_sdef{_ur:gb|}{\_urlgskip} + +\_def\_urlfont{\_tt} % url font +\_def\_urlxskip{\_penalty9990\_hskip0pt plus0.03em\_relax} % skip between normal characters +\_def\_urlskip{\_null\_nobreak\_hskip0pt plus0.1em\_relax} % skip before :// / . ? = - & +\_def\_urlbskip{\_penalty100 \_hskip0pt plus0.1em\_relax} % skip after :// / . ? = - & +\_def\_urlgskip{\_penalty-500\_relax} % "goodbreak" penalty generated by \| \_public \url ; \_endcode % ---------------------------------------- -There are four types of internal links and one type of external link: +There are six types of internal links and one type of external link used +in \OpTeX/. They are used in the format :. \begitems * `ref: