% 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}
