animate (20nov18)

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

1 files changed, 87 insertions, 15 deletions

diff --git a/Master/texmf-dist/source/latex/animate/animate.tex b/Master/texmf-dist/source/latex/animate/animate.tex
index d54f2973b91..786bc1a2989 100644
--- a/Master/texmf-dist/source/latex/animate/animate.tex
+++ b/Master/texmf-dist/source/latex/animate/animate.tex
@@ -61,7 +61,7 @@
 %  \makeatother
 %\fi
 
-\def\keywords{include portable PDF animation animated PDF animating embed animated graphics LaTeX pdfLaTeX LuaLaTeX PSTricks pgf TikZ LaTeX-picture MetaPost inline graphics vector graphics animated GIF LaTeX dvips ps2pdf dvipdfmx XeLaTeX JavaScript Acrobat Reader PDF-XChange Foxit Reader}
+\def\keywords{include portable PDF animation SVG animation animated PDF animated SVG dvisvgm html TeX4ht web animating embed animated graphics LaTeX pdfLaTeX LuaLaTeX PSTricks pgf TikZ LaTeX-picture MetaPost inline graphics vector graphics animated GIF LaTeX dvips ps2pdf dvipdfmx XeLaTeX JavaScript Acrobat Reader PDF-XChange Foxit Reader Firefox Chrome Chromium}
 \hypersetup{
   pdftitle={The animate Package},
   pdfsubject={Documentation},
@@ -80,7 +80,7 @@
   \def\day{#3}
 }
 
-\hyphenation{Ja-va-Script}
+\hyphenation{Ja-va-Script pro-vid-ed}
 
 \begin{document}
 \title{The {\sffamily animate} Package}
@@ -95,31 +95,33 @@
 \begin{abstract}
 \raggedright
 
-\noindent A LaTeX package for creating portable, JavaScript driven PDF animations from sets of vector graphics or raster image files or from inline graphics.
+\noindent A LaTeX package for creating portable, JavaScript driven PDF and SVG animations from sets of vector graphics or raster image files or from inline graphics.
 \vskip 0.2\baselineskip
 
 \emph{Keywords}: \keywords
 \end{abstract}
-
+%\vspace{1.5cm}
 \tableofcontents
 
 %\newpage
 \section{Introduction}
-This package provides an interface for creating PDFs with animated content from sets of graphics or image files, from inline graphics, such as \LaTeX-picture, PSTricks or pgf/TikZ generated pictures, or just from typeset text. Unlike standard movie/video formats, package `animate' allows for animating vector graphics. The result is roughly similar to the SWF (Flash) format, although not as space-efficient.
+This package provides an interface for creating PDF and SVG files with animated content from sets of graphics or image files, from inline graphics, such as \LaTeX-picture, PSTricks or pgf/TikZ generated pictures, or just from typeset text. Unlike standard movie/video formats, package `animate' allows for animating vector graphics. The result is roughly similar to the SWF (Flash) format, although not as space-efficient.
 
 The user interacts with the animation through optional animation controls or using the mouse like so: Pressing the mouse button over the animation widget immediately pauses a playing animation and releasing it resumes playback. Pressing the shift-key at the same time reverses the playback direction. Keeping the mouse button pressed while moving the mouse pointer off the animation widget permanently pauses playback.
 
-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+.
+Package `animate' supports the usual workflows for making PDF, i.\,e. pdf\LaTeX{}, Lua\LaTeX{}, \LaTeX{} $\rightarrow$ \verb+dvips+ $\rightarrow$ \verb+ps2pdf+/Distiller and \pXepLaTeX{} $\rightarrow$ \verb+(x)dvipdfmx+, and \LaTeX{} $\rightarrow$ \verb+dvisvgm+ for SVG.
 
-PDF files with animations can be viewed in Acrobat Reader (except on mobile devices), PDF-XChange and Foxit Reader.
+PDF files with animations can be viewed in Acrobat Reader (except on mobile devices), PDF-XChange and Foxit Reader. Animated SVG produced by means of \LaTeX{} and \verb+dvisvgm+ are self-contained files that can be embedded into HTML using the \verb+<object>+ tag or opened directly in a Web browser, such as Firefox or Chromium.
 
 \section{Requirements}
 \begin{trivlist}
 %\item $\varepsilon$-\TeX
 \item pdf\TeX{}, version $\ge1.20$, or Lua\TeX{}, version $\ge0.95$, for direct PDF output
 \item Ghostscript, version $\ge9.15$ or Adobe Distiller for PS to PDF conversion
-\item dvipdfmx, version $\ge20080607$ for DVI to PDF conversion
-\item Acrobat Reader (version $\ge7$), PDF-XChange, Foxit Reader
+\item \verb+dvipdfmx+ for DVI to PDF conversion
+\item \verb+dvisvgm+ for DVI to SVG conversion (also requires Ghostscript)
+\item PDF: Acrobat Reader (version $\ge7$), PDF-XChange, Foxit Reader
+\item SVG: Firefox, Chrome/Chromium and others
 \end{trivlist}
 
 \section{Installation}
@@ -140,6 +142,7 @@ to the preamble of the document source, i.\,e. somewhere between \verb+\document
 \begin{verbatim}
 dvipdfmx
 xetex
+dvisvgm
 export
 autoplay
 autopause
@@ -164,16 +167,22 @@ type=<file ext>
 method=icon | widget | ocg
 poster[=first | <num> | last | none]
 \end{verbatim}
-Except for `\verb+dvipdfmx+', `\verb+xetex+' and `\verb+export+', the listed package options 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+', `\verb+xetex+' and `\verb+export+', by appending `\verb+=false+'.
+Except for `\verb+dvipdfmx+', `\verb+xetex+', `\verb+dvisvgm+' and `\verb+export+', the listed package options 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+', `\verb+xetex+', `\verb+dvisvgm+ and `\verb+export+', by appending `\verb+=false+'.
 
 \begin{animateinline}[autoplay,loop,nomouse]{1}\strut\emph{Important:}\newframe[3]\end{animateinline} Option `\verb+-Ppdf+' should \emph{not} be used with \verb+dvips+ when converting DVI to 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.
 
-All workflows require the `graphicx' package to be loaded explicitly. For \verb+dvipdfmx+, `\verb+dvipdfmx+' must be set as a document class option, as in
+All workflows require the `graphicx' package to be loaded explicitly.
+
+Options `\verb+dvipdfmx+' or `\verb+dvisvgm+' must be set for the document class, as in
 %\verb+\documentclass[dvipdfmx,...]{...}+,
 \begin{verbatim}
   \documentclass[dvipdfmx,...]{...}
 \end{verbatim}
-because this driver cannot be auto-detected by `animate', `graphicx' and other packages.
+or
+\begin{verbatim}
+  \documentclass[dvisvgm,...]{...}
+\end{verbatim}
+because these drivers cannot be auto-detected by `animate', `graphicx' and other packages.
 
 Usually, a second \LaTeX{} run is necessary to resolve internally created object references. A warning message will be issued if appropriate.
 
@@ -229,7 +238,7 @@ For example, given the sequence `frame\_5.png' through `frame\_50.png' from a po
   \animategraphics{12}{frame_}{5}{50}
 \end{verbatim}
 
-The possible file formats depend on the output driver being used. In the case of \LaTeX{} + \verb+dvips+, files with the `eps' extension are at first searched for, followed by `mps' (\MP-generated Postscript) and `ps'. With pdf\LaTeX{} and Lua\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]{Only Lua\LaTeX{} currently supports JPEG2000.} and with \XeLaTeX{} or \LaTeX{}+\verb+dvipdfmx+: (1)~`pdf', (2)~`mps', (3)~`eps', (4)~`ps', (5)~`png', (6)~`jpg', (7)~`jpeg', (8)~`bmp'. That is, files capable of storing vector graphics are found first. Make sure that all file names have \emph{lower case} extensions.
+The possible file formats depend on the output driver being used. In the case of \LaTeX{} + \verb+dvips+, files with the `eps' extension are at first searched for, followed by `mps' (\MP-generated Postscript) and `ps'. With pdf\LaTeX{} and Lua\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]{Only Lua\LaTeX{} currently supports JPEG2000.}, with \XeLaTeX{} or \LaTeX{}+\verb+dvipdfmx+: (1)~`pdf', (2)~`mps', (3)~`eps', (4)~`ps', (5)~`png', (6)~`jpg', (7)~`jpeg', (8)~`bmp', and with \LaTeX{}+\verb+dvisvgm+: (1)~`eps', (2)~`ps', (3)~`svg', (4)~`png', (5)~`jpg', (6)~`jpeg'. That is, files capable of storing vector graphics are found first. Make sure that all file names have \emph{lower case} extensions.
 
 This searching procedure can be skipped thanks to the package and command option `\verb+type=<file ext>+'. It enforces the embedding of files with the given file name extension \verb+<file ext>+.
 
@@ -250,7 +259,7 @@ The following options to \verb+\animategraphics+ and `\verb+animateinline+' have
 \begin{verbatim}
 label=<label text>
 \end{verbatim}
-The animation is given a label, \verb+<label text>+, which must be unique. Labelling an animation enables its JavaScript programming interface by defining \verb+anim['<label text>']+, which is a JavaScript reference to the animation object. The animation object provides a number of properties and methods that can be used for controlling the animation playback from within user defined JavaScript. For details, see Section~\ref{sect:api}.
+The animation is given a label, \verb+<label text>+, which must be unique. Labelling an animation enables its JavaScript programming interface by defining \verb+anim['<label+ \verb+text>']+, which is a JavaScript reference to the animation object. The animation object provides a number of properties and methods that can be used for controlling the animation playback from within user defined JavaScript. For details, see Section~\ref{sect:api}.
 \begin{verbatim}
 type=[<file ext>]
 \end{verbatim}
@@ -375,7 +384,7 @@ Each line of the timeline file that is not blank and which does not begin with a
 \begin{verbatim}
   [*]:[<frame rate>]:[<transparencies>][:<JavaScript>]
 \end{verbatim}
-While any field may be left blank, the first two colons are mandatory. The \verb+<JavaScript>+ field is explained on p.~\pageref{sect:jsfield}.
+While any field may be left blank, the first two colons are mandatory. The fourth field, \verb+<JavaScript>+, is explained on p.~\pageref{sect:jsfield}.
 
 An asterisk (`\verb+*+') in the leftmost field causes the animation to pause at that frame, very much as a \verb+\newframe*+ would do; a number in the second field changes the frame rate of the animation section that follows. In connection 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.
 
@@ -644,6 +653,7 @@ The second, somewhat more complex example, Fig.~\ref{fig:scarab}, animates the g
 \immediate\closeout\TimeLineFile
 %
 \animategraphics[
+  type=mps,
   width=0.8\linewidth,
   controls,
   loop,
@@ -1284,6 +1294,67 @@ dt dt Tm nT mul { % pop
 \end{document}
 \end{lstlisting}
 
+\section{Producing animated SVG} 
+Thanks to Martin Gieseking's `\verb+dvisvgm+' utility~\cite{dvisvgm} that ships with all major \TeX{} distributions, package `animate' can produce self-contained animated SVG, with all the bits and pieces already included that are necessary to run in modern Web browsers as standalone files or as embedded objects within a Web page made of HTML. Animations have the same look and usability, including optional control buttons, as if they were embedded in a PDF document.
+
+Moreover, as `\verb+dvisvgm+' is linked against the Ghostscript library, it can parse and convert embedded Postscript to inline SVG code. It is therefore compatible with the popular TikZ and PSTricks \LaTeX{} packages.
+ 
+SVG is a one-page graphics format. Therefore, it is most useful to first produce DVI with a single animation per file or page. Then, `\verb+dvisvgm+' converts every page of the DVI input to a standalone SVG file. For a standalone animated SVG, use the `article' document class and pass `\verb+dvisvgm+' as a global option. In this way, it gets conveyed to  `animate' and other packages to be loaded, such as `graphicx' or TikZ. Note that the `standalone' document class is not required; `\verb+dvisvgm+' already computes the tightly enclosing bounding box around the page content by default.
+
+The following code may serve as a template for generating standalone SVG:
+\begin{lstlisting}
+\documentclass[12pt,dvisvgm]{article}
+
+\usepackage{animate}
+\usepackage{graphicx}
+
+%\usepackage{xcolor}
+%\pagecolor{white} % opaque background with solid colour
+
+%\usepackage{pstricks} % enable as needed
+%\usepackage{tikz}
+
+\pagestyle{empty}
+
+\begin{document}
+\begin{center}
+
+%
+% \animategraphics{..}{...}{...}{...}
+%
+% or  
+%  
+% \begin{animateinline}{..} ... \end{animateinline} 
+%
+
+\end{center}
+\end{document}
+\end{lstlisting}
+Note that when animating external graphics with \verb+\animategraphics+, only Postscript (EPS, PS) files are converted to inline SVG code; files in other formats (SVG, PNG, JPEG) remain external and must be bundled with the final SVG output. Unfortunately, the use of (E)PS with \verb+\animategraphics+ is limited to vector graphics. If such files contain bitmapped content they must be converted to PNG (or JPEG, if photographs). Of course, these files remain external to the final animated SVG.
+
+Use one of
+\begin{verbatim}
+latex
+platex
+lualatex --output-format=dvi
+xelatex -no-pdf
+\end{verbatim}
+to produce DVI or XDV output from the \LaTeX{} source. After this, SVG is obtained by running
+\begin{verbatim}
+dvisvgm --no-fonts -exact
+\end{verbatim}
+on the intermediate DVI or XDV file. Option `\verb+--no-fonts+' prompts `\verb+dvisvgm+' to retrace font glyphs as graphical paths. It ensures that the text font looks as in normal PDF output. Option `\verb+--exact+' tells `\verb+dvisvgm+' to calculate exact bounding boxes around font glyphs. This avoids clipping of glyphs in the SVG output, as glyphs usually tend to be slightly bigger than their boxes defined in the font files. To convert multipage DVI/XDV with several animations, add option `\verb+-p1,-+'. By default, `\verb+dvisvgm+' processes only the very first page of the input file. As SVG derives from XML it is not known to be particularly economical in terms of file size. Compressed SVG, with file extension `\verb+svgz+', shortens download times and is supported by most Web browsers. It can be generated by adding option `\verb+-z+'.
+
+The recommended way to include animated SVG into HTML is to use the \verb+<object>+ tag. The \verb+<img>+ tag does not work here, as it ignores the embedded JavaScript. However, it may still be used as fallback. Also, it allows for search engine indexing, if desired:
+\begin{lstlisting}
+<object type="image/svg+xml" data="animatedImage.svg">
+  <!-- fallback & search engine indexing -->
+  <img src="animatedImage.svg" />
+</object>
+\end{lstlisting}
+
+In \TeX4ht documents, the whole \verb+<object>...</object>+ tag can be inserted by wrapping it in a \verb+\HCode{...}+ command.
+
 \section{Bugs}\label{sect:bugs}
 \begin{itemize}
   \item The maximum frame rate that can actually be achieved largely depends on the complexity of the graphics and on the available hardware. Starting with version 8, Acrobat Reader appears to be somewhat slower. However, you might want to experiment with the graphical hardware acceleration feature that was introduced in Reader 8. Go to menu `Edit' $\rightarrow$ `Preferences' $\rightarrow$ `Page Display' $\rightarrow$ `Rendering' to see whether hardware acceleration is available. A 2D GPU acceleration check box will be visible if a supported video card has been detected.
@@ -1347,6 +1418,7 @@ I would like to thank François Lafont who discovered quite a few bugs and made
 
 \begin{thebibliography}{8}
   \bibitem{chupin} Chupin, M.: \emph{Syracuse MetaPost/Animations.} URL: \href{http://melusine.eu.org/syracuse/metapost/animations/chupin/?idsec=scara}{\url{http://melusine.eu.org/}} \href{http://melusine.eu.org/syracuse/metapost/animations/chupin/?idsec=scara}{\url{syracuse/metapost/animations/chupin/?idsec=scara}}
+\bibitem{dvisvgm} \emph{dvisvgm: A fast DVI to SVG converter} URL: \url{http://dvisvgm.de}
 \bibitem{gilg05} Gilg, J.: PDF-Animationen. In: \emph{Die \TeX nische Kom\"odie}, Issue 4, 2005, pp.~30--37
 %\bibitem{hol} Holeček, J.: \emph{Animations in a pdf\TeX-generated PDF}. URL: \url{http://www.fi.muni.cz/~xholecek/tex/pdfanim.xhtml}
 \bibitem{hol} Holeček, J.; Sojka, P.: Animations in pdf\TeX-generated PDF. In: \emph{\TeX, XML, and Digital Typography}, Springer, 2004, pp.~179--191. doi:10.1007/978-3-540-27773-6\textunderscore14