path: root/texmf-dist/source/latex/digicap-pro/doc/digicap_man.tex

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