animate (24mar20)

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

1 files changed, 26 insertions, 23 deletions

diff --git a/Master/texmf-dist/source/latex/animate/animate.tex b/Master/texmf-dist/source/latex/animate/animate.tex
index 0a178a58f49..684d9216df6 100644
--- a/Master/texmf-dist/source/latex/animate/animate.tex
+++ b/Master/texmf-dist/source/latex/animate/animate.tex
@@ -161,6 +161,7 @@ draft
 final
 controls[=(all|true|on) |
           (none|false|off) | {[play][,step][,stop][,speed]}]
+controlsaligned=left[+<indent>] | center | right[+<indent>]
 width=<h-size>
 height=<v-size> | totalheight=<v-size>
 keepaspectratio
@@ -343,6 +344,14 @@ controls=(none | false | off) | {[play][,step][,stop][,speed]}
 \end{verbatim}
 Inserts control buttons below the animation widget. Visibility of buttons can be fine-tuned through optional keys. By default, if setting `\verb+controls+' alone, all available buttons are shown, while any of `\verb+none+', `\verb+false+' or `\verb+off+' suppresses them altogether. A comma-separated selection from `\verb+play+', `\verb+step+', `\verb+stop+' and `\verb+speed+' enables corresponding pairs or groups of buttons. Such a comma list must be enclosed in braces, i.\,e. \verb+controls={..., ..., ...}+. If all buttons are shown, their meaning is as follows, from left to right: stop \& first frame, step backwards, play backwards, play forwards, step forwards, stop \& last frame, decrease speed, default speed, increase speed. Both `play' buttons are replaced by a large `pause' button while the animation is playing.
 \begin{verbatim}
+controlsaligned=left[+<indent>] | center | right[+<indent>]
+\end{verbatim}
+Animation controls are centred below the animation widget by default. With this option one can choose between centred, flush-left or flush-right alignment. The optional \verb+<indent>+ inserts additional horizontal space that pushes the control buttons away from the left or right edge of the animation widget towards the opposite side. \verb+<indent>+ must be a valid \TeX{} dimension. Negative values may be used, as in
+\begin{verbatim}
+    controlsaligned=right+-4em,
+\end{verbatim}
+in which case control buttons protrude beyond the animation's right vertical edge by \verb+4em+.
+\begin{verbatim}
 buttonsize=<size>
 \end{verbatim}
 Changes the control button height to \verb+<size>+, which must be a valid \TeX{} dimension. The default button height is \verb+1.44em+ and thus scales with the current font size.
@@ -913,7 +922,7 @@ A timeline file, written on-the-fly, is used to assemble the curve segments fram
 \noindent\begin{animateinline}[
   timeline=lorenz.tln,
   controls,poster=last,
-  begin={\begin{pspicture}(-39,-13)(39,60)},
+  begin={\begin{pspicture}(-36,-13)(36,55)},
   end={\end{pspicture}}
 ]{10}
   %coordinate axes
@@ -1317,18 +1326,16 @@ 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. Animated SVG even work on mobile devices.
+\section{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. Animated SVG even work on mobile devices.
 
-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.
+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 single-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 animated SVG file. 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. If `standalone' is still to be used, `\verb+preview+' must be added as a global document class option.
+SVG is a single-page graphics format. Therefore, it is recommended to produce documents with a single animation per file or page. Thereafter, \verb+dvisvgm+ converts every page of the DVI input to a standalone animated SVG file. You may want to use the `standalone' document class for creating standalone SVG animations. Pass `\verb+dvisvgm+' as a global document class option. In this way, it gets conveyed to `animate' and other packages to be loaded, such as `graphicx' or TikZ.
 
 The following code may serve as a template for generating standalone animated SVG:
 \begin{lstlisting}
-\documentclass[dvisvgm]{article}
-
-\pagestyle{empty} % suppress page number
+\documentclass[dvisvgm]{standalone}
 
 \usepackage{animate}
 \usepackage{graphicx}
@@ -1340,7 +1347,6 @@ The following code may serve as a template for generating standalone animated SV
 %\usepackage{tikz}
 
 \begin{document}
-\begin{center}
 
 %
 % \animategraphics{..}{...}{...}{...}
@@ -1350,33 +1356,34 @@ The following code may serve as a template for generating standalone animated SV
 % \begin{animateinline}{..} ... \end{animateinline} 
 %
 
-\end{center}
 \end{document}
 \end{lstlisting}
-Note that when animating external graphics with \verb+\animategraphics+, only PDF and PostScript (EPS, PS, MPS) 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. Also note that PostScript files must have all required fonts embedded. This is not always the case for \MP-generated PostScript. Here, embedding of fonts is ensured by putting `\verb+prologues := 3;+' into the header of the \MP{} input. Unfortunately, animating PDF and PostScript files 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.
+Note that when animating external graphics with \verb+\animategraphics+, only PDF and PostScript (EPS, PS, MPS) 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. Thus, for obtaining self-contained SVG, it is recommended to convert PNG, JPEG and SVG files to PDF or PostScript first. Also note that PostScript files must have all required fonts embedded. This is not always the case for \MP-generated PostScript. Here, embedding of fonts is ensured by putting `\verb+prologues := 3;+' into the header of the \MP{} input.
 
 Use one of
 \begin{verbatim}
 latex
 platex
-lualatex --output-format=dvi
+dvilualatex
 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 --font-format=woff --exact --zoom=-1
+dvisvgm --font-format=woff --exact --zoom=-1 --page=1,- --optimize ...
 \end{verbatim}
 on the intermediate DVI or XDV file.
 
-Option `\verb+--font-format=woff+' (or `\verb+--font-format=woff2+') prompts `\verb+dvisvgm+' to embed document fonts in a format that is understood by Web browsers. It ensures that typeset text looks as in normal PDF output.
+Option `\verb+--font-format=woff+' (or `\verb+--font-format=woff2+') prompts \verb+dvisvgm+ to embed document fonts in a format that is understood by Web browsers. It ensures that typeset text 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.
+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.
 
 The purpose of `\verb+--zoom=-1+' is to produce responsive SVG. If embedded in a Web page, this kind of SVG will automatically scale to fill up the available space of its surrounding container, usually an \verb+<object>+ tag (see below). If viewed standalone in a Web browser, a responsive SVG fills up the complete browser tab.
 
-By default, `\verb+dvisvgm+' processes only the very first page of the input file. 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. To convert multipage DVI/XDV with several animations, add option `\verb+--page=1,-+'.
+
+With option `\verb+--optimize+', \verb+dvisvgm+ applies several optimizations to reduce the output file size.
 
-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+'. Also, option `\verb+--precision=1+' may be used to reduce the SVG file size. It limits the precision of floating point numbers, such as coordinates, to one decimal figure.
+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+'. Also, option `\verb+--precision=1+' may be used to reduce the SVG file size. It limits the precision of floating point numbers, such as coordinates, to one decimal figure. Sometimes, animations may behave stangely after applying this option. Then, of course, it should be omitted.
 
 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}
@@ -1395,10 +1402,6 @@ In \TeX4ht documents, the whole \verb+<object>...</object>+ tag can be inserted
 
   \item Animated SVG is best viewed in Web browsers that are based on the Blink rendering engine. The most prominent representatives are Chrome, its open-source base Chromium and Opera. Unfortunately, Firefox is very slow.
 
-%  \item Animations may run very slowly if viewed in the Acrobat Reader web-browser plugin. Instead, open the PDF locally in the Reader application for best results.
-
-%  \item The Acrobat Reader setting `Use page cache' (menu `Edit' $\rightarrow$ `Preferences' $\rightarrow$ `Startup') should be \emph{dis}abled for version 7, while remaining \emph{en}abled beginning with version 8 (menu `Edit' $\rightarrow$ `Preferences' $\rightarrow$ `Page Display' $\rightarrow$ `Rendering').
-
   \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, Acrobat Reader gets confused and will not display the frames within the animation widget.
 
   \item Animations do not work if the PDF was produced with Ghostscript versions older than 9.15.
@@ -1427,7 +1430,7 @@ In \TeX4ht documents, the whole \verb+<object>...</object>+ tag can be inserted
     into the editor window that opens, save the file and quit the editor.
     \item\label{item:laststep} To rebuild the format, enter\\
     {\tt initexmf -{}-dump=latex}
-    \item Repeat steps \ref{item:firststep}--\ref{item:laststep} with config files `{\tt pdflatex}' and `{\tt xelatex}'
+    \item Repeat steps \ref{item:firststep}--\ref{item:laststep} with config files {\tt pdflatex} and {\tt xelatex}
   \end{enumerate}
 
   \TeX\ Live:
@@ -1450,7 +1453,7 @@ In \TeX4ht documents, the whole \verb+<object>...</object>+ tag can be inserted
 \end{itemize}
 
 \section{Acknowledgements}
-I would like to thank François Lafont who discovered quite a few bugs and made many suggestions that helped to improve the functionality of the package. Many thanks to Jin-Hwan Cho, the developer of `\verb+dvipdfmx+', for contributing the `\verb+dvipdfmx+' specific code, and to Walter Scott for proof-reading the documentation.
+I would like to thank François Lafont who discovered quite a few bugs and made many suggestions that helped to improve the functionality of the package. Many thanks to Jin-Hwan Cho, the developer of \verb+dvipdfmx+, for contributing the \verb+dvipdfmx+ specific code, and to Walter Scott for proof-reading the documentation.
 
 \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}}