summaryrefslogtreecommitdiff
path: root/texmf-dist/source/latex/digicap-pro/doc/digicap_man.tex
blob: 66abf27dbf31934e1e041f4c998484b84adab096 (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
\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage[%
    web={centertitlepage,usetemplates,designv,
        forcolorpaper,tight*,latextoc,extended},
    eforms,uselayers,graphicxsp={showembeds},aebxmp
]{aeb_pro}
\usepackage{digicap-pro}

\usepackage{array}
%\usepackage[usecmtt]{myriadpro}

\usepackage[altbullet]{lucidbry}

%\usepackage{makeidx}
%\makeindex

\previewOn

\usepackage{acroman}

\usepackage[active]{srcltx}

\def\expath{../examples}


\urlstyle{rm}

\embedEPS{clifflee}{\expath/digis/IiFUCdIQ}%

\DeclareDocInfo
{
    university={\AcroTeX.Net},
    title={ \texorpdfstring{DigiCap Pro\\[1em]}
        {DigiCap Pro: }Captioning Digital Images},
    author={D. P. Story},
    email={dpstory@acrotex.net},
    subject={Documentation for AeB Pro from AcroTeX},
    talksite={\url{www.acrotex.net}},
    version={1.0},
    keywords={AeB, Adobe Acrobat, JavaScript},
    copyrightStatus=True,
    copyrightNotice={Copyright (C) \the\year, D. P. Story},
    copyrightInfoURL={http://www.acrotex.net}
}

\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

\advance\marginparwidth10pt


\chngDocObjectTo{\newDO}{doc}
\begin{docassembly}
var titleOfManual="The DigiCap Pro Manual";
var manualfilename="Manual_BG_Print_digicap.pdf";
var manualtemplate="Manual_BG_Brown.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}

\begin{document}

\maketitle

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

\section{Introduction}

The \textsf{digicap-pro} package came about several years ago (2008);
at that time, I was impressed by the tv guide layout of photos with
captions. The captions were laid on top of the photos using a
transparent box. I also saw this type of photo-caption layout on
\url{www.mlb.com}. This photo-caption layout inspired to reproduce
for {\LaTeX}/PDF.

This package provides commands for simply displaying the digital photo
with caption; the caption can be displayed as a rollover, that is, the caption
is not visible until the user rolls over the photo using a mouse.

Another component of the package is the display of collections of photos and captions.
The \url{www.mlb.com} has (or had) thumbnails of the photos, by clicking the thumb, the
photo with caption would appear.  Nowadays, this is done through the magic of Adobe Flash,
which gives clever transitions of the thumbs and photos. This package does not do Adobe Flash, but
perhaps a future edition of this package will incorporate Flash/Flex using my \texttt{rmannot} package.

\section{Requirements}

This package belongs to the high-class family of \textsf{\textcolor{blue}{AeB~Pro}}, hence,
the major requirement of this package is that the PDF be created using \textbf{Acrobat Distiller},
see Section~\ref*{ss:PDFCreator} for details.

\subsection{{\LaTeX} Package Requirements}

 The package builds on packages developed as part of \textsf{AeB} or \textsf{AeB~Pro}:
\begin{itemize}
 \item\textsf{aeb\_pro}: supplies support for layers and JavaScript management of layers
 \item\textsf{graphicxbox}: places a graphic as the background of a box
 \item\textsf{opacity-pro}: creates the transparency effects
 \item\textsf{eforms}: use to create Acrobat form buttons with a roll-over action to make
   roll-over captions visible or hidden.
 \item \textsf{grahicxsp}: used with the commands input with the \texttt{design1} option.
 See the section entitled \Nameref{s:photoalbum}.
\end{itemize}
The \textsf{graphicx} package is also used to import digital photos, or other graphics.


\reversemarginpar

\subsection{PDF Creator Requirements}\label{ss:PDFCreator}

The big restriction on this package is the requirement to use\marginpar{\raggedleft\app{dvips}\\\app{dvipsone}}
\textbf{Acrobat Distiller} (version 5.0, or version 6.0 for transparency).
The package was developed using Acrobat Distiller 8.1. The package supports the
creation of Postscript using \textsf{dvips} and \textsf{dvipsone}. These ``drivers''
are defined through the required package \textsf{aeb\_pro}.

\subsection{Transparency Requirements}

To get the transparency effect, \textbf{Acrobat Distiller} version 6.0 or
later is required. The default setting of the distiller does not
support the \textbf{SetTransparency} pdfmark; it is necessary to
edit the \texttt{.joboptions} file.

The procedure for editing \texttt{.joboptions} to support transparency is as follows:
\begin{enumerate}
    \item Start \textbf{Acrobat Distiller}
    \item From the Default Settings list, select the setting you want to edit,
    usually, this will be the \texttt{Standard} job options.
    \item Select \texttt{Settings} \texttt{>} \texttt{Edit Adobe PDF Settings} \texttt{(Ctrl+E)} from the
    distiller menu.
    \item Click the \texttt{SaveAs} button at the bottom of the \texttt{Adobe PDF Settings}
    dialog box. Save your .jobsettings file under a new name,
    say \texttt{Standard\_transparency} and make a note of where
    the distiller saves this file.
    \item With your favorite text editor, navigate to the folder where you saved your new
    \texttt{.job\-options} file, and open it in your editor.
    \item Look for the line that says
    \texttt{/AllowTransparency false}, and change this to read \texttt{/AllowTransparency true}.
    Save the changes and close the file.
    \item Use this \texttt{.joboptions} file, \texttt{Standard\_transparency} for example,
    whenever you distill with transparency pdfmarks.  If your {\LaTeX} file uses transparency,
    and you are using a \texttt{.joboptions} file with \texttt{/AllowTransparency false}, distillation
    will fail and the distiller log should say
\begin{Verbatim}[fontsize=\small]
%%[Error: The Postscript contains Transparency pdfmark, job aborted.]%%
%%[ /AllowTransparency is false in job option settings.]%%
%%[ Error: undefined; OffendingCommand: pdfmark;
    ErrorInfo: Transparency Group ]%%
\end{Verbatim}
This suggests that you should use your \texttt{.joboptions} file that supports transparency!

\newtopic \textbf{Note:} The required package \pkg{opacity-pro} comes with an
\app{Acrobat Distiller} job options file named
\texttt{Standard\_transparency.joboptions}. Instead of following the above
instructions you can simply drop this file in a place where Distiller
expects to find \texttt{.joboptions} files.\footnote{Go to \texttt{Settings
> Edit Adobe PDF Settings ...} in the Distiller application window, then
click the \texttt{SaveAs} button. A \textbf{Save Adobe PDF Settings As}
dialog box opens, and you can then see where Distiller likes to save its
\texttt{.joboptions} file. Copy the provided \texttt{.joboptions} to the
folder and restart Distiller, the \texttt{Standard\_transparency} should
now be visible in the drop down \textsf{Default Settings} list.}

\end{enumerate}

\section{Options of this Package}

Currently, there is only one option for this package, it is
\texttt{display1}.\marginpar{\raggedleft\opt{display1}} As noted in the
introduction, this package provides basic commands for showing digital
pictures with captions, and for displaying collections of photos using
thumbnail activation. When \opt{display1} is specified, additional code input
to support photo displays; refer to Section~\ref{s:photoalbum} for details of
using \opt{display1} to create a photo album.  Future versions of this package
may have additional display formats, perhaps provided by enthusiastic users.


\section{The DigiCap Pro Commands}

In this section we present the new commands defined in the \pkg{digicap-pro} package, and as a bonus,
we also present, Section~\ref{s:photoalbum}, a series of commands to create a photo presentation.

\subsection{Digital Photos with Captions}\label{ss:digiCap}

For the mere captioning of a photo, there is one major command for this
package, all other commands (presented in Section~\ref{s:photoalbum}) are built around this one:
\bVerb\takeMeasure{\string\digiCap*[\ameta{pos-kvs}]\darg{\ameta{path}}[\ameta{design-kvs}]\darg{\ameta{caption}}}%
\begin{dCmd*}[commandchars=!()]{\bxSize}
\digiCap*[!ameta(pos-kvs)]{!ameta(path)}[!ameta(design-kvs)]{!ameta(caption)}
\end{dCmd*}
\eVerb
\textbf{The star-option.} If \texttt{*} is present, the caption becomes a rollover caption.
\paragraph*{Optional key-values for the first parameter (\ameta{pos-kvs}).} This set of parameters
 control the placement of the caption on top of the background picture. There is
 also a parameter to set the options for the \cs{includegraphics} command, and one to set
the  form field name, in the case of a rollover.
\begin{description}
\item[\texttt{outerboxsep}:] The space the surrounds the boundary of the caption, the default is \texttt{3pt}
\item[\texttt{vcaption}:] The vertical placement of the caption on the background graphic, possible
   values are \texttt{b}, \texttt{c}, and \texttt{t}. The default is \texttt{b}.
\item[\texttt{hcaption}:] The horizontal placement of the caption on the background graphic, possible
   values are \texttt{l}, \texttt{c}, and \texttt{r}. The default is \texttt{c}.
\item[\texttt{inclgraphicx}:] The value of this key is a list of key-value pairs that are passed on to the
  underlying \cs{includegraphics} command.
\item[\texttt{rollovername}:] The basename of the push button form field that is used for a rollover effect.
   This command is used only with \cs{digiCap*}, ignored otherwise. For the \cs{digiCap*}
   command, this key is optional, if not present, this package supplies a name.
\end{description}

\paragraph*{Second parameter, required (\ameta{path}).} The second parameter is
 the path to the digital photo (or graphic) to be used as a background to
 this box.

\paragraph*{Optional key-values for the third parameter (\ameta{design-kvs}).} These are additional options for the design
of the box that contains the caption.
\begin{description}
   \item[\texttt{borderwidth}:] The border width. The default is \texttt{2pt}
   \item[\texttt{fboxsep}:] The space between the border and the text, the default is \texttt{6pt}
   \item[\texttt{width:}] The width of \cs{parbox}, the default is \cs{linewidth}
   \item[\texttt{bordercolor}:] A named color of border, the default is \texttt{black}. A special value
   of \texttt{nocolor} is recognized, in that case, no color is applied.
   \item[\texttt{bgcolor:}] A named color of background, the default is \texttt{white}. A special value
   of \texttt{nocolor} is recognized, in that case, no color is applied.
   \item[\texttt{borderop:}] A number type, the opacity for border $0 \le \mbox{number} \le 1$, the default is~$.5$
   \item[\texttt{bgop:}] A number type, the opacity for background $0 \le \mbox{number} \le 1$, the default is~$.5$
   \item[\texttt{textop:}] A number type, the opacity for text $0 \le \mbox{number} \le 1$, the default is~$1$
   \item[\texttt{borderblend:}] The blend mode for the border, the default is \texttt{Normal}
   \item[\texttt{bgblend:}] The blend mode for the background, the default is \texttt{Normal}
\end{description}

\paragraph*{Fourth parameter, required.} The text of the caption.

\exSrc{digicap-tst}The following is a sample of examples, see the demo file
\texttt{digicap-tst.tex} for extensive examples of \cs{digiCap} with its options.
\begin{center}
\digiCap[inclgraphicx={name=clifflee,width=.75\linewidth},vcaption=b,
    hcaption=c,outerboxsep=0pt]{\expath/digis/IiFUCdIQ}[borderwidth=0bp,
    fboxsep=10bp,bordercolor=nocolor,bgop=.7]{\parskip6pt\bfseries
    \makebox[\linewidth]{\textcolor{red}{Lee ices A's win
    streak with an eight-inning gem}}\\\relax\footnotesize
    Lee ices A's win streak with an eight-inning gem Cliff Lee retired
    14 straight in a 7-1 Indians win over the A's on Sunday. Grady
    Sizemore had three RBIs as Cleveland halted its three-game skid.}\\[1ex]
%
\digiCap*[inclgraphicx={name=clifflee,width=.75\linewidth},vcaption=c,hcaption=l,outerboxsep=0pt]
    {\expath/digis/IiFUCdIQ}[borderwidth=4bp,fboxsep=10bp,
    bordercolor=blue,bgop=.7]{\parskip6pt\bfseries
    \makebox[\linewidth]{\textcolor{webblue}{Lee ices A's win
    streak with an eight-inning gem}}\\\relax\footnotesize
    Lee ices A's win streak with an eight-inning gem Cliff Lee retired
    14 straight in a 7-1 Indians win over the A's on Sunday. Grady
    Sizemore had three RBIs as Cleveland halted its three-game skid.}%
\end{center}
The topmost photo has a static caption at the bottom of the photo, the photo below it has a rollover
caption, the caption box has been designed with a border. The verbatim listing of these two images
are

\begin{Verbatim}[xleftmargin=\parindent,numbers=left,fontsize=\footnotesize]
\digiCap[inclgraphicx={width=.75\linewidth},
    vcaption=b,hcaption=c,outerboxsep=0pt]
    {\expath/digis/IiFUCdIQ}[borderwidth=0bp,fboxsep=10bp,bordercolor=nocolor,
    bgop=.7]{\parskip6pt\bfseries
    \makebox[\linewidth]{\textcolor{red}{Lee ices A's win
    streak with an eight-inning gem}}\\\relax\footnotesize
    Lee ices A's ... as Cleveland halted its three-game skid.}
\end{Verbatim}
In line~(1), the \texttt{inclgraphicx} key sets the width of the graphic at
\verb!.75\linewidth!. The first optional option continues on line~(2), we set
\texttt{vcaption} and \texttt{hcaption} to the defaults (hence need not have
appeared). The second required parameter is in line~(3). The third (optional)
parameter also begins in line~(3) and continues onto line~(4): among the
options is setting the \texttt{bordercolor} to \texttt{nocolor} and the
\texttt{bgop} (background opacity) to .7. The fourth required parameter is
begins in line~(4) and goes through line~(7). A title line is put in red, and
the caption text set in a smaller size font.

The second photo has code,

\begin{Verbatim}[xleftmargin=\parindent,numbers=left,fontsize=\footnotesize]
\digiCap*[inclgraphicx={width=.75\linewidth},vcaption=c,hcaption=l,
    outerboxsep=0pt]{\expath/digis/IiFUCdIQ}[borderwidth=4bp,fboxsep=10bp,
    bordercolor=blue,bgop=.7]{\parskip6pt\bfseries
    \makebox[\linewidth]{\textcolor{webblue}{Lee ices A's win
    streak with an eight-inning gem}}\\\relax\footnotesize
    Lee ices A's ... Cleveland halted its three-game skid.}
\end{Verbatim}
We use \cs{digiCap*}, the \texttt* signals that this digital photo should have a
rollover caption. We set \texttt{vcaption} to \texttt{c}, which centers the caption
vertically. In the third (optional) parameter, we set the \texttt{borderwidth} to 4bp,
\texttt{fboxsep} to 10bp, \texttt{bordercolor} to blue and \texttt{bgop} to .7.

Again, many examples appear in \texttt{digicap-tst.tex}.


\subsubsection{Using \textsf{graphicxsp} Package}

For normal uses, \cs{digiCap} is used to display several
\emph{different} photos, photos are not repeatedly used. Each time a
photo is displayed, it is imported into the document using the
command \cs{includegrpahics}, if you show the same photo five times,
the same graphic file is imported five times. This most certainly
increases the file size.

If the \textsf{graphicxsp} package is also used (required for the
commands of the next section), photos can be embedded in the
document and used multiple times without significantly increasing
the size of the file size. The \textsf{digicap-pro} package allows
for the use of the \textsf{graphicxsp} package, naturally.

\def\nameKey{\textcolor{red}{name=clifflee}}

The two instances of the Cliff Lee photo seen earlier is an example.
In the verbatim code, I deleted one key-value pair. The true verbatim code is
\begin{Verbatim}[xleftmargin=\parindent,numbers=left,fontsize=\footnotesize,commandchars=\|\<\>]
\digiCap[inclgraphicx={|nameKey,width=.75\linewidth},vcaption=b,
    hcaption=c,outerboxsep=0pt]{\expath/digis/IiFUCdIQ}[borderwidth=0bp,
    fboxsep=10bp,bordercolor=nocolor,bgop=.7]{\parskip6pt\bfseries
    \makebox[\linewidth]{\textcolor{red}{Lee ices A's win
    streak with an eight-inning gem}}\\\relax\footnotesize
    Lee ices A's win ... as Cleveland halted its three-game skid.}\\[1ex]
\end{Verbatim}
The new key-value pair is shown in red in line~(1). Within the \texttt{inclgraphicx} key we specify
the symbolic name for the graphic, \texttt{name=clifflee}. In the preamble of this document,
the follow code appears: \verb!\embedEPS{clifflee}{\expath/digis/IiFUCdIQ}! (the \cs{expath} expands
to the path to the folder containing the \texttt{digis} folder).

\exSrc{digicap-embed}The file \texttt{digicap-embed.tex} contains an example of this embedding.

\subsection{Displaying Collections of Digital Photos}\label{s:photoalbum}

Now, if you want to display a number of photos, you can either place one or two per page,
or you can present all photos on the same page, the latter is the approach we take here.

\paragraph*{Creating a photo album.} For each photo\marginpar{\small\raggedleft\opt{display1} option}, we create a smaller version (thumbnail) and set it as a
button appearance. When you rollover the button, the larger version of the
photo makes its appearance in the photo viewing area. The code for setting up
the thumbnail layout is contained in additional code that is input with the
\opt{design1} option.

\paragraph*{Demo files for photo album.} There are three demo files for this
section contained in the \texttt{photoalbum} folder:
\begin{itemize}
\item[]\exSrc[../photoalbum/digis/]{eastern_trip_por}\texttt{eastern\_trip\_por.tex}
\item[]\exSrc[../photoalbum/digis/]{eastern_trip_ls}\texttt{eastern\_trip\_ls.tex}
\item[]\exSrc[../photoalbum/digis/]{eastern_trip_ls_2pg}\texttt{eastern\_trip\_ls\_2pg.tex}
\end{itemize}
These three present the same collection of photos
with different layouts for the thumbnails.

\subsubsection{The Main Controls}\label{photoAlbum}

We describe the commands in the order in which they appear in the
document.

\paragraph*{Declaring the picture collection}\leavevmode
\bVerb\def\1{n}\takeMeasure{\quad\darg{\ameta{name\SUB1}}\darg{\ameta{path\SUB1}}\darg{\ameta{title\SUB1}}\darg{\ameta{caption\SUB1}},}%
\begin{dCmd*}[commandchars=!()]{\bxSize}
\PicsThisDoc
{%
!quad{!ameta(name!SUB1)}{!ameta(path!SUB1)}{!ameta(title!SUB1)}{!ameta(caption!SUB1)},
!quad{!ameta(name!SUB2)}{!ameta(path!SUB2)}{!ameta(title!SUB2)}{!ameta(caption!SUB2)},
!quad...
!quad{!ameta(name!SUB!1)}{!ameta(path!SUB!1)}{!ameta(title!SUB!1)}{!ameta(caption!SUB!1)}
}
\end{dCmd*}
\eVerb
In the preamble of the document, the \cs{PicsThisDoc} commands declares
the pictures to be displayed in this document. The arguments for this command
are a comma-delimited list, each item in the list consists of four parameters, as described
below:
\begin{itemize}
  \item \ameta{name}: a symbolic name that references this picture
  \item \ameta{path}: the path to the photo (or any graphic), in the EPS format
  \item \ameta{title}: a title for this photo
  \item \ameta{caption}: a caption, or description, of this photo

  \item[] Within the \ameta{caption}, the commands
      \cs{graphicHeight}\marginpar{\small\raggedleft
      \cs{graphicHeight}\\\cs{graphicWidth}} and \cs{graphicWidth} are
      defined. Their values are the height and the width of the (scaled)
      photo. An example of usage for \cs{graphicHeight} can be found in the
      demo file \texttt{digicap-tst.tex}.
\end{itemize}

\paragraph*{Setting the presentation order.} The order the pictures are presented is set by the following command, also
placed in the body of the document before the insertion of the pictures.
\bVerb\def\1{n}\takeMeasure{\string\presentationOrder\darg{\ameta{name\SUB1},\ameta{name\SUB2},...,\ameta{name\SUB\1}}}%
\begin{dCmd*}[commandchars=!()]{\bxSize}
\presentationOrder{!ameta(name!SUB1),!ameta(name!SUB2),...,!ameta(name!SUB!1)}
\end{dCmd*}
\eVerb The names are defined by the \cs{PicsThisDoc} command.

\paragraph*{Setting the display dimensions.} The photos are placed in a \cs{parbox}
with height of \ameta{height} and width of \ameta{width}.
\bVerb\def\1{n}\takeMeasure{\string\digiDisplaySpace\darg{\ameta{height}}\darg{\ameta{width}}}%
\begin{dCmd*}[commandchars=!()]{\bxSize}
\digiDisplaySpace{!ameta(height)}{!ameta(width)}
\end{dCmd*}
\eVerb Reads the information defined by \cs{presentationOrder} and inserts
the photos at the current location in a \cs{parbox}

\paragraph*{Insert the captions}\leavevmode
\bVerb\def\1{n}\takeMeasure{\string\insertCaptions}%
\begin{dCmd*}[commandchars=!()]{\bxSize}
\insertCaptions
\end{dCmd*}
\eVerb Places the caption of the current photo at the current location.

\paragraph*{Insert the thumbnails}\leavevmode
\bVerb\takeMeasure{\string\insertThumbs\darg{\ameta{rows}}\darg{\ameta{columns}}}%
\begin{dCmd*}[commandchars=!()]{\bxSize}
\insertThumbs{!ameta(rows)}{!ameta(columns)}
\end{dCmd*}
\eVerb
Lays out a \env{tabular} environment with \ameta{rows} and
\ameta{columns}; within this \env{tabular} environment, the thumbnails are
inserted.

\paragraph*{Placement of the photo album elements.}
The several commands \cs{digiDisplaySpace}, \cs{insertCaptions}, and
\cs{insertCaptions} are placed on a page after the command \cs{presentationOrder},
and can be arranged anyway desired; the three demo files give examples of
different arrangements.

\subsubsection{Additional Controls}

The \cs{digiDisplaySpace} command ultimately uses \cs{digiCap} to display the
photos, but \cs{digiCap} has two optional arguments, labeled \ameta{pos-kvs>}
and \ameta{design-kvs>} in the description of \cs{digiCap},
page~\pageref*{ss:digiCap}, that cannot be accessed. The \textsf{digicap-pro}
package provides a way of setting these options for all photos, and for a
particular photo.
\bVerb\takeMeasure{\string\dcSecondOpt[\ameta{name}]\darg{\ameta{design-kvs}}}%
\begin{dCmd*}[commandchars=!()]{\bxSize}
\dcFirstOpt[!ameta(name)]{!ameta(pos-kvs)}
\dcSecondOpt[!ameta(name)]{!ameta(design-kvs)}
\end{dCmd*}
\endgroup
\CmdDescription \cs{dcFirstOpt} inserts its key-value pairs into the first optional argument
of \cs{digiCap}, the one labeled \ameta{pos-kvs}. See
\hyperref[ss:digiCap]{Section~\ref*{ss:digiCap}}, page~\pageref*{ss:digiCap}, for a list of these
options. When the key-values are passed without a first argument, the key-values are applied to
all photos; when the optional argument is specified (\ameta{name} is a symbolic name of one of
the photos in the collection defined by \cs{PicsThisDoc}), the key-value pairs are applied only
to that photo. For example,
\begin{Verbatim}[xleftmargin=\parindent]
\dcFirstOpt{vcaption=b,hcaption=c,outerboxsep=0pt}
\dcFirstOpt[p1]{vcaption=t,hcaption=c,outerboxsep=0pt}
\end{Verbatim}
The first line sets the global options for all the photos (this is actually the package
default, and  need not be specified here), the second line is the specification for
the photo labeled \texttt{p1}. To repeat, the default definition for \cs{dcFirstOpt}
is
\bVerb\takeMeasure{\string\dcFirstOpt\darg{vcaption=b,hcaption=c,outerboxsep=0pt}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\dcFirstOpt{vcaption=b,hcaption=c,outerboxsep=0pt}
\end{dCmd}
\eVerb Similar comments are made for \cs{dcSecondOpt} that sets the second
optional argument of \cs{digiCap} (which is actually the third parameter of
that command), see, again, \hyperref[ss:digiCap]{Section~\ref*{ss:digiCap}},
page~\pageref*{ss:digiCap}, for a listing in the paragraph titled
\textbf{Optional key-values for the third parameter}. The default setting for
\cs{dcSecondOpt} is
\bVerb\takeMeasure{\string\dcSecondOpt\{borderwidth=0bp,fboxsep=10bp,}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\dcSecondOpt{borderwidth=0bp,fboxsep=10bp,
    bordercolor=nocolor,bgop=.7}
\end{dCmd}
\eVerb
The default behavior is that the caption appears with the photo. The \cs{digiCap}
command does have an option for making the caption itself into a rollover; when the user
rolls over the photo, the caption appears. To activate this feature of \cs{digiCap}
use the command \cs{useRollovers} before the \cs{presentationOrder}.

\bVerb\takeMeasure{\string\useRollovers\quad\string\noRollovers}%
\begin{dCmd*}[commandchars=!()]{\bxSize}
\useRollovers!quad\noRollovers
\end{dCmd*}
\eVerb
You can turn off the roll over feature with \cs{noRollovers}. It is
possible to have some of the photos displayed on one page, and the
others on another page. The rollovers can be activated for one set
of pictures, and deactivated for the other. (For photo displays over
two pages, see the demo file \texttt{eastern\_trip\_ls\_2pg.tex}.


\paragraph*{Formatting the Long Captions.} The long caption is the text that accompanies the
photo, and is overlaid on top of the photo using a ``see through'' box.
\cs{longCapFmt} is used for globally formatting the caption. This formatting
can changed locally from within the fourth parameter---the \ameta{caption}
parameter---, see the syntax for \cs{PicsThisDoc}, at the beginning of this
section on \hyperref[photoAlbum]{page~\pageref*{photoAlbum}}. The default
long caption formatting is \verb!\longCapFmt{}!, but a declaration of
\verb!\longCapFmt{\bfseries}! puts all the captions in bold.
\bVerb\takeMeasure{\string\longCapFmt\darg{\ameta{format-declns}}}%
\begin{dCmd*}[commandchars=!()]{\bxSize}
\longCapFmt{!ameta(format-declns)}
\end{dCmd*}
\endgroup
\paragraph*{Formatting the Short Captions.} The short captions,
perhaps a better term might have been the title of the photo, are
defined as the third parameter, the \ameta{title} parameter, (in
the set of four) of \cs{PicsThisDoc}. Use \cs{shortCapFmt} to apply
format declarations:
\bVerb\takeMeasure{\string\shortCapFmt\darg{\ameta{format-declns}}}%
\begin{dCmd*}[commandchars=!()]{\bxSize}
\shortCapFmt{!ameta(format-declns)}
\end{dCmd*}
\eVerb The default definition for \cs{shortCapFmt} is
\begin{dCmd}{.67\linewidth}
\shortCapFmt{\sffamily\bfseries\color{blue}}
\end{dCmd}

\paragraph*{Setting Appearance and Width of the Thumbs.} The thumbnails are
automatically generated by \cs{insertThumbs}, but \cs{insertThumbs} does not
contain any controls over the appearance or width of the buttons created.
For this reason, \cs{setThumbAppearances} and \cs{setWidthOfThumbs}
are provided.

\bVerb\takeMeasure{\string\setThumbAppearances[\ameta{name}]\darg{\ameta{ro-kvs}}}%
\begin{dCmd*}[commandchars=!()]{\bxSize}
\setThumbAppearances[!ameta(name)]{!ameta(ro-kvs)}
\end{dCmd*}
\eVerb When the optional parameter \ameta{name} is not present, the
\ameta{ro-kvs} are taken as global key-value pairs, applied to all the
thumbs. When \ameta{name} is passed, the key-value pairs are applied only to
the thumb associated with \ameta{name}. The key-value pairs themselves allow
the document author to set the rollover attributes of the thumb, and to set
the boundary color and width.
\begin{itemize}
\item\texttt{normalop}: The opacity of the normal appearance of the thumb, the default
is~.5.
\item\texttt{rolloverop}: The opacity of the rollover appearance of the thumb, the default
is~1.
\item\texttt{downop}:  The opacity of the down appearance of the thumb, the default
is~.3.
\item\texttt{boundarywidth}: The boundary width of the unscaled digital photo. The
default is 30 (points).
\item\texttt{rgbcolor}: The RGB color of the boundary, a space delimited
    list of three numbers between 0 and 1. If the \pkg{xcolor}
    package\marginpar{\small\raggedleft\pkg{xcolor} and named colors} is used,
    than you can use a named color for the value; for example,
    \texttt{rgbcolor=red}. There is no default, since, the default color is
    in CMYK color space.
\item\texttt{cmykcolor}: The CMYK color of the boundary, a space delimited list of four numbers
between 0 and 1. If the \pkg{xcolor}
    package\marginpar{\small\raggedleft\pkg{xcolor} and named colors} is used,
    than you can use a named color for the value; for example,
    \texttt{cmykcolor=magenta}.
The default is \texttt{0 0 1 0} (yellow).
\end{itemize}
The following code,
\bVerb\takeMeasure{\string\setThumbAppearances[p1]\darg{rgbcolor=1 0 0}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\setThumbAppearances[p1]{rgbcolor=1 0 0}!quad%!normalfont( or possibly !texttt(rgbcolor=red))
\end{dCmd}
\eVerb
sets the border color to red of the thumbnail associated with the name \texttt{p1};
the other default values are still in effect.

The width of the thumbnails are calculated automatically, based on the number
of columns and the linewidth of the tabular environment the thumbs are being
laid out in. The \texttt{digicap-pro} package sets the width of the thumbs using
\cs{setWidthOfThumbs}. The default setting is \verb!\setWidthOfThumbs{0pt}!.
If the width is set to 0pt (the default), the width of the thumbs are
set dynamically using the formulas:
\begin{Verbatim}[xleftmargin=\parindent]
\setWidthOfThumbs{\linewidth/(\dc@maxCols)-\tabcolsep*2}
\end{Verbatim}
Here, \cs{dc@maxCols} is the number of columns declared in the second
parameter of \cs{insert\-Thumbs}. The \textsf{calc} package is used in this
calculation. If the document author sets \cs{setWidthOfThumbs} to a length
other than \texttt{0pt}, this declared length is used as the width of the
thumbs.

The width between rows of the tabular layout can be adjusted using
command \cs{addvspacetorows}.
\bVerb\takeMeasure{\string\addvspacetorows\darg{\ameta{length}}}%
\def\1{\rlap{\hskip\bxSize\enspace{\normalfont{(\texttt{1ex})}}}}
\begin{dCmd*}[commandchars=!()]{\bxSize}
!1\addvspacetorows{!ameta(length)}
\end{dCmd*}
\eVerb
The default of \ameta{length} is given in parentheses above.

\subsection{The \texorpdfstring{\protect\cs{opcolorbox}}{\CMD{opcolorbox}} Command}

The \cs{opcolorbox} commands creates two color boxes, a larger one with a smaller one
centered vertically and horizontally inside the larger one.
Transparent options allow separate control over the opacity settings
of the larger and smaller rectangle as well as the text that is
written within the smaller rectangle.

The purpose of this \cs{opcolorbox} is to contain the caption of the
digital photo, and is laid on top of the photo. The key-value pairs passed through the
third (optional) parameter of \cs{digiCap}, are, in turn, passed on to \cs{opcolorbox}
to create the underlying color box for the caption.

\bVerb\takeMeasure{\string\opcolorbox[\ameta{kvs}]\darg{\ameta{text}}}%
\begin{dCmd*}[commandchars=!()]{\bxSize}
\opcolorbox[!ameta(kvs)]{!ameta(text)}
\end{dCmd*}
\eVerb
The optional parameter consists of key-value pairs, the same ones as for the second
option parameter of \cs{digiCap}, see page~\pageref{ss:digiCap}. We reproduce these
key-values here for your convenience:

\paragraph*{Optional key-values for the first parameter}
\begin{description}
   \item[\texttt{borderwidth}:] The border width. The default is \texttt{2pt}
   \item[\texttt{fboxsep}:] The space between the border and the text, the default is \texttt{6pt}
   \item[\texttt{width:}] The width of \cs{parbox}, the default is \cs{linewidth}
   \item[\texttt{bordercolor}:] A named color of border, the default is \texttt{black}. A special value
   of \texttt{nocolor} is recognized, in that case, no color is applied.
   \item[\texttt{bgcolor:}] A named color of background, the default is \texttt{white}. A special value
   of \texttt{nocolor} is recognized, in that case, no color is applied.
   \item[\texttt{borderop:}] A number type, the opacity for border $0 \le \mbox{number} \le 1$, the default is~$.5$
   \item[\texttt{bgop:}] A number type, the opacity for background $0 \le \mbox{number} \le 1$, the default is~$.5$
   \item[\texttt{textop:}] A number type, the opacity for text $0 \le \mbox{number} \le 1$, the default is~$1$
   \item[\texttt{borderblend:}] The blend mode for the border, the default is \texttt{Normal}
   \item[\texttt{bgblend:}] The blend mode for the background, the default is \texttt{Normal}
\end{description}
The second parameter \ameta{text} is the text that is to appear within the
box.\medskip

A document author does not normally have a need to use \cs{opcolorbox}, the
demo file \texttt{eastern\_trip\_ls\_2pg.tex} demonstrates one possible use
of this box.

%\paragraph*{Limitations of \app{dvips}.} It appears that the \textbf{CA} entry
%is not obeyed when the PDF is distilled from a PS file created by \app{dvips}
%(Refer to the documentation for the \pkg{opacity-pro} package for a
%discussion of these entries). Therefore, only the \textbf{ca} entry is
%obeyed.\footnote{The key that directly sets the \textbf{ca} entry is
%\texttt{textop}; however, the \pkg{digicap-pro} does the following: }
%The setting of \ameta{ca} should be small enough to get
%discernable transparency, but not so much that the text is difficult to read.
%Recommendation: set \ameta{ca} to .7 or there abouts.

\newtopic\noindent
That's all for now, I simply must get back to my retirement. \dps

\end{document}