% 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\parindent} \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.6, 2020/07/12}, 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} 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. \newtopic\noindent Version 2.3.6 (dated 2020/07/12 or later) now allows an \pkg{aeb\_mlink} document to be compiled by \app{pdflatex}, \app{lualatex}, and \app{xelatex} without errors; however, all commands defined in the package do nothing other then to display their \ameta{text} with no links created. This makes it nice for the lovers of these drivers to compile the document with their favorite driver and view the PDF in their favorite PDF previewer, such as \app{SumatraPDF}. Later, the document author can switch over to a \app{latex\,->\,dvips\,->\ameta{\upshape{distiler\string|ps2pdf}}} workflow to acquire the multi-line link version. \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, it could be as small as two.) \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[\ameta{opts}]\darg{\ameta{text}}}% \begin{minipage}{\bxSize} \begin{Verbatim}[frame=single,rulecolor=\color{webblue},commandchars=!()] \mlhypertext[!ameta(opts)]{!ameta(text)} \end{Verbatim} \end{minipage}\quad\takeMeasure{\string\mlsetLink[\ameta{opts}]\darg{\ameta{text}}}% \begin{minipage}{\bxSize} \begin{Verbatim}[frame=single,rulecolor=\color{webblue},commandchars=!()] \mlsetLink[!ameta(opts)]{!ameta(text)} \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[\ameta{opts}]\darg{\ameta{named-dest}}\darg{\ameta{text}}}% \begin{dCmd}[commandchars=!()]{\bxSize} \mlhyperlink[!ameta(opts)]{!ameta(named-dest)}{!ameta(text)} \end{dCmd} \endgroup %[\ameta{opts}]\darg{\ameta{named-dest}}\darg{\ameta{text} %[!ameta(opts)]{!ameta(text)}[\ameta{opts}]\darg{\ameta{text}} \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[\ameta{opts}]\darg{\ameta{label}}\darg{\ameta{text}}}% \begin{dCmd}[commandchars=!()]{\bxSize} \mlhyperref[!ameta(opts)]{!ameta(label)}{!ameta(text)} \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[\ameta{opts}]\darg{\ameta{label}}}% \begin{dCmd}[commandchars=!()]{\bxSize} \mlnameref[!ameta(opts)]{!ameta(label)} \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[\ameta{opts}]\darg{\ameta{label}}}% \begin{dCmd}[commandchars=!()]{\bxSize} \mlNameref[!ameta(opts)]{!ameta(label)} \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[\ameta{opts}]\darg{\ameta{url}}\darg{\ameta{text}}}% \begin{dCmd}[commandchars=!()]{\bxSize} \mlhref[!ameta(opts)]{!ameta(url)}{!ameta(text)} \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 an 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[\ameta{opts}]\darg{\ameta{url}}}% \begin{dCmd}[commandchars=!()]{\bxSize} \mlurl[!ameta(opts)]{!ameta(url)} \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,commandchars={!@^}] \mlsetLink[\ui{% !quad@border=visible,^ !quad@linestyle=underlined,^ !quad@bordercolor={0 0.6 0},^ !quad@linktxtcolor=webgreen,^ !quad@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}