% makeindex < aebpro_man.idx > aebpro_man.ind
\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage[
    web={centertitlepage,usetemplates,designv,
        forcolorpaper,latextoc,extended},
    eforms,uselayers,graphicxsp={showembeds},aebxmp
]{aeb_pro}
\usepackage{opacity-pro}

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

\usepackage[altbullet]{lucidbry}

%\usepackage{makeidx}
%\makeindex

\usepackage{acroman}

%\usepackage[active]{srcltx}


\urlstyle{rm}
\let\pkg\textsf
\let\app\textsf
\let\env\texttt

\def\tutpath{doc/tutorial}
\def\tutpathi{tutorial}
\def\expath{../examples}

\DeclareDocInfo
{
    university={\AcroTeX.Net},
    title={ \texorpdfstring{Opacity-Pro\\[1em]}
        {Opacity-Pro: }Support for transparency},
    author={D. P. Story},
    email={dpstory@acrotex.net},
    subject={Documentation for AeB Pro from AcroTeX},
    talksite={\url{www.acrotex.net}},
    version={1.1, 2018/05/13},
    keywords={AeB, Adobe Acrobat, JavaScript, transparency},
    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

\reversemarginpar

\chngDocObjectTo{\newDO}{doc}
\begin{docassembly}
var titleOfManual="The Opacity Pro Manual";
var manualfilename="Manual_BG_Print_opacity.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 \pkg{opacity-pro} package defines one command and one environment that are
used to set the \emph{opacity} and \emph{blend} of an object. The reader interested in
transparency should read Chapter 7 of the \textsl{PDF Reference, Sixth
Edition} for Version 1.7. The techniques used in this package were derived
from the \textsl{pdfmark Reference}.

As the suffix ``\texttt{pro}'' might suggest, this package is for
those who use distiller version 6.0 or greater to produce PDFs. The
\textsf{opacity-pro} uses distiller with the \textsf{Adobe PDF
Settings} set to process the transparency operator. For your
convenience, the \textsf{Adobe PDF Settings} file
\texttt{Standard\_transparency.joboptions} is included in the
distribution. Place this file wherever distiller looks for the
\texttt{.joboptions} files.\footnote{Go to \texttt{Settings > Edit
Adobe PDF Settings ...} in the Distiller application window, then
click the \texttt{SaveAs} button. A \textsf{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.}

The package doesn't really require other packages, but normally, it
is used with the color or the graphicx packages. It does require
that a .dvi to .ps converter be used that recognizes the special
\verb!\special{ps: ...}!.  This includes, of course,
\textsf{dvips}.

\section{Requirements and Options}

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}

A minimal example can be successfully compiled using the \pkg{opacity-pro} package alone.


\subsection{Package options}

There are two options \opt{dvips} and \opt{dvipsone}\marginpar{\small \raggedleft\opt{dvips}\\\opt{dvipsone}} corresponding
to the two converter
utilities \app{dvips.exe} and \app{dvipsone.exe}. The \opt{dvips} option is the default so
it need not be specified.

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

The big restriction on this package is the requirement to
use \app{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
\app{dvips} and \app{dvipsone}. These ``drivers'' are defined through the
required package \app{aeb\_pro}.

\subsection{Transparency Requirements}

To get the transparency effect\marginpar{\small\raggedleft\app{Distiller} required}, \app{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 \pkg{opacity-pro} package comes with a \app{Distiller} job options file named
\texttt{Standard\_transparency.joboptions}. Instead of going through 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{Setting transparency}

In this section we present the \cs{settransparency} command and the
\env{settransparency} environment.

\bVerb\takeMeasure{\cs{settransparency}*[\ameta{BM}]\darg{\ameta{ca}}\darg{\ameta{CA}}[\ameta{PDFKVs}]\darg{\ameta{content}}}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\settransparency*[!ameta(BM)]{!ameta(ca)}{!ameta(CA)}[!ameta(PDFKVs)]{!ameta(content)}
\end{dCmd}
\eVerb The syntax for the environment is,
\bVerb\takeMeasure{\string\begin\darg{settransparency}[\ameta{BM}]\darg{\ameta{ca}}\darg{\ameta{CA}}[\ameta{PDFKVs}]}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\begin{settransparency}[!ameta(BM)]{!ameta(ca)}{!ameta(CA)}[!ameta(PDFKVs)]
!quad!ameta(content)
\end{settransparency}
\end{dCmd}
\eVerb There is a star-version as well.
\bVerb\takeMeasure{\string\begin\darg{settransparency*}[\ameta{BM}]\darg{\ameta{ca}}\darg{\ameta{CA}}[\ameta{PDFKVs}]}%
\begin{dCmd}[commandchars=!()]{\bxSize}
\begin{settransparency*}[!ameta(BM)]{!ameta(ca)}{!ameta(CA)}[!ameta(PDFKVs)]
!quad!ameta(content)
\end{settransparency*}
\end{dCmd}
\eVerb The parameters are,
\begin{enumerate}
 \item[\texttt{*}] (optional) If present, the PDF entries \textbf{ca} and \textbf{CA}
     are set as \texttt{/ca \ameta{ca}} and \texttt{/CA \ameta{CA}};
     otherwise, the algorithm for setting the \textbf{ca} and \textbf{CA}
     entries into the PDF is used. The algorithm is described in the
     paragraph \textbf{\nameref{para:limits}} below.
 \item[\ameta{BM}] Current blend mode. Names recognized are \texttt{Normal}, \texttt{Multiply},
 \texttt{Screen}, \texttt{Overlay}, \texttt{Darken},
 \texttt{Lighten}, \texttt{ColorDodge}, \texttt{ColorBurn},
 \texttt{HardLight}, \texttt{SoftLight}, \texttt{Difference},
 \texttt{Exclusion}, \texttt{Hue}, \texttt{Color}, \texttt{Saturation}  and
 \texttt{Luminosity}. See the accompanying file \texttt{blend\-modes.tex} for a description
                      of each.
 \item[\ameta{ca}] Current alpha constant, specifying the constant
      shape or constant opacity value to be used for \emph{non-stroking operations}, which
      includes filling paths. A number between 0 and 1, inclusive. Default is 1.0.
 \item[\ameta{CA}] Current stroking alpha constant, specifying the constant
      shape or constant opacity value to be used for \emph{stroking operations}.
      A number between 0 and 1, inclusive. Default is 1.0.
\item[\ameta{PDFKVs}] (optional) These pairs can be inserted using the optional
    fourth parameter (see page 38 of the \textsl{pdfmark Reference, Version
    8.0}, for a listing of these other key-value pairs).
\end{enumerate}
 In the environment case, the last parameter is optional, so {\TeX} will be
 looking for a left brace `\texttt{[}', if the \ameta{content} of the environment
 begins with a command, that command will get expanded while {\TeX} looks for
 a left brace; if this is a problem, simply put an empty optional argument
 `\texttt{[]}' to make {\TeX} happy.

The target object, \ameta{contents},\footnote
{These can be text, pictures, color boxes, and so on.} is either the fifth argument, or
the content of the environment.

Refer to the examples provided by this distribution to see the command and
environment in action.

\paragraph*{Limitations of \app{dvips}.}\label{para:limits} A background,
such as one created by \cs{colorbox} or \cs{fcolorbox} may be stroked
(\ameta{ca}) as \app{dvipsone} does, or filled (\ameta{CA}) as \app{dvips}
does. Text is usually filled (\ameta{ca}). Because \app{dvips} fills a
background and text, it creates a problem when trying to have text overlay a
colorful background, where the text and background have different opacity
values (both set by \ameta{ca}).

\subparagraph*{An algorithm.} For \app{dvips}, we implement the following
algorithm: The value of \ameta{ca} is taken from the value of \ameta{CA}, if
the value of \ameta{CA} is specified. In this way, for \app{dvips} we always
have $\mbox{\ameta{ca}}=\mbox{\ameta{CA}}$. We do it this way because of the
\pkg{digicap-pro} package; the user sets the \texttt{textop} key
(corresponding to \ameta{CA}) and the \texttt{bgop} key (\ameta{ca}).

\subparagraph*{Bypassing the algorithm with \texttt{*}.} When the star-option
is taken, the algorithm is bypassed; as a result we set \texttt{/ca
\ameta{ca}} and \texttt{/CA \ameta{CA}}. This is useful in instances where
paths are stroked. See the sample file \texttt{op-pst.tex} for an example of
the use of the star-option.

%\begin{flushleft}
%\quad\settransparency{.2}{}{\colorbox{yellow}{\settransparency{.2}{}{Some text}}}
%\end{flushleft}
\subparagraph*{Recommendations.} 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 thereabouts.

\paragraph*{Contrasting background and text using different opacities}\leavevmode
\begin{description}
\item[\bfseries\textsf{dvips}] The first item below illustrates that \textsf{dvips} does not obey
the second argument. The second item show a workaround.\footnote{The effects illustrated for this
case are simulated as the author uses the \textsf{dvipsone} driver.}
  \begin{itemize}
    \item \settransparency{.7}{.7}{\colorbox{yellow}{\textbf{Some text}}}\\[3pt]
        {\small\verb~\settransparency{.7}{.2}{\colorbox{yellow}{\textbf{Some text}}}~}\\[3pt]
        In the above yellow box, both the background yellow and the
        foreground text have opacity .7 because \app{dvips} fills both
        background and text.
    \item \settransparency{.2}{.2}{\colorbox{yellow}{\settransparency{.7}{.7}{\textbf{Some text}}}}\\[3pt]
        {\small\verb~\settransparency{.2}{.2}{\colorbox{yellow}~\\
        \null\qquad\verb~{\settransparency{.7}{.7}{\textbf{Some text}}}}~}\\[3pt]
        That is, we enclose the yellow background in a transparency value of .2 (the first argument is read only)
        and within the \cs{colorbox} argument, we use a transparency value of .7 (first argument is read only).

        For \app{dvips} users, the second argument can be empty, because, again, only the first argument has
        any effect on filled objects.
  \end{itemize}
\item[\bfseries\textsf{dvipsone}] \settransparency{.7}{.2}{\colorbox{yellow}{\textbf{Some text}}}\\[3pt]
        {\small\verb~\settransparency{.7}{.2}{\colorbox{yellow}{\textbf{Some text}}}~}\\[3pt]
       For the \textsf{dvipsone} driver,\footnote{very few users of
       \textsf{dvipsone} remain on earth, I am one.} the second parameter
       has an effect.
\end{description}

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

\end{document}
% ca = text, CA=background dvips obeys only ca, so we want to
% set CA = ca wherever possible
\def\op@ck@defs#1#2{\def\op@argi{#1}\def\op@argii{#2}%
  \def\op@ca{\@empty}\def\op@CA{\@empty}%
    \ifx\op@argii\@empty
    \else
      \def\op@CA{/CA #2}%
    \fi
    \if\op@driver0\relax
      \ifx\op@argi\@empty
        \edef\op@ca{\noexpand\def\noexpand\op@ca{\op@CA}}%
        \lowercase\expandafter{\op@ca}% ca = CA
      \else
        % ca nonempty
        \ifx\op@argii\@empty
          \def\op@ca{/ca #1}%
          \def\op@CA{/CA #1}% CA = ca
        \else % CA nonempty
          % in this case, we set ca = CA, even though
          % there is a value for ca
          \def\op@ca{/ca #2}% ca = CA
        \fi
      \fi
    \else
      \def\op@ca{/ca #1}%
    \fi
}