summaryrefslogtreecommitdiff
path: root/texmf-dist/source/latex/opacity-pro/doc/opacity_man.tex
diff options
context:
space:
mode:
Diffstat (limited to 'texmf-dist/source/latex/opacity-pro/doc/opacity_man.tex')
-rw-r--r--texmf-dist/source/latex/opacity-pro/doc/opacity_man.tex364
1 files changed, 364 insertions, 0 deletions
diff --git a/texmf-dist/source/latex/opacity-pro/doc/opacity_man.tex b/texmf-dist/source/latex/opacity-pro/doc/opacity_man.tex
new file mode 100644
index 00000000..1a56a324
--- /dev/null
+++ b/texmf-dist/source/latex/opacity-pro/doc/opacity_man.tex
@@ -0,0 +1,364 @@
+% 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
+}