animate (23sep14)

git-svn-id: svn://tug.org/texlive/trunk@35238 c570f23f-e606-0410-a88d-b1316a301751

4 files changed, 64 insertions, 33 deletions

diff --git a/Master/texmf-dist/doc/latex/animate/ChangeLog b/Master/texmf-dist/doc/latex/animate/ChangeLog
index d40312302b7..acc04eb1983 100644
--- a/Master/texmf-dist/doc/latex/animate/ChangeLog
+++ b/Master/texmf-dist/doc/latex/animate/ChangeLog
@@ -1,3 +1,12 @@
+2014-09-23
+	* Change: Ghostscript 9.15+ now required for PS to PDF conversion;
+	`depth' option now deprecated and ignored
+	* New: options `totalheight', `keepaspectratio', `nomouse' added; `width',
+	`height', `totalheight', `keepaspectratio', `scale' added as package options
+	* Fix: OCG and XObject-related code rewritten, mostly thanks to recent
+	 Ghostscript additions and fixes (BDC, EMC, SP pdfmarks); code reorganized
+	 in order to reduce driver dependent code
+
 2014-08-07
 	* Fix: improved fix from 2014-08-06, removing need for global catcode
 	changes
@@ -18,7 +27,7 @@
 
 2014-03-25
 	* fix: bugs related to AcroForm and OCProperties catalog entries;
-	documenation
+	documentation
 
 2014-03-12
 	* Fix: incompatibility with pgf-3.0
@@ -30,7 +39,7 @@
 	* Change: Dependency of controls on OCGs removed; better LuaLaTeX support
 
 2014-02-06
-	* New: JavaScript API for animation control
+	* New: JavaScript API for animation control added
 	* Fix: broken PDF-XChange Viewer support due to [2013-07-19] changes
 
 2013-09-24
diff --git a/Master/texmf-dist/doc/latex/animate/README b/Master/texmf-dist/doc/latex/animate/README
index b522816f591..85943467d4c 100644
--- a/Master/texmf-dist/doc/latex/animate/README
+++ b/Master/texmf-dist/doc/latex/animate/README
@@ -17,8 +17,8 @@ Description:
     It supports the usual PDF making workflows, i. e.  pdfLaTeX, LaTeX -> dvips
     -> ps2pdf (Ghostscript)/Distiller and (Xe)LaTeX -> (x)dvipdfmx.
 
-    The resulting PDF can be viewed in current Adobe Readers on all supported
-    platforms.
+    The resulting PDF can be viewed in current Adobe Readers on supported
+    platforms (except mobile devices).
 
     Note, this file only gives a summary of usage and available package and
     command options. Please refer to the documentation `animate.pdf' for details
@@ -34,10 +34,12 @@ Usage:
 
     \usepackage[<package options>]{animate}
 
-    * Package options: autopause, autoplay, autoresume, controls, final, draft,
-                     buttonsize=<size>, buttonbg=<colour>, buttonfg=<colour>,
-                     loop, palindrome, step, poster[=first | none | last],
-                     useocg, dvipdfmx, xetex
+    * Package options: width=<h-size>, height=<v-size>, totalheight=<v-size>,
+                       keepaspectratio, scale=<factor>, nomouse,
+                       autopause, autoplay, autoresume, controls, final, draft,
+                       buttonsize=<size>, buttonbg=<colour>, buttonfg=<colour>,
+                       loop, palindrome, step, poster[=first | none | last],
+                       useocg, dvipdfmx, xetex
 
 
     \animategraphics[<options>]{<frame rate>}{<file basename>}{<first>}{<last>}
@@ -54,8 +56,9 @@ Usage:
     }
     \end{animateinline}
 
-    * Command options: width=<width>, height=<height>, depth=<depth>,
-                       scale=<factor>, autopause, autoplay, autoresume, final,
+    * Command options: width=<h-size>, height=<v-size>, totalheight=<v-size>,
+                       keepaspectratio, scale=<factor>, nomouse,
+                       autopause, autoplay, autoresume, final,
                        draft, controls, buttonsize=<size>, buttonbg=<colour>,
                        buttonfg=<colour>, loop, palindrome, step, measure,
                        poster[=first | none | last], begin={<begin text>},
@@ -69,7 +72,7 @@ Requirements:
 
     e-TeX
     pdfTeX, version >= 1.20
-    Ghostscript, version >= 8.31 or Adobe Distiller
+    Ghostscript, version >= 9.15 or Adobe Distiller
     dvipdfmx, version >= 20080607
     Adobe Reader, version >= 7
 
diff --git a/Master/texmf-dist/doc/latex/animate/animate.pdf b/Master/texmf-dist/doc/latex/animate/animate.pdf
index 8df430904ef..510d0092273 100644
--- a/Master/texmf-dist/doc/latex/animate/animate.pdf
+++ b/Master/texmf-dist/doc/latex/animate/animate.pdf
diff --git a/Master/texmf-dist/doc/latex/animate/animate.tex b/Master/texmf-dist/doc/latex/animate/animate.tex
index 3f1e902f64a..a826ae8703b 100644
--- a/Master/texmf-dist/doc/latex/animate/animate.tex
+++ b/Master/texmf-dist/doc/latex/animate/animate.tex
@@ -1,4 +1,4 @@
-% Copyright 2007--2010 Alexander Grahn
+% Copyright 2007--\today Alexander Grahn
 %
 % This material is subject to the LaTeX Project Public License. See
 %    http://mirrors.ctan.org/help/Catalogue/licenses.lppl.html
@@ -10,6 +10,7 @@
 \usepackage{pst-3dplot}
 \usepackage{pst-node,pst-plot,pst-tools,pst-text,pst-ode}
 \usepackage{media9}
+%\usepackage[useocg]{animate}
 \usepackage{animate}
 \usepackage{intcalc}
 \usepackage{graphicx}
@@ -67,6 +68,8 @@
 %  pdfpagelayout=SinglePage
 }
 
+%\usepackage[scaled=0.85]{luximono}
+
 \def\XeLaTeX{X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}}\kern-.125em\LaTeX}
 \def\pXepLaTeX{(X\kern-.1667em\lower.5ex\hbox{\reflectbox{E}})\kern-.125em\LaTeX}
 
@@ -84,7 +87,7 @@
 \def\@anim@sanitize{}\def\@anim@endsanitize{}
 \expandafter\parsedate\@anim@version\relax %set current date to package date
 \makeatother
-\author{Alexander Grahn \animategraphics[autoplay,loop,height=1.8ex]{8}{bye_}{0}{3}\protect\footnote{Animated GIF taken from \href{http://www.phpBB.com}{phpBB} forum software and burst into a set of EPS files using \href{http://www.imagemagick.org}{ImageMagick} before embedding.} \protect\footnote{Animations may run slowly if viewed in the Adobe Reader browser plugin.}\\[1ex]\includegraphics[height=2.7ex]{mailto}}
+\author{Alexander Grahn \animategraphics[autoplay,loop,height=1.8ex,nomouse]{8}{bye_}{0}{3}\protect\footnote{Animated GIF taken from \href{http://www.phpBB.com}{phpBB} forum software and burst into a set of EPS files using \href{http://www.imagemagick.org}{ImageMagick} before embedding.} \protect\footnote{Animations may run slowly if viewed in the Adobe Reader browser plugin.}\\[1ex]\includegraphics[height=2.7ex]{mailto}}
 \maketitle
 \endgroup
 \begin{abstract}
@@ -112,8 +115,8 @@ The final PDF can be viewed in current Adobe Readers on all supported platforms
 \begin{trivlist}
 \item $\varepsilon$-\TeX
 \item pdf\TeX{}, version $\ge1.20$ or Lua\TeX{} for direct PDF output
-\item Ghostscript, version $\ge8.31$ or Adobe Distiller for PS to PDF conversion
-% \item Ghostscript, version $\ge9.15$ or Adobe Distiller for PS to PDF conversion
+%\item Ghostscript, version $\ge9.31$ or Adobe Distiller for PS to PDF conversion
+\item Ghostscript, version $\ge9.15$ or Adobe Distiller for PS to PDF conversion
 \item dvipdfmx, version $\ge20080607$ for DVI to PDF conversion
 \item Adobe Reader, version $\ge7$ or PDF-XChange Viewer
 \end{trivlist}
@@ -144,16 +147,21 @@ palindrome
 draft
 final
 controls
+width=<h-size>
+height=<v-size> | totalheight=<v-size>
+keepaspectratio
+scale=<factor>
 buttonsize=<size>
 buttonbg=<colour>
 buttonfg=<colour>
 step
+nomouse
 useocg
 poster[=first | none | last]
 \end{verbatim}
 Except for `\verb+dvipdfmx+' and `\verb+xetex+', the options above are also available (among others) as command options and will be explained shortly. However, if used as package options they have global scope, taking effect on all animations in the document. In turn, command options locally override global settings. Options without an argument are boolean options and can be negated, with the exception of package-only options `\verb+dvipdfmx+' and `\verb+xetex+', by appending `\verb+=false+'.
 
-If PDF is generated via DVI and Postscript by the command sequence \verb+latex+ $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+, the `graphicx' package is required. \begin{animateinline}[autoplay,loop]{1}\strut\emph{Important:}\newframe[3]\end{animateinline} The \verb+dvips+ option `\verb+-Ppdf+' should \emph{not} be set when converting the intermediate DVI into Postscript. If you cannot do without, put `\verb+-D 1200+' \emph{after} `\verb+-Ppdf+' on the command line. Users of \LaTeX-aware text editors with menu-driven toolchain invocation, such as \TeX{}nicCenter, should check the configuration of the \verb+dvips+ call.
+If PDF is generated via DVI and Postscript by the command sequence \verb+latex+ $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+, the `graphicx' package is required. \begin{animateinline}[autoplay,loop,nomouse]{1}\strut\emph{Important:}\newframe[3]\end{animateinline} The \verb+dvips+ option `\verb+-Ppdf+' should \emph{not} be set when converting the intermediate DVI into Postscript. If you cannot do without, put `\verb+-D 1200+' \emph{after} `\verb+-Ppdf+' on the command line. Users of \LaTeX-aware text editors with menu-driven toolchain invocation, such as \TeX{}nicCenter, should check the configuration of the \verb+dvips+ call.
 
 %Sometimes, if the same animation sequence made from graphics files is to be embedded multiple times into the document, more compact PDF output may be obtained by passing option `\verb+-dMaxInlineImageSize=0+' to \verb+ps2pdf+.
 
@@ -161,6 +169,7 @@ If PDF is generated via DVI and Postscript by the command sequence \verb+latex+
 
 Occasionally, a second \LaTeX{} run may be necessary to resolve internally created object references. An appropriate warning will be issued in such a case.
 
+\clearpage
 \section{The user interface}
 Package `animate' provides the command
 \begin{verbatim}
@@ -254,11 +263,11 @@ step
 \end{verbatim}
 Step through the animation one frame at a time per mouse-click. The \verb+<frame rate>+ argument will be ignored.
 \begin{verbatim}
-width=<width>
-height=<height>
-depth=<depth>
+width=<h-size>
+height=<v-size> | totalheight=<v-size>,
+keepaspectratio
 \end{verbatim}
-Resize the animation widget. Option `\verb+depth+' specifies how far the animation widget should extend below the base line of the running text. If only one or two of these options are given, the remaining, unspecified dimensions are scaled to maintain the aspect ratio. Any valid \TeX{} dimension is accepted as a parameter. In addition, the length commands \verb+\width+, \verb+\height+, \verb+\depth+ and \verb+\totalheight+ can be used to refer to the original dimensions of the animation widget which correspond to the size of the first frame of the animated sequence.
+Resize the animation widget. If only one of `\verb+width+' or `\verb+[total]height+' is given, the other dimension of the animation widget is scaled to maintain the aspect ratio of the first frame's content. If both `\verb+width+' and `\verb+[total]height+' are given together with `\verb+keepaspectratio+', the first frame's content is resized to fit within \verb+<h-size>+ and \verb+<v-size>+ while maintaining its original aspect ratio. Any valid \TeX{} dimension is accepted as a parameter. In addition, the length commands \verb+\width+, \verb+\height+, \verb+\depth+ and \verb+\totalheight+ can be used to refer to the original dimensions of the first frame of the animated sequence.
 \begin{verbatim}
 scale=<factor>
 \end{verbatim}
@@ -294,9 +303,13 @@ final
 \end{verbatim}
 With `\verb+draft+' the animation is not embedded. Instead, a box with the exact dimensions of the animation is inserted. Option `\verb+final+' does the opposite as it forces the animation to be built and embedded. Both options can be used to reduce compilation time during authoring of a document. To get the most out of them it is recommended to set `\verb+draft+' globally as a package or class option and to set `\verb+final+' locally as a command option of the animation that is currently worked on. After the document has been finished, the global `\verb+draft+' option can be removed to embed all animations.
 \begin{verbatim}
+nomouse
+\end{verbatim}
+Animation widget will not respond to mouse clicks. Unless the JavaScript interface, Sect.~\ref{sect:api}, p.~\pageref{sect:api}, is used to control the animation, it is recommended to also set at least one of the `\verb+autoplay+' or `\verb+controls+' options.
+\begin{verbatim}
 useocg
 \end{verbatim}
-Use an alternative animation method based on Optional Content Groups (OCGs, also known as PDF Layers). May result in slower animations.
+Use an alternative animation method based on Optional Content Groups (OCGs, also known as PDF Layers). In rare cases this may lead to better animation performance. Moreover, it allows overlaying animations with other typeset material, that is, playing animations in the page background.
 \begin{verbatim}
 measure
 \end{verbatim}
@@ -319,7 +332,7 @@ A short note on the `\verb+tikzpicture+' environment: Unlike `\verb+pspicture+',
   end={\end{tikzpicture}}
 \end{verbatim}
 
-\clearpage
+%\clearpage
 \subsection{The `{\tt timeline}' option}\label{sect:timeline}
 \begin{verbatim}
 timeline=<timeline file>
@@ -353,7 +366,7 @@ The letter `\verb+c+', if put into \verb+<transparencies>+, clears an animation
 \myparagraph*{Timeline example with a single animation stack}
 Table~\ref{tab:single} is an example of a single-stack animation. It lists the contents of a timeline file together with the resulting stack of transparencies. Note how the stack is strictly built from the bottom up as transparency specifications are read from left to right and line by line from the timeline file. In frame No. 4, the stack is first cleared before new transparencies are deposited on it. Also note that the stack is viewed from above and transparencies in higher stack position overprint the lower ones.
 
-\begin{table}[ht]\centering
+\begin{table}[hb]\centering
 \caption{Timeline example of a single-stack animation}\label{tab:single}
 \begin{tabular}[t]{c|l|c}\hline
 frame No. & timeline file & transparency stack\\\hline\hline
@@ -371,11 +384,11 @@ frame No. & timeline file & transparency stack\\\hline\hline
 Figures~\ref{fig:taylor} and \ref{fig:lorenz} in Section~\ref{sect:examples} are animation examples with a single transparency stack.
 
 \myparagraph*{Grouping objects into layers (= sub-stacks) using `{\tt;}'}
-Due to the stack-like nature of the animation, the position of a transparency specification in the timeline file determines its \emph{depth} level in relation to other transparencies. The timeline file is processed line by line and from left to right. In a single-stack animation, the stack is strictly built from the bottom up, such that earlier transparencies are overprinted by more recent ones. This may turn out to be inconvenient in certain situations. For example, it might be desirable to change the background image in the middle of an animation without affecting objects that are located in the foreground. For this purpose, transparency specifications can be grouped into layers or sub-stacks using the semicolon (\verb+;+) as a separator. New transparencies can now be put on top of the individual sub-stacks. After a line of the timeline file has been processed, the global stack is built by placing the sub-stacks on top of the other. Again, the left-to-right rule applies when determining the height of the sub-stacks in relation to each other within the global stack.
+Due to the stack-like nature of the animation, the position of a transparency specification in the timeline file determines its \emph{depth} level in relation to other transparencies. The timeline file is processed line by line and from left to right. In a single-stack animation, the stack is strictly built from the bottom up, such that earlier transparencies are overprinted by more recent ones. This may turn out to be inconvenient in certain situations. For example, it might be desirable to change the background image in the middle of an animation without affecting objects that are located in the foreground. For this purpose, transparency specifications can be grouped into layers (sub-stacks) using the semicolon (\verb+;+) as a separator. New transparencies can now be put on top of the individual sub-stacks. After a line of the timeline file has been processed, the global stack is built by placing the sub-stacks on top of the other. Again, the left-to-right rule applies when determining the height of the sub-stacks in relation to each other within the global stack.
 
 The layer concept is best illustrated by an example. In the timeline of Table~\ref{tab:multi}, transparencies are grouped into two sub-stacks only. One is reserved for the background images, transparencies No. 0 \& 1, to be exchanged in frame No. 3, as well as for two other transparencies, No. 7 \& 8, to be interspersed in frame No. 1. A second sub-stack takes the foreground objects that are successively added to the scene. The dotted lines in the third column of the table just mark the border between the two sub-stacks. In frame No. 3, `\verb+c+' first clears the bottom sub-stack before the new background image is inserted. (Instead, `\verb+x3+' could have been used with transparency No. 0 in frame No. 0.) As can be seen in the specifications of frames No. 2 \& 4, sub-stacks need not be explicitly populated; the leading semicolons just ensure the proper assignment of transparencies to animation sub-stacks.
 
-\begin{table}[hb]\centering
+\begin{table}[ht]\centering
 \caption{Timeline example with two sub-stacks}\label{tab:multi}
 \begin{tabular}[t]{c|l|c}\hline
 frame No. & timeline file & transparency stack\\\hline\hline
@@ -476,7 +489,7 @@ Also, the programming interface can be used to create custom buttons for playbac
 \begin{tabularx}{\linewidth}[t]{lllX}\hline
 name & type & access & description\\\hline\hline
 {\tt numFrames} & Integer & read-only & Holds the total number of animation frames.\\
-{\tt frameNum}  & Integer & read+write & Gets or sets the current frame being/to\,be displayed. Note that the values are zero-based. Assigning values less than zero or greater than {\tt numFrames-1} results in an error.\\
+{\tt frameNum}  & Integer & read+write & Gets or sets the current frame being/to\,be displayed. Note that frame numbers are zero-based. Assigning values less than zero or greater than {\tt numFrames-1} results in an error.\\
 {\tt fps} & Number & read+write & Gets or sets the animation frame rate (frames per second). Assigning values less than zero results in an error.\\
 {\tt dt} & Number & read-only & Holds the time span (milliseconds) for display of the current frame.\\
 {\tt isPlaying} & Boolean & read-only & Holds the value {\tt true} if the animation is currently playing, {\tt false} otherwise.\\
@@ -485,7 +498,7 @@ name & type & access & description\\\hline\hline
 \end{tabularx}
 \end{table}
 
-\begin{table}[hbp]
+\begin{table}[htbp]
 \centering
 \caption{Animation object methods}\label{tab:methods}
 \begin{tabularx}{\linewidth}[t]{lX}\hline
@@ -499,7 +512,7 @@ name & description\\\hline\hline
 \end{tabularx}
 \end{table}
 
-\clearpage
+%\clearpage
 \section{Examples}
 \subsection[Animations from sets of files, using `animategraphics' command]{Animations from sets of files, using {\tt \string\animategraphics} command}\label{sect:examples}
 Animations in this section are made from graphics files that were prepared with \MP. Run `\verb+mpost --tex=latex+' on the files ending in `.mp' in the `files' directory to generate the graphics files. Both examples make use of the `\verb+timeline+' option to reduce the resulting PDF file size.
@@ -560,7 +573,11 @@ The first example, Fig.~\ref{fig:taylor}, originally written by Jan Hole\v{c}ek~
 ::7
 ::8
 \end{VerbatimOut}
-\animategraphics[label=taylor,controls,loop,timeline=timeline.txt]{4}{exp_}{0}{8}
+\animategraphics[
+  label=taylor,
+  controls, loop,
+  timeline=timeline.txt
+]{4}{exp_}{0}{8}
 
 \mediabutton[
   jsaction={
@@ -1248,9 +1265,9 @@ dt dt Tm nT mul { % pop
 
   \item The \verb+dvips+ option `\verb+-Ppdf+' should be avoided entirely or followed by something like `\verb+-D 1200+' on the command line in order to set a sensible DVI resolution. This does \emph{not} degrade the output quality! The configuration file `config.pdf' loaded by option `\verb+-Ppdf+' specifies an excessively high DVI resolution that will be passed on to the final PDF. Eventually, Adobe Reader gets confused and will not display the frames within the animation widget.
 
-%  \item Animations do not work if the PDF has been produced with Ghostscript versions older than 9.15.
+  \item Animations do not work if the PDF has been produced with Ghostscript versions older than 9.15.
 
-  \item If the \LaTeX{} $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+/Distiller route is being taken, make sure that the original graphics size (i.\,e. not scaled by any of the `{\tt scale}', `{\tt width}', `{\tt height}' or `{\tt depth}' options) does not exceed the page size of the final document. During PS to PDF conversion every graphic of the animation is temporarily moved to the upper left page corner. Those parts of the graphics that do not fit onto the document page will be clipped in the resulting PDF. Fortunately, graphics files for building animations may be resized easily to fit into a given bounding box by means of the `{\tt epsffit}' command line tool:
+  \item If the \LaTeX{} $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+/Distiller route is being taken, make sure that the original graphics size (i.\,e. not scaled by any of the `{\tt scale}', `{\tt width}', `{\tt height}' or `{\tt totalheight}' options) does not exceed the page size of the final document. During PS to PDF conversion every graphic of the animation is temporarily moved to the upper left page corner. Those parts of the graphics that do not fit onto the document page will be clipped in the resulting PDF. Fortunately, graphics files for building animations may be resized easily to fit into a given bounding box by means of the `{\tt epsffit}' command line tool:
 
 \quad{\tt epsffit -c <llx> <lly> <urx> <ury> infile.eps outfile.eps}
 
@@ -1287,9 +1304,11 @@ Note that the name of the Ghostscript executable may vary between operating syst
     {\tt fmtutil-sys -{}-byfmt xelatex}
   \end{enumerate}
 
-  \item If you are postprocessing the created PDF file with tools such as pdftk to split the document into different parts, then the animation may fail. To work around this, do not use the `{\tt useocg}' (OCGs, PDF layers) option.  In addition, the control buttons also use OCGs to change their appearance to provide feedback about the running state, independent of the `{\tt useocg}' option. The workaround for this is not to use the `{\tt controls}' option.
+  \item If a PDF containing animations is postprocessed using tools like PDFtk to split the document into separate files, then animations in the output documents may not work.
+    
+  \item PDFs with animations cannot be embedded (via {\tt \string\includegraphics, \string\includepdf}) into other documents as the animation capability gets lost.
 
-  \item Animations should not be placed on \emph{multilayered} slides created with presentation making classes such as Beamer or Powerdot. Although possible (on the last overlay of a slide, at best), the result might be disappointing. Put animations on flat slides only. (Of course, slides without animations may still have overlays.)
+  \item Animations should not be placed on \emph{multilayered} slides, also known as overlays, created with presentation making classes such as Beamer or Powerdot. Although possible (on the last overlay of a slide, at best), the result might be disappointing. Put animations on flat slides only. (Of course, slides without animations may still have overlays.)
 \end{itemize}
 
 \section{Acknowledgements}