From b8d4bb76703bcb15578e2b23c5d256532180b894 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Tue, 3 Dec 2019 03:01:24 +0000 Subject: CTAN sync 201912030301 --- .../latex/contrib/graphicxsp/docs/graphicxsp.pdf | Bin 0 -> 127824 bytes macros/latex/contrib/graphicxsp/docs/grxsp_man.pdf | Bin 0 -> 217893 bytes macros/latex/contrib/graphicxsp/docs/grxsp_man.tex | 846 +++++++++++++++++++++ 3 files changed, 846 insertions(+) create mode 100644 macros/latex/contrib/graphicxsp/docs/graphicxsp.pdf create mode 100644 macros/latex/contrib/graphicxsp/docs/grxsp_man.pdf create mode 100644 macros/latex/contrib/graphicxsp/docs/grxsp_man.tex (limited to 'macros/latex/contrib/graphicxsp/docs') diff --git a/macros/latex/contrib/graphicxsp/docs/graphicxsp.pdf b/macros/latex/contrib/graphicxsp/docs/graphicxsp.pdf new file mode 100644 index 0000000000..2ccbfc68dd Binary files /dev/null and b/macros/latex/contrib/graphicxsp/docs/graphicxsp.pdf differ diff --git a/macros/latex/contrib/graphicxsp/docs/grxsp_man.pdf b/macros/latex/contrib/graphicxsp/docs/grxsp_man.pdf new file mode 100644 index 0000000000..45fd08de1c Binary files /dev/null and b/macros/latex/contrib/graphicxsp/docs/grxsp_man.pdf differ diff --git a/macros/latex/contrib/graphicxsp/docs/grxsp_man.tex b/macros/latex/contrib/graphicxsp/docs/grxsp_man.tex new file mode 100644 index 0000000000..1ae9208c75 --- /dev/null +++ b/macros/latex/contrib/graphicxsp/docs/grxsp_man.tex @@ -0,0 +1,846 @@ +% makeindex < aebpro_man.idx > aebpro_man.ind +\documentclass{article} +\usepackage[fleqn]{amsmath} +\usepackage[ + web={centertitlepage,designv,forcolorpaper,tight*,latextoc,pro}, + eforms,linktoattachments,aebxmp +]{aeb_pro} +\usepackage{aeb_mlink} +\usepackage[dvipsone,showembeds]{graphicxsp}\previewOff +\usepackage{array,fancyvrb} + +%\usepackage[LY1]{fontenc} +%\usepackage[scaled=0.93]{helvet} +%\usepackage{mtpro} + +%\usepackage{myriadpro} + +%\usepackage{calibri} +\usepackage[altbullet]{lucidbry} + + +%\usepackage{makeidx}\makeindex + +\usepackage{acroman} +\usepackage[active]{srcltx} + +\urlstyle{tt} + +\def\tutpath{doc/tutorial} +\def\tutpathi{tutorial} +\def\expath{../examples} + +\DeclareDocInfo +{ + university={\AcroTeX.Net}, + title={\texorpdfstring{\pkg{GraphicxSP}\\[1em]} + {GraphicxSP: }Using and re-using Embedded Graphics}, + author={D. P. Story}, + email={dpstory@acrotex.net}, + subject={Documentation for AeB Pro from AcroTeX}, + talksite={\url{www.acrotex.net}}, + version={1.0.3, 2019/11/13}, + Keywords={XMP, E4X, Adobe Acrobat, JavaScript}, + copyrightStatus=True, + copyrightNotice={Copyright (C) \the\year, D. P. Story}, + copyrightInfoURL={http://www.acrotex.net} +} + +\def\anglemeta#1{$\langle\textit{\texttt{#1}}\rangle$} +\def\meta#1{\textit{\texttt{#1}}} +\let\meta\anglemeta +\def\darg#1{\texttt{\{#1\}}} +\def\takeMeasure{\bgroup\obeyspaces\takeMeasurei} +\def\takeMeasurei#1{\global\setbox\webtempboxi\hbox{\ttfamily#1}\egroup} +\def\bxSize{\wd\webtempboxi+2\fboxsep+2\fboxrule} +\let\pkg\textsf +\let\env\texttt +\let\opt\texttt +\let\app\textsf + +\let\amtIndent\leftmargini +\def\SUB#1{${}_{\text{#1}}$} + +\newdimen\aebdimen \aebdimen 0pt %\advance\aebdimen\partopsep +\newcommand\bVerb[1][]{\begingroup#1\vskip\aebdimen\parindent0pt}% +\def\eVerb{\vskip\aebdimen\endgroup\noindent} + +\def\setDisplayNumber#1#2{\kern0pt + \setlength\abovedisplayshortskip{0pt}% + \setlength\belowdisplayshortskip{0pt}% + \setlength\abovedisplayskip{0pt}% + \setlength\belowdisplayskip{0pt}% + \begin{equation}\label{#2}\end{equation}\kern0pt +} + + +\makeatletter +\renewcommand{\paragraph} + {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\bfseries}} +\renewcommand*\l@subsection{\@dottedtocline{2}{1.5em}{2.5em}} +\renewcommand*\descriptionlabel[1]{\hspace\labelsep + \normalfont #1} +\newcommand{\aebDescriptionlabel}[1]{% + \setlength\dimen@{\amtIndent+\labelsep}% + {\hspace*{\dimen@}#1}} +\makeatother +\newenvironment{aebDescript} + {\begin{list}{}{\setlength{\labelwidth}{0pt}% + \setlength{\leftmargin}{\leftmargin}% + \setlength{\leftmargin}{\leftmargin+\amtIndent}% + \setlength\itemindent{-\leftmargin}% + \let\makelabel\aebDescriptionlabel + }}{\end{list}} + +\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 + +\special{!userdict begin + /Draw_Ellipse { + /m matrix currentmatrix def + 4 2 roll translate scale + 0 0 1 0 360 arc + closepath + m setmatrix + } def end +} +\embedEPS[hiresbb,transparencyGroup]{myBestPic}{graphics/AdobeDon} +\embedEPS[hiresbb,transparencyGroup]{myBG}{graphics/border1} + +\begin{createImage}{\bboxOf{myBestPic}}{upsideDownAD} + 0 \heightOf{myBestPic} rmoveto + currentpoint translate + 1 -1 scale [ {myBestPic} /SP pdfmark +\end{createImage} + +\begin{createImage}{\bboxOf{myBestPic}}{transparentAD} + [ /ca .3 /SetTransparency pdfmark + [ {myBestPic} /SP pdfmark +\end{createImage} + +\begin{createImage}{\bboxOf{myBestPic}}{nAdobeDon} + [ {myBestPic} /SP pdfmark +\end{createImage} +\begin{createImage}{\bboxOf{myBestPic}}{dAdobeDon} + [ /ca .3 /SetTransparency pdfmark + [ {myBestPic} /SP pdfmark +\end{createImage} + +\begin{createImage}{\bboxOf{myBestPic}}{rAdobeDon} + [ /ca .5 /SetTransparency pdfmark + [ {myBestPic} /SP pdfmark +\end{createImage} + +\begin{createImage}{0 0 100 100}{xO} +.7529 setgray 0 0 100 100 rectfill 1 setgray 2 2 moveto 2 98 lineto +98 98 lineto 96 96 lineto 4 96 lineto 4 4 lineto fill 0.34 setgray +98 98 moveto 98 2 lineto 2 2 lineto 4 4 lineto 96 4 lineto +96 96 lineto fill 0 setgray 22.5 22.5 moveto 1 0 0 setrgbcolor +/Helvetica 72 selectfont (O) show +\end{createImage} + + +%\definePath\bgPath{"C:/Users/Public/Documents/% +% ManualBGs/Manual_BG_Print_AeB.pdf"} +%\begin{docassembly} +%\addWatermarkFromFile({% +% bOnTop: false, +% cDIPath: \bgPath +%}) +%\executeSave() +%\end{docassembly} + +\chngDocObjectTo{\newDO}{doc} +\begin{docassembly} +var titleOfManual="The graphicxsp Package"; +var manualfilename="Manual_BG_Print_graphicxsp.pdf"; +var manualtemplate="Manual_BG_Blue.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} + +Beginning with Version 5.0, ``Acrobat Distiller allows a Postscript +language program to specify that a given set of graphical operations +should be encapsulated and treated as a single object. The pdfmarks +\textbf{BP} (Begin Picture) and \textbf{EP} (End Picture) enclose a +set of graphic operations. The \textbf{SP} (Show Picture) pdfmark +indicates where to insert an object (which may be inserted in more +than one place).''\,\footnote{Section 4.6.1 of the \textit{pdfmark +Reference Manual}, Technical Note \#5150, Version 5.0} This is the +approach taken by this package. + +\pkg{GraphicxSP} includes commands for embedding an EPS graphic (using the +\textbf{BP} and \textbf{EP} pdfmark operators) in a PDF derived from +a {\LaTeX} source and for displaying the graphic, possibly multiple +times. For documents that use the same graphic multiple times (for +backgrounds, watermarks, company logos, appearances for form fields, +etc.) using \pkg{GraphicxSP} will (greatly) reduce the size of the +PDF.\footnote{The amount of reduction in file size depends on how +many times a particular graphic is repeatedly used.} + +The PDF 1.4 (Acrobat version 5.0) introduces the notion of +transparency into the Adobe imaging model. Support for transparency +through the pdfmark paradigm does not appear until Version +6.0.\,\footnote{Section 4.6.1 of the \textit{pdfmark Reference +Manual}, Technical Note \#5150, Version 6.0, page~33.} This package +also supports transparency feature through the +\textbf{SetTransparency} pdfmark. + +\pkg{GraphicxSP}, as the name might suggest, is an extension of the +graphicx package. Functionality for \pkg{GraphicxSP} is accessed through +the \cs{includegrapics} command. Additional key-values for the +\cs{includegrapics} command are defined that support the use +\pkg{GraphicxSP}. + +\section{Requirements} + +{\LaTeX}, PDF, and transparency requirements are discussed in this section. + +\subsection{{\LaTeX} package requirements} + +This package requires the \pkg{graphicx} package (by D. P. Carlisle and S. P. Q. +Rahtz), the \pkg{eso-pic} package (by Rolf Niepraschk) and the \pkg{everyshi} +package (by Martin Schr\"oder). \pkg{GraphicxSP} redefines a few commands of the +first two packages: the \pkg{graphics}/\pkg{graphicx} package commands \cs{Gin@setfile} +and \cs{Gin@getbase} are redefined, as is the \pkg{eso-pic} command \cs{@ShipoutPicture}. + +\pkg{AeB} (Acro\negthinspace\TeX{} eDucation Bundle) is not a required +package, but to successfully compile the example +\texttt{grxsp\_forms\_aeb.tex}, you need the latest \pkg{AeB} as some +modification to the eforms package were made. See +\mlurl{http://www.math.uakron.edu/~dpstory/graphicxsp.html} for the latest +version. + +\subsection{PDF creator requirements} + +The big restriction on this package is the requirement to use +\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 \app{dvips} and \app{dvipsone}. + +Though distiller is required, there is no reason why, however, this +package can't be modified to work for any PDF creator that supports +the pdfmark; in particular, I invite anyone to extend this package +to \app{GhostScript}. + +\subsection{Transparency requirements} + +To get the transparency effect, \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. + +\newtopic\noindent +The procedure for editing \texttt{.joboptions} to support transparency is as follows: +\begin{enumerate} + \item Start 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 \textsf{Settings\;>\;Edit\;Adobe\;PDF\;Settings\;(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 + \texttt{.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{.joboptions} file, and open it in your + editor. + \item Look for the line \texttt{/AllowTransparency false}, change + \texttt{false} to \texttt{true} so that it now reads + \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! + +\end{enumerate} + +\section{Options of this package} + +Currently, there is a minimal of package options + +\begin{itemize} +\item \texttt{dvips}: Use this option if you are a user of most any other + {\TeX} systems available to the community. +\item \texttt{dvipsone}: Use this option if you are a user of the Y{\small\&}\!Y + {\TeX} system to create your Postscript file. +\item \texttt{preview}: The dvi previewers are designed to show a preview + of the graphic, these previewers know nothing about the \textbf{SP} + pdfmark (Show Picture). If you use the \texttt{preview} option, a + \cs{fbox} is placed around all graphics inserted by the + \pkg{GraphicxSP} package. This option sets a boolean switch, + \cs{ifpreview} to true. You are free to locally set this switch to get + the \cs{fbox} to appear, use include \cs{previewtrue} in your document, + or, to turn the preview off again, type \cs{previewfalse}. +\item \texttt{showembeds}: As just mentioned, dvi previewers are + designed to preview graphics; consequently, the graphic files + embedded by \pkg{GraphicxSP}, will have a preview as well. The + embedding command \cs{embedEPS} is required to appear only in + the preamble, so the preview for this embedded graphics always + appears on the first page. \pkg{GraphicxSP} covers these embedded + files using a white \texttt{colorbox}; content and other + graphics are placed on top of the white \texttt{colorbox}. Using + the \texttt{showembeds} will cause this white color box not to + be created, hence, you can see the dvi preview of the embedded + graphics, stacked one on top of the other. +\item \texttt{draft}: Similar to the option of the same name in the + graphicx package. Instead of displaying an image, a rectangular + box is displayed with the name of the graphic in its interior. +\item \texttt{shownonames}: If this option is chosen along with + the \texttt{draft} option, the name of the graphic is not displayed. +\end{itemize} + +\section{The \texorpdfstring{\protect\pkg{GraphicxSP}}{GraphicxSP} commands} + +In this section we present the new commands defined in the \pkg{GraphicxSP} package. + +\subsection{Embedding commands} + +Before we can show a graphic, we first must embed it using the +\cs{embedEPS} command. +\bVerb\takeMeasure{\string\embedEPS[\meta{key-values}]\darg{\meta{name}}\darg{\meta{path}}} +\begin{dCmd}[commandchars=!()]{\bxSize} +\embedEPS[!meta(key-values)]{!meta(name)}{!meta(path)} +\end{dCmd} +\endgroup +\CmdLoc This command is restricted to the preamble. + +\PD The parameters are as follows: +\begin{enumerate} +\item The first optional parameter takes key-value pairs: +\begin{itemize} + \item \texttt{hiresbb}: This is a key from the graphicx package. + When this key is present, graphicx will look for the high + resolution bounding box; otherwise, is looks for the + bounding box. + \item \texttt{transparencyGroup}: Use this key if the embedded + graphic is to be used with transparency. The key is normally + used by itself, but it can be given values, a good old-fashion + reading of Chapter 7 on Transparency in the PDF Reference, sixth + edition, version 1.7, is necessary. +\end{itemize} +\item The second parameter \meta{name} is the symbolic name for +the graphic. This symbolic name must be unique to the document (or +distiller will crash); \pkg{GraphicxSP} will stop compilation if two +embedded EPS files are given the same name. +\item The third parameter is the path to the graphic, an EPS +graphic. The graphic can be in the current folder, or on the +graphics search path. The same rules hold here as in the graphicx +package. +\end{enumerate} +For example, +\bVerb\takeMeasure{\string\embedEPS[hiresbb,transparencyGroup]\darg{myBestPic}\darg{graphics/AdobeDon}} +\begin{dCmd*}[commandchars=!()]{\bxSize} +\embedEPS[hiresbb,transparencyGroup]{myBestPic}{graphics/AdobeDon} +\end{dCmd*} +\eVerb +When a file is embedded, certain parameters are saved and are +available for use by the document author. Each of the commands below +take the symbolic name, \meta{name} of the graphic as their only +argument. +\begin{itemize} +\item \cs{bboxOf\darg{\meta{name}}}: The dimensions of the bounding box, + \texttt{llx} \texttt{lly} \texttt{urx} \texttt{ury}, of the graphic + with symbolic name \meta{name}. The individual values of this bounding box + can be accessed by the next four commands. + +\item \cs{llxOf\darg{\meta{name}}}: The lower left x-coordinate of the + (high res) bounding box as read by graphicx. + +\item \cs{llyOf\darg{\meta{name}}}: The lower left y-coordinate of the + (high res) bounding box as read by graphicx. + +\item \cs{urxOf\darg{\meta{name}}}: The upper left x-coordinate of the + (high res) bounding box as read by graphicx. + +\item \cs{uryOf\darg{\meta{name}}}: The upper left y-coordinate of the + (high res) bounding box as read by graphicx. + +\item \cs{heightOf\darg{\meta{name}}}: The height of the graphic, based on + the bounding box information, \cs{uryOf\darg{\meta{name}}} - + \cs{llyOf\darg{\meta{name}}}. + +\item \cs{widthOf\darg{\meta{name}}}: The width of the graphic, based on + the bounding box information, \cs{urxOf\darg{\meta{name}}} - + \cs{llxOf\darg{\meta{name}}}. +\end{itemize} +Each expands to a number representing Adobe points. To convert these +numbers for use by {\TeX} just add the suffix \texttt{bp}, e.g., in +{\TeX} space, the height of the graphic is \cs{heightOf\darg{\meta{name}}bp}. + +These commands are useful when creating variations on an +\cs{embedEPS} graphic using the \texttt{createImage} environment +defined below, or for creating form fields with an \cs{embedEPS} +graphic as an appearance. + +The \cs{embedEPS} command is designed for graphics that are in an exterior +EPS file. You can also define a graphic, or image, using raw +Postscript using the \Indextt{createImage} environment. + +%\bVerb\takeMeasure{\string\begin\darg{createImage}[\meta{key-values}]\darg{\meta{bbox}}\darg{\meta{name}}} +%\begin{dCmd}[commandchars=!()]{\bxSize} +%\begin{createImage}[!meta(key-values)]{!meta(bbox)}{!meta(name)} +% !meta(postscript code) +%\end{createImage} +%\end{dCmd} +%\eVerb + + +\bVerb\takeMeasure{\string\begin\darg{createImage}[\meta{key-values}]\darg{\meta{bbox}}\darg{\meta{name}}} +\begin{minipage}[c]{\linewidth} +\begin{minipage}[c]{\bxSize} +\begin{dCmd}[commandchars=!()]{\bxSize} +\begin{createImage}[!meta(key-values)]{!meta(bbox)}{!meta(name)} + !meta(postscript code) +\end{createImage} +\end{dCmd} +\end{minipage}\hfill +\begin{minipage}[c]{\linewidth-(\bxSize)} +\setDisplayNumber\label{createImg} +\end{minipage} +\end{minipage}\medskip +\eVerb The \env{createImage} environment defines a command \cs{\meta{name}} that expands to +\meta{name}. If \cs{\meta{name}} is already defined, a message appears in the log to that effect. +Normally \meta{name} consists of non-active characters; however, if other characters are used, +the command \cs{csOf\darg{\meta{name}}} can be used. The \cs{\meta{name}} command was created to support +the \pkg{icon-appr} package. + +\PD The parameters are as follows: +\begin{enumerate} +\item The first optional parameter takes key-value pairs: +\begin{itemize} + \item \texttt{transparencyGroup}: Use this key if the embedded + graphic is to be use with transparency. The key is normally + used by itself, but it can be given values, a good + old-fashion reading of Chapter 7 on Transparency in the PDF + Reference, sixth edition, version 1.7, is necessary. +\end{itemize} +\item The second parameter, \meta{bbox}, is the bounding box of the +image being created. +\item The third parameter \meta{name} is the symbolic name for +the graphic. This symbolic name must be unique to the document (or +distiller will crash); \pkg{GraphicxSP} will stop compilation if two +embedded EPS files are given the same name. +\end{enumerate} +The following image appears in one of the demo files of this package, and is code +written many years ago for a tic-tac-toe game in PDF. +\begin{Verbatim} +\begin{createImage}{0 0 100 100}{xO} +.7529 setgray 0 0 100 100 rectfill 1 setgray 2 2 moveto 2 98 lineto +98 98 lineto 96 96 lineto 4 96 lineto 4 4 lineto fill 0.34 setgray +98 98 moveto 98 2 lineto 2 2 lineto 4 4 lineto 96 4 lineto +96 96 lineto fill 0 setgray 22.5 22.5 moveto 1 0 0 setrgbcolor +/Helvetica 72 selectfont (O) show +\end{createImage} +\end{Verbatim} + +\begin{Verbatim} +\embedEPS[hiresbb,transparencyGroup]{myBestPic}{graphics/AdobeDon} +\end{Verbatim} +we can then manipulate this image a little +\begin{Verbatim} +\begin{createImage}{\bboxOf{myBestPic}}{upsideDownAD} + 0 \heightOf{myBestPic} rmoveto + currentpoint translate + 1 -1 scale [ {myBestPic} /SP pdfmark +\end{createImage} +\end{Verbatim} +Notice that we reposition the graphic to fit inside the bounding box. + +I don't mean to get ahead of myself, but you can introduce transparency as well. + +\begin{Verbatim} +\begin{createImage}{\bbox{myBestPic}}{transparentAD} + [ /ca .3 /SetTransparency pdfmark + [ {myBestPic} /SP pdfmark +\end{createImage} +\end{Verbatim} +All these examples will appear again below when \cs{includegraphics} and \cs{insertEPS} +are discussed. + +\newtopic\noindent +The commands \cs{llxOf}, \cs{llyOf}, \cs{urxOf}, \cs{uryOf}, \cs{bboxOf}, +\cs{heightOf} and \cs{widthOf} are also defined for images created by the +\texttt{createImage} environment. + + +\subsection{Inserting graphics commands} + +Once we have embedded our graphics using \cs{embedEPS} or create a +new image or modified an old image using the \texttt{createImage} +environment, we can display them to our heart's content. There are two +commands for displaying a embedded graphic, \cs{includegraphics} and +\cs{insertEPS}. + +\bVerb\takeMeasure{\string\includegraphics[name=\meta{name},\meta{key-values}]\darg{\meta{path}}} +\begin{dCmd}[commandchars=!()]{\bxSize} +\includegraphics[name=!meta(name),!meta(key-values)]{!meta(path)} +\insertEPS[!meta(key-values)]{!meta(name)} +\end{dCmd} +\endgroup + +\PD The \meta{name} key is required in the \cs{includegraphics} +command, the value is the symbolic \meta{name} of the graphic to +be used. When the name key is used, the \meta{path} parameter is not +used in \pkg{GraphicxSP} and can actually be empty; if the name key is not +specified, then \cs{includegraphics} behaves just like it always +does, includes the file in the document and displays it. Because +\meta{path} is not used with SP graphics, \pkg{GraphicxSP} offers +\cs{insertEPS} as an alternative; here the \meta{name} is given as the +second argument. The \meta{key-values} are described next. + +\KVP Both commands take all the key-values of the \cs{includegraphics} command, plus +a few more: +\begin{enumerate} + \item \texttt{name=\meta{name}}: The symbolic name (\meta{name}) for + the graphic, it is required with the \cs{includegraphics} command, + and is ignored in the \cs{insertEPS} command. In the later command, + \meta{name} is entered as the second argument. + + \item \texttt{transparency=\meta{key-values}}: Here you can enter + various key-value pairs for setting transparency. These + keys-values are listed in the pdfmark Reference in the section + on the SetTransparency pdfmark. Of the ones listed, I've only explored + \textbf{BM}, \textbf{ca} and \textbf{CA}. The following come from the pdfmark Reference on these three: + \begin{itemize} + \item \textbf{CA}: Current stroking alpha constant, + specifying the constant shape or constant opacity value to + be used for stroking operations. Default is 1.0. + \item \textbf{ca}: Same as CA, but for nonstroking operation. Default is 1.0. + \item \textbf{BM}: Current blend mode. Default is Normal. + Other blend modes are Normal, Multiply, Screen, + Darken, Lighten, ColorDodge, ColorBurn, HardLight, + SoftLight, Difference, Exclusion. See the PDF + Reference for a description of these. + + \end{itemize} + The most useful of these is \textbf{ca}, and it is illustrated + in the demo files and well as here. + + \item[] \textbf{Example:} \verb!transparency={/ca .3 /BM/Normal}! + + \item \texttt{presp=\meta{postscript}}: This allows you to insert + Postscript commands just before \textbf{SP} pdfmark. + \item \texttt{postsp=\meta{postscript}}: This allows you to insert + Postscript commands just after \textbf{SP} pdfmark. +\end{enumerate} +The latter two key-values can be used to create special effects, as illustrated below. + +\subsection{Examples} + +%\previewtrue + +\begin{center} +\includegraphics[name=myBestPic,width=1in]{}\\ +\small\verb!\includegraphics[name=myBestPic,width=1in]{}! +\end{center} + +Below is the image created not from a EPS file, but from Postscript language code. + +\begin{center} +\includegraphics[name=xO,width=1in]{}\\ +\small\verb!\includegraphics[name=x0,width=1in]{}! +\end{center} + +The \meta{path} argument can remain empty as it is not used when the name key is +present. Now, we'll switch over to the shorter \cs{embedEPS} command. + +Here is the image created earlier using the \texttt{createImage} environment. The same effect +can be done with \cs{scalebox}. + +\begin{center} +\insertEPS[width=1in]{upsideDownAD}\\ +\verb!\insertEPS[width=1in]{upsideDownAD}! +\end{center} + +Below is the transparent image created using the \texttt{createImage} environment. The same effect +can be done by setting the \texttt{transparency} key set to \verb!{/ca .3}!. The background is white +and it is this white background you see showing through the image. + +\begin{center} +\insertEPS[width=1in]{transparentAD}\\ +\verb!\insertEPS[width=1in]{transparentAD}! +\end{center} + + + +Next, we set the \texttt{transparency} key to an opacity value ranging from 70\% on the left (\texttt{/ca .7}) +to 30\% on the right (\texttt{/ca .3}), and place a colorful background under the +image so you can see the transparency of the image. + +\begin{center}\previewfalse +\insertEPS[width=\linewidth,height=80pt]{myBG} %transparency={/ca .3 /BM/Normal}, +\smash{\raisebox{15pt}{\makebox[\linewidth][c]{% +\insertEPS[width=1in,transparency={/ca .7}]{myBestPic}\hfill +\insertEPS[width=1in,transparency={/ca .6}]{myBestPic}\hfill +\insertEPS[width=1in,transparency={/ca .5}]{myBestPic}\hfill +\insertEPS[width=1in,transparency={/ca .4}]{myBestPic}\hfill +\insertEPS[width=1in,transparency={/ca .3}]{myBestPic}}}} +\small\verb!transparency={/ca .7}...transparency={/ca .3}! +\end{center} + +We can rotate the image using the usual graphicx controls, as below, or we can +use \cs{rotatebox}. + +\begin{center} +\insertEPS[width=1in,angle=45]{myBestPic}\\ +\small\verb!\insertEPS[width=1in,angle=45]{myBestPic}! +\end{center} + +Any of the keys of \cs{includegraphics} can be used to manipulate +the image. The images can also be manipulated using other graphicx +commands, \cs{resizebox}, \cs{scalebox} and \cs{rotatebox}, for +example. + +Finally, here is an example of the use of \texttt{presp} and \texttt{postsp}: + +\def\mypreSP#1{% + newpath + \widthOf{#1} 2 div \heightOf{#1} 2 div + \widthOf{#1} 2 div \heightOf{#1} 2 div + Draw_Ellipse + clip + newpath +} +\def\mypostSP#1{% + gsave + [ /ca .4 /SetTransparency pdfmark + \widthOf{#1} 2 div \heightOf{#1} 2 div + \widthOf{#1} 2 div \heightOf{#1} 2 div + Draw_Ellipse + 0.4 0.7 1 setrgbcolor + fill + grestore + gsave + [ /CA .5 /BM/Screen /SetTransparency pdfmark + \widthOf{#1} 2 div \heightOf{#1} 2 div + \widthOf{#1} 2 div \heightOf{#1} 2 div + Draw_Ellipse + 40 setlinewidth + 0.4 0.7 1 setrgbcolor + stroke + grestore +} + +\begin{center} +\includegraphics[name=myBestPic,width=1.5in, + presp={\mypreSP{myBestPic}}, + postsp={\mypostSP{myBestPic}}]{myBestPic} +\end{center} +The \texttt{presp} code is + +\begin{Verbatim}[fontsize=\small] +\def\mypreSP#1{% + newpath + \widthOf{#1} 2 div \heightOf{#1} 2 div + \widthOf{#1} 2 div \heightOf{#1} 2 div + Draw_Ellipse + clip + newpath +} +\end{Verbatim} +and clips the image in the shape of an ellipse. In this case, the +image is almost square, so the image is almost circular. + +The \texttt{postsp} is + +\begin{Verbatim} +\def\mypostSP#1{% + gsave + [ /ca .4 /SetTransparency pdfmark + \widthOf{#1} 2 div \heightOf{#1} 2 div + \widthOf{#1} 2 div \heightOf{#1} 2 div + Draw_Ellipse + 0.4 0.7 1 setrgbcolor + fill + grestore + gsave + [ /CA .5 /BM/Screen /SetTransparency pdfmark + \widthOf{#1} 2 div \heightOf{#1} 2 div + \widthOf{#1} 2 div \heightOf{#1} 2 div + Draw_Ellipse + 40 setlinewidth + 0.4 0.7 1 setrgbcolor + stroke + grestore +} +\end{Verbatim} +After clipping the image itself, and displaying the image, we then +cover the image with an ellipse the same size, set the transparency +to 40\% opacity and fill, giving the image a bluish haze. Next, draw +the ellipse again and stroke it with a line 40 points wide. Give it an +opacity of 50\%, so \texttt{AdobeDon} will shine through. + + +\section{Special techniques for form appearances}\label{forms} + +In addition to using embedded graphics to display an image with +\cs{includegraphics} or \cs{insertEPS}, these images can be +used as appearances for form fields. Examples of a push button and +checkbox can be found in the demo files, here reproduce the push +button example. + +For this techniques, the eforms package is required. The forum +support of hyperref may not support the \textbf{AP} key the way +eforms does. + +In the preamble, we have +\begin{Verbatim} +\begin{createImage}{\bboxOf{myBestPic}}{nAdobeDon} + [ {myBestPic} /SP pdfmark +\end{createImage} + +\begin{createImage}{\bboxOf{myBestPic}}{rAdobeDon} + [ /ca .5 /SetTransparency pdfmark + [ {myBestPic} /SP pdfmark +\end{createImage} + +\begin{createImage}{\bboxOf{myBestPic}}{dAdobeDon} + [ /ca .3 /SetTransparency pdfmark + [ {myBestPic} /SP pdfmark +\end{createImage} +\end{Verbatim} + +We use \cs{bboxOf} to set the bounding boxes to be the same as the +original \texttt{myBestPic} image, and define a normal, rollover and +down appearances for the button (\texttt{nAdobeDon}, +\texttt{rAdobeDon} and \texttt{dAdobeDon}), respectively. We use +various opacity settings for the appearances. + +The button code is + +\begin{Verbatim}[xleftmargin=\parindent,fontsize=\small] +\resizebox{.5in}{!}{\pushButton[\BC{}\BG{}\S{S} + \A{\JS{app.alert("AcroTeX rocks the world!"); this.dirty=false;}} + \autoCenter{y}\TP{1}\FB{true} + \I{nAdobeDon}\IX{dAdobeDon}\RI{rAdobeDon} +]{pbAdobeDon}{\widthOf{myBestPic}bp}{\heightOf{myBestPic}bp}} +\end{Verbatim} +See the \pkg{eforms} manual for details of these key-value pairs.\smallskip + +Finally, the button looks like this: \resizebox{.5in}{!}{\pushButton[% + \autoCenter{y}\BC{}\BG{}\S{S} + \A{\JS{app.alert("AcroTeX rocks the world!");this.dirty=false;}} + \I{nAdobeDon}\IX{dAdobeDon}\RI{rAdobeDon}\TP{1}\FB{true} +]{pbAdobeDon}{\widthOf{myBestPic}bp}{\heightOf{myBestPic}bp}}\par\smallskip\noindent +In light of the discussion following display~\eqref{createImg} on page~\pageref*{createImg}, the code for the above +button could have been, +\begin{Verbatim}[xleftmargin=\parindent,fontsize=\small] +\resizebox{.5in}{!}{\pushButton[\BC{}\BG{}\S{S} + \A{\JS{app.alert("AcroTeX rocks the world!"); this.dirty=false;}} + \autoCenter{y}\TP{1}\FB{true} + \I{\nAdobeDon}\IX{\dAdobeDon}\RI{\rAdobeDon} +]{pbAdobeDon}{\widthOf{myBestPic}bp}{\heightOf{myBestPic}bp}} +\end{Verbatim} +When using \textbf{SP} images for form fields in this way, the images +\textbf{must always pass} through a \texttt{createImage} environment where the +bounding boxes can be precisely set, in the verbatim listing above, +note \verb!\bboxOf{myBestPic}! sets the bounding box. The reason you +can't use an embedded image directly is that the embedded image has +had its bounding box reset to an enormous value. See the +documentation in graphicxsp.dtx for more details. + +The dimensions of the push button are the last two arguments of the +\cs{pushButton} command and are set to \verb!\widthOf{myBestPic}bp! +and \verb!\heightOf{myBestPic}bp!, (Note the use of the \texttt{bp} +dimension.) We then resize this field using \cs{resizebox}! Very +swave how the graphicx and \pkg{GraphicxSP} work together. + +\section{Tips} + +Since you are using distiller, you have Acrobat as well. Try using +the PDF Optimizer (\texttt{Advanced > PDF Optimizer} menu) to +further reduce the size of the file. If you have Acrobat Pro 8.0, +you can do a Save As, by selecting Adobe PDF Files, Optimized from +the Save as type list. This is the same as using the PDF Optimizer. + +An example of the savings is this manual, after distillation +document size was 176.6 KB, after the PDF Optimizer was done, the +file size was 113.6 KB. That's a reduction of 63 KB or that's a +reduction of 38\,\%. For some of the demo files, the reduction is +much more dramatic since the images are used and re-used many more +times than in this document. + + +\section{\texorpdfstring{\protect\pkg{GraphicxSP}}{GraphicxSP} example files} + +The example files can be found in the \texttt{examples} folder of the \pkg{GraphicxSP} +distribution. They are +\begin{itemize} +\item \texttt{grxsp\_tst\_noaeb.tex}: General test file demonstrating SP graphics, + does not require AeB (Acro\negthinspace\TeX{} eDucation Bundle). +\item \texttt{grxsp\_tst\_aeb.tex}: Same as previous file, but using AeB. +\item \texttt{grxsp\_comp\_noaeb.tex}: A comparison between graphicx \cs{includegraphics} + and SP graphics. AeB not used. +\item \texttt{grxsp\_comp\_aeb.tex}: Same as previous file, but AeB is used. +\item \texttt{grxsp\_forms\_aeb.tex}: This file demonstrates using SP graphics as appearances + of form fields. AeB required. +\item \texttt{grxsp\_layers\_aebpro.tex}: Demonstrates the use of SP graphics with + Optional Content Groups, or layers. AeB Pro required. +\end{itemize} + +\noindent +That's all for now, I simply must get back to my retirement. \dps + +\end{document} -- cgit v1.2.3