animate (16oct14)

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

4 files changed, 22 insertions, 11 deletions

diff --git a/Master/texmf-dist/doc/latex/animate/ChangeLog b/Master/texmf-dist/doc/latex/animate/ChangeLog
index acc04eb1983..2fe422b3657 100644
--- a/Master/texmf-dist/doc/latex/animate/ChangeLog
+++ b/Master/texmf-dist/doc/latex/animate/ChangeLog
@@ -1,3 +1,11 @@
+2014-10-16
+	* New: third animation method added (based on JS methods `getIcon' &
+	`buttonSetIcon') with best animation performance (frame rate) so far; set as
+	default for pdfLaTeX/XeLaTeX/dvipdfmx, Widget based method is default for
+	dvips, as before
+	* Change: option `useocg' removed in favour of `method=icon | widget | ocg'
+	for selecting one of the implemented animation methods
+
 2014-09-23
 	* Change: Ghostscript 9.15+ now required for PS to PDF conversion;
 	`depth' option now deprecated and ignored
diff --git a/Master/texmf-dist/doc/latex/animate/README b/Master/texmf-dist/doc/latex/animate/README
index 85943467d4c..8dd40522376 100644
--- a/Master/texmf-dist/doc/latex/animate/README
+++ b/Master/texmf-dist/doc/latex/animate/README
@@ -39,7 +39,7 @@ Usage:
                        autopause, autoplay, autoresume, controls, final, draft,
                        buttonsize=<size>, buttonbg=<colour>, buttonfg=<colour>,
                        loop, palindrome, step, poster[=first | none | last],
-                       useocg, dvipdfmx, xetex
+                       method=icon | widget | ocg, dvipdfmx, xetex
 
 
     \animategraphics[<options>]{<frame rate>}{<file basename>}{<first>}{<last>}
@@ -62,7 +62,8 @@ Usage:
                        draft, controls, buttonsize=<size>, buttonbg=<colour>,
                        buttonfg=<colour>, loop, palindrome, step, measure,
                        poster[=first | none | last], begin={<begin text>},
-                       end={<end text>}, timeline=<timeline file>, useocg,
+                       end={<end text>}, timeline=<timeline file>,
+                       method=icon | widget | ocg,
                        every=<number>, bb=<llx> <lly> <urx> <ury>,
                        viewport=<llx> <lly> <urx> <ury>,
                        trim=<left> <bottom> <right> <top>
diff --git a/Master/texmf-dist/doc/latex/animate/animate.pdf b/Master/texmf-dist/doc/latex/animate/animate.pdf
index 510d0092273..51d576e80b9 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 a826ae8703b..89937dea5a8 100644
--- a/Master/texmf-dist/doc/latex/animate/animate.tex
+++ b/Master/texmf-dist/doc/latex/animate/animate.tex
@@ -11,7 +11,7 @@
 \usepackage{pst-node,pst-plot,pst-tools,pst-text,pst-ode}
 \usepackage{media9}
 %\usepackage[useocg]{animate}
-\usepackage{animate}
+\usepackage{../animate}
 \usepackage{intcalc}
 \usepackage{graphicx}
 \graphicspath{{files/}}
@@ -107,7 +107,7 @@ This package provides an interface to create PDFs with animated content from set
 
 Package `animate' supports the usual PDF making workflows, i.\,e. pdf\LaTeX{}, Lua\LaTeX{}, \LaTeX{} $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+/Distiller and \pXepLaTeX{} $\rightarrow$ \verb+(x)dvipdfmx+.
 
-The final PDF can be viewed in current Adobe Readers on all supported platforms or in PDF-XChange Viewer.
+The final PDF can be viewed in current Adobe Readers on all supported platforms (except mobile devices) or in PDF-XChange Viewer.
 
 %The `animate' package relies on Optional Content Groups (OCG), also known as PDF layers, which is a feature provided by the PDF-1.5 specification. Each frame of an animation is associated with an OCG that is hidden or made visible in a dynamic fashion by means of Adobe Reader's built-in JavaScript engine.
 
@@ -118,7 +118,7 @@ The final PDF can be viewed in current Adobe Readers on all supported platforms
 %\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
+\item Adobe Reader, version $\ge7$ or PDF-XChange Viewer (with option `\verb+method=widget+' or `\verb+method=ocg+')
 \end{trivlist}
 
 \section{Installation}
@@ -156,7 +156,7 @@ buttonbg=<colour>
 buttonfg=<colour>
 step
 nomouse
-useocg
+method=icon | widget | ocg
 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+'.
@@ -167,7 +167,7 @@ If PDF is generated via DVI and Postscript by the command sequence \verb+latex+
 
 \XeLaTeX{} and \verb+dvipdfmx+ require the `graphicx' package to be loaded. While \XeLaTeX{} will be auto-detected (package option `\verb+xetex+' is optional), `animate' and `graphicx' need the package option `\verb+dvipdfmx+' in the case of \verb+dvipdfmx+.
 
-Occasionally, a second \LaTeX{} run may be necessary to resolve internally created object references. An appropriate warning will be issued in such a case.
+Usually, a second \LaTeX{} run is necessary to resolve internally created object references. A warning message will be issued if appropriate.
 
 \clearpage
 \section{The user interface}
@@ -307,13 +307,13 @@ 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
+method=icon | widget | ocg
 \end{verbatim}
-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.
+The package implements three different animation methods. The `\verb+icon+' method is the default one for the pdf\LaTeX, \XeLaTeX{} and \verb+dvipdfmx+ workflows, and `\verb+widget+` for the \verb+dvips+ route. The `\verb+icon+' method usually gives the best animation performance (achievable frame rate). Forcing `\verb+icon+' in the case of \verb+dvips+ unfortunately leads to dead `hyperref'-inserted links in the final PDF; it should be enabled only if the `hyperref' package is \emph{not} used. This is for technical reasons, more specifically, due to a limitation of the `\verb+pdfmark+' Postscript operator. The `\verb+ocg+' method is an alternative animation method based on Optional Content Groups (OCGs, also known as PDF Layers). In rare cases (standalone animations without animation controls) it may lead to better animation performance than the other two methods. Moreover, it allows overlaying animations with other typeset material, that is, playing animations in the page background.
 \begin{verbatim}
 measure
 \end{verbatim}
-Measures the frame rate during one cycle of the animation. (For testing purposes.)
+Measures the frame rate during one cycle of the animation and prints the value to the JavaScript console of the Reader. (For testing purposes.)
 \begin{verbatim}
 begin={<begin text>}
 end={<end text>}
@@ -1265,7 +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 was produced with Ghostscript versions older than 9.15.
+
+  \item The default animation method (`{\tt icon}') is not supported in PDF-XChange Viewer. Use one of `{\tt method=widget}' or `{\tt method=ocg}' instead.
 
   \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: