animate update (4jul07)

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

4 files changed, 175 insertions, 102 deletions

diff --git a/Master/texmf-dist/doc/latex/animate/README b/Master/texmf-dist/doc/latex/animate/README
index fb0e666a0f2..d3b570d2956 100644
--- a/Master/texmf-dist/doc/latex/animate/README
+++ b/Master/texmf-dist/doc/latex/animate/README
@@ -1,92 +1,94 @@
-                             =====================

-                              The animate Package

-                             =====================

-

-Author:

-

-    Alexander Grahn

-

-

-Description:

-

-    This package provides an interface to create portable, JavaScript driven PDF

-    animations from sets of (vector) graphics files or from inline (vector)

-    graphics, such as LaTeX-picture, PSTricks or pgf/TikZ generated pictures,

-    or just from typeset text.

-

-    It supports the usual PDF making workflows, i. e.  pdfLaTeX and LaTeX ->

-    dvips -> ps2pdf (Ghostscript).

-

-    The resulting PDF can be viewed in current Adobe Readers on all supported

-    platforms.

-

-    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

-    `doc/' directory for details and examples.

-

-    Keywords: include, portable, PDF, animation, animating, embed, animated,

-              graphics, LaTeX, pdfLaTeX, PSTricks, pgf, TikZ, LaTeX-picture,

-              inline graphics, vector graphics, dvips, ps2pdf, JavaScript,

-              Adobe Reader

-

-

-Usage:

-

- \usepackage[<package options>]{animate}

-

- -- 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>}

-

- \begin{animateinline}[<options>]{<frame rate>}

-     ... typeset material ...

- \newframe[<frame rate>]

-     ... typeset material ...

- \newframe*[<frame rate>]

-     ... 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]

-

-

-Requirements:

-

-  pdfeTeX, version >= 1.20

-  Adobe Reader, version >= 6

-

-

-Installation:

-

-  Put the file animate.sty to a place where TeX can find it.

-

-

-License:

-

-  This material is subject to the LaTeX Project Public License. See

-

-     http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html

-

-  for the details of that license.

+                             =====================
+                              The animate Package
+                             =====================
+
+Author:
+
+    Alexander Grahn
+
+
+Description:
+
+    This package provides an interface to create portable, JavaScript driven PDF
+    animations from sets of (vector) graphics files or from inline (vector)
+    graphics, such as LaTeX-picture, PSTricks or pgf/TikZ generated pictures,
+    or just from typeset text.
+
+    It supports the usual PDF making workflows, i. e.  pdfLaTeX and LaTeX ->
+    dvips -> ps2pdf (Ghostscript).
+
+    The resulting PDF can be viewed in current Adobe Readers on all supported
+    platforms.
+
+    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
+    `doc/' directory for details and examples.
+
+    Keywords: include, portable, PDF, animation, animating, embed, animated,
+              graphics, LaTeX, pdfLaTeX, PSTricks, pgf, TikZ, MetaPost,
+              LaTeX-picture, inline graphics, vector graphics, dvips, ps2pdf,
+              JavaScript, Adobe Reader
+
+
+Usage:
+
+ \usepackage[<package options>]{animate}
+
+  * 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>}
+
+ \begin{animateinline}[<options>]{<frame rate>}
+     ... typeset material ...
+ \newframe[<frame rate>]
+     ... typeset material ...
+ \newframe*[<frame rate>]
+     ... 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],
+                     begin={<begin text>}, end={<end text>},
+                     timeline=<timeline file>
+
+
+Requirements:
+
+  pdfeTeX, version >= 1.20
+  Adobe Reader, version >= 6
+
+
+Installation:
+
+  Put the file animate.sty to a place where TeX can find it.
+
+
+License:
+
+  This material is subject to the LaTeX Project Public License. See
+
+     http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html
+
+  for the details of that license.
diff --git a/Master/texmf-dist/doc/latex/animate/doc/animate.pdf b/Master/texmf-dist/doc/latex/animate/doc/animate.pdf
index 1d89bfa140e..4f6af7af3ac 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 6090d6b0021..7e9cc0dc8d1 100644
--- a/Master/texmf-dist/doc/latex/animate/doc/animate.tex
+++ b/Master/texmf-dist/doc/latex/animate/doc/animate.tex
@@ -28,7 +28,7 @@
 \parindent0pt
 \parskip1.2ex
 
-\def\keywords{include, portable, PDF, animation, animating, embed, animated, graphics, LaTeX, pdfLaTeX, PSTricks, pgf, TikZ, LaTeX-picture, inline graphics, vector graphics, dvips, ps2pdf, JavaScript, Adobe Reader}
+\def\keywords{include, portable, PDF, animation, animating, embed, animated, graphics, LaTeX, pdfLaTeX, PSTricks, pgf, TikZ, LaTeX-picture, MetaPost, inline graphics, vector graphics, dvips, ps2pdf, JavaScript, Adobe Reader}
 \hypersetup{
   bookmarksnumbered,linktocpage,breaklinks,
   pdftitle={The animate Package},
@@ -119,9 +119,11 @@ and the environment
 
 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 parameter \verb+<frame rate>+ specifies the number of frames per second of the animation.
 
-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 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. Both \verb+\newframe+ variants take an optional argument that allows to change the frame rate in the middle of an animation.
+By default, the animation is build 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 below).
 
-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. 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 $0001\dots0100$.
+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.
+
+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. 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 parameter. The possible file formats depend on whether \LaTeX{} or pdf\LaTeX{} is used. In the case of \LaTeX{}, files with the extension `\verb+eps+' are searched for at first, followed by `\verb+mps+' (\MP-generated Postscript) and `\verb+ps+'. With pdf\LaTeX{} the searching order is: (1)~`\verb+pdf+', (2)~`\verb+mps+', (3)~`\verb+png+', (4)~`\verb+jpg+', (5)~`\verb+jpeg+', (6)~`\verb+jbig2+' and (7)~`\verb+jb2+'. That is, files capable to store vector graphics are found first. Make sure that all file names have \emph{lower case} extensions.
 
@@ -141,6 +143,11 @@ autoresume
 \end{verbatim}
 Resume previously paused animation when the page is opened again.
 \begin{verbatim}
+begin={<begin text>}
+end={<end text>}
+\end{verbatim}
+(`\verb+animateinline+' only.) \verb+<begin text>+ and \verb+<end text>+ are inserted into the code at start and end of each frame. Mainly used for setting up some drawing environment, such as\\ \verb+begin={\begin{pspicture}(...)(...)},+ \verb+end={\end{pspicture}}+.
+\begin{verbatim}
 loop
 \end{verbatim}
 The animation restarts immediately after reaching the end.
@@ -172,16 +179,54 @@ buttonbg=<colour>
 \end{verbatim}
 The background of the animation and control button widgets is transparent by default. It can be turned into a solid colour by the parameter \verb+<colour>+, which is an array of space-separated numbers (\emph{without} surrounding brackets) in the range from 0.0 to 1.0. The number of array elements determines the colour model in which the colour is defined: (1) gray value, (3) RGB, (4) CMYK.
 \begin{verbatim}
+poster=[first | none | last]
+\end{verbatim}
+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.
+\begin{verbatim}
 step
 \end{verbatim}
 Step through the animation by one frame per mouse-click.
 \begin{verbatim}
-poster=[first | none | last]
+timeline=<timeline file>
 \end{verbatim}
-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.
+\verb+<timeline file>+ is a plain text file whose contents determines the order of appearance of the embedded material during the animation. In addition, it allows to freely reorder, repeat and overlay the material at any point of the animation. This may greatly reduce the file size of the resulting PDF, as objects that do not change between several or all frames, such as coordinate axes or labels, can be embedded once and reused in other frames of the animation.
+
+If a timeline is associated with the animation, the graphics files or inline graphics embedded by \verb+animategraphics+ and `\verb+animateinline+' no longer represent the actual frames of the animation. Rather, they are a collection of \emph{transparencies} that can be played with at will. In order to identify the transparencies within the timeline file, they are numbered in the order of their inclusion, starting at zero.
+
+Each line of the timeline file that is not blank and which does not begin with a comment (`\verb+%+') specifies \emph{one} frame of the animation. There may be more transparencies than animation frames and vice-versa. A frame specification consists of three, colon (`\verb+:+') separated fields:
+\begin{verbatim}
+  [*]:[<frame rate>]:[<frame content>]
+\end{verbatim}
+While any field may be left blank, the colons are mandatory.
+
+An asterisk (`\verb+*+') in the leftmost field causes the animation to pause at that frame, very much like a \verb+\newframe*+ would do; a number in the second field changes the frame rate of the animation section that follows. (In connexion with the `\verb+timeline+' option the asterisk extension and the optional \verb+<frame rate>+ argument of \verb+\newframe+ cease to make sense and will be tacitly ignored, if present.) The third field \verb+<frame content>+ is a comma separated list of \emph{transparency specifications} that determines the content of the frame. A single transparency specification obeys the syntax
+\begin{verbatim}
+  <transparency ID>[x<number of frames>]
+\end{verbatim}
+where \verb+<transparency ID>+ is an integer number that identifies the transparency to be drawn into the current animation frame. As pointed out above, the transparencies are consecutively numbered in the order of their inclusion, starting at zero. The optional postfix `\verb+x<number of frames>+' specifies the number of consecutive frames the transparency is to appear within. If omitted, a postfix of `\verb+x1+' is assumed, which causes the transparency to be shown in the current frame only. Obviously, \verb+<number of frames>+ must be a non-negative integer number. The meaning of postfix `\verb+x0+' is special; it causes the transparency to be shown in all frames, starting with the current one, until the end of the animation.
+
+Note, that the order in which transparency specifications appear in the timeline file determines their depth level. The animation can be visualised as a pile of transparencies. Transparencies are always put on top of that pile, possibly overdrawing objects that are on previously deposited transparencies. Once on the pile, each transparency remains at its place for the specified number of frames and is removed afterwards. That is, for a transparency to appear always on top it must be put to the rightmost end of each line in the timeline file.
+
+Consider the two timelines
+\begin{verbatim}
+  ::1,0 % zero'th transparency always on top
+  ::2,0
+  ::3,0
+  ::4,0
+  ...
+\end{verbatim}
+and
+\begin{verbatim}
+  ::0x0,1 % zero'th transparency in the lowest level
+  ::2
+  ::3
+  ::4
+  ...
+\end{verbatim}
+In the first example, transparency no. `0' appears in the uppermost depth level throughout the animation; it will never be obscured by other transparencies' content. In the second example it is put on the lowest level (because it is the first transparency specification in the file) and stays there for the rest of the animation.
 
 \section{Examples}
-\subsection[Animation from a set of files, using `animategraphics' command]{Animation from a set of files, using `{\tt animategraphics}' command}
+\subsection[Animation from a set of files, using `animategraphics' command]{Animation from a set of files, using `{\tt animategraphics}' command together with `{\tt timeline'} option}
 \small
 \begin{verbatim}
 \documentclass{article}
@@ -191,15 +236,32 @@ Specifies which frame (first, last or none) to display and print if the animatio
 \begin{document}
 
 \begin{center}
-  \animategraphics[controls,loop]{4}{frame_}{0}{8}
+  \animategraphics[
+    controls, loop,
+    timeline=timeline.txt
+  ]{4}{frame_}{0}{8}
 \end{center}
 
 \end{document}
 \end{verbatim}
-
 \normalsize
+Contents of file `\verb+timeline.txt+':
+\small
+\begin{verbatim}
+::0x0 % coordinate system & y=e^x, repeated until last frame
+::1   % one blue curve per frame
+::2
+::3
+::4
+::5
+::6
+::7
+::8
+\end{verbatim}
+\normalsize
+
 \begin{center}
-  \animategraphics[controls,loop]{4}{frame_}{0}{8}
+  \animategraphics[controls,loop,timeline=timeline.txt]{4}{frame_}{0}{8}
 \end{center}
 
 \subsection[Animating PSTricks graphics, using `animateinline' environment]{Animating PSTricks graphics, using `{\tt animateinline}' environment}
@@ -329,7 +391,7 @@ Specifies which frame (first, last or none) to display and print if the animatio
 
   \item Currently, animations should not be placed on \emph{multilayered} slides created with the Beamer class. Although possible, the result might be disappointing. 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 The \verb+dvips+ option `\verb+-Ppdf+' should be avoided entirely or followed by something like `\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=...+'.
 
diff --git a/Master/texmf-dist/doc/latex/animate/doc/files/timeline.txt b/Master/texmf-dist/doc/latex/animate/doc/files/timeline.txt
new file mode 100644
index 00000000000..c0945a66a6b
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/animate/doc/files/timeline.txt
@@ -0,0 +1,9 @@
+::0x0 % coordinate system & y=e^x, repeated until last frame
+::1   % one blue curve per frame
+::2
+::3
+::4
+::5
+::6
+::7
+::8