update animate from CTAN

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

3 files changed, 113 insertions, 46 deletions

diff --git a/Master/texmf-dist/doc/latex/animate/doc/animate.pdf b/Master/texmf-dist/doc/latex/animate/doc/animate.pdf
index 3f0ebce6ee6..b36b4fc248f 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 6015c3ae370..d7a359c9b17 100644
--- a/Master/texmf-dist/doc/latex/animate/doc/animate.tex
+++ b/Master/texmf-dist/doc/latex/animate/doc/animate.tex
@@ -124,17 +124,30 @@ and the environment
 \end{animateinline}
 \end{verbatim}
 
-While \verb+\animategraphics+ can be used to assemble animations from sets of existing graphics files, the environment `\verb+animateinline+' is meant 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 parameter \verb+<frame rate>+ specifies the number of frames per second of the animation.
+While \verb+\animategraphics+ can be used to assemble animations from sets of existing graphics files or from multipage PDF, the environment `\verb+animateinline+' is meant 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 parameter \verb+<frame rate>+ specifies the number of frames per second of the animation.
 
 By default, the animation is built frame by frame in the order of inclusion of the embedded material. However, extended control of the order of appearance, superposition and repetition of the material is available through the `\verb+timeline+' option (see Section~\ref{sect:timeline}).
 
 The command \verb+\newframe+ terminates a frame and starts the next one. It can be used inside the `\verb+animateinline+' environment only. There is a starred variant, \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. Both \verb+\newframe+ variants take an optional argument that allows to change the frame rate in the middle of an animation.
 
+\emph{Sets of graphics files}\\[0.8\parskip]
 All files of the sequence should exist and be consecutively numbered. (Exception to this rule is allowed in connexion with the `\verb+every+' option, see below). {\tt <file base\-name>} is the leftmost part of the file name that is common to all members of the sequence. \verb+<first>+ is the number of the first and \verb+<last>+ the number of the last file in the set. File names may be simply numbered, such as $0\dots99$. If there are leading zeros, make sure that all file numbers have the same number of digits, such as $0000\dots0099$.
 
 There is no file name extension to be specified as a parameter. The possible file formats depend on whether \LaTeX{} or pdf\LaTeX{} is used. In the case of \LaTeX{}, files with the extension `eps' are searched for at first, followed by `mps' (\MP-generated Postscript) and `ps'. With pdf\LaTeX{} the searching order is: (1)~`pdf', (2)~`mps', (3)~`png', (4)~`jpg', (5)~`jpeg', (6)~`jbig2', (7)~`jb2', (8)~`jp2'\footnotemark[1], (9)~`j2k'\footnotemark[1], (10)~`jpx'\footnotemark[1]\footnotetext[1]{JPEG2000 is not yet supported by pdf\TeX.}. That is, files capable to store vector graphics are found first. Make sure that all file names have \emph{lower case} extensions.
 
-For example, given the sequence `frame\_5.png' through `frame\_19.png' from a possibly larger set that shall be used to build the animation. Then, {\tt <file base\-name>} would be specified as `\verb+frame_+', \verb+<first>+ as `\verb+5+' and \verb+<last>+ as `\verb+19+'.
+For example, given the sequence `frame\_5.png' through `frame\_50.png' from a possibly larger set that shall be used to build an animation running at 12 frames per second. Then, the correct inclusion command reads
+\begin{verbatim}
+  \animategraphics{12}{frame_}{5}{50}
+\end{verbatim}
+
+\emph{Multipage PDF inclusion (pdf\LaTeX{} only)}\\[0.8\parskip]
+If the file `\verb+<file basename>+.pdf' exists (again, there is no file name extension to be specified), it is taken as a multipage document where each page represents one frame of the animation. In this case, the last two arguments, \verb+<first>+ \& \verb+<last>+, are interpreted differently from above; they specify a zero-based range of pages to be included in the animation. Either or both of them may be left empty, `\verb+{}+', in which case they default to $0$ and $n-1$, where $n$ is the total number of available pages. Arguments that fall outside this range are automatically corrected to the maximum allowed number, i.\,e. $n-1$.
+
+For example, the line
+\begin{verbatim}
+  \animategraphics{12}{frames}{}{}
+\end{verbatim}
+would create an animation from all pages of the file `frames.pdf', running at 12 fps.
 
 \section{Command options}
 The following options to \verb+\animategraphics+ and `\verb+animateinline+' have been provided:
@@ -261,8 +274,7 @@ and
 \end{verbatim}
 In the first example, transparency No. 0 appears in the foreground throughout the animation; it will never be obscured by other transparencies' content. In the second example it is put to the background, because it is the first transparency specification in the file, and stays there for the rest of the animation.
 
-\emph{Grouping objects into layers using `{\tt;}'}
-
+\emph{Grouping objects into layers using `{\tt;}'}\\[0.8\parskip]
 The stack-like concept of animations, where transparencies are always put on top such that they overprint the content of previously deposited transparencies, can be inconvenient in certain situations. For example, it might be desirable to allow for changing 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 \emph{layers} using the semicolon (\verb+;+) as a separator instead of the comma. This is best illustrated by an example:
 \begin{verbatim}
   ::0x49;2x0,3x0
@@ -275,11 +287,10 @@ The stack-like concept of animations, where transparencies are always put on top
   ::   ;104x0,105x0
   ...
 \end{verbatim}
-In this timeline, the transparencies are grouped into two layers. One is reserved for the background images, transparencies No. 0 \& 1, that shall be exchanged after 49 frames, and another one for the foreground objects that are successively added to the scene. As can be seen in this example, layers need not be explicitly populated; the leading semicolons just ensure the proper relationship between transparencies and animation layers. Note that without setting up two layers, the foreground objects on transparencies 2 through 99 that have been added during the first 49 frames would be overprinted by the new background image, transparency 1, from frame 50 onward.
+In this timeline, the transparencies are grouped into two layers. One is reserved for the background images, transparencies No. 0 \& 1, to be exchanged after 49 frames, and another one for the foreground objects that are successively added to the scene. As can be seen in this example, layers need not be explicitly populated; the leading semicolons just ensure the proper relationship between transparencies and animation layers. Note that without setting up two layers, the foreground objects on transparencies 2 through 99 that have been added during the first 49 frames would be overprinted by the new background image, transparency 1, from frame 50 onward.
 
 See the second animation in Section~\ref{sect:examples} for a working example that makes use of the timeline and the layer concept.
 
-\newpage
 \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+' on the files ending in `.mp' in the `doc/files' directory to generate the graphics files. Both examples make use of the `\verb+timeline+' option to reduce the resulting PDF file size.
diff --git a/Master/texmf-dist/tex/latex/animate/animate.sty b/Master/texmf-dist/tex/latex/animate/animate.sty
index be7c5b2b223..c13b714aa30 100644
--- a/Master/texmf-dist/tex/latex/animate/animate.sty
+++ b/Master/texmf-dist/tex/latex/animate/animate.sty
@@ -13,7 +13,7 @@
 % Supports LaTeX->dvips->ps2pdf or pdfLaTeX workflows.
 
 \NeedsTeXFormat{LaTeX2e}
-\ProvidesPackage{animate}[2007/11/28]
+\ProvidesPackage{animate}[2007/11/30]
 \RequirePackage{keyval}
 \RequirePackage{ifthen}
 \RequirePackage{ifpdf}
@@ -146,33 +146,33 @@
 
 %tests whether file is known, if so it returns identifier of form xobj
 %otherwise `!'
-\def\@anim@fileknown#1{% #1 file name
+\def\@anim@fileknown#1#2{% #1 file name, #2 page No
   %identify file by md5sum
-  \expandafter\ifx\csname file:\pdfmdfivesum file {#1}\endcsname\relax!%
-  \else\@anim@getkeyval{file:\pdfmdfivesum file {#1}}\fi%
+  \expandafter\ifx\csname file:\pdfmdfivesum file {#1}.#2\endcsname\relax!%
+  \else\@anim@getkeyval{file:\pdfmdfivesum file {#1}.#2}\fi%
 }
-\def\@anim@makefileknown#1#2{%
-  \@anim@newkey{file:\pdfmdfivesum file {#1}}{#2}%
+\def\@anim@makefileknown#1#2#3{% #1 file name, #2 page No, #3 Form XObj ID
+  \@anim@newkey{file:\pdfmdfivesum file {#1}.#2}{#3}%
 }
 
 \ifpdf
   %helper macro that typesets graphics file into savebox
-  \def\@anim@filebox#1{% #1 filename
+  \def\@anim@filebox#1#2{% #1 filename, #2 page No. for multipage files
     \ifx\@anim@gropts\@empty%
       \def\@anim@mps{.mps}%
       \ifx\@anim@ext\@anim@mps%
         \global\setbox\@anim@box=\hbox{\convertMPtoPDF{#1}{1}{1}}%
       \else%
-        \pdfximage{#1}%
+        \pdfximage page #2 {#1}%
         \global\setbox\@anim@box=\hbox{\pdfrefximage\pdflastximage}%
       \fi%
     \else%
-      \edef\@anim@curfile{*[\@anim@gropts]{#1}}%
+      \edef\@anim@curfile{*[page=#2\@anim@gropts]{#1}}%
       \global\setbox\@anim@box=\hbox{\expandafter\includegraphics\@anim@curfile}%
     \fi%
   }
 \else
-  \def\@anim@filebox#1{% #1 filename
+  \def\@anim@filebox#1#2{% #1 filename, #2 ignored
     \ifx\@anim@gropts\@empty%
       \edef\@anim@curfile{*{#1}}%
     \else%
@@ -183,17 +183,19 @@
 \fi
 
 %create Form XObject from graphics file
-\def\@anim@ximage#1#2#3{%#1:@anim@num, #2:@anim@curframe@zb, #3:filename
-  \ifthenelse{\equal{\@anim@fileknown{#3}}{!}}{% new file to be embedded
-    \@anim@filebox{#3}% store file in a box
+\def\@anim@ximage#1#2#3#4{%#1:@anim@num, #2:@anim@curframe@zb, #3:filename,
+  %#4: page number of multipage pdf
+  \ifthenelse{\equal{\@anim@fileknown{#3}{#4}}{!}}{% new file to be embedded
+    \@anim@filebox{#3}{#4}% store file in a box
     \@anim@xinline{#1}{#2}{\@anim@box}{!}% delegate Form XObject creation
-    \@anim@makefileknown{#3}{\@anim@lastxform}% keep form xobject number
+    \ifx\@anim@gropts\@empty\if@anim@multipdf\message{<#4>}\fi\fi%
+    \@anim@makefileknown{#3}{#4}{\@anim@lastxform}% keep form xobject number
   }{% file known, re-use existing form xobject
     \ifnum#2=0
-      \@anim@filebox{#3}% for size determination of first frame
-      \@anim@xinline{#1}{#2}{\@anim@box}{\@anim@fileknown{#3}}%
+      \@anim@filebox{#3}{#4}% for size determination of first frame
+      \@anim@xinline{#1}{#2}{\@anim@box}{\@anim@fileknown{#3}{#4}}%
     \else%
-      \@anim@xinline{#1}{#2}{}{\@anim@fileknown{#3}}%
+      \@anim@xinline{#1}{#2}{}{\@anim@fileknown{#3}{#4}}%
     \fi%
   }%
 }
@@ -1034,6 +1036,48 @@
   }%
 }
 
+\newboolean{@anim@multipdf} % multipage PDF?
+
+\ifpdf
+  %detects multipage PDF and corrects user supplied page range
+  \def\@anim@checkmultipdf#1{% #1: file base name
+    \IfFileExists{#1.pdf}{%
+      \gdef\@anim@ext{.pdf}%
+      \@anim@filebox{#1.pdf}{1}%
+      \ifx\@anim@first\@empty%
+        \@anim@curframe=\@ne%
+      \else%
+        \ifnum\@anim@first<0 \gdef\@anim@first{0}\fi%
+        \@anim@curframe=\@anim@first%
+        \advance\@anim@curframe by \@ne% because pdfximage pages are 1-based
+        \ifnum\@anim@curframe>\pdflastximagepages
+          \@anim@curframe=\pdflastximagepages% correct wrong user input
+        \fi%
+      \fi%
+      \xdef\@anim@first{\the\@anim@curframe}%
+      \ifx\@anim@last\@empty%
+        \@anim@curframe=\pdflastximagepages%
+      \else%
+        \ifnum\@anim@last<0 \gdef\@anim@last{0}\fi%
+        \@anim@curframe=\@anim@last%
+        \advance\@anim@curframe by \@ne%
+        \ifnum\@anim@curframe>\pdflastximagepages
+          \@anim@curframe=\pdflastximagepages%
+        \fi%
+      \fi%
+      \ifnum\@anim@first>\@anim@curframe
+        \xdef\@anim@last{\@anim@first}%
+        \xdef\@anim@first{\the\@anim@curframe}%
+      \else%
+        \xdef\@anim@last{\the\@anim@curframe}%
+      \fi%
+      \setboolean{@anim@multipdf}{true}%
+    }{}%
+  }
+\else
+  \def\@anim@checkmultipdf#1{}% no-op in dvi mode
+\fi
+
 %user command for embedding animation sequence
 % #1: options
 % #2: frame rate (fps)
@@ -1052,14 +1096,19 @@
   \def\@anim@first{#4}%
   \def\@anim@last{#5}%
   %
+  \@anim@checkmultipdf{\@anim@base}%test for multipage pdf
   \@anim@curframe=\@anim@first%
   \@anim@curframe@zb=0%
+  %
   \if@anim@draft%
-    %get file name extension
-    \@anim@getext{%
-      \@anim@base\@anim@pad{\@anim@first}{\the\@anim@curframe}%
-    }%
-    \@anim@filebox{\@anim@base\@anim@first\@anim@ext}% store file in a box
+    \if@anim@multipdf%
+      %store file in a box
+      \@anim@filebox{\@anim@base.pdf}{\@anim@first}%
+    \else%
+      %get file name extension
+      \@anim@getext{\@anim@base\@anim@first}%
+      \@anim@filebox{\@anim@base\@anim@first\@anim@ext}{1}%
+    \fi%
     %draw draftbox according to dimensions of the first frame
     \@anim@draftbox{\@anim@box}%
   \else%
@@ -1083,14 +1132,20 @@
     %
     %read all frames of the sequence
     \loop\ifnum\@anim@curframe>\@anim@last\else%
-      %get file name extension of current file
-      \@anim@getext{%
-        \@anim@base\@anim@pad{\@anim@first}{\the\@anim@curframe}%
-      }%
-      %embed graphics
-      \@anim@ximage{\the\@anim@num}{\the\@anim@curframe@zb}{%
-        \@anim@base\@anim@pad{\@anim@first}{\the\@anim@curframe}\@anim@ext%
-      }%
+      \if@anim@multipdf%
+        %embed graphics
+        \@anim@ximage{\the\@anim@num}{\the\@anim@curframe@zb}{\@anim@base.pdf}{%
+          \the\@anim@curframe}%
+      \else%
+        %get file name extension of current file
+        \@anim@getext{%
+          \@anim@base\@anim@pad{\@anim@first}{\the\@anim@curframe}%
+        }%
+        %embed graphics
+        \@anim@ximage{\the\@anim@num}{\the\@anim@curframe@zb}{%
+          \@anim@base\@anim@pad{\@anim@first}{\the\@anim@curframe}\@anim@ext%
+        }{1}%
+      \fi%
       \advance\@anim@curframe by \@anim@every%
       \advance\@anim@curframe@zb by \@ne%
     \repeat%
@@ -2019,14 +2074,14 @@
   \xdef\@anim@fgcolour{\@anim@@fgcolour}%
   \xdef\@anim@btnsize{\@anim@@btnsize}%
   \xdef\@anim@poster{\@anim@@poster}%
-  \let\if@anim@controls=\if@anim@@controls%
-  \let\if@anim@loop=\if@anim@@loop%
-  \let\if@anim@autoplay=\if@anim@@autoplay%
-  \let\if@anim@autoresume=\if@anim@@autoresume%
-  \let\if@anim@autopause=\if@anim@@autopause%
-  \let\if@anim@palindrome=\if@anim@@palindrome%
-  \let\if@anim@step=\if@anim@@step%
-  \let\if@anim@draft=\if@anim@@draft%
+  \global\let\if@anim@controls=\if@anim@@controls%
+  \global\let\if@anim@loop=\if@anim@@loop%
+  \global\let\if@anim@autoplay=\if@anim@@autoplay%
+  \global\let\if@anim@autoresume=\if@anim@@autoresume%
+  \global\let\if@anim@autopause=\if@anim@@autopause%
+  \global\let\if@anim@palindrome=\if@anim@@palindrome%
+  \global\let\if@anim@step=\if@anim@@step%
+  \global\let\if@anim@draft=\if@anim@@draft%
   \gdef\@anim@posterocg{}%
   \gdef\@anim@properties{}%
   \gdef\@anim@xobject{}%
@@ -2038,10 +2093,11 @@
   \gdef\@anim@pfpsat{}%
   \gdef\@anim@tmlnfile{}%
   \setboolean{@anim@timeline}{false}%
-  \@anim@begin={}%
-  \@anim@end={}%
+  \global\@anim@begin={}%
+  \global\@anim@end={}%
   \gdef\@anim@every{1}% frames to be included
   \gdef\@anim@gropts{}%
+  \setboolean{@anim@multipdf}{false}%
 }
 
 %package options