summaryrefslogtreecommitdiff
path: root/texmf-dist/doc/latex/aeb-mlink/aebmlink_man.tex
blob: eab753c4b8ccf72c88017b2d066c030f4f418b15 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
% 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}