animate update (3may07)

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

3 files changed, 94 insertions, 33 deletions

diff --git a/Master/texmf-dist/doc/latex/animate/README b/Master/texmf-dist/doc/latex/animate/README
index f87fc16a61d..2ab44324c3a 100644
--- a/Master/texmf-dist/doc/latex/animate/README
+++ b/Master/texmf-dist/doc/latex/animate/README
@@ -15,15 +15,27 @@ Description:
     or just from typeset text.
 
     It supports the usual PDF making workflows, i. e.  pdfLaTeX and LaTeX ->
-    dvips -> ps2pdf (Ghostscript) / Distiller.
+    dvips -> ps2pdf (Ghostscript).
 
-    The resulting PDF can be viewed in current Adobe Readers, version 7, on all
-    supported platforms. Unfortunately, beginning with Reader 8, animations
-    cease to work because of user-right restrictions that have been imposed on
-    several important JavaScript methods.
+    The resulting PDF can be viewed in current Adobe Readers on all supported
+    platforms.
 
-    Package `animate' is based on the work by Jan Holecek and Petr Sojka:
-    http://www.fi.muni.cz/~xholecek/tex/pdfanim.xhtml
+    The first release of `animate' was based on the work by Jan Holecek and Petr
+    Sojka:
+
+           http://www.fi.muni.cz/~xholecek/tex/pdfanim.xhtml
+
+    Meanwhile, the package was rewritten to use Optional Content Groups (OCG),
+    aka PDF-Layers. OCG-based animations are fully supported by Adobe Reader 8,
+    but have some performance issues. Playback is usually slower in Reader 8
+    than in previous versions, which is probably a bug.
+
+    The old, non-OCG approach is still available if the package file
+    `animate-noocg.sty' is used instead of `animate.sty'. However, options
+    `autoplay', `autopause' and `autoresume' are not functional in Reader 8.
+    Moreover, the animation position and the play/pause buttons are not properly
+    reset on page change. This is due to usage restrictions that Adobe imposed
+    on some important JavaScript methods in Reader 8.
 
     Note, this file only gives a summary of usage and available package and
     command options. Please refer to the documentation `animate.pdf' in the
@@ -39,9 +51,9 @@ Usage:
 
  \usepackage[<package options>]{animate}
 
- * Package options: autopause, autoplay, autoresume, controls,
-                    buttonsize=<size>, screenbg=<colour>, buttonbg=<colour>,
-                    loop, palindrome, step, poster=[first | none | last]
+ -- Package options: autopause, autoplay, autoresume, controls,
+                     buttonsize=<size>, screenbg=<colour>, buttonbg=<colour>,
+                     loop, palindrome, step, poster=[first | none | last]
 
 
  \animategraphics[<options>]{<frame rate>}{<file basename>}{<first>}{<last>}
@@ -50,19 +62,20 @@ Usage:
      ... typeset material ...
  \newframe
      ... typeset material ...
- \newframe
+ \newframe*
      ... typeset material ...
  \end{animateinline}
 
- * Command options: width=<width>, height=<height>, depth=<depth>,
-                    scale=<factor>, autopause, autoplay, autoresume, controls,
-                    buttonsize=<size>, screenbg=<colour>, buttonbg=<colour>,
-                    loop, palindrome, step, poster=[first | none | last]
+ -- Command options: width=<width>, height=<height>, depth=<depth>,
+                     scale=<factor>, autopause, autoplay, autoresume, controls,
+                     buttonsize=<size>, screenbg=<colour>, buttonbg=<colour>,
+                     loop, palindrome, step, poster=[first | none | last]
 
 
 Requirements:
 
-  pdfeTeX, version >= 1.30
+  pdfeTeX, version >= 1.20
+  Adobe Reader, version >= 6
 
 
 Installation:
diff --git a/Master/texmf-dist/doc/latex/animate/doc/animate.pdf b/Master/texmf-dist/doc/latex/animate/doc/animate.pdf
index b6909fe8ffe..c46cab4a786 100644
--- a/Master/texmf-dist/doc/latex/animate/doc/animate.pdf
+++ b/Master/texmf-dist/doc/latex/animate/doc/animate.pdf
diff --git a/Master/texmf-dist/doc/latex/animate/doc/animate.tex b/Master/texmf-dist/doc/latex/animate/doc/animate.tex
index 562b7dc2f9c..0a811854fe5 100644
--- a/Master/texmf-dist/doc/latex/animate/doc/animate.tex
+++ b/Master/texmf-dist/doc/latex/animate/doc/animate.tex
@@ -40,7 +40,8 @@
   linkbordercolor={0 0 1},
   menubordercolor={0 0 1},
   pagebordercolor={0 0 1},
-  urlbordercolor={0 0 1}
+  urlbordercolor={0 0 1},
+%  pdfpagelayout=SinglePage
 }
 
 \begin{document}
@@ -54,27 +55,27 @@ A \LaTeX{} package for creating portable, JavaScript driven PDF animations from
 \end{abstract}
 
 \tableofcontents
-
+\newpage
 \section{Introduction}
 This package provides an interface to create PDFs with animated content from sets of graphics files, from inline graphics, such as \LaTeX-picture, PSTricks or pgf/TikZ generated pictures, or just from typeset text. Unlike standard movie/ video formats, which can be embedded, for example, using the \LaTeX{} package `movie15'~\cite{movie15}, package `animate' allows for animating vector graphics. The result is roughly similar to the SWF (Flash) format, although not as space-efficient.
 
 Package `animate' supports the usual PDF making workflows, i.\,e. pdf\LaTeX{} and \LaTeX{} $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+\,(Ghost\-script).
 
-The final PDF can be viewed in Adobe Reader\textsuperscript{\scriptsize\textregistered}s, version 7, on all supported platforms. Unfortunately, beginning with Reader 8, animations cease to work because of user-right restrictions that have been imposed on several important JavaScript methods.
+The final PDF can be viewed in current Adobe Reader\textsuperscript{\scriptsize\textregistered}s on all supported platforms.
 
-The `animate' package is based on the work by Jan Hole\v{c}ek and Petr Sojka \cite{hol04}, who have shown how to animate the appearance of a so called Widget Annotation, provided by the PDF specification, by means of Adobe Reader's built-in JavaScript engine.
-
-\section{Installation}
-The file `animate.sty' should be stored in a place where \LaTeX{} can find it.
+The `animate' package makes use of 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 made visible or invisible in a dynamic fashion by means of Adobe Reader's built-in JavaScript engine.
 
 \section{Requirements}
 \begin{trivlist}
-\item pdf$\varepsilon$\TeX{}, version $\ge1.30$ for both, PDF and DVI output
-\item Adobe Reader, version 7
+\item pdf$\varepsilon$\TeX{}, version $\ge1.20$ for PDF output
+\item Adobe Reader, version $\ge6$
 \end{trivlist}
 
+\section{Installation}
+The file `animate.sty' should be stored in a place where \LaTeX{} can find it.
+
 \section{Using the package}
-Invoke the package by putting the line
+First of all, read Section~\ref{sect:bugs} on problems related to this package. Then, invoke the package by putting the line
 \begin{verbatim}
   \usepackage[<package options>]{animate}
 \end{verbatim}
@@ -82,8 +83,8 @@ to the preamble of your document, i.\,e. somewhere between \verb+\documentclass+
 
 `animate' honours the package options:
 \begin{verbatim}
-  autopause
   autoplay
+  autopause
   autoresume
   controls
   buttonsize=<size>
@@ -96,7 +97,7 @@ to the preamble of your document, i.\,e. somewhere between \verb+\documentclass+
 \end{verbatim}
 The same options are also available 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.
 
-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. \emph{Important:} 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+-X 2400 -Y 2400+' to the \emph{end} of the option list of \verb+dvips+. This overrides the DVI resolution specified in the \verb+dvips+ configuration file `\verb+config.pdf+'.
+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. \emph{Important:} 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+-X 2400 -Y 2400+' \emph{after} `\verb+-Ppdf+' on the command line.
 
 \section{The user interface}
 Package `animate' provides the command
@@ -109,12 +110,12 @@ and the environment
     ... typeset material ...
 \newframe
     ... typeset material ...
-\newframe
+\newframe*
     ... typeset material ...
 \end{animateinline}
 \end{verbatim}
 
-While \verb+\animategraphics+ can be used to assemble animations from sets of existing graphics files, the environment `\verb+animateinline+' is intended to create the animation from the typeset material it encloses. This material can be pictures drawn within the \LaTeX{} \verb+picture+ environment or using the advanced capabilities of PSTricks or pgf/TikZ. Even ordinary textual material may be animated in this way. The command \verb+\newframe+ terminates one frame and starts the next.
+While \verb+\animategraphics+ can be used to assemble animations from sets of existing graphics files, the environment `\verb+animateinline+' is intended to create the animation from the typeset material it encloses. This material can be pictures drawn within the \LaTeX{} \verb+picture+ environment or using the advanced capabilities of PSTricks or pgf/TikZ. Even ordinary textual material may be animated in this way. The command \verb+\newframe+ terminates a frame and starts the next one. There is a starred version, \verb+\newframe*+. If placed after a particular frame it causes the animation to pause at that frame. The animation continues normally after clicking it again.
 
 The parameter \verb+<frame rate>+ specifies the number of frames per second of the animation. All files of the sequence must be consecutively numbered. {\tt <file base\-name>} is the leftmost part of the file name that all members of the sequence have in common. \verb+<first>+ is the number of the first and \verb+<last>+ the number of the last file in the set. \verb+<first>+ and \verb+<last>+ must have the same number of digits to ensure proper sorting. If necessary, rename the files with zeros padded to the left.
 
@@ -173,9 +174,8 @@ Step through the animation by one frame per mouse-click.
 \begin{verbatim}
 poster=[first | none | last]
 \end{verbatim}
-Specifies which frame (first, last or none) to display when the animation widget is not activated. This option serves two purposes: (1) When printing the PDF document from within Adobe Reader, the specified frame makes its way onto the paper, even if the page containing the animation has never been visited by the (human) reader. (2) PDF Readers, such as Xpdf, which do not know about Widget Annotations and JavaScript have something that can be displayed and printed. Option `poster=first' need not be explicitly set since this is done by default.
+Specifies which frame (first, last or none) to display and print if the animation is not activated. Option `poster=first' need not be explicitly set because it is the default.
 
-\newpage
 \section{Examples}
 \subsection[Animation from a set of files, using `animategraphics' command]{Animation from a set of files, using `{\tt animategraphics}' command}
 \small
@@ -205,7 +205,6 @@ Specifies which frame (first, last or none) to display when the animation widget
 \usepackage{pst-3dplot}
 \usepackage{fp}
 \usepackage{animate}
-\usepackage{graphics}
 
 %draws a torus sector
 \newcommand{\torus}[1]{% #1: angle of the torus sector
@@ -287,6 +286,55 @@ Specifies which frame (first, last or none) to display when the animation widget
 \end{animateinline}%
 \end{center}
 
+\section{Bugs}\label{sect:bugs}
+\begin{itemize}
+  \item The command {\tt\string\multido} and its relatives from package `{\tt multido}' do not work if the loop body contains {\tt\string\newframe}. Use {\tt\string\whiledo} from package `{\tt ifthen}' instead. A counter must be declared to keep track of the number of iterations. Further variables that take fixed point decimals to be used within the loop body can be defined and incremented by means of the commands \verb+\FPset+ and \verb+\FPadd+ from package `{\tt fp}'. For example:
+\small
+\begin{verbatim}
+% declare loop counter
+\newcounter{iter}%
+
+\begin{animateinline}{12}
+  % initialize loop counter
+  \setcounter{iter}{0}%
+  % define some variable, e. g. `\somevar'
+  \FPset{\somevar}{1.0}%
+  %make copy `\varcopy' of `\somevar' with global scope
+  \xdef\varcopy{\somevar}%
+  ...
+  ... create first frame using \somevar(=1.0)
+  ... (\multido _can_ be used here!)
+  ... 
+  \whiledo{\theiter<50}{% do 50 iterations
+    % start new frame
+    \newframe%
+    %increment loop counter by 1
+    \addtocounter{iter}{1}%
+    %increment \somevar by, e. g., 0.5
+    \FPadd{\somevar}{\varcopy}{0.5}%
+    %refresh the copy
+    \xdef\varcopy{\somevar}%
+    ...
+    ... create frame using \somevar
+    ... (\multido _can_ be used here!)
+    ... 
+  }
+\end{animateinline}
+\end{verbatim}
+\normalsize
+
+  \item Currently, animations cannot be placed on multilayered slides created with the Beamer class. Put animations on flat slides only. (Of course, slides without animations may still have overlays.)
+
+  \item The \verb+dvips+ option `\verb+-Ppdf+' should be avoided entirely or followed by `\verb+-X 2400+ \verb+-Y 2400+' on the command line in order to set a sensible DVI resolution. In times of Type-1 fonts, this does \emph{not} degrade the output quality! The configuration file `\verb+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 with complex graphics and/or many frames may cause \LaTeX{} to fail with a `\verb+TeX capacity exceeded+' error. Enlarge \TeX{}'s memory with command line option `\verb+--mem-max=...+'.
+
+  \item Originally, package `\verb+animate+' was based on a method suggested by Jan Hole\v{c}ek and Petr Soika~\cite{hol04}, but was rewritten to use Optional Content Groups (OCG). OCG-based animations are fully supported in Adobe Reader 8, but have some performance issues. Playback is usually slower in Reader 8 than in older Reader versions, which is probably a bug. The non-OCG approach performs better in Adobe Reader 8, but package/command options `\verb+autoplay+', `\verb+autopause+' and `\verb+autoresume+' do not work. Moreover, the animation position and the play/pause' buttons are not properly reset on page change. This is due to usage restrictions that Adobe imposed on some important JavaScript methods in Reader 8. A non-OCG version of the package is still available as `\verb+animate-noocg.sty+'.
+\end{itemize}
+
+\section{Acknowledgements}
+I would like to thank Fran\c{c}ois Lafont who discovered quite a few bugs and made many suggestions that helped to improve the functionality of the package.
+
 \begin{thebibliography}{8}
   \bibitem{movie15} \emph{The Movie15 Package}. URL: \href{http://www.ctan.org/tex-archive/macros/latex/contrib/movie15/}{\tt http://www.ctan.org/tex-archive/macros/} \href{http://www.ctan.org/tex-archive/macros/latex/contrib/movie15/}{\tt latex/contrib/movie15}
   \bibitem{hol04} Hole\v{c}ek, J. ; Sojka, P.: Animations in pdf\TeX-generated PDF. In: \emph{Lecture Notes in Computer Science}, Vol. 3130, 2004, pp.~179--191