diff options
Diffstat (limited to 'texmf-dist/source/latex/aeb-mlink/doc/aebmlink_man.tex')
-rw-r--r-- | texmf-dist/source/latex/aeb-mlink/doc/aebmlink_man.tex | 873 |
1 files changed, 0 insertions, 873 deletions
diff --git a/texmf-dist/source/latex/aeb-mlink/doc/aebmlink_man.tex b/texmf-dist/source/latex/aeb-mlink/doc/aebmlink_man.tex deleted file mode 100644 index 5190c8fa..00000000 --- a/texmf-dist/source/latex/aeb-mlink/doc/aebmlink_man.tex +++ /dev/null @@ -1,873 +0,0 @@ -% 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{acroman} - -\def\amtIndent{15pt} - -\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, 2018/04/26}, - 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 - -\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. - -\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 several actions 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) 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} -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 an -hyphen at the break point. For URLs, a hyphen may not be appropriate. - -%\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 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} |