diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/aeb_mlink |
Initial commit
Diffstat (limited to 'macros/latex/contrib/aeb_mlink')
-rw-r--r-- | macros/latex/contrib/aeb_mlink/README.md | 54 | ||||
-rw-r--r-- | macros/latex/contrib/aeb_mlink/aeb_mlink.dtx | 1574 | ||||
-rw-r--r-- | macros/latex/contrib/aeb_mlink/aeb_mlink.ins | 60 | ||||
-rw-r--r-- | macros/latex/contrib/aeb_mlink/doc/aebmlink_man.pdf | bin | 0 -> 309586 bytes | |||
-rw-r--r-- | macros/latex/contrib/aeb_mlink/doc/aebmlink_man.tex | 927 | ||||
-rw-r--r-- | macros/latex/contrib/aeb_mlink/examples/mlink_tst.pdf | bin | 0 -> 62931 bytes | |||
-rw-r--r-- | macros/latex/contrib/aeb_mlink/examples/mlink_tst.tex | 150 | ||||
-rw-r--r-- | macros/latex/contrib/aeb_mlink/examples/mlink_tst_url.pdf | bin | 0 -> 35662 bytes | |||
-rw-r--r-- | macros/latex/contrib/aeb_mlink/examples/mlink_tst_url.tex | 48 | ||||
-rw-r--r-- | macros/latex/contrib/aeb_mlink/examples/np_test.txt | 1 | ||||
-rw-r--r-- | macros/latex/contrib/aeb_mlink/examples/shameless_ad.pdf | bin | 0 -> 40725 bytes |
11 files changed, 2814 insertions, 0 deletions
diff --git a/macros/latex/contrib/aeb_mlink/README.md b/macros/latex/contrib/aeb_mlink/README.md new file mode 100644 index 0000000000..5903461b8d --- /dev/null +++ b/macros/latex/contrib/aeb_mlink/README.md @@ -0,0 +1,54 @@ +Package: aeb_mlink +Author: D. P. Story +Dated: 2018/08/18 + +The aeb_mlink package defines new link commands to create multi-line links. +The new commands are \mlhypertext, \mlhyperlink, \mlhyperref, \mlnameref, +\mlNameref, \mlhref, and \mlurl. + +PDF Creators: Adobe Distiller or ps2pdf + +What's New (2018/08/18): Created \turnSyllbCntOn (\turnSyllbCntOff) to turn +on (resp., off) the viewing of syllable numbers. Reorganize core program to +accommodate the use of \mlhypertext command within the program code of +annot_pro. (This is to implement text markup annotations in that package.) + +What's New (2018/04/26): Included a 'dummy' package named aeb-mlink. The +aeb_mlink package is listed on CTAN as aeb-mlink, though there is no such +package by that name. Well, now there is. + +What's New (2018/04/20): Previously, the links created by aeb_mlink consisted +of a series of rectangles around each of the syllables of the hypertext or +url; the little rectangles responded in unison when any one of them were +clicked. In this version, Postscript procedures are used to combine the +little rectangles into one rectangle per line of hypertext. Also the Rect +entry has been changed to be the smallest rectange that encloses the +hypertext (or url). The Postscript tries to detect problems with the links, +and reports to the log (distiller or ps2pdf log). The PDF Specification does +not support cross-page links, to resolve this issued, a method of 'cracking' +a link apart, breaking it into two links. The second link is free to move to +the next page. + +This package requires the latest version of AeB, in particular, the eforms +package required is dated 2018/03/22 or later. See ctan.org/pkg/acrotex. + +In addition to the demo files distributed with the package, there are two new +demo files available from the AcroTeX Blog webiste: + + aeb_mlink: Fixing multi-line link boxes + (http://www.acrotex.net/blog/?p=1377) + + aeb_mlink: Crossing page boundaries with multi-line links + (http://www.acrotex.net/blog/?p=1383) + +Let me know if there are problems or suggested features. e-mail +me at dpstory@uakron.edu or dpstory@acrotex.net + +My other web site is http://blog.acrotex.net/ has the latest on my +ruminations on LaTeX and PDF. + +Now, I simply must get back to my retirement. + +D. P. Story +dpstory@uakron.edu + diff --git a/macros/latex/contrib/aeb_mlink/aeb_mlink.dtx b/macros/latex/contrib/aeb_mlink/aeb_mlink.dtx new file mode 100644 index 0000000000..5a8b97fef2 --- /dev/null +++ b/macros/latex/contrib/aeb_mlink/aeb_mlink.dtx @@ -0,0 +1,1574 @@ +% \iffalse +%<*copyright> +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% aeb_mlink.sty package, %% +%% Copyright (C) 2006--2018 D. P. Story %% +%% dpstory@acrotex.net %% +%% %% +%% This program can redistributed and/or modified under %% +%% the terms of the LaTeX Project Public License %% +%% Distributed from CTAN archives in directory %% +%% macros/latex/base/lppl.txt; either version 1.2 of %% +%% the License, or (at your option) any later version. %% +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%</copyright> +%<package>\NeedsTeXFormat{LaTeX2e} +%<package>\ProvidesPackage{aeb_mlink} +%<package> [2018/08/18 v2.3.4 AeB MLink (dps)] +%<*driver> +\documentclass{ltxdoc} +\usepackage{xcolor} +\usepackage[colorlinks,hyperindex=false]{hyperref} +\usepackage{aeb_mlink} +\pdfstringdefDisableCommands{\let\\\textbackslash}% +\OnlyDescription % comment out for implementation details +\EnableCrossrefs +\CodelineIndex +\RecordChanges +\InputIfFileExists{aebdocfmt.def}{\PackageInfo{web}{Inputting aebdocfmt.def}} + {\def\IndexOpt{\DescribeMacro}\def\IndexKey{\DescribeMacro}\let\setupFullwidth\relax + \PackageInfo{web}{aebdocfmt.def cannot be found}} +\begin{document} +\def\CMD#1{\textbackslash#1} +\let\pkg\textsf +\let\env\texttt +\let\opt\texttt +\let\app\textsf +\def\visispace{\symbol{32}} +\def\ameta#1{\ensuremath{\langle\textit{\texttt{#1}}\rangle}} +\def\meta#1{\textsl{\texttt{#1}}} +\def\SUB#1{\ensuremath{{}_{\mbox{\scriptsize\ttfamily#1}}}} +\def\darg#1{\texttt{\char123\relax#1\char125\relax}} +\addtolength{\marginparwidth}{3pt} + \GetFileInfo{aeb_mlink.sty} + \title{The \textsf{aeb\_mlink} Package\texorpdfstring{\\}{: } + A member of the AeB Pro family} + \author{D. P. Story\\ + Email: \texttt{dpstory@uakron.edu}} + \date{processed \today} + \maketitle + \tableofcontents + \DocInput{aeb_mlink.dtx} +\IfFileExists{\jobname.ind}{\newpage\setupFullwidth\par\PrintIndex} + {\paragraph*{Index} The index goes here. Execute + \[\texttt{makeindex -s gind.ist -o aeb\_mlink.ind aeb\_mlink.idx}\] on the command line and recompile + \texttt{web.dtx}.} +\IfFileExists{\jobname.gls}{\PrintChanges} + {\paragraph*{Change History} The list of changes goes here. Execute + \[\texttt{makeindex -s gglo.ist -o aeb\_mlink.gls aeb\_mlink.glo}\] on the command line and recompile + \texttt{aeb\_mlink.dtx}.} +\end{document} +%</driver> +% \fi +% \MakeShortVerb{|} +% \InputIfFileExists{aebdonotindex.def}{\PackageInfo{web}{Inputting aebdonotindex.def}} +% {\PackageInfo{aeb_mlink}{cannot find aebdonotindex.def}} +% +% \section{Introduction} +% This package creates \underbar{m}ultiline-\underbar{links}. +% The package \textsf{hyperref} does create links, but generally +% these links cannot be broken across lines, unless \textsf{pdflatex} +% is used to create a PDF. +% +% This package uses the \texttt{QuadPoints} entry in the link annotation to create +% a bounding region; consequently, this package requires \textbf{Acrobat Distiller} +% to create a PDF. \texttt{QuadPoints} is a PDF 1.6 feature, so these multiline links +% will work in Adobe Reader 7.0 or later. If viewed in a version of Adobe Reader previous +% to 7.0, the viewer will use the underlying bounding box. +% +% LaTeX package requirements are the \textsf{eForms} and \textsf{hyperref}. Only the use +% of \textsf{dvips} and \textsf{dvipsone} is supported. +% +%The key to creating a multi-line is contained in Table~8.24 of the +%PDF Reference. The description of \texttt{QuadPoints} in the PDF Reference +%is as follows: +% +%\begin{quote}\small +%(Optional; PDF 1.6) An array of $8 \times n$ numbers specifying the +%coordinates of $n$ quadrilaterals in default user space that comprise +%the region in which the link should be activated. The coordinates +%for each quadrilateral are given in the order +%$$ +% x_1\ y_1\ x_2\ y_2\ x_3\ y_3\ x_4\ y_4 +%$$ +%specifying the four vertices of the quadrilateral in +%counterclockwise order. For orientation purposes, such as when +%applying an underline border style, the bottom of a quadrilateral is +%the line formed by $(x_1 , y_1)$ and $(x_2 , y_2)$. If this entry is not +%present or the viewer application does not recognize it, the region +%specified by the \texttt{Rect} entry should be used. \texttt{QuadPoints} should be +%ignored if any coordinate in the array lies outside the region +%specified by \texttt{Rect}. +%\end{quote} +% \begin{macrocode} +% \end{macrocode} +% \section{The \texorpdfstring{\protect\pkg{aeb-mlink}}{aeb-mlink} Package} +% The \pkg{aeb\_mlink} package is listed on CTAN as \pkg{aeb-mlink}; there was, in +% fact, no \pkg{aeb-mlink}. Here, we provide a `dummy' package by that name which +% passes everything on to \pkg{aeb\_mlink}. +% \begin{macrocode} +% Begin Alt pkg +%<*altpkgname> +\NeedsTeXFormat{LaTeX2e} +\RequirePackage{xkeyval} +\ProvidesPackage{aeb-mlink} + [2018/04/26 v1.0 AeB MLink Alt-name (dps)] +\DeclareOptionX*{\PassOptionsToPackage{\CurrentOption}{aeb_mlink}} +\ProcessOptionsX +\RequirePackage{aeb_mlink}[2018/08/18] +%</altpkgname> +% \end{macrocode} +% \section{Package Requirements and Options} +% After having established the alternate of this package, we now work on the package itself. +% \changes{v2.3}{2018/04/26}{Added \string\pkg{aeb-mlink} as an alternate name for this package} +% \begin{macrocode} +% Begin Package +%<*package> +\RequirePackage{xkeyval} +\RequirePackage{ifpdf}[2006/02/20] +\RequirePackage{ifxetex}[2006/08/21] +\newif\if@ml@dvips \@ml@dvipstrue +\def\mlcsarg#1#2{\expandafter#1\csname#2\endcsname} +% \end{macrocode} +% \begin{macro}{dvipsone} +% Set the driver for \texttt{dvipsone} +% \begin{macrocode} +\DeclareOptionX{dvipsone}{\def\eq@drivernum{0}\@ml@dvipsfalse + \PassOptionsToPackage{dvipsone}{eforms} + \PassOptionsToPackage{dvipsone}{hyperref} +} +% \end{macrocode} +% \end{macro} +% \begin{macro}{dvips} +% Set the driver for \texttt{dvips} +% \begin{macrocode} +\DeclareOptionX{dvips}{\def\eq@drivernum{0}\@ml@dvipstrue + \PassOptionsToPackage{dvips}{eforms} + \PassOptionsToPackage{dvips}{hyperref} +} +\DeclareOptionX*{\PassOptionsToPackage{\CurrentOption}{eforms}} +% \end{macrocode} +% \end{macro} +% \begin{macrocode} +\@ifundefined{mldblevel}{\newcount\mldblevel + \mldblevel=0 }{} +\define@key{aeb_mlink.sty}{dblevel}[0]{\mldblevel=#1 } +% \end{macrocode} +% \begin{macrocode} +\def\ml@err@msg{This package requires the driver dvips and\MessageBreak + Adobe Distiller as the PDF creator} +\ifpdf\PackageError{aeb_mlink}{\ml@err@msg}\else + \ifxetex\PackageError{aeb_mlink}{\ml@err@msg}\else + \let\ExecuteOptions@SAVE\ExecuteOptions + \let\ExecuteOptions\ExecuteOptionsX + \InputIfFileExists{web.cfg}{} + {\@ifundefined{l@tex@@@@driver}{\ExecuteOptionsX{dvips}} + {\ExecuteOptionsX{dvipsone}}}% + \let\ExecuteOptions\ExecuteOptions@SAVE +\fi\fi +\ProcessOptionsX +% \end{macrocode} +% We require hyperref, eforms and soul. For eforms, a recent version is needed, +% \texttt{2008/03/14} or later. +% \begin{macrocode} +\RequirePackage{hyperref} +\RequirePackage{refcount} +% \end{macrocode} +% Beginning with the version of \pkg{eforms} dated 2018/03/22 or later, there are several +% link options that are defined. These are \cs{mlfix}, \cs{mlstrut}, \cs{mlcrackat} and +% \cs{mlhyph}. +% \begin{macrocode} +\RequirePackage{eforms}[2018/08/16] +\RequirePackage{soul} +% \end{macrocode} +% +% \section{Driver Dependent Code} +% +% Driver dependent definitions for dvipsone and dvips. +% \begin{macrocode} +\def\ps@mark{[\space} +\ifnum\mldblevel>0 + \def\mlpgMsg{(\string\n Beginning of page: ) pf + PhysicalPage 20 string cvs + pf(\string\n)pf}\else + \def\mlpgMsg{}\fi +\def\pgmonitoring{\if@ml@dvips + dup /PhysicalPage exch 1 add def + /PhysicalPage PhysicalPage def^^J\fi + \mlpgMsg +} +% \end{macrocode} +% Redefining \cs{mllnkcontainer}, defined in \pkg{eforms} +% dated 2018/03/14 or later. If \cs{ifoldstylequads} is true, +% we do not set \texttt{/Rect} to the minimal rectangle, rather +% it is set to the region defining the whole page. This was +% the default rectangle in the past. +% \begin{macrocode} +\def\smallRectTF{\ifoldstylequads false\else + \iffixmlinks true\else false\fi\fi\space + \ifSmallRect true\else false\fi\space and} +\def\ml@@nnotName{mLink} % dps +\def\mllnkcontainer#1{bCreateLink { xoMsgB { + \smallRectTF\space mlRectFix^^J% + #1}if}{(\ml@@nnotName\the\aeb@mLinkCnt) mlIsBldMsg}ifelse} +% \end{macrocode} +% \cs{pboxRect} is defined in \pkg{eforms} +% \begin{macrocode} +\def\pboxRect{mlRect } +\if@ml@dvips +% \end{macrocode} +% \textsf{\textbf{dvips} driver:} Code for the \textsf{dvips} driver +% This next \cs{special} defines some standard conversion +% formulas, {\TeX} to PDF and PDF to {\TeX} for \textsf{dvips}. +% \begin{macrocode} + \def\mlDict{SDict} + \special{!userdict begin + /TeXtoPDF {65536 div DVImag mul} def % sp to pts + /PDFtoDvips {72.27 div Resolution mul} def % points to dots + /PDFtoVDvips {72.27 div VResolution mul} def % points to dots + /DvipstoPDF {72.27 mul Resolution div} def % dots to points + /HTeXtoDvips {TeXtoPDF PDFtoDvips} def % sp to dots + /VTeXtoDvips {TeXtoPDF PDFtoVDvips} def^^J% % sp to dots + /PhysicalPage 0 def^^J% + /PageHeight {vsize} def^^J% + /PDFtoTeX {PDFtoDvips} def^^J% + /pf{print flush}def^^J% + /bop-hook{ \pgmonitoring\space } def + end} +% \end{macrocode} +% This command calculates the \cs{QuadPoints} array +% when we are using the \textsf{dvips} driver. +% \begin{macrocode} + \def\setQuadBox{% + currentpoint DvipstoPDF \aeb@bbox@dp\space TeXtoPDF add + neg vsize add 72 sub % y1 + exch DvipstoPDF 72 add exch % x1 + 2 copy exch \aeb@bbox@wd\space TeXtoPDF add exch % x2 + 2 copy \aeb@bbox@ht\space TeXtoPDF add % y3 + 2 copy exch \aeb@bbox@wd\space TeXtoPDF sub exch % x4 + } +% \end{macrocode} +% For the bounding rectangle, we just enclose the entire page. This +% simplifies things greatly. +% \begin{macrocode} + \def\par@@Rect + {% + 72 neg PDFtoDvips vsize 72 sub PDFtoVDvips + hsize 72 sub PDFtoDvips 72 neg PDFtoVDvips + } +% \end{macrocode} +% \textsf{\textbf{dvipsone} driver:} Code for the \textsf{dvipsone} driver +% This next \cs{special} defines some standard conversion +% formulas, {\TeX} to PDF and PDF to {\TeX} in the \textsf{YandY {\TeX} System}. +% \begin{macrocode} +\else + \def\mlDict{dvidict} + \special{!/TeXtoPDF {65536 div mag 1000 div mul} def + /PDFtoTeX {65536 mul mag 1000 div div} def^^J% + /pf{print flush}def^^J% + /bphook{ \pgmonitoring\space } def^^J% + } +% \end{macrocode} +% This command calculates the \cs{QuadPoints} array +% when we are using the \textsf{dvipsone} driver. +% \begin{macrocode} + \def\setQuadBox{% + currentpoint \aeb@bbox@dp\space add TeXtoPDF + neg PageHeight add 72 sub % y1 + exch TeXtoPDF 72 add exch % x1 + 2 copy exch \aeb@bbox@wd\space TeXtoPDF add exch % x2 + 2 copy \aeb@bbox@ht\space TeXtoPDF add % y3 + 2 copy exch \aeb@bbox@wd\space TeXtoPDF sub exch % x4 + } +% \end{macrocode} +% For the bounding rectangle, we just enclose the entire page. This +% simplifies things greatly. +% \begin{macrocode} + \def\par@@Rect + {% + 72 neg PDFtoTeX PageHeight 72 sub PDFtoTeX + PageWidth 72 sub PDFtoTeX 72 neg PDFtoTeX + } +\fi +% \end{macrocode} +% +% \section{The Multi-line Linking Commands} +% +% We use a box, and two counters for this package. +% \begin{macrocode} +\newbox\aeb@bbox +\newcount\aeb@arrayIndx \aeb@arrayIndx=0 +\newcount\aeb@mLinkCnt \aeb@mLinkCnt=0 +\newcount\syllableCnt \syllableCnt=0 +\newif\ifmllinktotalchanged\mllinktotalchangedfalse +% \end{macrocode} +% When \cs{ifSmallRect} is true (the default), the smallest possible \texttt{Rect} +% is constructed to enclose the text; obeyed only when \cs{iffixmlinks} (defined in \pkg{eforms} +% is true. +% \begin{macrocode} +\newif\ifSmallRect \SmallRecttrue +\AtEndDocument{\wrtmlinktot@l\ckchngmlinktot@l\wrt@linksnotformed} +\def\wrt@linksnotformed{\iflinknotformed + \PackageWarningNoLine{aeb_mlink}{Some link calculations are not + complete.\MessageBreak + DO NOT CONVERT TO PDF at this time. Compile at \MessageBreak + least twice more}\fi} +\def\wrtmlinktot@l{\immediate\write\@auxout{\string\gdef + \string\mlinkstotal{\the\aeb@mLinkCnt}}} +\def\ckchngmlinktot@l{\@ifundefined{mlinkstotal}{} + {\ml@mlinktot@l@changed}} +\def\ml@mlinktot@l@changed{% + \ifnum\mlinkstotal=\the\aeb@mLinkCnt\relax\else + \PackageWarningNoLine{aeb_mlink}{The number of links has + changed. Compile again\MessageBreak until this message + does not appear}\immediate + \write\@auxout{\string\mllinktotalchangedtrue}\fi +} +\def\ml@mllinktotalchanged{\ifmllinktotalchanged + \PackageWarningNoLine{aeb_mlink} + {The number of links has changed, continue\MessageBreak + to compile}\fi} +\AtBeginDocument{\ml@mllinktotalchanged} +\def\CurrentBorderColor{\@linkbordercolor} +\def\ml@nocolorHighlight{I} +\def\ml@nocolorLineStyle{S} +\def\ml@nocolorLineWidth{1} +\def\ml@setnocolorDefaults{% +\def\ml@nocolor@defaults{\H{\ml@nocolorHighlight}% + \S{\ml@nocolorLineStyle}\W{\ml@nocolorLineWidth}% + \Color{\CurrentBorderColor}}% +} +\ifHy@colorlinks + \let\ml@nocolor@defaults\@empty +\else + \ml@setnocolorDefaults +\fi +\def\ml@earlyExecProps#1{% + \eq@setWidgetProps\relax{#1}% +} +% \end{macrocode} +% The new scheme of fixing up the quad points write information +% to the AUX file, which then requires multiple compilations to bring +% that information up to date in the document. When working on document +% development, you can declare \cs{OldStyleBoxesOn} in the preamble to revert +% to the old style boxes that do not require AUX info. +%\changes{v2.1.3}{2018/03/10}{Reinstate old style link} +% \begin{macrocode} +\newif\ifoldstylequads \oldstylequadsfalse +\def\OldStyleBoxesOn{\mlfixOff\oldstylequadstrue} +\def\OldStyleBoxesOff{\oldstylequadsfalse} +\@onlypreamble\OldStyleBoxesOn +\@onlypreamble\OldStyleBoxesOff +\let\mlh@preambleCmdInsert\relax +\def\mlcs#1{\texttt{\@backslashchar#1}} +\bgroup\@makeother\% +\gdef\CMT#1{ %\space #1}\egroup +\def\mldbModeOn{\def\mldb##1##2{##2}} +\def\mldbModeOff{\def\mldb##1##2{}} +\def\mldb#1#2{\ifnum#1<\mldblevel#2\fi} +\def\ml@adj@x{2}\def\ml@adj@y{2} +\def\mlMaxNSylls{30} +% usage \mlcrackinsat{\removelastspace} +\def\removelastspace{\hskip-\fontdimen2\font} +\AtBeginDvi{\special{!% +% \end{macrocode} +% \paragraph*{Begin Postscript code} This code is executed as the PDF is created +% by either \app{Adobe Distiller} (preferred) or \app{ps2pdf}. Information is +% written to the \app{distiller} (\app{ps2pdf}) log.\medskip\par +% +% {\noindent}A switch to determine if the link should be created or now; it may not be +% fully formed. +% \begin{macrocode} +/bCreateLink true def +% \end{macrocode} +% The length of the arrays we deal with are multiples of eight (8), we use a value +% of 17 as a way of testing whether an array size has been updated. All arrays +% are set to 17 in length initially. +% \begin{macrocode} +/mlIsBld 17 def^^J% +/mlIsBldMsg {^^J% + /sName exch def^^J% + (\string\n!! )pf + sName 20 string cvs pf + ( is not completely formed, + compile again!!\string\n)pf^^J% +} def^^J% +/xoMsgB true def^^J% +/xoMsg {^^J% + /Indx exch def^^J% + /sName exch def^^J% + /nSyllable Indx 8 div def^^J% dpsa08 + (!!------------------------------------------------------------------% + \string\n Warning:\string\n + The text of )pf + sName 20 string cvs pf + ( has crossed a page boundary from page )pf + PhysicalPage 1 sub 10 string cvs pf + ( to ) pf PhysicalPage 10 string cvs pf + sName 0 1 getinterval (m) eq { + (.\string\n Cross page links are not supported by the + PDF Specification)pf + (.\string\n This link is not constructed, + please fix it.\string\n)pf + (Break point is after syllable number )pf + nSyllable cvi 20 string cvs pf (.\string\n)pf + (Use the \string\\mlcrackat{)pf + nSyllable cvi 20 string cvs pf + (} option with this link.\string\n)pf + }{ + (.\string\n Cross page annotations are not supported by the + PDF Specification)pf + (.\string\n This annotation is not constructed, + please fix it.\string\n)pf + (Break point is after syllable number )pf + nSyllable cvi 20 string cvs pf (.\string\n)pf + (Use the mlcrackat=)pf + nSyllable cvi 20 string cvs pf + ( option with this annotation.\string\n)pf + } ifelse + (!!------------------------------------------------------------------% + \string\n)pf^^J% +} def^^J% +% \end{macrocode} +% quadpointsfixup is the major procedure for combining all `rectangles' that are on +% the same line. +% \begin{macrocode} +/quadpointsfixup {^^J% + /ary exch def^^J% + /quadL exch def^^J% + /sName exch def^^J% +\mldb0{(Processing )pf sName pf (: OK\string\n)pf^^J}% +%\mldb0{lnkCnt 20 string cvs pf (: OK\string\n) pf^^J}% +quadL 0 eq { +(Problems with this link, length=0, + will skip the creation of this link)pf^^J% +}{ +% \end{macrocode} +% Begin by defining some variables needed for this operation. +% \begin{macrocode} +/gOffset 0 def^^J% +% \end{macrocode} +% \texttt{gY} holds the y-coordinate of the lower-left corner of the first entry +% of a quad. We use it and others like it to determine at which syllable the line +% is broken. +% \begin{macrocode} +/gY ary\space 1 gOffset add get def^^J% +\mldb1{(gY is ) pf gY 20 string cvs print^^J}% +\mldb1{flush (\string\n) pf^^J}% +/gN 0 def^^J% +% \end{macrocode} +% \texttt{gMrk} is an array that will load the offsets into \texttt{mLinkFxup\ameta{num}}. Each +% offset is the beginning of a line. We initially set the length of the array to 10, though +% this may not be correct. That is, we assume the hypertext will not exceed 10 lines in length. +% \begin{macrocode} +/gMrk 10 array def^^J% limitation +% \end{macrocode} +% The first entry is always 0, because marks the location of the quad corresponding to the +% beginning of the first syllable. +% \begin{macrocode} +gMrk 0 0 put^^J% +% \end{macrocode} +% \texttt{gMrkL} is the length of the array, we set it to 1, as we've already inserted +% the first entry into \texttt{gMrkL}. +% \begin{macrocode} +/gMrkL 1 gOffset add def^^J% +\mldb2{(Begin first for\string\n) pf^^J}% +% \end{macrocode} +% Begin a for loop\marginpar{\raggedleft for loop}. The purpose of this loop is to search +% through the quad points of \texttt{mLinkFxup\ameta{num}} and find the offsets into the +% structure where the line breaks occur. +% \begin{macrocode} +0 8 quadL 8 sub {^^J% +% \end{macrocode} +% \texttt{gIndx} is the loop counter, which we use below. Since we are dealing +% with quads, we increment by 8 each time. +% \begin{macrocode} + /gIndx exch def^^J% +\mldb2{(Outside gt if with gIndx=) pf^^J}% +\mldb2{gIndx 20 string cvs pf^^J}% +\mldb2{(\string\n) pf^^J}% +% \end{macrocode} +% \texttt{getEntry} is the y-coordinate of the lower-left corner of the +% quad we are currently examining. We will compare its value to that +% of \cs{gY}. +% \begin{macrocode} + /getEntry ary\space 1 gOffset add get def^^J% +\mldb2{(getEntry=) pf getEntry 20 string cvs pf^^J}% +\mldb2{(\string\n) pf^^J}% +% \end{macrocode} +% Here's where we compare \texttt{gY} with \texttt{getEntry}. If they differ +% by more than 2 points then the line has changed. (We do it this way since these +% are decimal numbers and they may have been rounded in unpredictable ways.\marginpar{\raggedleft if comparison} +% \begin{macrocode} + gY getEntry sub abs 2 gt {^^J% +\mldb2{(Inside gt if\string\n) pf^^J}% +% \end{macrocode} +% The two entries differ, so a line break must have occurred. We inert value +% of \texttt{gIndx} into \texttt{gMrk}. \texttt{gIndx} is essentially the offset +% into \texttt{mLinkFxup\ameta{num}} where the line break occurs. +% \begin{macrocode} + gMrk gMrkL gIndx put^^J% +% \end{macrocode} +% Increment \texttt{gMrkL} accordingly. +% \begin{macrocode} + /gMrkL gMrkL 1 add def^^J% +% \end{macrocode} +% Place the new y-value in \texttt{gY} before we look back +% and look for another line break. +% \begin{macrocode} + /gY getEntry def^^J% +\mldb2{(Updating gY to )pf gY 20 string cvs pf^^J}% +\mldb2{(\string\n) pf^^J}% +\mldb2{(gMrkL=)pf gMrkL 20 string cvs pf^^J}% +\mldb2{(\string\n) pf^^J}% +% \end{macrocode} +% End of the if\marginpar{\raggedleft end if} +% \begin{macrocode} + } if^^J% + /gOffset gOffset 8 add def^^J% +% \end{macrocode} +% End of the for loop\marginpar{\raggedleft end for} +% \begin{macrocode} +} for^^J% +\mldb2{(end first for\string\n) pf^^J}% +% \end{macrocode} +% We finished searching for line breaks and are now going to work on combining +% contiguous quads. Contiguous quads are the ones between the offsets recorded +% in the \texttt{gMrk} array. Now, if there are now line breaks, the length +% of \texttt{gMrk} is one +% +% \texttt{gAry} is a temporary array that holds all the quads \emph{corresponding to +% one line}. Each syllable generates an quad of length 8. Here, we assume any given +% line has at most \cs{mlMaxNSylls} syllables, (currently set to \mlMaxNSylls, but may be revised). The array \texttt{gAry} is declared +% inside the next loop, so it is redeclared at each iteration of the loop. If \app{Distiller} of \app{ps2pdf} +% fails, it may be due to \cs{mlMaxNSylls} being too small for some of your sentences; in this case, redefine +% \cs{mlMaxNSylls} to a larger value. +% \changes{v2.3.2}{2018/08/09}{\string\cs{mlMaxNSylls} now sets the array size of gAryL} +% \begin{macrocode} + /gAryL 8 \mlMaxNSylls\space mul def^^J% limitation +\mldb2{(gAryL=) pf gAryL 20 string cvs pf^^J}% +\mldb2{(\string\n)pf^^J}% +% \end{macrocode} +% \texttt{gFixup} is an array that will hold the final combined quad points, this array +% is the one that will be referenced by the \texttt{QuadPoints} entry of the link annotation. +% It's length is set to 8 times the number of lines over which the hypertext is broken (\texttt{gMrkL}) +% One quad for each line, rather than many quads, one for each syllable. +% \begin{macrocode} + /gFixup 8 gMrkL mul array def^^J% links + /aFixup 8 gMrkL mul array def^^J% text markup annotations + /gOffset 0 def^^J% +\mldb2{(for loop: gMrkL=)pf gMrkL 20 string cvs pf^^J}% +\mldb2{(\string\n) pf^^J}% +% \end{macrocode} +% The last loop. In this loop, for each line of hypertext, +% we build its contiguous quad and load it into \texttt{gFixup}.\marginpar{\raggedleft begin for} +% \begin{macrocode} +0 1 gMrkL 1 sub {^^J% +\mldb2{(After gAry\string\n) pf^^J}% +\mldb2{(Top of for loop\string\n) pf^^J}% + /gIndx exch def^^J% +\mldb2{(gIndx=)pf gIndx 20 string cvs pf^^J}% +\mldb2{(\string\n)pf^^J}% +\mldb2{(gMrk=)pf gMrk gIndx get 20 string cvs pf^^J}% +\mldb2{(\string\n) pf^^J}% +\mldb2{(mLinkFxup<num> length = )^^J}% +\mldb2{pf ary\space length 20 string cvs^^J}% +\mldb2{pf (\string\n) pf^^J}% +% \end{macrocode} +% We need to determine if we are examining the quads for the last line, or not. +% The calculation of \texttt{gCount} is dependent on this. +% \begin{macrocode} +gIndx 1 add gMrkL eq {^^J% + /gCount ary\space length gMrk gIndx get sub def^^J% +}{^^J% + /gCount gMrk gIndx 1 add get gMrk gIndx get sub def^^J% +} ifelse^^J% +% \end{macrocode} +% Declare the \texttt{gAry} array +% \begin{macrocode} +/gAry gAryL array def^^J% +\mldb2{(gCount=)pf gCount 20 string cvs pf^^J}% +\mldb2{(\string\n)pf^^J}% +% \end{macrocode} +% We want to copy a slice of \texttt{mLinkFxup\ameta{num}}, we declare the next +% array of length \texttt{gCount} just computed. +% \begin{macrocode} +/sliceOfLinkfxup gCount array def^^J% +% \end{macrocode} +% Populate this array with a slice of \texttt{mLinkFxup\ameta{num}} beginning at +% \texttt{gMrk[gIndx]} and including the subsequent \texttt{gCount} entries. +% array of length \texttt{gCount} just computed. +% \begin{macrocode} +sliceOfLinkfxup 0 ary gMrk gIndx get^^J% + gCount getinterval putinterval^^J% + gAry 0 sliceOfLinkfxup putinterval^^J% +\mldb1{(Listing elements of gFixup\string\n) pf^^J}% +\mldb1{gAry 0 get 20 string cvs pf (\string\n)pf^^J}% +\mldb1{gAry 1 get 20 string cvs pf (\string\n)pf^^J}% +\mldb1{gAry gCount 1 sub 5 sub get + 20 string cvs pf (\string\n)pf^^J}% +\mldb1{gAry gCount 1 sub 4 sub get + 20 string cvs pf (\string\n)pf^^J}% +\mldb1{gAry gCount 1 sub 3 sub get + 20 string cvs pf (\string\n)pf^^J}% +\mldb1{gAry gCount 1 sub 2 sub get + 20 string cvs pf (\string\n)pf^^J}% +\mldb1{gAry 6 get 20 string cvs pf (\string\n)pf^^J}% +\mldb1{gAry 7 get 20 string cvs pf (\string\n)pf^^J}% + gFixup gOffset [^^J% + gAry 0 get ^^J% x1 ll 1 + gAry 1 get^^J% y1 ll 1 + gAry gCount 1 sub 5 sub get^^J% x2 lr 2 + gAry gCount 1 sub 4 sub get^^J% y2 lr 2 + gAry gCount 1 sub 3 sub get^^J% x3 ur 3 + gAry gCount 1 sub 2 sub get^^J% y3 ur 3 + gAry 6 get^^J% x4 ul 4 + gAry 7 get^^J% y4 ul 4 + ] putinterval^^J% +% \end{macrocode} +% When forming quad points for text markup annotations, the PDF reference is not followed. We have +% to reorder the array \texttt{gFixup} to conform to how Acrobat/Reader expect it. Entries 0 and 4 +% are increased by the same amount that was subtracted out earlier in +% \changes{v2.3.2}{2018/08/09}{Form the array \string\texttt{aFixup} for \string\pkg{aeb\_mlink}} +% \begin{macrocode} + aFixup gOffset [^^J% + gAry 6 get gOffset 0 eq {\ml@adj@x\space add}if^^J% x4 ul 4 + gAry 7 get^^J% y4 ul 4 + gAry gCount 1 sub 3 sub get^^J% x3 ur 3 + gAry gCount 1 sub 2 sub get^^J% y3 ur 3 + gAry 0 get gOffset 0 eq {\ml@adj@x\space add}if^^J% x1 ll 1 + gAry 1 get 1 sub^^J% y1 ll 1 + gAry gCount 1 sub 5 sub get^^J% x2 lr 2 + gAry gCount 1 sub 4 sub get 1 sub^^J% y2 lr 2 + ] putinterval^^J% + /gOffset gOffset 8 add def^^J% + } for^^J% +\mldb2{(End of second for\string\n) pf^^J}% + } ifelse +} def^^J% +% \end{macrocode} +% \texttt{smallquadpointsfixup} fixes up the bounding boxes. Raises their heights +% by \cs{ml@adj@y} (removed), and moves the left boundary \cs{ml@adj@x} to the left. +% \changes{v2.1.2}{2018/03/09}{Added PS proc \string\texttt{smallquadpointsfixup}} +% \begin{macrocode} +/smallquadpointsfixup {^^J% +/gIndx exch def^^J% +/ary exch def^^J% +/lnkCnt exch def^^J% +/quadL exch def^^J% +/gSFup 8 array def^^J% + gSFup 0 ary 0 gIndx add get + gIndx 0 eq {\ml@adj@x\space sub} if put^^J% x1 + gSFup 1 ary 1 gIndx add get put^^J% y1 + gSFup 2 ary 2 gIndx add get put^^J% x2 + gSFup 3 ary 3 gIndx add get put^^J% y2 + gSFup 4 ary 4 gIndx add get put^^J% x3 + gSFup 5 ary 5 gIndx add get put^^J% + gSFup 6 ary 6 gIndx add get + gIndx 0 eq {\ml@adj@x\space sub} if put^^J% x4 + gSFup 7 ary 7 gIndx add get put^^J% + ary gIndx gSFup putinterval^^J% +} def^^J% +% \end{macrocode} +% The \texttt{mlRectFix} procedure creates the minimum sized rectangle +% that encloses the text, and we use this as the dimensions of \texttt{/Rect} +% \changes{v2.1.10}{2018/03/25}{Set \string\texttt{/Rect} to minimal rectangle containing text} +% \begin{macrocode} +/mlRectFix {^^J% +/ifRectFix exch def^^J% +ifRectFix { + /nL gFixup length 8 sub def^^J% number of lines + /xMin gFixup 0 get def^^J% + 0 8 nL {^^J% + /Indx exch def^^J% + gFixup Indx get xMin lt {/xMin gFixup Indx get def}if } for^^J% + /xMin xMin 2 sub def^^J% + /xMax gFixup 2 get def^^J% + 2 8 nL 2 add {^^J% + /Indx exch def^^J% + gFixup Indx get xMax gt {/xMax gFixup Indx get def}if } for^^J% + /xMax xMax 2 add def^^J% + /yMin gFixup 1 get def^^J% + 1 8 nL 1 add {^^J% + /Indx exch def^^J% + gFixup Indx get yMin lt {/yMin gFixup Indx get def}if } for^^J% + /yMin yMin 4 sub def^^J% + /yMax gFixup 5 get def^^J% + 5 8 nL 5 add{^^J% + /Indx exch def^^J% + gFixup Indx get yMax gt {/yMax gFixup Indx get def}if } for^^J% + /yMax yMax 2 add def^^J% + /mlRect {/Rect [^^J% + xMin 72 sub PDFtoTeX^^J% + PageHeight 72 sub yMax sub PDFtoTeX^^J% + xMax 72 sub PDFtoTeX^^J% + PageHeight yMin sub 72 sub PDFtoTeX ]^^J% + }def^^J% +}{^^J% + /mlRect{/Rect [ \par@@Rect ] }def^^J% +}ifelse^^J% +ifRectFix { +\mldb1{(/Rect [)pf^^J% +xMin 20 string cvs pf( )pf^^J% +yMax 20 string cvs pf( )pf^^J% +xMax 20 string cvs pf( )pf^^J% +yMin 20 string cvs pf(]\string\n)pf^^J}% +} if^^J% +} def +}} +% \end{macrocode} +% \leavevmode\DescribeMacro{\mlMarksOn} +% Added tracking marks. Turn them on with \cs{mlMarksOn} and off again +% with \DescribeMacro{\mlMarksOff}\cs{mlMarksOff}. +% \changes{v2.1.8}{2018/03/19}{Added tracking marks} +% \begin{macrocode} +\newif\ifmlmarks\mlmarksfalse +\def\mlMarksOn{\mlmarkstrue} +\def\mlMarksOff{\mlmarksfalse} +% \end{macrocode} +% \leavevmode\DescribeMacro{\ml@MrkLnk}\hskip-\marginparsep\darg{\ameta{num}} +% The internal command \cs{ml@MrkLnk} typesets the tracking mark; it may be redefined. +% When the link is within a \env{tabular} environment (and perhaps others), in this case, +% \cs{baselineskip=0pt}. We raise instead the height of the capital letter `T', +% plus a little. +% \changes{v2.1.9}{2018/03/22}{Changed the definition of \cs{ml@MrkLnk}} +% \begin{macrocode} +\def\MrkLnkLtr{L} +\def\ml@MrkLnk#1{\ifmlmarks\bgroup\ifdim\baselineskip=0pt + \setbox\z@\hbox{T}\gdef\ml@raiseamt{\ht\z@+.4pt}\else + \gdef\ml@raiseamt{.6\baselineskip}\fi\smash{\rlap{\normalfont\normalcolor\bfseries + \raisebox{\ml@raiseamt}{\tiny\strut{\MrkLnkLtr#1}}}}\egroup\fi} +\newif\iflinknotformed \linknotformedfalse +\newif\ifcr@ckit \cr@ckitfalse +\def\ml@underlinded{U} +% \end{macrocode} +% \begin{macro}{\mlhypertext} +% \leavevmode\hskip-\marginparsep\texttt{[\ameta{opts}]\darg{\ameta{text}}} +% This is a general purpose hypertext link. Not only is it +% a fine stand-alone linking command, but it also serves +% as a building block to some convenience commends that follow. +% +% The commands takes two arguments, the first an optional one the second +% one requires. +% \begin{enumerate} +% \item[\texttt{\ameta{opts}}] (Optional) A standard optional argument for \pkg{eforms} to change +% the appearance of the link and/or to include actions. +% \item[\texttt{\ameta{text}}] The text to be enclosed by the link. +% \end{enumerate} +% The most recently, \pkg{eforms} defines \cs{mlhypertext} to a warning +% message. So if \cs{mlhypertext} is already defined, we \cs{renewcommand} +% else we \cs{newcommand}. +% \changes{v2.1.17}{2018/04/19}{added conditional command definition for \string\cs{mlhypertext}} +% \changes{v2.3.1}{2018/07/18}{added \string\cs{hglue0pt} to add some hard glue just before +% the beginning of \string\cs{mlhypertext}} +% \begin{macrocode} +\@ifundefined{mlhypertext}{\newcommand}{\renewcommand}% +{\mlhypertext}[2][]{\hglue0pt\begingroup + \global\ml@displaytrue + \toks@=\expandafter{#2}% + \edef\ml@HytextArg{{\the\toks@}}% + \global\aeb@arrayIndx=\z@ + \def\ml@setlink##1{\setLinkPbox{% + \QuadPoints{mLink##1}#1}}% + \expandafter\processAppArgs\set@LinkPboxDefaults + \presets{\ml@nocolor@defaults}\S{S}\W{0}#1\end\@nil + \ifx\eq@S@value\ml@underlinded + \let\itsunderline\ef@YES\else\let\itsunderline\ef@NO\fi +% \end{macrocode} +% Now we test whether \cs{eq@mlcrackat} is empty or not. If not-empty +% we break this link to two parts. +% \begin{macrocode} + \ifx\eq@mlignore\ef@YES + \global\advance\aeb@mLinkCnt\@ne\relax + \def\ml@next{\mlhypertext@i{#1}}\else + \ifx\eq@mlcrackat\@empty +% \end{macrocode} +% A `normal' link, continue +% \begin{macrocode} + \global\advance\aeb@mLinkCnt\@ne\relax + \def\ml@next{\mlhypertext@i{#1}}% + \else % \eq@mlcrackat not \@empty +% \end{macrocode} +% \textbf{Crack it up.} We define \cs{ml@next} to call \cs{mlhypertext} consecutively; +% the first time we specify |\mlignore{0}| to indicate this link +% is the first part, and then |mlignore{1}| to indicate the second part. +% For the first part, we proceed as usual until we get the the syllable +% number specified by \cs{mlcrackAt}, then we continue with the next +% \cs{mlhypertext} command, we remove all content up to the syllable number +% \cs{mlcrackAt}, and typeset the rest; for example, +%\begin{quote} +%This is a test sentence that \textcolor{gray}{we want to break across pages.} (1)\\ +%\textcolor{gray}{This is a test sentence that} we want to break across pages. (2) +%\end{quote} +%The first link produces the typeset material in (1), where grayed-out text are removed; while +%the second link produces line (2), again, with the grayed-out material removed. +% \begin{macrocode} + \def\ml@next{\global\ml@displaytrue\let\ml@space\space + \mlhypertext[#1\mlignore{0}]{#2}\eq@mlcrackinsat + \penalty-100 \cr@ckittrue + \global\ml@displayfalse\let\ml@space\space + \mlhypertext[#1\mlignore{1}]{#2}\aftergroup + \normalcolor\endgroup}% + \fi + \fi + \ml@next +} +\def\mlhypertext@i#1{% + \@ifundefined{mLinkLngth\the\aeb@mLinkCnt}{\global + \linknotformedtrue\def\ml@lngth{17}} + {\edef\ml@lngth{\@nameuse{mLinkLngth\the\aeb@mLinkCnt}}}% + \ml@start@link{\the\aeb@mLinkCnt}{\ml@lngth}% Step 1 + \def\mlh@preambleCmdInsert{% + \ml@MrkLnk{\the\aeb@mLinkCnt}\ml@earlyExecProps{#1}}% + \def\mlh@postambleCmd{\endgroup}% +% \end{macrocode} +% Start \pkg{soul} on \cs{mlhypertext} (\cs{aeb@mlh}) +% \begin{macrocode} + \expandafter\aeb@mlh\ml@HytextArg + \ml@finish@link{\the\aeb@mLinkCnt}{\ml@lngth}% + \ml@setlink{\the\aeb@mLinkCnt}% + \ifoldstylequads\else + \iffixmlinks\literalps@out{restore}\fi\fi + \@ifundefined{mLinkLngth\the\aeb@mLinkCnt}{% + \immediate\write\@auxout{\string\mlcsarg + \string\gdef{mLinkLngth\the\aeb@mLinkCnt}{17}}% + }{\immediate\write\@auxout{\string\mlcsarg + \string\gdef{mLinkLngth\the\aeb@mLinkCnt}% + {\the\aeb@arrayIndx}}}\endgroup +} +\def\mlh@setQuadSyllable#1#2#3#4{% +% #1 = current array Index +% #2 = quad total +% #3 = link cnt +% #4 = content + \setbox\aeb@bbox=\hbox{\ml@strut#4}% + {% + \setbox\@tempboxa\hbox{\ml@strut}% + \ifx\itsunderline\ef@YES\@tempdima1bp\relax\else + \@tempdima\dp\@tempboxa \ifdim\@tempdima>2bp + \advance\@tempdima-2bp\fi + \fi + \ifx\isstrikeout\ef@YES\advance\@tempdima-2bp\fi + \dp\aeb@bbox\@tempdima + \@tempdima\ht\@tempboxa \advance\@tempdima\dp\aeb@bbox + \advance\@tempdima1bp + \ht\aeb@bbox\@tempdima\def\x{\the\count\z@}% + \count\z@=\ht\aeb@bbox\xdef\aeb@bbox@ht{\x}% + \count\z@=\wd\aeb@bbox\xdef\aeb@bbox@wd{\x}% + \count\z@=\dp\aeb@bbox\xdef\aeb@bbox@dp{\x}% + }% + \ifoldstylequads + \literalps@out{% + bCreateLink {^^J% + \mlDict\space/mLinkFxup#3\space known {^^J% + \ps@mark{mLink#3} + \the\aeb@arrayIndx\space [\setQuadBox] + \space /PUTINTERVAL pdfmark}{^^J% + xoMsgB { + /xoMsgB false def + (\ml@@nnotName\the\aeb@arrayIndx) + #3\space + xoMsg % dpsa08 + } if^^J% xoMsgB + } ifelse } if + }% + \else + \literalps@out{% + bCreateLink {^^J% + \mlDict\space/mLinkFxup#3\space known {^^J% + mLinkFxup#3\space + #1\space[\setQuadBox] putinterval^^J% +% \end{macrocode} +% Initiate fix up of little rectangles +% \begin{macrocode} + #2\space % + #3\space + mLinkFxup#3\space + #1\space + smallquadpointsfixup }{^^J% + xoMsgB { + /xoMsgB false def + (\ml@@nnotName#3) + #1\space + xoMsg % dpsa08 + } if^^J% xoMsgB + } ifelse } if + }% + \fi + \global\advance\aeb@arrayIndx8\relax +} +% \end{macrocode} +% \end{macro} +% The next four commands are used internally, though \cs{aebnameref}, +% \cs{labelRef} and \cs{atPage} are public, and can be used. +% \begin{macrocode} +\def\aeb@exiii{\expandafter\expandafter\expandafter} +\def\aebnameref#1{\@ifundefined{r@#1}{??} + {\aeb@exiii\@thirdoffive\csname r@#1\endcsname}} +\def\labelRef#1{\@ifundefined{r@#1}{Doc-Start} + {\aeb@exiii\@fourthoffive\csname r@#1\endcsname}} +\def\atPage#1{\getrefbykeydefault{#1}{page}{??}} +% \end{macrocode} +% \begin{macro}{\mlhyperlink} +% \begin{macro}{\mlhyperref} +% \begin{macro}{\mlnameref} +% \begin{macro}{\mlNameref} +% These four commands mimic the \pkg{hyperref} commands of the same root name. +% The commands \cs{mlhyperlink} and \cs{mlhyperref} take three +% parameters (the first one optional). The optional parameter +% modifies the appearance of the link, the second is the +% target/destination of the link, the third is the text the link is +% wrapped around. In the case of \cs{mlhyperlink} that target is a +% defined by \cs{hypertarget}; for \cs{mlhyperref} the target is a +% latex label. +% +% The commands \cs{mlnameref} and \cs{mlNameref} take two parameters +% (the first is optional). As before, the first modifies the +% appearance of the link, the second is the target, a latex label. +%\begin{flushleft} +% Syntax: \ttfamily\string\mlhyperlink[\ameta{opts}]\darg{\ameta{named-dest}}\darg{\ameta{text}} +%\end{flushleft} +% \begin{macrocode} +\newcommand\mlhyperlink[3][]{% + \mlhypertext[#1\A{/S/GoTo/D (#2)}]{#3}} +% \end{macrocode} +%\begin{flushleft} +% Syntax: \ttfamily\string\mlhyperref[\ameta{opts}]\darg{\ameta{label}}\darg{\ameta{text}} +%\end{flushleft} +% \begin{macrocode} +\newcommand\mlhyperref[3][]{% + \mlhypertext[#1\A{/S/GoTo/D (\labelRef{#2})}]{#3}} +% \end{macrocode} +%\begin{flushleft} +% Syntax: \ttfamily\string\mlnameref[\ameta{opts}]\darg{\ameta{label}} +%\end{flushleft} +% \begin{macrocode} +\newcommand\mlnameref[2][]{\protected@edef\ml@temp{\aebnameref{#2}}% + \def\ml@tempi{\mlhypertext[#1\A{/S/GoTo/D (\labelRef{#2})}]}% + \expandafter\ml@tempi\expandafter{\ml@temp}} +% \end{macrocode} +% We use a work around to a |\relax| problem encountered in the +% |\mlNameRef| command. {\LaTeX} inserts a |relax| at the end of label +% titles, which stops soul. We insert |\let\SOUL@stop\ml@SOUL@stop|, +% this seems to work, no guarantees. +%\begin{flushleft} +% Syntax: \ttfamily\string\mlNameref[\ameta{opts}]\darg{\ameta{label}} +%\end{flushleft} +% \begin{macrocode} +\newcommand\mlNameref[2][]{\let\SOUL@stop\ml@SOUL@stop + \protected@edef\ml@temp{`\aebnameref{#2}' on page~\atPage{#2}}% + \def\ml@tempi{\mlhypertext[#1\A{/S/GoTo/D (\labelRef{#2})}]}% + \expandafter\ml@tempi\expandafter{\ml@temp}} +% \end{macrocode} +% \end{macro} +% \end{macro} +% \end{macro} +% \end{macro} +% The next three commands are modifications some low \pkg{hyperref} commands +% found in the \texttt{pdfmark.def} file. Depending on the parsing, \cs{href} +% calls one of these three; we intercept them, and insert +% our own command \cs{mlhypertext} so the link string gets wrapped around +% if needed. These are in preparation for the definition of \cs{mlhref}. +% \begin{macrocode} +\def\ml@hyper@linkurl#1#2{\hyper@chars + \let\ef@thislinkcolor\@urlcolor + \let\CurrentBorderColor\@urlbordercolor + \mlhypertext[\presets{\mlhref@args}\A{/S/URI/URI(#2)}]{#1}% + \endgroup +} +\def\ml@hyper@linkfile#1#2#3{% + \let\ef@thislinkcolor\@filecolor + \let\CurrentBorderColor\@filebordercolor + \ifx\@pdfstartview\@empty + \def\theView{[0 /Fit]}\else + \def\theView{[0 \@pdfstartview]}\fi + \@ifundefined{ifHy@pdfnewwindow} + {\ifHy@newwindow}{\ifHy@pdfnewwindow}% + \def\isWindow{/NewWindow true}\else + \let\isWindow\@empty\fi + \mlhypertext[\presets{\mlhref@args}\A{/S/GoToR \isWindow + /F (#2) /D \ifx\\#3\\\theView\else(#3)\fi}]{#1}% + \endgroup +} +\def\ml@hyper@launch run:#1\\#2#3{% + \let\ef@thislinkcolor\@filecolor + \let\CurrentBorderColor\@runbordercolor + \@ifundefined{ifHy@pdfnewwindow} + {\ifHy@newwindow}{\ifHy@pdfnewwindow}% + \def\isWindow{/NewWindow true}\else + \let\isWindow\@empty\fi + \mlhypertext[\presets{\mlhref@args}\A{/S/Launch\isWindow + /F (#1) \ifx\\#3\\\else /Win << /P (#3) /F (#1) >> \fi}]{#2}% + \endgroup +} +% \end{macrocode} +% Below is the code for \cs{mlhref}. We first let the old commands found in \texttt{pdfmark.def} +% equal to the new versions, then we call \cs{href} to do all the parsing. Things +% eventually comes back to the above three commands. +% \begin{macrocode} +\let\aeb@saved@href\href +% \end{macrocode} +% \begin{macro}{\mlhref} +% This command is similar to \cs{href}. This command also takes +% three arguments, one optional. The first is usual optional argument +% that allow one to modify the appearance of the link, the second one +% is the URL that we are linking to, the third is the text that we are +% wrapping this link around. +%\begin{flushleft} +% Syntax: \ttfamily\string\mlhref[\ameta{opts}]\darg{\ameta{url}}\darg{\ameta{text}} +%\end{flushleft} +% \begin{macrocode} +\newcommand{\mlhref}[1][]{% + \begingroup + \def\mlhref@args{#1}% + \let\hyper@linkurl\ml@hyper@linkurl + \let\hyper@linkfile\ml@hyper@linkfile + \let\@hyper@launch\ml@hyper@launch + \aeb@saved@href +} +% \end{macrocode} +% \end{macro} +% \begin{macro}{\mlurl} +% The multi-line version of Donald Arseneau's url package. There +% are problems with this one, will continue to work on it. +% \changes{v2.0}{2016/02/16}{Added support for the \cs{url} command.} +% +% The problem is not as ``easy'' as the previous cases. Arseneau places the URL in math mode +% and it does not reconstruct (\texttt{soul} terminology) as it should. Our solution is to +% hijack three commands of \texttt{soul}, these are \cs{SOUL@doword}, \cs{SOUL@analyze}, and \cs{SOUL@dosyllable}, +% and modify them to do the work on an URL. +% \begin{macrocode} +\newbox\ml@urlbuildi +\newbox\ml@urlbuildii +% \end{macrocode} +% We modify \cs{SOUL@doword} and name it \cs{ml@SOUL@doword}. +% \begin{macrocode} +\def\ml@SOUL@doword{% + \global\setbox\ml@urlbuildi\hbox{}% + \global\setbox\ml@urlbuildii\hbox{}% + \edef\x{\the\SOUL@word}% + \ifx\x\empty + \else + \SOUL@buffer={}% + \setbox\z@\vbox{% + \SOUL@tt + \hyphenchar\font`\- + \hfuzz\maxdimen + \hbadness\@M + \pretolerance\m@ne + \tolerance\@M + \leftskip\z@ + \rightskip\z@ + \hsize1sp + \everypar{}% + \parfillskip\z@\@plus1fil + \hyphenpenalty-\@M + \noindent + \hskip\z@ + \relax + \the\SOUL@word}% +% \end{macrocode} +% We don't do the reconstruction, so no need for the message. +% \begin{macrocode} + \let\SOUL@errmsg\relax +% \let\SOUL@errmsg\SOUL@error + \let\-\relax + \count@\m@ne +% \end{macrocode} +% Here is the first major change, rather than splitting off to \cs{SOUL@analyze}, we go +% to our modified version, \cs{ml@SOUL@analyze}. +% \begin{macrocode} + \ml@SOUL@analyze + \SOUL@word={}% + \fi +} +% \end{macrocode} +% We modify \cs{SOUL@analyze} and name it \cs{ml@SOUL@analyze}. +% \begin{macrocode} +\def\ml@SOUL@analyze{{% + \setbox\z@\vbox{% + \unvcopy\z@ + \unskip + \unpenalty + \global\setbox\@ne=\lastbox}% + \ifvoid\@ne + \else +% \end{macrocode} +% We encapsulate our changes at this point in \cs{ml@interface@analyze} +% \begin{macrocode} + \ml@interface@analyze + \SOUL@syllgoal=\wd\@ne + \advance\count@\@ne +% \end{macrocode} +% We get the tokens recursively, but we jump back to \cs{ml@SOUL@analyze} not +% \cs{SOUL@analyze}. +% \begin{macrocode} + \ml@SOUL@analyze + \SOUL@syllwidth\z@ + \SOUL@syllable={}% + \ifnum\count@>\z@ + \advance\SOUL@syllgoal-\SOUL@ttwidth +% \end{macrocode} +% At this point, we jump to \cs{ml@SOUL@dosyllable} rather than +% \cs{SOUL@dosyllable}. +% \begin{macrocode} + \ml@SOUL@dosyllable + \SOUL@getkern{\the\SOUL@lasttoken}{\SOUL@hyphkern}% + {\SOUL@sethyphenchar}% + \SOUL@everyhyphen + \else +% \end{macrocode} +% Use \cs{ml@SOUL@dosyllable} not \cs{SOUL@dosyllable}. +% \begin{macrocode} + \ml@SOUL@dosyllable + \fi + \fi +}} +% \end{macrocode} +% +% \begin{macrocode} +\newif\ifml@display \ml@displaytrue +% \end{macrocode} +% We modify \cs{SOUL@dosyllable} and name it \cs{ml@SOUL@dosyllable}. +% \begin{macrocode} +\def\ml@SOUL@dosyllable{% + \SOUL@gettoken + \SOUL@eventuallyexhyphen{\the\SOUL@token}% + \edef\x{\the\SOUL@token}% + \ifx\x\SOUL@hyphenhintM + \let\SOUL@n\ml@SOUL@dosyllable + \else\ifx\x\SOUL@lowerthanM + \SOUL@gettoken + \SOUL@getkern{\the\SOUL@lasttoken}{\SOUL@charkern} + {\the\SOUL@token}% + \SOUL@everylowerthan + \SOUL@puttoken + \let\SOUL@n\ml@SOUL@dosyllable + \else\ifdim\SOUL@syllwidth=\SOUL@syllgoal + \SOUL@everysyllable + \SOUL@puttoken + \let\SOUL@n\relax + \else + \ifx\x\SOUL@stopM + \SOUL@errmsg + \global\let\SOUL@errmsg\relax + \let\SOUL@n\relax + \else + \setbox\tw@\hbox{\SOUL@tt\the\SOUL@token}% + \advance\SOUL@syllwidth\wd\tw@ + \global\SOUL@lasttoken=\SOUL@token + \SOUL@gettoken + \SOUL@getkern{\the\SOUL@lasttoken}{\SOUL@charkern} + {\the\SOUL@token}% + \SOUL@puttoken + \global\SOUL@token=\SOUL@lasttoken + \SOUL@everytoken + \edef\x{\SOUL@syllable={\the\SOUL@syllable\the\SOUL@token}}\x +% \end{macrocode} +% Here is the only change, we direct flow back to \cs{ml@SOUL@dosyllable} +% \begin{macrocode} + \let\SOUL@n\ml@SOUL@dosyllable + \fi\fi\fi\fi + \SOUL@n +} +% \end{macrocode} +% We put most of our changes to \cs{ml@SOUL@analyze} in +% \DescribeMacro{\ml@interface@analyze}\cs{ml@interface@analyze} +% \begin{macrocode} +\def\ml@interface@analyze{% + \global\advance\syllableCnt\@ne % dpsa11 + \setbox\@ne\hbox{\unhbox\@ne}% +% \end{macrocode} +% If we say \verb!\mlurl{http://www.math.uakron.edu/~dpstory}!, then the \cs{box\cs{z@}} above contains +% the following tokens, listed at their breakpoints:\goodbreak +% \begin{flushleft} +% \texttt{http:}\\ +% \texttt{\string\\}\\ +% \texttt{www.}\\ +% \texttt{math.}\\ +% \texttt{uakron.}\\ +% \texttt{edu/}\\ +% \texttt{\string~dpstory} +% \end{flushleft} +% The idea is to get each of these using \verb~\global\setbox\@ne=\lastbox~ (bottom to top) +% and to build the URL with the quad points calculated. Each new token is added in front +% of the URL as we build it. Results are held in \cs{ml@urlbuild}. We insert \cs{penalty0} to +% promote a break point between components, as each component is enclosed in an \cs{hbox} now. +% \begin{macrocode} +% \end{macrocode} +% We'll try cracking the url here, if requested. +% \begin{macrocode} + \ifx\eq@mlcrackat\@empty +% \end{macrocode} +% Ordinary link, we don't crack it apart, continue with the old code. +% \begin{macrocode} + \ml@bld@quadchunks{\the\aeb@mLinkCnt} + {\ml@qlngthchunki}{\ml@urlbuildi}% + \else + \ifnum\syllableCnt=\revCrackAt\relax +% \end{macrocode} +% Everything is in reverse order, this is the last syllable of the first chunk +% \begin{macrocode} + \aeb@arrayIndx=\z@ +% \end{macrocode} +% start first link +% \begin{macrocode} + \ml@start@link{\the\aeb@mLinkCnt}{\ml@qlngthchunki}% + \ml@bld@quadchunks{\the\aeb@mLinkCnt} + {\ml@qlngthchunki}{\ml@urlbuildi}% + \else +% \end{macrocode} +% Continue with first link +% \begin{macrocode} + \ifnum\syllableCnt>\revCrackAt\relax + \ml@bld@quadchunks{\the\aeb@mLinkCnt} + {\ml@qlngthchunki}{\ml@urlbuildi}% + \else + \ifnum\syllableCnt=\@ne +% \end{macrocode} +% start second link +% \begin{macrocode} + \aeb@arrayIndx=\z@ +% \end{macrocode} +% Everything is in reverse order, this is the last syllable of the second chunk +% \begin{macrocode} + \ml@start@link{\aeb@mLinkCnt@}{\ml@qlngthchunkii}% + \ml@bld@quadchunks{\aeb@mLinkCnt@} + {\ml@qlngthchunkii}{\ml@urlbuildii}% + \else +% \end{macrocode} +% continue with second link +% \begin{macrocode} + \ml@bld@quadchunks{\aeb@mLinkCnt@} + {\ml@qlngthchunkii}{\ml@urlbuildii}% + \fi + \fi + \fi + \fi +} +\def\ml@bld@quadchunks#1#2#3{{% +% #1 = link cnt +% #2 = chunk size +% #3 = \ml@urlbuild to i or ii + \@ifundefined{mLinkLngth\the\aeb@mLinkCnt} + {\edef\@indx{\the\aeb@arrayIndx}} + {\@tempcnta#2\relax + \advance\@tempcnta-8\relax + \advance\@tempcnta-\aeb@arrayIndx + \def\@indx{\the\@tempcnta}% + }% + \@tempcntb=\@indx \divide\@tempcntb by 8 + \advance\@tempcntb by 1 +\ifx#3\ml@urlbuildii \advance\@tempcntb by \eq@mlcrackat\relax\fi + \global\setbox#3=\hbox{% + \mlh@setQuadSyllable{\@indx}{#2}{#1}{\unhcopy\@ne}% + \hbox{\unhcopy\@ne}\relax\ml@typeset@@syl{\@tempcntb}\penalty0\unhcopy#3}%hbox +}} +% \end{macrocode} +% After the above preliminaries, we finally define \DescribeMacro{\mlurl}\cmd{\mlurl}. +%\begin{flushleft} +% Syntax: \ttfamily\string\mlurl[\ameta{opts}]\darg{\ameta{url}} +%\end{flushleft} +% \begin{macrocode} +\newcommand{\mlurl}{\begingroup\@makeother\~\relax% \def~{\string~}% + \ef@sanitize@toks\mlurl@} +% \end{macrocode} +% After sanitizing, we save the URL (\texttt{\#2}) an a macro +% \cs{ml@url} using the \cs{urldef} command, defined in the \textsf{url} package. +% \begin{macrocode} +\newcommand{\mlurl@}[2][]{\@ifundefined{ef@thislinkcolor} + {\let\ef@thislinkcolor\normalcolor}{}\expandafter + \def\expandafter\ef@thislinkcolor@SAVE + \expandafter{\ef@thislinkcolor}% + \def\ml@setlink##1{\setLinkPbox{\A{\URI{#2}}% + \QuadPoints{mLink##1}#1}}% +% \end{macrocode} +% We get the link options early to determine if this link is to +% be underlined. +% \begin{macrocode} + \expandafter\processAppArgs\set@LinkPboxDefaults + \presets{\ml@nocolor@defaults}\S{S}\W{0}#1\end\@nil + \ifx\eq@S@value\ml@underlinded + \let\itsunderline\ef@YES\else\let\itsunderline\ef@NO\fi +% \end{macrocode} +% \cs{ml@url} is the specified url to create a link around +% \begin{macrocode} + \global\aeb@arrayIndx=0\relax + \global\syllableCnt=0\relax + \global\advance\aeb@mLinkCnt\@ne\relax +% \end{macrocode} +% \begin{macrocode} + \@ifundefined{mLinkLngth\the\aeb@mLinkCnt}{% + \global\linknotformedtrue\def\ml@lngth{17}% + \def\ml@qlngthchunki{17}} + {\@tempcnta\@nameuse{mLinkLngth\the\aeb@mLinkCnt}\relax + \edef\ml@lngth{\the\@tempcnta}%\multiply\@tempcnta8\relax + \edef\ml@qlngthchunki{\the\@tempcnta}}% +% \end{macrocode} +% We make some calculations in preparation to a link that will be +% cracked apart. +% \cs{mlM@XCNT} is the number of syllables of the un-cracked URL. +% \begin{macrocode} + \@ifundefined{mLinkSyCnt\the\aeb@mLinkCnt} + {\def\mlM@XCNT{0}\def\ml@lngthchunki{0}\def\ml@lngthchunkii{0}% + \def\ml@qlngthchunki{0}\def\ml@qlngthchunkii{0}\def\revCrackAt{0}} + {\edef\mlM@XCNT{\@nameuse{mLinkSyCnt\the\aeb@mLinkCnt}}% +% \end{macrocode} +% When \cs{mlM@XCNT} is known, and \cs{eq@mlcrackat} is known, we can calculate +% the number of syllables of each chunk of the URL, for the first chunk, it is +% \cs{eq@mlcrackat}, for the second it is $\cs{mlM@XCNT} - \cs{eq@mlcrackat}$. +% \begin{macrocode} + \ifx\eq@mlcrackat\@empty\else + \@tempcnta\mlM@XCNT\relax\advance\@tempcnta-\eq@mlcrackat\relax + \edef\ml@lngthchunki{\eq@mlcrackat}% + \edef\ml@lngthchunkii{\the\@tempcnta}% + \@tempcnta\ml@lngthchunki\relax\multiply\@tempcnta8\relax + \edef\ml@qlngthchunki{\the\@tempcnta}% + \@tempcnta\ml@lngthchunkii\relax\multiply\@tempcnta8\relax + \edef\ml@qlngthchunkii{\the\@tempcnta}% +% \end{macrocode} +% We take these chunks off in reverse order so we measure each from the end of the url. +% This calculation can be move to earlier code where it is not executed for each syllable (chunk). +% \cs{revCrackAt} is the value of \cs{eq@mlcrackat} as measure from the end of the url. +% \begin{macrocode} + \@tempcnta\mlM@XCNT\relax + \advance\@tempcnta-\eq@mlcrackat\relax + \advance\@tempcnta\@ne + \edef\revCrackAt{\the\@tempcnta}% + \fi}% + \@tempcnta\aeb@mLinkCnt\advance\@tempcnta\@ne + \edef\aeb@mLinkCnt@{\the\@tempcnta}% + \urldef\ml@url\nolinkurl{#2}% + \def\SOUL@mlhpreamble{%\begingroup + \mlh@preambleCmdInsert\ef@colorthislink}\hyper@chars + \let\ef@thislinkcolor\@urlcolor + \let\CurrentBorderColor\@urlbordercolor +% \end{macrocode} +% Within this group, we direct the \pkg{soul} package to our customized versions of the +% commands. +% \begin{macrocode} + \let\ml@SOUL@doword@SAVE\SOUL@doword + \let\SOUL@doword\ml@SOUL@doword +% \end{macrocode} +% The next several lines are taken from the definition of \cs{mlhypertext}, the basic command +% for construction many of the `\cs{ml}' commands of this package. +% \begin{macrocode} + \ifx\eq@mlcrackat\@empty + \ml@start@link{\the\aeb@mLinkCnt}{\ml@lngth}\fi + \def\mlh@preambleCmdInsert{\ml@MrkLnk{\the\aeb@mLinkCnt}% + \ml@earlyExecProps{#1}}% + \def\mlh@postambleCmd{% + \expandafter +% \end{macrocode} +% The coloring of the hypertext does not work unless we make the definition +% global, so we do so and hope this does not mess other things up. +% \changes{v2.0.1}{2017/09/19}{Save the incoming link color} +% Save the incoming link color so we can globally change it. +% After the link is formed, change it back again. +% \begin{macrocode} + \def\expandafter\ef@thislinkcolor + \expandafter{\ef@thislinkcolor}}% +% \end{macrocode} +% Finally, we call \cs{aeb@mlh} which starts \textsf{soul} with \cs{SOUL@}. +% This does this analysis, the custom command build the url in \cs{ml@urlbuild}, which +% we then unbox. +% \begin{macrocode} + \aeb@mlh\ml@url\ef@colorthislink\unhcopy\ml@urlbuildi + \expandafter\gdef\expandafter\ef@thislinkcolor + \expandafter{\ef@thislinkcolor@SAVE}% + \immediate\write\@auxout{\string\mlcsarg\string + \gdef{mLinkSyCnt\the\aeb@mLinkCnt}{\the\syllableCnt}}% dpsa11 + \immediate\write\@auxout{\string\mlcsarg + \string\gdef{mLinkLngth\the\aeb@mLinkCnt}{\the\aeb@arrayIndx}}% + \ifx\eq@mlcrackat\@empty + \ml@finish@link{\the\aeb@mLinkCnt}{\ml@lngth}% + \ml@setlink{\the\aeb@mLinkCnt}% + \iffixmlinks\literalps@out{restore}\fi + \else + \ml@finish@link{\the\aeb@mLinkCnt}{\ml@qlngthchunki}% + \ml@setlink{\the\aeb@mLinkCnt}% + \iffixmlinks\literalps@out{restore}\fi + \eq@mlcrackinsat\penalty-100 + \ml@start@link{\aeb@mLinkCnt@}{\ml@qlngthchunkii}% + \penalty0\@ifundefined{mLinkLngth\the\aeb@mLinkCnt}{} + {\ml@MrkLnk{\aeb@mLinkCnt@}}\unhcopy\ml@urlbuildii + \ml@finish@link{\aeb@mLinkCnt@}{\ml@qlngthchunkii}% + \ml@setlink{\aeb@mLinkCnt@}\iffixmlinks + \literalps@out{restore}\fi + \global\advance\aeb@mLinkCnt\@ne + \fi\aftergroup\normalcolor\endgroup +} +\def\ml@start@link#1#2{% Step 1 +% #1=link number +% #2 = final quad length + \literalps@out{% + /xoMsgB true def^^J% + \ps@mark/_objdef {mLink#1}% + /type /array /OBJ pdfmark^^J% + \ifoldstylequads + /mLinkFxup#1\space0 array def + \else + /bCreateLink mlIsBld #2\space eq not def^^J% + bCreateLink{ /mLinkFxup#1\space + #2\space array def }if + \fi + }% +} +% \end{macrocode} +% Make \texttt{gFixup} into a macro, so other packages (\pkg{aeb\_mlink} can intercept and insert +% its own procedure here. +% \changes{v2.3.2}{2018/08/09}{We make \string\texttt{gFixup} into a macro name \string\cs{FixupProc}} +% \begin{macrocode} +\def\FixupProc{gFixup} +\def\ml@finish@link#1#2{% Step 4 and 5 +% #1=link number +% #2 = final quad length + \ifoldstylequads\else + \ifnum\aeb@arrayIndx=0\relax + \PackageWarning{aeb_mlink}{% + Problem with mLink\the\aeb@mLinkCnt, Will skip the \MessageBreak + creation of this link}\fi + \literalps@out{% +% \end{macrocode} +% If \cs{iffixmlinks} is true, we fix the links, otherwise, we no not. +% \begin{macrocode} + \iffixmlinks + \ifnum\aeb@arrayIndx>0 + save^^J% + bCreateLink {^^J% + \mlDict\space/mLinkFxup#1\space known {^^J% + (\ml@@nnotName#1) + #2\space + mLinkFxup#1\space + quadpointsfixup^^J% + \ps@mark{mLink#1} 0 \FixupProc\space + /PUTINTERVAL pdfmark^^J% + }if }if + \fi + \else +% \end{macrocode} +% (2018/04/20) Added \texttt{bCreateLink}, etc., to protect +% against \app{distiller}/\app{ps2pdf} from crashing when \cs{mlfix\darg{n}}. +% \changes{v2.1.18}{2018/04/20}{Added \string\texttt{bCreateLink}, etc., to protect +% against distiller/ps2pdf from crashing} +% \begin{macrocode} + bCreateLink {^^J% + \mlDict\space/mLinkFxup#1\space known {^^J% + \ps@mark{mLink#1} 0 mLinkFxup#1 + /PUTINTERVAL pdfmark^^J% + }if }if + \fi}% +\fi} +% \end{macrocode} +% \end{macro} +% \section{Macros used by the SOUL Interface} +% \begin{macrocode} +\ifHy@colorlinks + \def\ef@colorthislink{\color{\ef@thislinkcolor}} +\else + \let\ef@colorthislink\relax +\fi +% \end{macrocode} +% I've inserted \verb|\let\protect\@empty| to make |mlnameref| and |mlNameref| work. +% \begin{macrocode} +\def\ml@SOUL@stop{\relax} +\def\SOUL@mlhpreamble{\begingroup +% \end{macrocode} +% (2011/12/27) Originally, I had \verb|\let\protect\@empty| here, but removing this +% seems to do no harm, so, we'll go for it. +% \begin{macrocode} + \mlh@preambleCmdInsert\ef@colorthislink} +\def\SOUL@mlheverysyllable{% dpsaug16 + \global\advance\syllableCnt\@ne + \ifx\eq@mlcrackat\@empty + \expandafter\SOUL@mlheverysyllable@i + \else + \expandafter\SOUL@mleverysyllable@ii + \fi +} +\let\eq@@mlhyph\@empty +\def\ml@typset@syl#1{\raisebox{\ml@raiseamt} + {\smash{\normalfont\normalcolor\tiny\strut\llap{\the#1}}}} +\def\turnSyllbCntOn{\mlMarksOn\let\ml@typeset@@syl\ml@typset@syl} +\def\turnSyllbCntOff{\let\ml@typeset@@syl\@gobble} +\turnSyllbCntOff +\def\SOUL@mlheverysyllable@i{% + \mlh@setQuadSyllable{\the\aeb@arrayIndx}{\ml@lngth}% + {\the\aeb@mLinkCnt}{\the\SOUL@syllable\eq@@mlhyph}% + \the\SOUL@syllable %\SOUL@setkern\SOUL@charkern + \ml@typeset@@syl{\syllableCnt}\eq@@mlhyph +}% +\def\SOUL@mleverysyllable@ii{% + \ifnum\eq@mlchunk=0\relax + \ifnum\syllableCnt>\eq@mlcrackat\relax + \global\ml@displayfalse + \else + \global\ml@displaytrue + \ifnum\syllableCnt=\eq@mlcrackat\relax + \let\eq@@mlhyph\eq@mlhyph + \global\let\ml@space\relax + \else + \let\eq@@mlhyph\@empty + \global\let\ml@space\space + \fi + \SOUL@mlheverysyllable@i + \fi + \else + \ifnum\syllableCnt>\eq@mlcrackat\relax + \global\ml@displaytrue + \SOUL@mlheverysyllable@i + \else + \global\ml@displayfalse + \fi + \fi + \ml@dynamicsetup +} +%\def\SOUL@mlheveryspace#1{#1\space\hskip\spaceskip} +\let\ml@space\space +\def\SOUL@mlheveryspace#1{% + #1\ml@space\global\let\ml@space\space +} +\def\SOUL@mlheveryhyphen{% + \discretionary{% + \unkern + \SOUL@setkern\SOUL@hyphkern + \SOUL@sethyphenchar + }{}{}% +} +\def\SOUL@mlheveryexhyphen#1{\global\advance\syllableCnt\@ne + \mlh@setQuadSyllable{\the\aeb@arrayIndx}{\ml@lngth}% + {\the\aeb@mLinkCnt}{\SOUL@setkern\SOUL@hyphkern#1}% + \SOUL@setkern\SOUL@hyphkern\hbox{#1}% + \discretionary{}{}{% + \SOUL@setkern\SOUL@charkern + }% +} +\def\mlh@postambleCmd{\relax} +\def\ml@dynamicsetup{%dpsaug16 + \ifml@display + \global\let\SOUL@everyspace\SOUL@mlheveryspace + \global\let\SOUL@everyexhyphen\SOUL@mlheveryexhyphen + \else + \gdef\SOUL@everyspace##1{}% + \gdef\SOUL@everyexhyphen##1{}% + \fi +} +\def\SOUL@mlhpostamble{\mlh@postambleCmd} +\def\SOUL@mlhsetup{\SOUL@setup + \let\SOUL@preamble\SOUL@mlhpreamble + \let\SOUL@everysyllable\SOUL@mlheverysyllable + \ml@dynamicsetup +% \let\SOUL@everyspace\SOUL@mlheveryspace + \let\SOUL@everyhyphen\SOUL@mlheveryhyphen +% \let\SOUL@everyexhyphen\SOUL@mlheveryexhyphen + \def\SOUL@postamble{\SOUL@mlhpostamble}% +} +\DeclareRobustCommand*\aeb@mlh{\syllableCnt=0 + \SOUL@mlhsetup\SOUL@} +% \end{macrocode} +% \begin{macrocode} +% End of Package +%</package> +% \end{macrocode} +% \Finale +\endinput diff --git a/macros/latex/contrib/aeb_mlink/aeb_mlink.ins b/macros/latex/contrib/aeb_mlink/aeb_mlink.ins new file mode 100644 index 0000000000..d98e0b6927 --- /dev/null +++ b/macros/latex/contrib/aeb_mlink/aeb_mlink.ins @@ -0,0 +1,60 @@ +%% +%% This file will generate fast loadable files and documentation +%% driver files from the doc files in this package when run through +%% LaTeX or TeX. +%% +%% Copyright 1999-2006 D. P. Story +%% +%% This file is part of the `AcroTeX eDucation Bundle'. +%% ------------------------------------------- +%% +%% It may be distributed under the conditions of the LaTeX Project Public +%% License, either version 1.2 of this license or (at your option) any +%% later version. The latest version of this license is in +%% http://www.latex-project.org/lppl.txt +%% and version 1.2 or later is part of all distributions of LaTeX +%% version 1999/12/01 or later. +%% +%% --------------- start of docstrip commands ------------------ +%% +\def\filedate{2018/04/26} +\def\batchfile{aeb_mlink.ins} +% +\input docstrip +\ifx\generate\undefined + \Msg{**********************************************} + \Msg{*} + \Msg{* This installation requires docstrip} + \Msg{* version 2.4 or later.} + \Msg{*} + \Msg{* An older version of docstrip has been input} + \Msg{*} + \Msg{**********************************************} + \errhelp{Move or rename old docstrip.tex and get a newer one.} + \errmessage{Old docstrip in input path} + \batchmode + \csname @@end\endcsname\end +\fi + +\keepsilent +\askforoverwritefalse +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\preamble +\endpreamble +\generate +{% + \file{aeb_mlink.sty}{\from{aeb_mlink.dtx}{copyright,package}} + \file{aeb-mlink.sty}{\from{aeb_mlink.dtx}{copyright,altpkgname}} +} + +\Msg{***************************************************************} +\Msg{*} +\Msg{* \space To finish the installation you have to copy the files } +\Msg{*} +\Msg{* \space *.sty, *.cfg and *.def into a directory searched by TeX} +\Msg{*} +\Msg{***************************************************************} + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\endinput diff --git a/macros/latex/contrib/aeb_mlink/doc/aebmlink_man.pdf b/macros/latex/contrib/aeb_mlink/doc/aebmlink_man.pdf Binary files differnew file mode 100644 index 0000000000..b672ae4a22 --- /dev/null +++ b/macros/latex/contrib/aeb_mlink/doc/aebmlink_man.pdf diff --git a/macros/latex/contrib/aeb_mlink/doc/aebmlink_man.tex b/macros/latex/contrib/aeb_mlink/doc/aebmlink_man.tex new file mode 100644 index 0000000000..6957dcf21f --- /dev/null +++ b/macros/latex/contrib/aeb_mlink/doc/aebmlink_man.tex @@ -0,0 +1,927 @@ +% makeindex < aebpro_man.idx > aebpro_man.ind +\documentclass{article} +%\usepackage[fleqn]{amsmath} +\usepackage[ + web={centertitlepage,designv,forcolorpaper, + tight*,latextoc,pro,usetemplates}, + eforms={useui}, + aebxmp +]{aeb_pro} +\usepackage[dblevel=1]{aeb_mlink} + +%\usepackage{myriadpro} +\usepackage[altbullet]{lucidbry} +\usepackage{xbmks} + +\DeclareInitView{layoutmag={navitab:UseOutlines}} +\xbmksetup{colors={int=red},styles={intbf}} + + +\usepackage{acroman} + +%\def\amtIndent{15pt} +\edef\amtIndent{\the\leftmargini} + +\usepackage[active]{srcltx} + +\DeclareDocInfo +{ + university={\AcroTeX.Net}, + title={The \textsf{aeb\_mlink} Package\texorpdfstring{\\[1em]}{: }AeB Pro Family}, + author={D. P. Story}, + email={dpstory@acrotex.net}, + subject={Wrapping links around to the next line}, + keywords={multi-line links, quad points, latex, pdf, aeb}, + talksite={\url{www.acrotex.net}}, + version={2.3.4, 2018/08/18}, + copyrightStatus={True}, + copyrightNotice={Copyright (C) 2006-\the\year, D. P. Story}, + copyrightInfoURL={http://www.acrotex.net} +} +\nocopyright +\DeclareInitView{windowoptions=showtitle} + +\def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}% + \kern-.6em \hbox{$\mathcal S$}}$} + + + +\def\AcroTeX{Acro\negthinspace\TeX} + +\def\unskipparskip{\vskip-\parskip} +\renewenvironment{sverbatim} +{\parskip0pt\noindent\small\verbatim}{\endverbatim\par\aftergroup\unskipparskip} +\renewenvironment{ssverbatim} +{\parskip0pt\noindent\footnotesize\verbatim}{\endverbatim\par\aftergroup\unskipparskip} + +\def\anglemeta#1{$\langle\textit{\texttt{#1}}\rangle$} +\let\ameta\anglemeta +\def\meta#1{\textit{\texttt{#1}}} +\def\darg#1{\texttt{\{#1\}}} +\def\takeMeasure{\bgroup\obeyspaces\takeMeasurei} +\def\takeMeasurei#1{\global\setbox\webtempboxi\hbox{\ttfamily#1}\egroup} +\def\bxSize{\wd\webtempboxi+2\fboxsep+2\fboxrule} +\let\pkg\textsf +\let\env\texttt +\let\opt\texttt +\let\app\textsf + +%\let\amtIndent\leftmargini +%\let\amtIndent\parindent +\def\SUB#1{${}_{\text{#1}}$} + +\newdimen\aebdimen \aebdimen 0pt %\advance\aebdimen\partopsep +\newcommand\bVerb[1][]{\begingroup#1\vskip\aebdimen\parindent0pt}% +\def\eVerb{\vskip\aebdimen\endgroup\noindent} + +\def\cmdtitle#1{\texorpdfstring{\protect\cs{#1}}{\textbackslash{#1}}} + +\renewcommand\hproportionwebauthor{.5} +\universityLayout{fontsize=Large} +\titleLayout{fontsize=LARGE} +\authorLayout{fontsize=Large} +\tocLayout{fontsize=Large,color=aeb} +\sectionLayout{indent=-62.5pt,fontsize=large,color=aeb} +\subsectionLayout{indent=-31.25pt,color=aeb} +\subsubsectionLayout{indent=0pt,color=aeb} +\subsubDefaultDing{\texorpdfstring{$\bullet$}{\textrm\textbullet}} + +\makeatletter +\def\cs#1{\texttt{\@backslashchar#1}} +\renewcommand{\paragraph} + {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\bfseries}} +\renewcommand{\subparagraph} + {\@startsection{subparagraph}{5}{15pt}{6pt}{-3pt}{\bfseries}} +\makeatother + +%\parindent0pt\parskip\medskipamount + + +%\definePath\bgPath{"C:/Users/Public/Documents/% +% ManualBGs/Manual_BG_Print_AeB.pdf"} +%\begin{docassembly} +%\addWatermarkFromFile({% +% bOnTop: false, +% cDIPath: \bgPath +%}) +%\executeSave() +%\end{docassembly} + +\chngDocObjectTo{\newDO}{doc} +\begin{docassembly} +var titleOfManual="The AeB mLink Manual"; +var manualfilename="Manual_BG_Print_mlink.pdf"; +var manualtemplate="Manual_BG_Blue.pdf"; // Blue, Green, Brown +var _pathToBlank="C:/Users/Public/Documents/ManualBGs/"+manualtemplate; +var doc; +var buildIt=false; +if ( buildIt ) { + console.println("Creating new " + manualfilename + " file."); + doc = \appopenDoc({cPath: _pathToBlank, bHidden: true}); + var _path=this.path; + var pos=_path.lastIndexOf("/"); + _path=_path.substring(0,pos)+"/"+manualfilename; + \docSaveAs\newDO ({ cPath: _path }); + doc.closeDoc(); + doc = \appopenDoc({cPath: manualfilename, oDoc:this, bHidden: true}); + f=doc.getField("ManualTitle"); + f.value=titleOfManual; + doc.flattenPages(); + \docSaveAs\newDO({ cPath: manualfilename }); + doc.closeDoc(); +} else { + console.println("Using the current "+manualfilename+" file."); +} +var _path=this.path; +var pos=_path.lastIndexOf("/"); +_path=_path.substring(0,pos)+"/"+manualfilename; +\addWatermarkFromFile({ + bOnTop:false, + bOnPrint:false, + cDIPath:_path +}); +\executeSave(); +\end{docassembly} + +\reversemarginpar + +%\mlMarksOn + + +\begin{document} + +\maketitle + +\pdfbookmarkx[1]{Title Page}[action={\Named{FirstPage}}]{TitlePage} +\pdfbookmarkx[1]{Links to AcroTeX.Net}[action={/S/GoTo/D(undefined)},% + color=magenta,style={bf}]{acrotex} +\belowpdfbookmarkx{http://www.acrotex.net}[action={\URI{http://www.acrotex.net}},% + color=magenta,style={bf}]{home} +\belowpdfbookmarkx{http://blog.acrotex.net}[action={\URI{http://blog.acrotex.net}},% + color=magenta,style={bf}]{blog} + + +\selectColors{linkColor=black} + +\tableofcontents + +\selectColors{linkColor=webgreen} + +\section{Introduction} + +This package creates \underbar{m}ulti-line \underbar{link}s, a dream of mine +for a number of years. The package \pkg{hyperref} does create links, +but generally these links cannot be broken across lines, unless the +application \app{pdflatex} (or \app{xelatex}) is used to create a PDF; +however, since my workflow is primarily through \app{Acrobat Distiller}, this +does me little good. + +This package uses the \texttt{QuadPoints} entry of the link annotation +dictionary to create a bounding region; consequently, this package +requires\marginpar{\small\raggedright\flushright \app{Distiller} or +\app{ps2pdf} required} \app{Acrobat Distiller} or the \app{ps2pdf.exe} +converter to create a PDF. The \texttt{QuadPoints} entry in the link +annotation is a PDF 1.6 feature, so these multi-line links will work in +\app{Adobe Reader} 7.0 or later. If viewed in a version of \app{Adobe Reader} +previous to 7.0, the viewer will use the underlying bounding box, which is the +smallest rectangle containing the link text. + +\section{Alternate package name: \texorpdfstring{\protect\pkg{aeb-mlink}}{aeb-mlink}} + +This package is known on CTAN as \pkg{aeb-mlink} +(\href{http://www.ctan.org/pkg/aeb-mlink}{ctan.org/pkg/aeb-mlink}), even +though there is no such package by that name, until now. Included within this distrubution +is the `dummy' package \pkg{aeb-mlink} which loads \pkg{aeb\_mlink} and passes all options +to it. + +\section{Requirements} + +The following {\LaTeX} packages are the major ones required by \texttt{aeb\_mlink}. +\begin{itemize} + \item \pkg{eforms} provides form and link support, \`a la + {Acro\negthinspace\TeX} (\href{http://www.ctan.org/pkg/acrotex}{ctan.org/pkg/acrotex}). + \item \pkg{hyperref} provides link support, including the + commands \cs{hyperref}, \cs{hyperlink}, \cs{href}, \cs{nameref}, + \cs{Nameref}, and \cs{href}. + \item \pkg{soul} a very nice package by Melchior FRANZ, used by + \pkg{aeb\_mlink} to break the text of a link into its syllables (\href{http://www.ctan.org/pkg/soul}{ctan.org/pkg/soul}). +% \nolinkurl{CTAN: tex-archive/macros/latex/contrib/soul/}} + +\end{itemize} + +\section{Package options} + +There are only two package options---the name of the dvi-to-ps converter application to be used---, +these are \opt{dvips} and \opt{dvipsone}.\footnote{\app{dvipsone.exe} is the dvi-to-ps converter +of the Y\&Y {\TeX} System, no longer available, but is used by this author.} The default is \opt{dvips}. + +%\Hy@colorlinksfalse + +\bVerb[\aebdimen=6pt] +\begin{minipage}[t]{.5\linewidth} +\begin{Verbatim}[xleftmargin=\amtIndent,commandchars=!(),fontsize=\small] +\documentclass{article} +\usepackage{xcolor} +\usepackage[colorlinks]{hyperref} +\usepackage[!anglemeta(options)]{aeb_mlink} +\end{Verbatim} +\end{minipage}\quad\begin{minipage}[t]{.4\linewidth} +\begin{Verbatim}[commandchars=!(),fontsize=\small] +\documentclass{article} +\usepackage[designi]{web} +\usepackage[!anglemeta(options)]{aeb_mlink} +\end{Verbatim} +\end{minipage} +\eVerb Above are two typical preambles for the use of \pkg{aeb\_mlink}: +\begin{itemize} + \item The one on the left inputs \pkg{xcolor} (recommended) and + \pkg{hyperref} explicitly. The \opt{colorlinks} option is + recommended for \pkg{hyperref}. These two are followed by + \pkg{aeb\_mlink}. + \item The preamble representation on the right uses the \pkg{web} + package, which internally inputs both \pkg{xcolor} (if available) and + \pkg{hyperref} (with \opt{colorlinks} option). Again, \pkg{aeb\_mlink} + comes last. +\end{itemize} + +\paragraph*{Options of \pkg{aeb\_mlinks}.} These are, +\begin{description} + \item[\normalfont\texttt{dvips}] Use this option when the \textsf{dvips} application is used + to create the Postscript file. + \item[\normalfont\texttt{dvipsone}] Use this option when the \textsf{dvipsone} application is used + to create the Post\-script file. (Only a few people worldwide use this option.) + \item[\normalfont\texttt{dblevel=\ameta{\upshape{0|1|2}}}] To obtain information on the multi-line links being + created. Each value gives more information about what is going on. Used for development. + \item[\normalfont\ameta{eforms-options}] Any options other than the ones listed above are passed to the + \pkg{eforms} package. +\end{description} +Since \pkg{eforms} is a required package, the \pkg{acrotex} bundle +(\pkg{AeB}) is installed; consequently, if you've set up the \texttt{web.cfg} +configuration file (that accompanies \pkg{AeB}) with either +\cs{ExecuteOptions\darg{dvips}} or \cs{ExecuteOptions\darg{dvipsone}}, the +specification of the driver (\opt{dvips} or \opt{dvipsone}) is not normally +needed. + +\section{Multi-line link commands} + +We define seven multi-line hypertext link commands: \cs{mlhypertext}, +\cs{mlhyperlink}, \cs{mlhyperref}, \cs{mlnameref}, \cs{mlNameref}, +\cs{href}, and \cs{mlurl}. The first is a basic command that is used in the definitions of +the other six. + +%\newtopic\noindent\textbf{Note:} Because of the way the bounding boxes are +%constructed, it is best that the bounding rectangle is set on invisible, that +%is, the line width of the boundary line is zero. The \opt{colorlinks} option +%of \app{hyperref} should be taken. + +\exSrc{mlink_tst}The demo file is \texttt{mlink\_tst.tex}, it illustrates all +the commands -- with the exception of \cs{mlurl} -- of this package. The +demo file for \cs{mlurl} is a separate file and is mentioned in +\hyperref[ss:mlrul]{Section~\ref*{ss:mlrul}}. + +\subsection{\cmdtitle{mlhypertext} (\cmdtitle{mlsetLink})} A general purpose multi-line link command. + +\bVerb[\aebdimen=8pt]\takeMeasure{\string\mlhypertext[\#1]\darg{\#2}}% +\begin{minipage}{\bxSize} +\begin{Verbatim}[frame=single,rulecolor=\color{webblue}] +\mlhypertext[#1]{#2} +\end{Verbatim} +\end{minipage}\quad\takeMeasure{\string\mlsetLink[\#1]\darg{\#2}}% +\begin{minipage}{\bxSize} +\begin{Verbatim}[frame=single,rulecolor=\color{webblue}] +\mlsetLink[#1]{#2} +\end{Verbatim} +\end{minipage} +\endgroup + + +\PD The first parameter is optional, and is used to set the appearance and the actions of the link. +The second parameter is the text around which the link is constructed. + +\CmdDescription The \pkg{eforms} package defines \cs{mlsetLink} to +\cs{mlhypertext} (this is to conform to the naming conventions of +\pkg{eforms}). Either command sets a hypertext link having a default +appearance, and no action. The default appearance is the same as that of +\cs{hyperlink}, the command from \pkg{hyperref}. If \opt{colorlinks} +option was taken in the hyperref package, the text is colored \cs{@linkcolor} +(usually red); otherwise, the text is the default color at the time, and a +boundary rectangle is created by AcroForms with color \cs{@linkbordercolor} +(usually red).\footnote{The \pkg{web} package changes the default coloring of \pkg{hyperref}.} + +\newtopic +For example, the following link is constructed using +\cs{mlhypertext}: \mlhypertext[\A{\JS{app.alert("AcroTeX rocks!")}}]% +{Acrobat Distiller, version~7.0 or greater} was used to +create this PDF document. + +\bVerb\takeMeasure{\string\mlhypertext[\string\A\darg{\string\JS\darg{app.alert("AcroTeX rocks!")}}]\%}% +\begin{dCmd*}{\bxSize} +\mlhypertext[\A{\JS{app.alert("AcroTeX rocks!")}}]% + {Acrobat Distiller, version~7.0 or greater} +\end{dCmd*} +\eVerb In the above example, the link, shown in \textcolor{webgreen}{green} +is broken across lines. Though is not shown in this example, these links +can break a line at a hyphenation point as well. The optional argument is +used to create an alert box that appears when the link is clicked. + +\subsection{\cmdtitle{mlhyperlink}} A multi-line version of the \cs{hyperlink} command. + +\bVerb\takeMeasure{\string\mlhyperlink[\#1]\darg{\#2}\darg{\#3}}% +\begin{dCmd}{\bxSize} +\mlhyperlink[#1]{#2}{#3} +\end{dCmd} +\endgroup + +\PD The first parameter is optional, and is used to set the appearance, but \textit{not the actions} of the link. +The second parameter is a named destination, perhaps created by the \cs{hypertarget} command of +\pkg{hyperref}. The third parameter is the text around which the link is constructed. + +\CmdDescription This command is the multi-line version of the \pkg{hyperref} command \cs{hyperlink}. +The default appearance is the same as \cs{hyperlink}, as described above in \cs{mlhypertext}. +The action of this link is to jump to a named destination; the action cannot be changed by defining +a different action through the first parameter. + +This link uses the \cs{mlhyperlink} command: +\so{Welcome!} \mlhyperlink{retire}{Welcome, $\dots$ to my humble retirement residence, such as it is!} +\bVerb\takeMeasure{\string\mlhyperlink\darg{retire}\{Welcome, \$\string\dots\$ to my humble}% +\begin{dCmd*}{\bxSize} +\mlhyperlink{retire}{Welcome, $\dots$ to my humble +retirement residence, such as it is!} +\end{dCmd*} +\eVerb In this example, the line is broken at a hyphenation, cool! We jump to +the named destination, \texttt{retire}. On the last page, +the following text appears +\begin{quote} +\verb!My humble retirement \hypertarget{retire}{home}.! +\end{quote} +creating the named destination of \texttt{retire}. + +\subsection{\cmdtitle{mlhyperref}}\label{ss:mlhyperref} +A multi-line version of the \cs{hyperref} command. + +\bVerb\takeMeasure{\string\mlhyperref[\#1]\darg{\#2}\darg{\#3}}% +\begin{dCmd}{\bxSize} +\mlhyperref[#1]{#2}{#3} +\end{dCmd} +\endgroup +\PD The first parameter is optional, and is used to set the +appearance, but \textit{not the actions} of the link. The second +parameter is a label name created by the \cs{label} command of +\LaTeX. The third parameter is the text around which the link is +constructed. + +\CmdDescription This is the multi-line version of \cs{hyperref}, the command +defined by the \pkg{hyperref} package. The default appearance is the same +as \cs{hyperref}. The action of this link is to jump to a destination created +by the \cs{label} command of the cross-referencing system of \LaTeX; the +action cannot be changed by defining a different action through the first +parameter. + +\newtopic +This link uses the \cs{mlhyperref} command: \mlhyperref[\ui{linktxtcolor=red}]{retirement} +{Welcome! Welcome to my humble retirement residence, such as it is!} + +\bVerb\takeMeasure{\string\mlhyperref[\string\ui\darg{linktxtcolor=red}]\darg{retirement}}% +\begin{dCmd*}{\bxSize} +\mlhyperref[\ui{linktxtcolor=red}]{retirement} +{Welcome! Welcome to my humble retirement +residence, such as it is!} +\end{dCmd*} +\eVerb The user-friendly interface is used to change the appearance of the +color of the link text. The second argument is \texttt{retirement}, which is +the label +affixed to the last section of this document, +\begin{quote} +\verb!\section{My \textbf{Retirement} Home}\label{retirement}! +\end{quote} +See \mlNameref{retirement}. + + +\subsection{\cmdtitle{mlnameref}} A multi-line version of the \cs{nameref} command. + +\bVerb\takeMeasure{\string\mlnameref[\#1]\darg{\#2}}% +\begin{dCmd}{\bxSize} +\mlnameref[#1]{#2} +\end{dCmd} +\endgroup + +\PD The first parameter is optional, and is used to set the appearance, but + \textit{not the actions} of the link. The second parameter is a name of + a {\LaTeX} label. + +\CmdDescription This is the multi-line version of the +\pkg{hyperref} (\pkg{nameref}) command, \cs{nameref}. The default appearance is +the same as \cs{hyperref}. The action of this link is to jump to a +destination created by the \cs{label} command of the +cross-referencing system of \LaTeX; the action cannot be changed by +defining a different action through the first parameter. + +\newtopic +This link uses the \cs{mlnameref} command: Click the link to witness \mlnameref{retirement}. +The code for this link is seen below: +\bVerb\takeMeasure{\string\mlnameref\darg{retirement}}% +\begin{dCmd*}{\bxSize} +\mlnameref{retirement} +\end{dCmd*} +\endgroup + +\subsection{\cmdtitle{mlNameref}} A multi-line version of the +\pkg{hyperref} command, \cs{Nameref}. + +\bVerb\takeMeasure{\string\mlNameref[\#1]\darg{\#2}}% +\begin{dCmd}{\bxSize} +\mlNameref[#1]{#2} +\end{dCmd} +\endgroup +\PD The first parameter is optional, and is used to set the + appearance, but \textit{not the actions} of the link. The second + parameter is a name of a {\LaTeX} label. + +\CmdDescription This is the multi-line version of the \pkg{hyperref} +(\pkg{nameref}) command, \cs{Nameref}. The default appearance is the same as +\cs{hyperref}. The action of this link is to jump to a destination created by +the \cs{label} command of the cross-referencing system of \LaTeX; the action +cannot be changed by defining a different action through the first parameter. + +\newtopic +This link uses the \cs{mlNameref} command: Click the link or go to +the page, \mlNameref{retirement}. The code for the link is seen below: +\bVerb\takeMeasure{\string\mlNameref\darg{retirement}}% +\begin{dCmd*}{\bxSize} +\mlNameref{retirement} +\end{dCmd*} +\endgroup + +\subsection{\cmdtitle{mlhref}} A multi-line version of the +\pkg{hyperref} command, \cs{href}. +\bVerb\takeMeasure{\string\mlhref[\#1]\darg{\#2}\darg{\#3}}% +\begin{dCmd}{\bxSize} +\mlhref[#1]{#2}{#3} +\end{dCmd} +\endgroup + +\PD The first parameter is optional, and is used to set the + appearance, but \textit{not the actions} of the link. The + second parameter is a URL, while the third parameter is the link text. + +\CmdDescription This is the multi-line version of the +\pkg{hyperref} command, \cs{href}. The default appearance is +the same as \cs{hyperref}. There is one of three actions, depending on the +third argument, just as with \cs{href}. The action cannot be changed by +defining a different action through the first parameter. + +%\begingroup +%\makeatletter +%\def\Hy@temp#1{\expandafter\Hy@@temp\csname @#1color\endcsname{#1}} +%\Hy@temp{link}{red} +%\Hy@temp{anchor}{black} +%\Hy@temp{cite}{green} +%\Hy@temp{file}{cyan} +%\Hy@temp{url}{magenta} +%\Hy@temp{menu}{red} +%\makeatother + +\newtopic +The next link uses the \cs{mlhref} command with URL: \mlhref{% +http://www.math.uakron.edu/~dpstory/acrotex.html#educational} +{See the educational offerings of the {Acro\negthinspace{\TeX}} Web +Site at the University of Akron} +\bVerb\takeMeasure{\{See the educational offerings of the \darg{Acro\string\negthinspace\darg{\string\TeX}} Web}% +\begin{dCmd*}{\bxSize} +\mlhref{% +http://www.math.uakron.edu/~dpstory/acrotex.html#educational} +{See the educational offerings of the {Acro\negthinspace{\TeX}} Web +Site at the University of Akron} +\end{dCmd*} +\eVerb +Use the \cs{mlhref} command with mailto URL: My email address at Acro\negthinspace\TeX.Net, +\mlhref{mailto:dpstory@acrotex.net}{dpstory at acrotex dot net}. +\bVerb\takeMeasure{\string\mlhref\darg{mailto:dpstory@acrotex.net}\darg{dpstory at acrotex dot net}}% +\begin{dCmd*}{\bxSize} +\mlhref{mailto:dpstory@acrotex.net}{dpstory at acrotex dot net} +\end{dCmd*} +\eVerb +If the second argument is a PDF file, the PDF viewer will open it from your local file system, +or if you are in a browser, will open it from the web, provided it can find the relative path +\bVerb\takeMeasure{shameless advertisement for Acro\string\negthinspace\string\TeX\}.}% +\begin{dCmd*}{\bxSize} +\mlhref{shameless_ad.pdf}{Here is a +shameless advertisement for Acro\negthinspace\TeX}. +\end{dCmd*} +\eVerb If the key word `\texttt{run:}' is used, the link is set up to launch +an application. The PDF viewer will attempt to open the file with the +application associated with the extension of the file provided. +\bVerb\takeMeasure{\string\mlhref\darg{run:\string\jobname.tex}\darg{This is the source file of this document}.}% +\begin{dCmd*}{\bxSize} +\mlhref{run:\jobname.tex}{This is the source file of this document}. +\end{dCmd*} +\endgroup + +\subsection{\cmdtitle{mlurl}}\label{ss:mlrul} + +A multi-line version of the \cs{url} command of the \pkg{url} package. +The \pkg{hyperref} modifies this command to make it into an unbreakable link (at least for those +using \app{Distiller}). +\bVerb\takeMeasure{\string\mlurl[\#1]\darg{\#2}}% +\begin{dCmd}{\bxSize} +\mlurl[#1]{#2} +\end{dCmd} +\endgroup + +\PD The first parameter is optional, and is used to set the + appearance, but \textit{not the actions} of the link. The + second parameter is a URL, the text of the link is the same as the URL. + +\CmdDescription This is the multi-line version of the +\pkg{url}/\pkg{hyperref} command, \cs{hurl}. The default appearance is +the same as set by \cs{hyperref}. + +\newtopic +The next link is an example of \cs{mlurl}: +\mlurl{http://www.math.uakron.edu/~dpstory/acrotex.html#educational}. The code for this link is found below: +\bVerb\takeMeasure{\string\mlurl\darg{http://www.math.uakron.edu/\string~dpstory/acrotex.html\#educational}}% +\begin{dCmd*}{\bxSize} +\mlurl{http://www.math.uakron.edu/~dpstory/acrotex.html#educational} +\end{dCmd*} +\eVerb The \pkg{url} package typesets the URL in math mode, which makes it +very difficult to wrap it to the next line with a hypertext link around it. +In math mode, spaces are ignored; consequently, if the URL contains spaces, +use \verb!\%20! (with backslash), the URL encoding for the space character. +See the Internet reference +\mlurl{http://www.w3schools.com/tags/ref_urlencode.asp} for a discussion of +the \textbf{\caps{HTML URL Encoding Reference}}. + + +\exSrc{mlink_tst_url}The demo file that illustrate all the commands to +follow is \texttt{mlink\_tst\_url.tex}. Additional details and examples are found in this +example file. + +\section{Setting the appearance and action} + +The appearance and the action (at least for \cs{mlhypertex}) can be set through the first +optional parameter. The optional parameter takes key-value pairs of two types: +\paragraph*{Key-value Pairs.} The optional first parameter of each of the form and link commands take +two styles of key-values: +\begin{enumerate} + \item eForms KVP: This is the key-value system originally developed, where each KVP has the form + \cs{\anglemeta{key}\darg{\anglemeta{val}}}. Through these keys, the appearance + and action of a link---if otherwise not restricted---may be set. + For example, \mlhypertext[\S{U}\W{1}\Color{0 0.6 0} + \linktxtcolor{webgreen} \A{\JS{app.alert("AcroTeX + rocks!")}}]{AcroTeX can be found at + \texttt{www.acrotex.net}, as close as your nearest web + browser.} +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] +\mlhypertext[\S{U}\W{1}\Color{0 0.6 0}\linktxtcolor{webgreen} +\A{\JS{app.alert("AcroTeX rocks!")}}]{AcroTeX...browser.} +\end{Verbatim} + + An alternative link format is to provide a visible rectangle; \mlhypertext[\W1\linktxtcolor{} + \Color{red}\A{\JS{app.alert("Wrap the link!")}}]{Use a link with a non-zero boundary size along + with {\protect\cs{S\string{S\string}}}, which is the default.} +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] +\mlhypertext[\W1\linktxtcolor{}\Color{red} +\A{\JS{app.alert("Wrap the link!")}}]{Use a ... boundary size.} +\end{Verbatim} + + The eForms KVP system is explained in the eforms manual, + \textsl{\mlhref{http://www.math.uakron.edu/~dpstory/acrotex/eformman.pdf}{Support for AcroForms and Links, and for Document JavaScript and Open Page Events}},\footnote + {\url{http://www.math.uakron.edu/~dpstory/acrotex/eformman.pdf}} + where a complete listing of all supported KVPs is found in the appendices. + + + \item \pkg{xkeyval} KVP: When the \opt{useui} option is taken of the eforms package, key-value pairs are + defined of the form \texttt{\anglemeta{key}[\,=\,\anglemeta{value}]}. The key-value pairs are actually a value of + a special eForms key, \cs{ui}. The value of \cs{ui} consists of a comma-delimited list of + \pkg{xkeyval} key-value pairs. For example, + \mlsetLink[\ui{% + border=visible, + linestyle=underlined, + bordercolor={0 0.6 0}, + linktxtcolor=webgreen, + js={app.alert("AcroTeX rocks!")}}]{AcroTeX + can be found at \texttt{www.acrotex.net}, as + close as your nearest web browser.} +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] +\mlsetLink[\ui{% + border=visible, + linestyle=underlined, + bordercolor={0 0.6 0}, + linktxtcolor=webgreen, + js={app.alert("AcroTeX rocks!")}}]{AcroTeX...browser.} +\end{Verbatim} + \item[] The \pkg{xkeyval} KVP system is described in the document + \textsl{\mlhref{http://www.math.uakron.edu/~dpstory/acrotex/eformman.pdf}{Support for AcroForms and Links, and for Document JavaScript and Open Page Events}}.\footnote + {ibid.} +\end{enumerate} + +\paragraph*{Keys special to the \pkg{aeb\_mlink} package.} The following links are defined +within \pkg{eforms}, but are only obeyed from within the option list of one of the +\cs{ml\ameta{cmdname}} commands. +\begin{itemize} +\item \cs{mlfix\darg{\ameta{\upshape{y|n}}}} (\pkg{xkeyval} KVP: \texttt{mlfix=\ameta{\upshape{yes|no}}})\\ + If \cs{mlfix\darg{y}} is specified, contiguous bounding rectangles are combined; otherwise they are not. + See Section~\ref{s:FixQuads} for more information. +\item \cs{mlstrut\darg{\ameta{some-strut}}} (\pkg{xkeyval} KVP: \texttt{mlstrut=\ameta{some-strut}})\\ + The value of this key sets the height of the bounding rectangles; the default is \cs{strut}. See + Section~\ref{s:FixQuads} for detains and examples. +\item \cs{mlcrackat\darg{\ameta{num}}} (\pkg{xkeyval} KVP: \texttt{mlcrackat=\ameta{num}})\\ + This key is use to crack (or break) an hypertext or url into two links. + The application is to enable the link to break across a page boundary. Refer + to the paragraph \textbf{\mlnameref{para:xpage}}, beginning on page~\pageref{para:xpage} + for more information on \cs{mlcrackat}. +\item \cs{mlhyph\darg{\ameta{\upshape{y|n}}}} (\pkg{xkeyval} KVP: \texttt{mlhyph=\ameta{\upshape{yes|no}}})\\ + When the \cs{mlcrackat} option is used, an hyphen is inserted provided \cs{mlhyph{y}}, otherwise, no hypen + is inserted. Refer to the paragraph \textbf{\mlnameref{spara:fixxpage}}, page~\pageref{spara:fixxpage}, for + an example. +\item \cs{mlcrackinsat\darg{\ameta{text}}} (\pkg{xkeyval} KVP: \texttt{mlcrackinsat=\ameta{text}})\\ + The value \ameta{text} of this key is inserted after the break point, when + \cs{mlcrackat} is used. Normally, nothing is inserted after the brake point. +\end{itemize} + +\section{Fixing the quad points}\label{s:FixQuads} + +In versions of \pkg{aeb\_mlink} prior to 2018/03/19, the each syllable +(possible break point) of multi-line text was enclosed in a bounding +rectangle (described by the coordinates of its four corners). For example, it +is well known that \mlhypertext[\A{\JS{app.alert("And so it +is");}}\mlfix{n}\linktxtcolor{}\W1\H{O}\S{S}\Color{red}]{the acrotex website +is free to all who dare to enter.} Now you see the individual bounding +rectangles; they are all linked together, if you click on one of them, they +all react. + +Beginning with the version of \pkg{aeb\_mlink} dated 2018/03/19, Postscript +code was introduced to fix up these bounding boxes so that all syllables +\emph{on the same line} are enclosed in a single bounding rectangle. +\mlhypertext[\A{\JS{app.alert("And so it is");}}\linktxtcolor{}\W1\H{O}\S{S}\Color{red}]{If we turn on this feature +and declare the acrotex website is free to all who dare to enter.} Very cool! + +\exAeBBlogPDF{p=1377} The demonstration document for these feature is found on the +\href{\urlAcroTeXBlog}{{\AcroTeX} Blog} web site. Refer to the article +titled \textsl{\href{\urlAcroTeXBlog?p=1377}{Fixing multi-line link boxes}}. + + +\paragraph*{Turning the fix on and off.} The feature of fixing up these +little rectangles into one rectangle per line is controlled by the commands +\cs{mlfixOn} and \cs{mlfixOff}; the first turns on the fix up, the second +turns it off. The default is \cs{mlfixOn}. These two commands turn on or off +the fix up for the document (or within a group), to turn the fix on or off +for an individual link, use the key-value pairs \verb~\mlfix{y}~ to turn on +the fix and \verb~\mlfix{n}~ to turn it off. These key-values are placed as +an optional argument of any of the \cs{ml\ameta{cmdname}} commands. For +example, +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars={!@^}] +\mlhypertext[!textbf@\mlfix{n}^\A{\JS{app.alert("And so it is");}} +\linktxtcolor{}\W1\H{O}\S{S}\Color{red}]{the acrotex website is +free to all} +\end{Verbatim} +The user-friendly counterpart is \texttt{mlfix=\ameta{\upshape{yes|no}}}. + +\paragraph*{Changing the vertical size of the rectangles.} The default height +and depth of the boxes are determined by \cs{strut}, in the current font +size. A \emph{new key is introduced}, \cs{mlstrut\darg{\ameta{some-strut}}}. +You can simple increase the vertical dimensions of the boxes by +\verb~\mlstrut{\large\strut}~ or \verb~\mlstrut{\huge\strut}~. +\mlhypertext[\A{\JS{app.alert("And so it is");}}\mlstrut{\large\strut}\linktxtcolor{}\W1\H{O}\S{S}\Color{red}] +{The acrotex website is free to all} link should have vertically expanded rectangles. +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars={!@^}] +\mlhypertext[!textbf@\mlstrut{\large\strut}^ +\A{\JS{app.alert("And so it is");}} +\linktxtcolor{}\W1\H{O}\S{S}\Color{red}]{The acrotex website +is free to all} +\end{Verbatim} +When the link is underlined (\verb~\S{U}~) the depth is set to 1bp. These +changes to the vertical size of the rectangles do not affect any text +positioning of the content, only the bounding boxes. + +\texttt{mlstrut=\ameta{some-strut}} is the counterpart to + \cs{mlstrut\darg{\ameta{some-strut}}} in the user-friendly key-value system. + +The \ameta{some-strut} argument can be anything that takes up vertical space, any horizontal space is ignored. +For example, \mlhypertext[\mlstrut{$\displaystyle\int_0^\pi$}\linktxtcolor{}\W1\H{O}\S{S}\Color{red} +\A{\JS{app.alert("No action defined, other than this one.")}}]{``The integral +{$\displaystyle\int_0^\pi \sin(x)\,dx$} has a value of a crummy little $2$.''} +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +\mlhypertext[\mlstrut{$\displaystyle\int_0^\pi$}\linktxtcolor{}\W1\H{O} +\S{S}\Color{red}]{``The integral {$\displaystyle\int_0^\pi \sin(x)\,dx$} +... $2$.''} +\end{Verbatim} + +\paragraph*{Important:} When the feature of fixing the +rectangles is active (with \cs{mlfixOn} or locally with \cs{mlfix\darg{y}}), +you need to \emph{compile the document at least three times} before +distilling the document; otherwise distiller fails. There are commands +written to the \textsf{AUX} file that needs to be up to date. This is only +needed after you modify any of the multi-line hypertext links. There are +{\LaTeX} warning messages written to the {\TeX} log to inform you if the +links are not fully formed; there are also messages in the distiller log. +Setting the package option \texttt{dblevel=1} can increase the amount of +feedback you get through the distiller log. + +\paragraph*{Marking the links.} You can run into trouble with one or more of the links. There +may be tex log or distiller log messages referring to the link number (e.g., +\texttt{mLink30}), but where is this link? By expanding \cs{mlMarksOn}, you +turn on the marking of the links. I'm turning on link marking for the rest of +the document. Look for `L\ameta{num}' beginning in section~\ref{ss:probs}. +Turn marking back off with \cs{mlMarksOff}. Above the starting point of each +link will be a tiny `L\ameta{num}'. The format for this little `L\ameta{num}' +is determined by the internal command \cs{ml@MrkLnk}; it may redefined as +desired. + + +\paragraph*{Viewing the syllable numbers.} You can display the syllable numbers of multi-line +hypertext by expanding \cs{turnSyllbCntOn}; \cs{turnSyllbCntOff} turns off this feature again. +For example, we expand \cs{turnSyllbCntOn} in a group: +\begin{quote} +\turnSyllbCntOn\mlhypertext{We have set {\cs{turnSyllbCntOn}} +in a group so the effects are not felt after the group}. +\end{quote} +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] +\begin{quote}\turnSyllbCntOn +\mlhypertext{We have set {\cs{turnSyllbCntOn}} in a +group so the effects are not felt after the group}. +\end{quote} +\end{Verbatim} +The sentence has 10 syllables, as counted by \pkg{soul} and \pkg{aeb\_mlink}. It should be noted that +\cs{turnSyllbCntOn} also executes \cs{mlMarksOn}. This feature may be useful for determining where to +break a link across pages, see the next paragraph. + +Notice we've enclose \verb~\cs{turnSyllbCntOn}~ in braces, as a reault, \pkg{soul} treats the contents +as a single syllable. If we want to break this long command across a line (or page), we would have to register +the command \cs{cs} with \cs{soulregister}: +\begin{quote}\turnSyllbCntOn\soulregister{\cs}{1} +\mlhypertext[\A{\JS{app.alert("...and it was so")}}]{Register \cs{cs} with \cs{soulregister} to have the command name \cs{turnSyllbCntOn} +break across lines (or pages).} +\end{quote} +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small] +\begin{quote}\turnSyllbCntOn\soulregister{\cs}{1} % global declaration +\mlhypertext{Register \cs{cs} with \cs{soulregister} to have +the command name \cs{turnSyllbCntOn} break across lines (or pages).} +\end{quote} +\end{Verbatim} + + +\mlMarksOn + +\paragraph*{Multi-line links that break across pages.}\label{para:xpage} This phenomenon is not +supported by the PDF Reference. These kinds of links can be created by +{\LaTeX} when the link is near the bottom of the page and {\LaTeX} moves a +portion of it to the next page. \pkg{aeb\_mlinks} detects this when the +document is distilled and places a message in the distiller (or \app{ps2pdf}) log. If you have +a link that crosses page boundaries, you need to reword the paragraph to +avoid this. The message reads,\goodbreak +\begin{Verbatim}[fontsize=\small] +Beginning of page: 3 +!!------------------------------------------------------------------ +Warning: +The text of mLink4 has crossed a page boundary from page 2 to 3. +Cross page links are not supported by the PDF Specification. +This link is not constructed, please fix it. +Break point is after syllable number 4. +Use the \mlcrackat{4} option with this link. +!!------------------------------------------------------------------ +\end{Verbatim} +and can't be missed. The link is not constructed. You can see here, there is a reference +to \texttt{mLink4}. You need to turn on link marking (\cs{mlMarksOn}) or just go to page~2 +and look at the bottom of the page. + +\subparagraph*{Fixing a cross-page link.}\label{spara:fixxpage} There are a couple of action choices you can +take to fix a link that has crossed a page boundary: (1) rewrite the +paragraph so the link does not cross the page boundary; (2) manually break the link; (3) do as the log file suggests, you +can use the \cs{mlcrackat\darg{4}} option. In this latter case, for example, +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +\mlhypertext[\mlcrackat{4}\mlhyph{y}!ameta(other-opts)] + {Doctor Story created the acrotex website.} +\end{Verbatim} +\begin{quote}\turnSyllbCntOn\def\pb{\penalty-10 \\\rule[2pt]{\linewidth-\widthof{\ (page break)}}{.4pt}\ \makebox[0pt][l]{(page break)}\\[3pt]}% +\ameta{latex-content}\dotfill\mlhypertext[\mlcrackat{4}\mlhyph{y}\mlcrackinsat{\pb}] + {Doctor Story created the acrotex website.} +\end{quote} +Two links are created, the first consisting of the text `Doctor Story cre-' +and the second on `ated the acrotex website.'; the second link (should) be +inserted on the next page. The link option \cs{mlhyp\darg{y}} inserts a +hyphen at the break point; for URLs, a hyphen may not be appropriate. +\textbf{Question:} What is the missing \ameta{other-opts} in the above example? + +%\kern7pt + +\exAeBBlogPDF{p=1383}\textbf{ A working document:} The demonstration document +for breaking links across pages is found on the +\href{\urlAcroTeXBlog}{{\AcroTeX} Blog} web site. Please refer to the +article titled +\textsl{\mlhref{\urlAcroTeXBlog?p=1377}{Crossing page +boundaries with multi-line links}}. Many other articles on {\AEB} and {\PDF} +can be found at the \href{\urlAcroTeXBlog}{{\AcroTeX} Blog} web site, as +well. + +%\normalcolor + +\paragraph*{Reverting to the old style.} +The restriction of having to compile multiple times before +distillation may be a burden when it comes to developing a document. You can +declare \cs{OldStyleBoxesOn} in the preamble to revert to the old style that +does not use the information written to the auxiliary file. After document +development and the text of all links are stable, you can then say +\cs{OldStyleBoxesOff} (or comment out \cs{OldStyleBoxesOn}) in the preamble. +Compiling then yields the better formed and combined bounding rectangles. + +\paragraph*{Minimally sized \texttt{/Rect}.} For multi-line links, the link +annotation contains two entries containing dimensions of rectangles, the +\texttt{/Rect} and \texttt{/QuadPoints} entries. Our focus in this paragraph +is on \texttt{/Rect}; there are two possible values for \texttt{/Rect}: (1) +the dimensions of the entire page, which has been the default value since the +inception of this package, or (2) the dimensions of the smallest rectangle +containing all the hypertext, the new default.\smallskip + +\noindent\strut{\fboxsep0pt\fcolorbox{blue}{white}{\parbox{\linewidth} +{\hskip\amtIndent For example, the following link is constructed using +\cs{mlhypertext}: \mlhypertext[\A{\JS{app.alert("AcroTeX rocks with minimal rectangles!")}}]% +{Acrobat Distiller, version~7.0 or greater} was used to +create this PDF document. The blue rectangle}}} is a representation of the `unseen' \texttt{/Rect} +dimensions. It is the smallest rectangle that contains the hypertext. You can revert to the old +default (the whole page) by expanding \cs{useSmallRectOff}, the default is \cs{useSmallRectOn}.\medskip + +\textbf{The importance of small rectangles.} In the current age we live in, +web browsers have their own `native' PDF viewers. These viewers generally do +not obey JavaScript actions but they do recognize basic actions such as +jumping to the destination in the document; however, they ignore the +\texttt{/QuadPoints} entry in a link, and respect only the \texttt{/Rect} +entry. In a `native' viewer, following a multi-line link may be problem when +the \texttt{/Rect} entry is set the whole page. Now, the \texttt{/Rect} is +the minimal rectangle, and following a link should not be an issue as long as +\emph{one rectangle is not contained within another}. Multi-line links are +fully supported by \app{Adobe Acrobat Reader}. + +\paragraph*{Tricky bits.} The use of \cs{mlnameref} and \cs{mlNameref} can be tricky when +the referenced label contains special commands or font changes. Two tricks +are to enclose the bad bits in braces (\texttt{\darg{}}) and/or \cs{protect} +commands. Section or paragraph commands that end up as PDF bookmark need to use +the \pkg{hyperref} command \cs{texorpdfstring}. To illustrate, an dummy subsection +is introduced, and the discussion on this topic is continued there. + + +\subsection{Discussion of \texorpdfstring + {{\protect\cs{mlnameref}}, {\protect\cs{mlNameref}}, and {\protect\cs{mlhypertext}}} + {\textbackslash{mlnameref}, \textbackslash{mlNameref}, and \textbackslash{mlhypertext}}}\label{ss:probs} + +To illustrate, we reference the section title ``\mlnameref{ss:probs}.'' The verbatim listing of this subsection is +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +\subsection{Discussion of problems with \texorpdfstring + {{\protect\cs{mlnameref}}, {\protect\cs{mlNameref}}, + and {\protect\cs{mlhypertext}}} + {\textbackslash{mlnameref}, \textbackslash{mlNameref}, + and \textbackslash{mlhypertext}}}\label{ss:probs} +\end{Verbatim} +Observe the use of \cs{texorpdfstring}, the first argument is typeset, the second +one is placed in the bookmarks. +\begin{itemize} + \item On the first argument of \cs{texorpdfstring}, we focus our comments + on the first \verb~{\protect\cs{mlnameref}}~ of the three commands + referenced. Note that it is enclosed in braces that signals the + \opt{soul} package, which does the parsing, to treat it as an + unbreakable unit. The control sequence \cs{cs} is protected by + \cs{protect}. Finally \cs{cs} is a command that produces a backslash in + front of its argument in monospace font. + + There are two `common' definitions of \cs{cs}-style commands: + \begin{itemize} + \item \verb~\def\cs#1{\texttt{\char`\\#1}}~ + \item \verb~\def\cs#1{\texttt{\@backslashchar#1}}~ (used in this manual) + \end{itemize} + The latter definition must be the one used within a section title, not the first one. + + The \pkg{aeb\_mlinks} defines \cs{mlcs} using the second version; that + is \begin{flushleft}\hskip\amtIndent\verb~\def\mlcs#1{\texttt{\@backslashchar#1}}~\end{flushleft} is defined. In + this way both definitions for \cs{cs} are available. The \cs{mlcs} + version must be used in text that can be referenced by \mlcs{mlnameref} + or \mlcs{mlNameref}. +\end{itemize} +In the above title declaration, if any of the components (the braces, the \cs{protect}, and the special +definition of \cs{cs}) {\LaTeX} compilation errors occur. + +Similar comments are made for \cs{mlhypertext}, \cs{mlhyperref}, and \cs{mlhyperlink}. These three take +a text phrase as its `hypertext' string. For example, +``\mlhyperref[\linktxtcolor{}\Color{red}\S{S}\W1]{ss:mlhyperref}{The exciting world of {\protect\mlcs{mlhyperref}} is average wonderful.}'' +\begin{Verbatim}[xleftmargin=\amtIndent,fontsize=\small,commandchars=!()] +\mlhyperref[\linktxtcolor{}\Color{red}\S{S}\W1]{ss:mlhyperref}{The + exciting world of {\protect\mlcs{mlhyperref}} is average wonderful.} +\end{Verbatim} +Notice the braces, the \cs{protect}, and the use of \cs{mlcs}; they work +together for a successful link construction. + +\newpage + +\section{My \textbf{Retirement} Home}\label{retirement} + +My humble retirement \hypertarget{retire}{home}. +\begin{flushleft} +\setLink[\H{N}\A{\Named{GoBack}}]{\includegraphics[scale=.5]{DSC01404}}\quad \raisebox{75pt}{\textbf{Click image to return from jump}} +\end{flushleft} + + +\newtopic\noindent +Now, I simply must get back to my retirement. \dps + +\end{document} + +\def\mlMaxNSylls{30} diff --git a/macros/latex/contrib/aeb_mlink/examples/mlink_tst.pdf b/macros/latex/contrib/aeb_mlink/examples/mlink_tst.pdf Binary files differnew file mode 100644 index 0000000000..02be88e97a --- /dev/null +++ b/macros/latex/contrib/aeb_mlink/examples/mlink_tst.pdf diff --git a/macros/latex/contrib/aeb_mlink/examples/mlink_tst.tex b/macros/latex/contrib/aeb_mlink/examples/mlink_tst.tex new file mode 100644 index 0000000000..e2a2a4ec43 --- /dev/null +++ b/macros/latex/contrib/aeb_mlink/examples/mlink_tst.tex @@ -0,0 +1,150 @@ +\documentclass{article} +\usepackage[fleqn]{amsmath} +\usepackage[designi]{web} +\usepackage{eforms} +\usepackage{aeb_mlink} +\usepackage{multicol} + +\renewcommand\hproportionwebtitle{.75} +\renewcommand{\titleauthorproportion}{.5} + + +\title{Demonstrating the \textsf{aeb\_mlink} Package\texorpdfstring{\\[3pt]}{: }A member of AeB Pro} +\author{D. P. Story} +\subject{Multi-line links using the AcroTeX eDucation Bundle} +\keywords{AeB, multi-line links} + +\university{NORTHWEST FLORIDA STATE COLLEGE\\ + Department of Mathematics} +\email{storyd@nwfsc.edu} +\version{2.2} +\revisionLabel{} + +\newcommand{\cs}[1]{\texttt{\char`\\#1}} + +\flJSStr\Msgi{First Link\\n\\nLet's try another! J\\374rgen and with unicode J\\u00FCrgen} +\flJSStr\Msgii{Success! Multi-line links with hyphenation!\\n\\nCongrats, J\\u00FCrgen} +\flJSStr\Msgiii{I said, \\"No, they won't work.\\"...I'm wrong again.} + +% \mlMarksOn + + +\begin{document} + +\maketitle + +\section{Introduction} + + +This file tests and demonstrates new macros for creating hypertext +links that wrap around a line. Most of the text is nonsense, and was +created to fill the page, no offence taken I hope + +This paragraph contains two links that go beyond the +\mlhypertext[\S{U}\W{1}\Color{0 .6 0}\A{\JS{app.alert(\Msgi);}}]{margins of this text width} so it wraps around to the +next line. Now, I'll \mlhypertext[\A{\JS{app.alert("Second +Link")}}]{insert a multi-line link.}\footnote{Techniques by D. P. +Story} Can we continue with this? Yes, so says D. P. Story. + +This paragraph contains two links that go beyond the +\mlhypertext[\A{\JS{app.alert("Third Link")}}]{margins of this text width}, +so it wraps around to the next line. Let's try a numbered equation: +\begin{equation} + \boxed{x + y = 1} +\end{equation} +Now, with your permission, I'll insert another one of these +\mlhypertext[\A{\JS{app.alert("Fourth Link")}}]{links of the +multiline type.}\footnote{D.P. Story is very nice fellow, but he has a rather +\mlhypertext[\A{\JS{app.alert("Footnote!")}}]{grand head; we must watch the +compliments} so we don't inflate his ego more.} Can we continue with +this? Yes, so says D. P. Story. + +%\turnSyllbCntOn + +On the next page, we try multiple column format. +\mlhypertext[\mlcrackat{3}\S{U}\W{1}\Color{0 0.6 0}\A{\JS{app.alert(\Msgii)}}]{Welcome my friends to my residence, humble as it is. The encyclopedia is a wonderful book.} +We shall study it closely during your visit. + +Try this great link: \mlhypertext[\A{\JS{app.alert("Yes, they do!");}}]{J\"{u}rgen, \LaTeX{} and +math \mbox{\smash[b]{$\displaystyle\int_0^1 f(x)\,dx$}} work admirably.} + + +\parskip0pt + +\begin{multicols}{2} +\noindent Being able to create multi-line links becomes important when the +\texttt{\string\linewidth} is narrow. On this page we create some +mindless text that will fill up all or part of the page, then create +some multi-line links. + +Without a doubt, \textsl{this method will fail if the paragraph contains +multi-line links that crosses a \emph{page boundary} or a \emph{\mlhypertext[\A{\JS{app.alert("Wrong again! However, there are problems +with page boundaries.");}}]{column boundary}}}. + +This paragraph contains two links that extend beyond the +\mlhypertext[\A{\JS{app.alert("Fifth Link")}}]{margins of this text +width} which causes it to wrap around to the next line. Note the +hyphenation of the link, this is due to the \textsf{soul} package. +As a further test, I'll \mlhypertext[\A{\JS{app.alert("Sixth +Link")}}]{insert a multi-line link} again. Can we continue with +this? Yes, so says D. P. Story. + +\end{multicols} + + +\section{Second of Three Sections}\label{second} + +Let us begin by having page filling mindless text, +then we'll force a page break, but before we break, a friend of +mine, asked if multi-line links work with math formulas. A very strange request, +\mlhypertext[\A{\JS{app.alert(\Msgiii)}}]{$ x= f(t)$, $ x= g(t)$, $h(x) = e^x$}, very strange +indeed. Let's try. + +Use \LaTeX/hyperref system of cross-referencing +\mlnameref{three}. The last link is a modification of +the \texttt{\string\nameref} command from hyperref.The +\texttt{\string\Nameref} command can be duplicated +\mlNameref{three} as well. + +\newpage + +\section{Third of Three Sections}\label{three} + +The second section, oops, I've lost count. I have nothing to say in +this section. I take that back, below are notes and problem areas: + +\begin{enumerate} + \item It is possible to break multi-line links across page boundaries, see + the \href{http://www.acrotex.net/blog/?p=1383}{{Acro\!\TeX} Blog} article + \textsl{\mlhref{http://www.acrotex.net/blog/?p=1383}{Crossing page boundaries with multi-line links}} for a demo file of this. + \item See the \textsf{soul} package documentation for limitations on the arguments + of the \cs{mlxx} commands. + \item Works for footnotes + \item Can use verbatim text in a paragraph, \verb!$#}^!, + but cannot include verbatim in a multi-line link. Is + there any real need to do so? +\end{enumerate} + +\section{URLs} + +Let us try a URL across lines: \mlhref[\S{U}\W{1}\Color{0.6 0 0}]{% +http://www.math.uakron.edu/~dpstory/acrotex.html#educational} +{See the educational offerings of the {Acro\negthinspace{\TeX}} Web +Site at the University of Akron}. This link plays off the +\texttt{\string\href} \hypertarget{command}{command}. There is also the \cs{mlurl} +command, illustrated in the file \texttt{mlink\_tst\_url.tex}. + +We can also call a local file, let's try: \mlhref{shameless_ad.pdf}{Here +is a shameless advertisement for Acro\!\TeX}. + +Try launching a file now, let's try a \LaTeX{} file: +\mlhref[\S{U}\W{1}\Color{.6 0 0}]{run:\jobname.tex}{This is the +source file of this document}.\footnote{Source document needs to be in the folder +containing this PDF file.} + +Finally, let's try my own email address at Acro\!\TeX.Net, +\mlhref{mailto:dpstory@acrotex.net}{dpstory at acrotex dot net}. + +\href{run:np_test.txt}{Launch Notepad}\footnote{Windows system required.} + +\end{document} diff --git a/macros/latex/contrib/aeb_mlink/examples/mlink_tst_url.pdf b/macros/latex/contrib/aeb_mlink/examples/mlink_tst_url.pdf Binary files differnew file mode 100644 index 0000000000..b8467599ab --- /dev/null +++ b/macros/latex/contrib/aeb_mlink/examples/mlink_tst_url.pdf diff --git a/macros/latex/contrib/aeb_mlink/examples/mlink_tst_url.tex b/macros/latex/contrib/aeb_mlink/examples/mlink_tst_url.tex new file mode 100644 index 0000000000..926dda1b14 --- /dev/null +++ b/macros/latex/contrib/aeb_mlink/examples/mlink_tst_url.tex @@ -0,0 +1,48 @@ +\documentclass{article} +% compile with or without the colorlinks option +\usepackage{xcolor} +\usepackage[colorlinks]{hyperref} +\usepackage{aeb_mlink} + +\definePath{\urlAcroTeXBlog}{http://www.acrotex.net/blog} +\definecolor{webgreen}{rgb}{0,.6,0} + +\parindent0pt \parskip3pt + +\begin{document} + +In this demo file we test the \verb~\mlurl~ command. + +OK, let's see if we still wrap around the line +\mlurl{http://www.math.uakron.edu/~dpstory}. Now let's try another link, the following URL +\mlurl[\S{U}\W{1}\Color{0 .6 0}\linktxtcolor{webgreen}]{http://www.acrotex.net}, does it wrap? Yes, +but did the change in color also change the color of the next link: \setLink[\A{\JS{app.alert("Splendid, you clicked a link, a link to nowhere. The color of the link is as it should be.")}}\Color{1 0 0}]{Go There!} + +Let's try a footnote.\footnote{OK, lets see if we still wrap around the line, does it work? +\mlurl{http://www.math.uakron.edu/~dpstory}.} + +Here, we reference a \textsf{AeB Pro} articles \mlurl{\urlAcroTeXBlog/?tag=aeb-pro}. + +If the URL contains spaces, uses URL encoding, see \mlurl{http://www.w3schools.com/tags/ref_urlencode.asp}, for example. +In the next example, we use \verb~\%20~ for space, the normal \texttt{\%20} is a problem because \texttt{\%} +is still the {\LaTeX} comment character. + +Try a PDF with search: \mlurl{http://www.math.uakron.edu/~dpstory/acrotex/aeb_man.pdf#page=8% +&search=AcroTeX\%20web\%20exerquiz}. + +The comment character can be used to wrap a long URL to the next line without effecting the address, +as is done in the source file. + +Let's take that long URL and break it across the page. + +\vspace{23\baselineskip} + +%\turnSyllbCntOn + + +Try a PDF with search: \mlurl[\mlcrackat{8}]{http://www.math.uakron.edu/~dpstory/acrotex/aeb_man.pdf#page=8% +&search=AcroTeX\%20web\%20exerquiz} + +That's a long URL that has been broken across the page boundary. + +\end{document} diff --git a/macros/latex/contrib/aeb_mlink/examples/np_test.txt b/macros/latex/contrib/aeb_mlink/examples/np_test.txt new file mode 100644 index 0000000000..d9ea39964e --- /dev/null +++ b/macros/latex/contrib/aeb_mlink/examples/np_test.txt @@ -0,0 +1 @@ +This is a test document for notepad to open. diff --git a/macros/latex/contrib/aeb_mlink/examples/shameless_ad.pdf b/macros/latex/contrib/aeb_mlink/examples/shameless_ad.pdf Binary files differnew file mode 100644 index 0000000000..69a0444099 --- /dev/null +++ b/macros/latex/contrib/aeb_mlink/examples/shameless_ad.pdf |