summaryrefslogtreecommitdiff
path: root/texmf-dist/doc/latex/fitr/fitr_man.tex
blob: 690f498f9a87e0b9842de2790a6beb0cba78d573 (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
% makeindex < aebpro_man.idx > aebpro_man.ind
\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage[
    web={centertitlepage,designv,forcolorpaper,
         usesf,latextoc,pro}, %tight,
    eforms,aebxmp
]{aeb_pro}
\usepackage{graphicx,array}
\usepackage[dvipsone,!preview,!viewMagWin]{fitr}
\usepackage[js=restoreHookBlink,js=jmpHookBlink]{lmacs}

\usepackage[fortextbook,usecustomdesign,nomarginwrite]{eqexam}

%\usepackage{myriadpro}
\usepackage[altbullet]{lucidbry}

\renewcommand\allowFXDefault{false}


%\usepackage{makeidx}
%\makeindex
\usepackage{acroman}

\makeatletter
\def\eq@fititin#1{\noindent\unskip\nobreak\hfill\penalty50
    \hskip2em\hbox{}\nobreak\hfill#1}
\def\fitit{\eq@fititin{\exrtnlabelformat}}
\@mparswitchfalse\reversemarginpar
\def\meta#1{$\langle\textit{\texttt{#1}}\rangle$}

\makeatother
%\usepackage[active]{srcltx}

\urlstyle{rm}
\def\fitrpkg{\textsf{f{i}tr}}

\DeclareDocInfo
{
    university={\AcroTeX.Net},
    title={\texorpdfstring{The}{The manual for the} f{i}tr Package\texorpdfstring{\\
        Defining and Jumping to\\a Rectangular Destination}{}},
    author={D. P. Story},
    email={dpstory@acrotex.net},
    subject=Documentation for the fitr package,
    talksite={\url{www.acrotex.net}},
    version={1.0},
    Keywords={LaTeX,PDF,fitr,JavaScript,Adobe Acrobat},
    copyrightStatus=True,
    copyrightNotice={Copyright (C) \the\year, D. P. Story},
    copyrightInfoURL={http://www.acrotex.net}
}
\DeclareInitView{windowoptions={showtitle}}


\def\dps{$\hbox{$\mathfrak D$\kern-.3em\hbox{$\mathfrak P$}%
   \kern-.6em \hbox{$\mathcal S$}}$}

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

%\pagestyle{empty}
\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}

\begin{document}

\maketitle

\selectColors{linkColor=black}
\tableofcontents
\selectColors{linkColor=webgreen}

\section{Introduction}

This package is an implementation of the \textbf{FitR} view-type
destination. The \textsl{PDF Reference} describes \textbf{FitR} as,
\begin{quote}
    Display the page designated by page, with its contents
    magnified just enough to fit the rectangle specified by the
    coordinates \textsl{left}, \textsl{bottom}, \textsl{right},
    and \textsl{top} entirely within the
    window both horizontally and vertically.
\end{quote}
The package supports the \textsf{dvips}, \textsf{dvipsone}, and
\textsf{pdftex}, \textsf{luatex}, \textsf{dvipdfm}, \textsf{dvipdfmx}, and
\textsf{xetex} applications, the first two assume that \textbf{Adobe
Distiller} is the PDF creator.

The only required packages are the \textsf{eforms} package (dated
2012/06/20 or later), which is part of the \textbf{AeB Bundle}, and
\textsf{collectbox} by Martin Scharrer, more on this package later, and
the ubiquitous \textsf{xcolor}.\footnote{The \textsf{eforms} package
itself brings in other packages, including \textsf{hyperref} and
\textsf{insdljs}.}

The package was developed in response to a user of the AeB Bundle who was
interested in developing documents for students with low vision; the idea
is to magnify regions of the document so the student can read more
comfortably. The demonstration files are \texttt{fitr\_demo.tex} which
illustrates the package and some special methods for people with low
vision, and \texttt{fitr\_minimal.tex}, which is the same demo file with
any and extra package stripped out.

\section{The Preamble and Package Options}

The minimal preamble for this package is
\begin{Verbatim}[xleftmargin=20pt,commandchars=!()]
\usepackage[!meta(driver),!meta(options)]{fitr}
\end{Verbatim}
The \textsf{hyperref} package is brought in through the \textsf{eforms} package.
Optionally, {\fitrpkg} can be used with other members of AeB (\textsf{web} and
\textsf{exerquiz}, for example).

Another package requirement is \textsf{collectbox} by Martin Scharrer;
quoting from the abstract of the documentation,
\begin{quote}
This package provides macros to collect and process an macro argument
(i.e. something which looks like a macro argument) as horizontal box
instead as a real macro argument. These ``arguments'' will be stored like
when using \cs{savebox}, \cs{sbox} or the \texttt{lrbox} environment and
allow verbatim or other special code. Instead of explicit braces also
implicit braces in the form of \cs{bgroup} and \cs{egroup} are supported.\dots
\end{quote}
The \cs{collectbox} command is used to collect the second argument of
\cs{jdRect}, see the discussion of \cs{jdRect} in Section~\ref*{jdRect}.
As a result, the second argument may contain verbatim text in it. Very cool.

The package has ten options: six driver options and four viewing
options.
\begin{itemize}
\item \textbf{Driver Options:} These are \texttt{dvips} (the default),
    \texttt{dvipsone}, and \texttt{pdftex} (which includes the use of
    lualatex), \texttt{dvipdfm}, \texttt{dvipdfmx}, and \texttt{xetex}. If you
    specify one of the first two, it is assumed that you are using
    \textbf{Adobe Distiller} as your PDF creator.

\item[] The \textsf{fitr} package checks whether the \textsf{web}
    package is loaded, if so, its uses the driver used by
    \textsf{web}; otherwise \textsf{fitr} auto-detects for
    \textsf{pdftex} and \textsf{xetex}. If no driver is passed, and
    neither \textsf{pdftex} nor \textsf{xetex} are detected, then
    \textsf{dvips} is the default driver.

\item \textbf{Viewing Options:} When you specify \texttt{preview}, the
bounding boxes of the buttons are shown in the dvi-previewer (or the PDF
document); you can turn off this preview by specifying \texttt{!preview}
(or removing \texttt{preview} entirely from the option list). The other
option type is \texttt{viewMagWin}, when this option the viewing window, a
rectangular region, becomes visible in the dvi-previewer (or in the PDF
document); specifying \texttt{!viewMagWin} turns off this type of preview.

\item[] The effects of the viewing options will be illustrated later in this
document, see \autoref{previewEx} on page~\pageref*{previewEx}.

\end{itemize}

\section{The one and only command}\label{jdRect}

The {\fitrpkg} has only one command, \cs{jdRect}, but there are two forms
of usage. \cs{jdRect} optionally creates a push button or link, and
optionally creates a viewing window. The term \emph{viewing window} refers
to a rectangular region that is created by the \textbf{FitR} destination
viewing specification, see \textbf{Table~8.2 Destination syntax} of the
\textsl{PDF Reference}, version 1.7. A \emph{named destination} is created
and is associated with the viewing window. When we jump to a viewing
window, this window is magnified to the largest extent possible. For
example, click on the either of the two displayed forms of the syntax for
\cs{jdRect}; after jumping to the viewing window, click on the same
display to return to the previous view.

%\previewtrue

There are two versions of \cs{jdRect}, the command itself, and a
\texttt{*} version, \cs{jdRect*}. The syntax follows, along with the
expected parameters.
\begin{quote}
    \jdRect*[adddestw=10bp,adddesth=10bp]{\cs{jdRect[\meta{key-values}]}}
\end{quote}
The above version is used to overlay a region with a button and view
window. No content is specified, but is defined by specifying the
\texttt{width} and \texttt{height}; it can be positioned using
\texttt{shift} and \texttt{lift}.

There is a \texttt{*}-version as well:
\begin{quote}
    \jdRect*[adddestw=10bp,adddesth=10bp]{\cs{jdRect*[\meta{key-values}]}\verb!{!\meta{content}\verb!}!}
\end{quote}
The second parameter \meta{content} is required when the \texttt{*} is
present. This version is meant to enclose \meta{content} within the button
and view window. The \texttt{width} and \texttt{height} keys are ignored,
but \texttt{shift} and \texttt{lift} are obeyed (though you may
\texttt{shift} or \texttt{lift} the button/view window away from the
content).

Before illustrating the \cs{jdRect} command, we first discuss its
key-value pairs.
\begin{itemize}
\item \texttt{lift=\meta{length}}: This key-value lifts (raises) the
    button/viewing window up (or down); for example,
    \texttt{lift=15pt} (or \texttt{lift=-15pt}). The default is a lift
    of \texttt{0pt}. See \autoref{displayEqEx} on page~\pageref*{displayEqEx}.

\item \texttt{shift=\meta{length}}: The amount of horizontal shift;
    positive to the right, negative to the left. For example,
    \texttt{shift=-1in} shifts the button/viewing window 1 inch to the
    left. The default is \texttt{0pt}. See
    \autoref{displayEqEx} on page~\pageref*{displayEqEx}.

\item \texttt{width=\meta{length}}: When using \cs{jdRect}---as
    opposed to \cs{jdRect*}---, the width of the button and viewing
    window is determined by the \texttt{width} key. For example
    \texttt{width=1in} creates a button/viewing window that is 1 inch
    wide. The value of this key is ignored when the \texttt{*} form of
    the \cs{jdRect} is used. The default value is \texttt{0pt}. This
    key is required when \texttt{*} is not present. See
    \autoref{displayEqEx} on page~\pageref*{displayEqEx}.

\item \texttt{height=\meta{length}}: Similar comments here as was made
    for the \texttt{width} key. This key is 0used to set the height of
    the button/viewing window. The default is 0pt. It is required when
    \texttt{*} is not present. See \autoref{displayEqEx} on
    page~\pageref*{displayEqEx}.

\item \texttt{ref=t|c|b}: The \texttt{ref} key-value pair determines
    the reference point of the button/viewing window. Permissible
    values are \texttt{t} top (the default), \texttt{c} center, and
    \texttt{b} bottom. This key is only obeyed with the \cs{jdRect*}
    form of the command; otherwise, a reference point of \texttt{b} is
    used.

\item \texttt{adddestw=\meta{length}}: The default is for the viewing window to have
the same dimensions as the underlying button. The \texttt{adddestw}
key-value pair is used to widen the viewing window; \texttt{adddestw=.2in}
widens the window by \texttt{.2in} on the left and \texttt{.2in} on the
right. See Figure~\ref*{bvw}, page~\pageref*{bvw}.

\item \texttt{adddesth=\meta{length}}: Similar to \texttt{adddestw} but for height.
The \texttt{adddesth}
key-value pair is used to increase the height the viewing window; \texttt{adddesth=.2in}
increases the height of the window by \texttt{.2in} on the top and \texttt{.2in} in the bottom.
See Figure~\ref*{bvw}, page~\pageref*{bvw}.
\begin{figure}[htb]
\begin{center}\setlength\fboxsep{0pt}
   \fbox{\parbox[c][.9in]{2.4in}
        {\vfill\hfil\fbox{\parbox[c][.5in]{2in}{\hfill\vfill}}\hfil\vfill}}\\[4pt]
        \caption{Button and Viewing Window}\label{bvw}
        {\small\texttt{width=2in,height=.5in,adddestw=.2in,adddesth=.2in}}
\end{center}
\end{figure}

\item \texttt{button=true|false}: \texttt{button} is a Boolean switch.
    If \texttt{true} (the default), \cs{jdRect} creates a push button.
    When the user pushes the button, the viewer zooms in to the view
    window. Clicking the same region again restores the previous view.

\item[] When \texttt{button} is \texttt{false}, the button is not created,
but the viewing window is still created. You can then jump to the viewing
window with a separate link or button. When \texttt{button=false}, use the
\texttt{dest} key to assigned a numbed destination to viewing window.
({\fitrpkg} automatically creates the definition names internally, they
are used by the buttons. If no button is created, name the destination so
your know its name and can reference it in link that jumps to that viewing
area.)


\item \texttt{link=jmp|restore} If \texttt{link} has a value, then
    {\fitrpkg} puts \texttt{button=false}. The \texttt{link} key is
    used to create jumps or restore actions to or from a viewing
    window. When \texttt{link=jmp} a jump action is created, the jump
    will be to the value of the \texttt{dest} key. If this is a pure
    link that jumps to another viewing window, then use the
    \texttt{nodest} key as well; no viewing window will be created
    around the link, as it is unlikely you'll want to jump to a link.

\def\RungePic{\kern0pt\includegraphics[width=\marginparwidth]{runge}}
\def\jrOpts#1#2{link=#1,dest=#2}

\item[] For example click on the link
\textbf{\jdRect*[nodest,\jrOpts{jmp}{rungePic},adddestw=10,adddesth=10]{Carl Runge}}%
\marginpar{\jdRect*[\jrOpts{restore}{rungePic},adddestw=\marginparsep,
adddesth=\marginparpush]{\parbox[t]{\marginparwidth}{\RungePic\\
\normalcolor\centering\footnotesize\textsf{Carl Runge}}}} and jump to
the picture of Runge in the margin. Click on the picture of Runge and
return to the previous view.

The jump to the picture from the text ``Carl Runge'' is as follows:
\begin{Verbatim}[xleftmargin=20pt]
\jdRect*[nodest,link=jmp,dest=rungePic,
adddestw=10bp,adddesth=10bp]{Carl Runge}
\end{Verbatim}
The important options are \texttt{nodest,link=jmp,dest=rungePic};
no (named) viewing window is created, we want to create a jump link here,
the destination of the jump link is the destination \texttt{rungePic}.

\item[] The color of the link is determined by \cs{@linkcolor}, a \textsf{hyperref}
command that holds a named color. This can be redefined at anytime,
directly using
\begin{Verbatim}[xleftmargin=20pt]
\makeatletter
\def\@linkcolor{blue}
\makeatother
\end{Verbatim}
or, if you are using the \texttt{pro} option with the \textsf{web}
package, you can say,
\begin{Verbatim}[xleftmargin=20pt]
\selectColors{linkColor=red}
\end{Verbatim}
When using the \textsf{web} package, the default is \texttt{webgreen}.

\item[] The action to restore the previous view is as follows:
\begin{Verbatim}[xleftmargin=20pt]
\marginpar{\jdRect*[link=restore,dest=rungePic,
    adddestw=\marginparsep,adddesth=\marginparpush
    ]{\parbox[t]{\marginparwidth}{\RungePic\\
    \normalcolor\centering\footnotesize\textsf{Carl Runge}}}}
\end{Verbatim}
The picture is placed in the margin using \cs{marginpar}; the command
\cs{RungePic} is a convenience macro that uses \cs{includegraphics} in
import the picture. The important options are
\texttt{link=restore,dest=rungePic}, this first key-value pair causes
\cs{jdRect} to create a restore link, the second one says to create a
viewing window with a name of \texttt{rungePic}, this is the
destination the Carl Runge link jumps to.


\item \texttt{nodest}: A Boolean switch whose default value is
    \texttt{false}. When \texttt{nodest} is used (making the switch a
    value of \texttt{true}), no viewing window is created.

\item \texttt{dest=\meta{name}}: This key is a way of explicitly naming the
    viewing window (the destination). The destination is normally
    automatically generated when \texttt{button=true}, this key is
    used with the \texttt{link} key, as illustrated above.
\item \texttt{allowFX}: A Boolean switch (of sorts). The \texttt{fitr}
    allows for special effects (FX) when a viewing window is jumped to
    and when the view is restored. The default value of
    \texttt{allowFX} is \texttt{true} allow special effects if there
    is any defined. By saying \texttt{allowFX=false}, no special
    effects are used, even if some are defined.

\item[] An example of special effects you say? Try clicking on the
    Pythagorean Theorem
    \jdRect*[allowFX,adddestw=10bp,adddesth=10bp]{$ a^2 + b^2 = c^2 $}
\end{itemize}

\section{Some Examples}

\everymath{\displaystyle}

In this section, several examples are presented that illustrate the
options of \cs{jdRect}.

\begin{example}\label{previewEx}\previewtrue\viewMagWintrue
\textbf{Illustrate Preview Rectangles.} The \texttt{preview} and
\texttt{viewMagWin} options just set Boolean switches. In this example, we
manually gives these switches a value of \texttt{true}
(\cs{previewtrue}\cs{viewMagWintrue}). Take a close look at the following
function
\jdRect*{$ f(x) = \frac{1}{\sqrt{2\pi}}\int_{-\infty}^x e^{-t^2/2}\,\text{d}t$},
or the more general form
\jdRect*[adddestw=20bp,adddesth=10bp]{$ f(x;\mu;\sigma) = \frac{1}{\sigma\sqrt{2\pi}}\int_{-\infty}^x e^{-\frac{(t-\mu)^2}{2\sigma^2}}\,\text{d}t$}
The preview rectangles are shown: For the one on the left, the dimensions
of the push button and the viewing rectangle are the same; for one on the
right, the dimensions of the viewing window have been increased by
using \texttt{adddestw=20bp,adddesth=10bp}. When you jump to each of these
viewing windows, you the one on the left is magnified much more than the
one on the right; the larger viewing window allows the user to see some of
the surrounding text.\fitit
\end{example}

\begin{example}\label{displayEqEx}
\textbf{Display Math.} Displayed math presents a problem. We take the
following set of equations to illustrate.

Suppose we want to classify third order \textsf{Runge-Kutta} type methods.
Start with
\begin{align*}
\jdRect[height=1.3in,width=2.6in,lift=16pt,shift=-15pt,
    adddestw=10bp,adddesth=10bp]
K_1 &= hf(t_n, y_n)\\
K_2 &= hf(t_n +r h, y_n+aK_1)\\
K_3 &= hf(t_n +s h, y_n+bK_1+cK_2)\\
K &= w_1 K_1+ w_2 K_2+ w_3 K_3\\
y_{n+1} &= y_n+K
\end{align*}
Find the system of equations satisfied by
\jdRect*[adddestw=10,adddesth=10]{$r,s, a, b, c, w_1, w_2, w_3$}
that will make the above algorithm a third order method.

The verbatim listing of this set of aligned equations is
\begin{Verbatim}[xleftmargin=20pt,numbers=left]
\begin{align*}
\jdRect[height=1.3in,width=2.6in,lift=16pt,shift=-15pt,
    adddestw=10bp,adddesth=10bp]
K_1 &= hf(t_n, y_n)\\
K_2 &= hf(t_n +r h, y_n+aK_1)\\
K_3 &= hf(t_n +s h, y_n+bK_1+cK_2)\\
K &= w_1 K_1+ w_2 K_2+ w_3 K_3\\
y_{n+1} &= y_n+K
\end{align*}
\end{Verbatim}
This is an example of \cs{jdRect} (the non-\texttt{*} version), so there
is no second argument.  In this case, we create our button dimensions
using \texttt{height=1.3in,width=2.6in}, line~(2). Note the positioning
of the \cs{jdRect} command, the upper-left point of the display. We then
use \texttt{lift=16pt,shift=-15pt} to move the button around to cover the
equations, line~(2); finally, we increase the dimensions of the viewing
window in line~(3) with \texttt{adddestw=10bp,adddesth=10bp}. Now, how
were the values of these keys determined? By trial and error, while the
\texttt{preview} and \texttt{viewMagWin} options were in effect. Below are
the same equations with \cs{previewtrue} and \cs{viewMagWintrue}, locally
invoked:\previewtrue\viewMagWintrue
\begin{align*}
\jdRect[height=1.3in,width=2.6in,lift=16pt,shift=-15pt,
    adddestw=10bp,adddesth=10bp]
K_1 &= hf(t_n, y_n)\\
K_2 &= hf(t_n +r h, y_n+aK_1)\\
K_3 &= hf(t_n +s h, y_n+bK_1+cK_2)\\
K &= w_1 K_1+ w_2 K_2+ w_3 K_3\\
y_{n+1} &= y_n+K
\end{align*}
The preview rectangles do not take up any {\TeX} space, so they overlap
parts of the paragraph content. When you zoom in, you'll see part of the
part of the word ``invoked:'', as seen in the upper-left corner, at least
according to the viewing window preview. Is it so?

After you've set the position of the rectangles, and after all changes
have been made to the underlying content, you don't need the preview
modes.\fitit
\end{example}

\begin{example}\label{CustomAppr}
\textbf{Customizing the appearance.} The properties of the underlying push button
is to be visible, but does not print. The background and the border are
transparent.  The default properties are passed to the push button using a
presets command:
\begin{Verbatim}[xleftmargin=20pt]
\newcommand{\overlayPresets}{\H{I}\BG{}\BC{}\S{S}}
\end{Verbatim}
See the \textsf{eforms} manual for the meaning of these cryptic symbols.
You can modify these settings locally, within a group, or globally. In
this example, we change the border to red dashed line. We redefine
\cs{overlayPresets} as follows:
\begin{Verbatim}[numbers=left,xleftmargin=20pt]
\renewcommand{\overlayPresets}{\H{I}\BG{}\BC{red}\S{D}}
\end{Verbatim}
\renewcommand{\overlayPresets}{\H{I}\BG{}\BC{red}\S{D}}%
The changes are in line~(2), we say \verb!\BC{red}! (the \textsf{xcolor} package is
required here for named colors; otherwise, we would say \verb~\BC{1 0 0}~),
and we've change \verb!\S{S}! to \verb~\S{D}~, which gives a dashed
(\texttt{D}) border as opposed to a solid (\texttt{S}) border. Now to
illustrate this. My name is \jdRect*{D. P. Story!}; lets increase the
viewing window, shall we? My name is \jdRect*[adddestw=10bp,adddesth=10bp]{D. P.
Story!}. Keep in mind that we are overlaying a push button; if you want
the underlying text to have a color, you need to color it yourself:
\jdRect*[adddestw=10bp,adddesth=10bp]{\textcolor{blue}{D. P. Story}!}
This last button has code,
\begin{Verbatim}[xleftmargin=20pt]
\jdRect*[adddestw=10bp,adddesth=10bp]%
    {\textcolor{blue}{D. P. Story}!}
\end{Verbatim}
As the changes to the preset appearance are inside a group, after this
example (environment)) \cs{overlayPresets} will revert to its definition
that was in effect outside the example.\fitit
\end{example}

\section{Special Effects}

For the standard set up, where there is a push button that overlays the
content along with the viewing window is jumps to, there are two
JavaScript ``hooks'' that can be exploited
\begin{itemize}
    \item \texttt{overlayJmpHook()} is an undefined JavaScript
        function that is executed after the jump to the viewing
        window. (It is enclosed in a \texttt{try/catch} construct that
        catches the error thrown.) The document author can define
        \texttt{overlayJmpHook()} to perform some action following the
        jump. The distribution of {\fitrpkg} comes with one
        definition, \texttt{jmpHookBlink.js}, which blinks the border
        following the jump.
    \item \texttt{overlayRestoreHook()} is an undefined JavaScript
        function that is executed following the restored view action.
        The document author needs to make a custom definition if
        special effects are desired. The distribution of {\fitrpkg}
        comes with one definition, \texttt{restoreHookBlink.js},
        which blinks the border following the restore action.
\end{itemize}
The preamble of this document says,
\begin{Verbatim}[xleftmargin=20pt]
\usepackage[js=restoreHookBlink,js=jmpHookBlink]{lmacs}
\end{Verbatim}
The \textsf{lmacs} package is a new package I made available to CTAN, its
a simple package that imports files with extensions of \texttt{.def}, \texttt{.cfg}, and
\texttt{.js}. We import \texttt{restoreHookBlink.js} and
\texttt{jmpHookBlink.js} using a key-value method, where the key is one of
the supported extensions; thus \texttt{js=restoreHookBlink} will import
the file texttt{restoreHookBlink.js} if it exists. By the way, another
nice feature of \textsf{lmacs} is that you can prefix an exclamation point
(!) to cancel out that import, for example, if we wanted to use \texttt{jmpHookBlink}
but not \texttt{restoreHookBlink} we say
\begin{Verbatim}[xleftmargin=20pt]
\usepackage[!js=restoreHookBlink,js=jmpHookBlink]{lmacs}
\end{Verbatim}

\begin{example}\label{fx}\renewcommand{\overlayPresets}{\H{I}\BG{}\BC{blue}\S{D}}%
\textbf{Special Effects.} Jump to the
\jdRect*[allowFX,adddestw=10bp,adddesth=10bp]{{\fitrpkg} Package!}

The verbatim listing is
\begin{Verbatim}[xleftmargin=20pt,numbers=left]
\renewcommand{\overlayPresets}{\H{I}\BG{}\BC{blue}\S{D}}%
...
Jump to the \jdRect*[allowFX,adddestw=10bp,adddesth=10bp]%
    {{\fitrpkg} Package!}
\end{Verbatim}
We redefined the \cs{overlayPresets} command, choosing an initial border
of blue. In line~(4), I've used \texttt{allowFX}, this key does not
normally to appear in the option list, its default value is normally
\texttt{true};  however, for this document, the following definition was
made in the preamble
\begin{Verbatim}[xleftmargin=20pt]
\renewcommand\allowFXDefault{false}
\end{Verbatim}
This (re)definition of \cs{allowFXDefault} sets the default value of
\texttt{allowFX} to \texttt{false}. This was done so the special effects
JavaScript functions could be imported (using \texttt{lmacs}) but their
effects would not be seen, by default. To see their effect, we have to
explicitly put \texttt{allowFX} to \texttt{true}, which is what the single
key does. (Or, you can say \texttt{allowFX=true}, but that is five more key
presses.)\fitit
\end{example}

Now, I simply must get back to my retirement. \dps

\end{document}