movie15 update

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

3 files changed, 42 insertions, 33 deletions

diff --git a/Master/texmf-dist/doc/latex/movie15/README b/Master/texmf-dist/doc/latex/movie15/README
index 0718bcd6681..e0d1259907e 100644
--- a/Master/texmf-dist/doc/latex/movie15/README
+++ b/Master/texmf-dist/doc/latex/movie15/README
@@ -13,7 +13,7 @@ Description:
     into PDF documents for use with LaTeX as well as pdfLaTeX. It follows the
     PDF-1.5 and PDF-1.6 specifications for embedding multimedia content. The
     specification allows media file data to be completely incorporated into the
-    PDF output, thus producing selfcontained PDF documents. A number of file
+    PDF output, thus producing self-contained PDF documents. A number of file
     formats is supported. For a (possibly incomplete) list see the table at the
     end of this file or refer to the PDF specification:
 
@@ -69,15 +69,21 @@ Usage:
                               player.  Re-use as file attachment can be
                               suppressed with `attach=false'.
 
+   autoclose                  Close the media player when the page is closed.
+                              Use of this option may be necessary for streamed
+                              media, such as Real Video.
+
    autopause                  Pause playback when page is closed.
 
    autoplay                   Start playback when page is opened. Useful for
                               side by side movies to be played back
                               simultaneously.
 
-   autostop                   Stop playback when page is closed.
-                              Default behaviour, override with option
-                              `continue'.
+   autostop                   Stops playing but keeps the media loaded when the
+                              page is closed. The media is rewound to its
+                              beginning or its `startat' position. This option
+                              is set by default if neither of the options
+                              `autopause', `autoclose' or `continue' is set.
 
    autoresume                 Resume previously paused playback when page
                               is opened.
@@ -114,8 +120,8 @@ Usage:
 
    palindrome[=true|false]    Play media forward and backward.
 
-   playerid=<playerid>        Forces a particular media player plugin to be used
-                              instead of the default one. Currently, the
+   playerid=<playerid>        Forces a particular media player plug-in to be
+                              used instead of the default one. Currently, the
                               following values are recognised:
                               AAPL_QuickTime, MACR_FlashPlayer, RNWK_RealPlayer,
                               MSFT_WindowsMediaPlayer, ADBE_MCI (Adobe builtin
@@ -214,11 +220,11 @@ Usage:
                               canvas. Only fixed point real numbers in the range
                               from 0 to 1 are allowed for the colour components.
 
-   3Djscript=<JavaScipt file> Things like animation, lighting, background colour
-                              etc. may also be script driven. Option `3Djscript'
-                              associates a <JavaScipt file> with the 3D object.
-                              The script will be executed upon activation of the
-                              object.
+   3Djscript=<JavaScript file> Things like animation, lighting, background
+                              colour etc. may also be script driven. Option
+                              `3Djscript' associates a <JavaScript file> with
+                              the 3D object. The script will be executed upon
+                              activation of the object.
 
 
  Additional options for use with `\movieref':
diff --git a/Master/texmf-dist/doc/latex/movie15/movie15.pdf b/Master/texmf-dist/doc/latex/movie15/movie15.pdf
index 9ed36dfae1e..650f59c5676 100644
--- a/Master/texmf-dist/doc/latex/movie15/movie15.pdf
+++ b/Master/texmf-dist/doc/latex/movie15/movie15.pdf
diff --git a/Master/texmf-dist/doc/latex/movie15/movie15.tex b/Master/texmf-dist/doc/latex/movie15/movie15.tex
index 7bae57c9ecb..5a253ea8d75 100644
--- a/Master/texmf-dist/doc/latex/movie15/movie15.tex
+++ b/Master/texmf-dist/doc/latex/movie15/movie15.tex
@@ -45,11 +45,11 @@ A \LaTeX{} package for inclusion of movies, sounds and 3D objects into PDF docum
 \tableofcontents
 \section{Introduction}
 
-The way multimedia content, i.\,e. movies and sounds, is included into PDF has changed with Adobe's PDF specification, version 1.5. PDF-1.5 supports a larger variety of movie and sound formats, limited only by the number of plugins available for Adobe Reader\textsuperscript{\scriptsize\textregistered}. With PDF-1.6, support for 3D objects, stored in the U3D file format, has been added. See Table \ref{table:mime} for a list of viable media formats. The specification allows media file contents to be completely embedded into the PDF output, thus producing selfcontained PDF documents.
+The way multimedia content, i.\,e. movies and sounds, is included into PDF has changed with Adobe's PDF specification, version 1.5. PDF-1.5 supports a larger variety of movie and sound formats, limited only by the number of plug-ins available for Adobe Reader\textsuperscript{\scriptsize\textregistered}. With PDF-1.6, support for 3D objects, stored in the U3D file format, has been added. See Table \ref{table:mime} for a list of viable media formats. The specification allows media file contents to be completely embedded into the PDF output, thus producing self-contained PDF documents.
 
 This package provides an interface to embed movies, sounds and 3D objects into PDF documents for use with \LaTeX{} as well as pdf\LaTeX. Media file contents is incorporated into PDF output by default. This is done either directly during source processing using pdf\LaTeX{} or during conversion from Postscript to PDF using Ghostscript's \verb+ps2pdf+.
 
-The final PDF output can be viewed with Windows\textsuperscript{\scriptsize\textregistered} and Mac OS\textsuperscript{\scriptsize\textregistered} versions of Adobe Reader. However, embedded media file data can also be extracted and saved to disk from within Readers which support file attachments. This makes PDF documents a little more portable to Readers which do not ship with a multimedia plugin.
+The final PDF output can be viewed with Windows\textsuperscript{\scriptsize\textregistered} and Mac OS\textsuperscript{\scriptsize\textregistered} versions of Adobe Reader. However, embedded media file data can also be extracted and saved to disk from within Readers which support file attachments. This makes PDF documents a little more portable to Readers which do not ship with a multimedia plug-in.
 
 \section{Installation}
 The file `movie15.sty' should be stored in a place where \LaTeX{} can find it.
@@ -76,7 +76,7 @@ pdf\LaTeX{}, version $\ge1.20$, is needed for direct PDF output.
 
 If the package option `\verb+3D+' is set, `movie15' loads Michael Mehlich's `fp' package for fixed point arithmetic. Since it does not belong to the core packages of most \TeX{} distributions it must be installed prior to selecting the `\verb+3D+' option.
 
-Adobe Reader, version 6, is required for playing movies and sounds, version 7 for rendering embedded 3D content. Unfortunately, only Windows and Mac versions of Adobe Reader provide the necessary plugins.
+Adobe Reader, version 6, is required for playing movies and sounds, version 7 for rendering embedded 3D content. Unfortunately, only Windows and Mac versions of Adobe Reader provide the necessary plug-ins.
 
 \section{The user interface}
 \subsection{Media inclusion}\label{usrif}
@@ -90,7 +90,11 @@ Below, common options to \verb+\includemovie+ are listed. Options specific to em
 \begin{verbatim}
 attach[=false]
 \end{verbatim}
-By default, the embedded data stream is re-used as embedded file attachment. This makes `movie15' a little more portable to PDF Readers which do not have a multimedia plugin because it gives the user the opportunity to extract the media file and to save it to disk for later playback with an external player. However, support of file attachments is required. Re-use as file attachment can be suppressed with option `\verb+attach=false+'. Note that `\verb+attach=false+' is a poor method to prevent the user from obtaining a copy of the media file. There are several (free) tools for decompressing and extracting stream objects from PDF files.
+By default, the embedded data stream is re-used as embedded file attachment. This makes `movie15' a little more portable to PDF Readers which do not have a multimedia plug-in because it gives the user the opportunity to extract the media file and to save it to disk for later playback with an external player. However, support of file attachments is required. Re-use as file attachment can be suppressed with option `\verb+attach=false+'. Note that `\verb+attach=false+' is a poor method to prevent the user from obtaining a copy of the media file. There are several (free) tools for decompressing and extracting stream objects from PDF files.
+\begin{verbatim}
+autoclose
+\end{verbatim}
+Close the media player when the page is closed. Use of this option may be necessary for streamed media, such as Real Video.
 \begin{verbatim}
 autopause
 \end{verbatim}
@@ -98,11 +102,11 @@ Pause playing when the page is closed.
 \begin{verbatim}
 autoplay
 \end{verbatim}
-Put this option to the options list if you want the playback of the media clip to be started automatically after the page has opened. This is especially useful if there are multiple movie clips on the current page to be played at the same time. Also resumes playback of previously paused media. In the case of embedded sound being started this way, \verb+<width>+ and \verb+<height>+ can be safely set to `0pt' since no further user interaction is necessary to start playing.
+Start playback of the media clip after the page has opened. This is especially useful if there are multiple movie clips on the current page to be played at the same time. Also resumes playback of previously paused media. In the case of embedded sound being started this way, \verb+<width>+ and \verb+<height>+ can safely be set to `0pt' since no further user interaction is necessary to start playing.
 \begin{verbatim}
 autostop
 \end{verbatim}
-Stop playing when the page is closed. This is default behaviour. Override with option `\verb+continue+'.
+Stops playing but keeps the media loaded when the page is closed. The media is rewound to its beginning or its `\verb+startat+' position. This option is set by default if neither of the options `\verb+autopause+', `\verb+autoclose+' or `\verb+continue+' is set.
 \begin{verbatim}
 autoresume
 \end{verbatim}
@@ -147,7 +151,7 @@ The media is played forward and backward, if supported by the media player. In c
 \begin{verbatim}
 playerid=<playerid>
 \end{verbatim}
-Forces a particular media player plugin to be used instead of the default one. Currently, the following values are recognized:\\[1ex]
+Forces a particular media player plug-in to be used instead of the default one. Currently, the following values are recognized:\\[1ex]
 {\tt\phantom{xxxx}AAPL\_QuickTime\\
 \phantom{xxxx}MACR\_FlashPlayer\\
 \phantom{xxxx}RNWK\_RealPlayer\\
@@ -165,7 +169,7 @@ Inserts still image from file \verb+<image>+ to be shown when the media clip is
 \begin{verbatim}
 rate=<rate>
 \end{verbatim}
-\verb+<rate>+ specifies the playback rate, where $1$ is normal playback, $0.5$ is halfspeed, $2$ is doublespeed, $-1$ is normal speed in reverse etc.
+\verb+<rate>+ specifies the playback rate, where $1$ is normal playback, $0.5$ is half speed, $2$ is double speed, $-1$ is normal speed in reverse etc.
 \begin{verbatim}
 repeat[=<repeats>]
 \end{verbatim}
@@ -216,9 +220,9 @@ volume=<percentage of original volume>
 The meaning of this option should be self explaining.
 
 \subsection{Inclusion of 3D objects}\label{3dtut}
-The PDF-1.6 specification, which was introduced with the advent of Adobe Acrobat/Reader 7, allows embedding of 3-dimensional graphic objects, such as CAD models or 3D scientific data, and lets the user interactively manipulate them. At time of writing this documentation, the only supported file format is U3D~\cite{3diforg}, and only one commercial software~\cite{dexp} for exporting into U3D format, yet from a number of CAD and 3D vector formats, including DXF and VRML, was known. Nevertheless, a tryout version of~\cite{dexp} can be downloaded from the Web site.
+The PDF-1.6 specification, which was introduced with the advent of Adobe Acrobat/Reader 7, allows embedding of 3-dimensional graphic objects, such as CAD models or 3D scientific data, and lets the user interactively manipulate them. At time of writing this documentation, the only supported file format is U3D~\cite{3diforg}, and only one commercial software~\cite{dexp} for exporting into U3D format, yet from a number of CAD and 3D vector formats, including DXF and VRML, was known. Nevertheless, a try-out version of~\cite{dexp} can be downloaded from the Web site.
 
-Selection of the `\verb+3D+' package option enables the 3D feature. Most of the command options listed in section~\ref{usrif} do what they are supposed to do in the case of embedded 3D as well. Other options are ignored, in particular `\verb+repeat+', `\verb+palindrome+', `\verb+startat+', `\verb+endat+', `\verb+rate+' and `\verb+volume+', because they do not make sense and `\verb+mouse+', because 3D objects are interactive by definition. Options `\verb+inline=false+' and `\verb+url+' are supported, but imply option `{\tt{}externalview\-er}', because the 3D Reader plugin handles embedded files only.
+Selection of the `\verb+3D+' package option enables the 3D feature. Most of the command options listed in section~\ref{usrif} do what they are supposed to do in the case of embedded 3D as well. Other options are ignored, in particular `\verb+repeat+', `\verb+palindrome+', `\verb+startat+', `\verb+endat+', `\verb+rate+' and `\verb+volume+', because they do not make sense and `\verb+mouse+', because 3D objects are interactive by definition. Options `\verb+inline=false+' and `\verb+url+' are supported, but imply option `{\tt{}externalview\-er}', because the 3D Reader plug-in handles embedded files only.
 
 There are a few options to \verb+\includemovie+ which define how the 3D object is positioned within the viewport of a virtual camera, or conversely, how the virtual camera is positioned and oriented within a coordinate system, called `The World', which bears the 3D object at a fixed position. Fig.~\ref{3dscene} should help to visualize the scenery: The virtual camera is orbiting at a distance of $ROO$ around the centre of orbit, specified by the position vector $\overrightarrow{COO}$; $\sphericalangle AAC$ is the camera's aperture angle. In addition, the direction vector $\overrightarrow{C2C}$ is needed to specify the initial camera position.
 \begin{figure}[ht]
@@ -226,7 +230,7 @@ There are a few options to \verb+\includemovie+ which define how the 3D object i
   \caption{Camera and 3D object in the World System $XYZ$; centre of orbit position vector $\vec{COO}$, centre of orbit to camera direction vector $\vec{C2C}$, radius of orbit $ROO$, aperture angle of camera $\sphericalangle AAC$.}\label{3dscene}
 \end{figure}
 
-The \emph{default view}, i. e. the view that is shown initially after activating the 3D object in the Reader, can be set using the options `\verb+3Dcoo+' for the centre of orbit, `\verb+3Dc2c+' for the centre of orbit to camera vector, `\verb+3Droo+' for the orbital radius and `\verb+3Daac+' for the aperture angle of the camera:
+The \emph{default view}, i.\,e. the view that is shown initially after activating the 3D object in the Reader, can be set using the options `\verb+3Dcoo+' for the centre of orbit, `\verb+3Dc2c+' for the centre of orbit to camera vector, `\verb+3Droo+' for the orbital radius and `\verb+3Daac+' for the aperture angle of the camera:
 \begin{verbatim}
 3Daac=<angle>
 \end{verbatim}
@@ -239,7 +243,6 @@ This option sets the aperture angle of the camera, measured in degrees. Fixed po
 to\\
 \phantom{xxxx}$+999999999999999999.999999999999999999$\\[1ex]
 are allowed.
-%Note that views with \emph{very small but larger than zero} inclination angles relative to the world axes \emph{may} lead to broken 3D inclusions when going the {\tt latex} $\rightarrow$ {\tt dvips} $\rightarrow$ {\tt ps2pdf} route. If this happens chances are great that a Ghostscript version prior to 8.53 has been used for PS to PDF conversion. This issue has been resolved since version 8.53.
 \begin{verbatim}
 3Dcoo=<x> <y> <z>
 \end{verbatim}
@@ -255,7 +258,7 @@ Thus, in order to get a `front view' of the 3D object it is sufficient to gradua
 
 Ideally, there should be no need for changing the default setting of \verb+3Dcoo=0 0 0+ for the centre of orbit. However, this requires that the 3D object or group of objects be centred around the world origin $(0,0,0)$ during file export into U3D format. (This is the default setting with~\cite{dexp}.) If the 3D object apparently pivots around an orbital centre that lies outside of the object's cubature, either the file export could be repeated with appropriate settings or the centre of orbit could be moved into the object centre using the `\verb+3Dcoo+' option. Regarding the latter method, this can be easily achieved if the object is examined from two different directions, say from left (\verb+3Dc2c=-1 0 0+) in order to adjust the \verb+<y>+ and \verb+<z>+ coordinates of `\verb+3Dcoo+' and from front (\verb+3Dc2c=0 -1 0+) in order to adjust the remaining \verb+<x>+ coordinate.
 
-Alternatively, good values for the `\verb+3Droo+' and `\verb+3Dcoo+' options can be found easily by temporarily inserting a hyperlink using the \verb+\movieref+ command together with the `\verb+3Dcalculate+' option. See section \ref{hyperlinks} for an explanantion and example \ref{ex3d} in section \ref{examples}. 
+Alternatively, good values for the `\verb+3Droo+' and `\verb+3Dcoo+' options can be found easily by temporarily inserting a hyperlink using the \verb+\movieref+ command together with the `\verb+3Dcalculate+' option. See section \ref{hyperlinks} for an explanation and example \ref{ex3d} in section \ref{examples}.
 
 \begin{verbatim}
 3Dviews=<views file>
@@ -264,7 +267,7 @@ Instead of or in addition to the default view, further \emph{named views} can be
 \begin{verbatim}
 [<name>]{<coo_x> <coo_y> <coo_z>}{<c2c_x> <c2c_y> <c2c_z>}{<roo>}{<aac>}
 \end{verbatim}
-The \verb+<name>+ entry is optional. If \verb+<name>+ is not given, a default name consisting of `View' followed by the number of the current entry in the list is formed. For \verb+<coo_x>+, \verb+<coo_y>+, \verb+<coo_z>+, \verb+<c2c_x>+, \verb+<c2c_y>+, \verb+<c2c_z>+, \verb+<roo>+ and \verb+<aac>+ the same rules as for the corresponding options `\verb+3Dcoo+', `\verb+3Dc2c+', `\verb+3Droo+' and `\verb+3Daac+' apply. Trailing whitespace or comment signs (\%) are allowed. Reading of the file stops either at its end, at the first empty line encountered or at the first line containing nothing but whitespace and/or a comment sign followed by arbitrary stuff.
+The \verb+<name>+ entry is optional. If \verb+<name>+ is not given, a default name consisting of `View' followed by the number of the current entry in the list is formed. For \verb+<coo_x>+, \verb+<coo_y>+, \verb+<coo_z>+, \verb+<c2c_x>+, \verb+<c2c_y>+, \verb+<c2c_z>+, \verb+<roo>+ and \verb+<aac>+ the same rules as for the corresponding options `\verb+3Dcoo+', `\verb+3Dc2c+', `\verb+3Droo+' and `\verb+3Daac+' apply. Trailing spaces or comment signs (\%) are allowed. Reading of the file stops either at its end, at the first empty line encountered or at the first line containing nothing but spaces and/or a comment sign followed by arbitrary stuff.
 
 \begin{verbatim}
 3Dbg=<r> <g> <b>
@@ -272,9 +275,9 @@ The \verb+<name>+ entry is optional. If \verb+<name>+ is not given, a default na
 This option sets the background colour of the canvas. Only fixed point real numbers in the range from 0 to 1 are allowed for the colour components.
 
 \begin{verbatim}
-3Djscript=<JavaScipt file>
+3Djscript=<JavaScript file>
 \end{verbatim}
-Things like animation, lighting, background colour etc. may also be script driven. Option `\verb+3Djscript+' associates a \verb+<JavaScipt file>+ with the 3D object. The script will be executed upon activation of the object. Refer to the Acrobat 3D JavaScript Reference~\cite{jscript3D} for details.
+Things like animation, lighting, background colour etc. may also be script driven. Option `\verb+3Djscript+' associates a \verb+<JavaScript file>+ with the 3D object. The script will be executed upon activation of the object. Refer to the Acrobat 3D JavaScript Reference~\cite{jscript3D} for details.
 
 \subsection{Media hyperlinks}\label{hyperlinks}
 A movie, sound or 3D object may serve as the destination of hyperlinks, which are inserted into the document using the command
@@ -330,12 +333,12 @@ Instead of referencing an existing view of the 3D object, a new one can be defin
 \begin{verbatim}
 3Dcalculate[=<aac angle>]
 \end{verbatim}
-Creates a link for calculating `\verb+3Droo+' and `\verb+3Dcoo+' settings of the virtual camera. Clicking the link opens a dialog box from which the settings can be copied to the clipboard for later insertion into the option list of \verb+\includemovie+. The default aperture angle of $30$\textdegree{} is used for the calculation unless an optional \verb+<aac angle>+ has been provided.
+Creates a link for calculating `\verb+3Droo+' and `\verb+3Dcoo+' settings of the virtual camera. Clicking the link opens a dialogue box from which the settings can be copied to the clipboard for later insertion into the option list of \verb+\includemovie+. The default aperture angle of $30$\textdegree{} is used for the calculation unless an optional \verb+<aac angle>+ has been provided.
 
 \begin{verbatim}
-3Djscript=<JavaScipt file>
+3Djscript=<JavaScript file>
 \end{verbatim}
-Runs the script \verb+<JavaScipt file>+ after clicking the link. Unlike the script that has been associated with the 3D annotation during object embedding, this JavaScript is not directly run by the JavaScript engine of the 3D plugin, but is run by Acrobat's own scripting engine. However, full access to the API of the 3D script engine is provided through the `\verb+context3D+' property of the `\verb+Annot3D+' object. For convenience, an associative array `\verb+annot3D+' has been provided for use within \verb+<JavaScipt file>+, in order to easily access the `\verb+Annot3D+' object of the annotation the enclosing link is pointing to. The particular element of the array is referenced by the annotation's label \verb+<label spec>+, enclosed in quotation marks. As an example, the `\verb+scene+' object can be referenced within \verb+<JavaScipt file>+ by
+Runs the script \verb+<JavaScript file>+ after clicking the link. Unlike the script that has been associated with the 3D annotation during object embedding, this JavaScript is not directly run by the JavaScript engine of the 3D plug-in, but is run by Acrobat's own scripting engine. However, full access to the API of the 3D script engine is provided through the `\verb+context3D+' property of the `\verb+Annot3D+' object. For convenience, an associative array `\verb+annot3D+' has been provided for use within \verb+<JavaScript file>+, in order to easily access the `\verb+Annot3D+' object of the annotation the enclosing link is pointing to. The particular element of the array is referenced by the annotation's label \verb+<label spec>+, enclosed in quotation marks. As an example, the `\verb+scene+' object can be referenced within \verb+<JavaScript file>+ by
 \begin{verbatim}
   annot3D["<label spec>"].context3D.scene
 \end{verbatim}
@@ -349,7 +352,7 @@ Two user commands have been provided that make `movie15' a replacement for the `
 \begin{verbatim}
   \hyperlinkmovie[<options>]{<label spec>}{<text>}
 \end{verbatim}
-All of the optional arguments to \verb+\includemovie+ and \verb+\movieref+ can be used with the compatibility macros as well. In addition, they honor the following options:
+All of the optional arguments to \verb+\includemovie+ and \verb+\movieref+ can be used with the compatibility macros as well. In addition, they honour the following options:
 \begin{verbatim}
 height=<height of display>
 width=<width of display>
@@ -380,7 +383,7 @@ duration=<duration in seconds>s
 \end{verbatim}
 The duration of the media segment to be played. The trailing `\verb+s+' is mandatory. Note that `\verb+duration+' cannot be used together with option `\verb+startat+' from \verb+\includemovie+. In order to define a media segment options can be combined as follows: `\verb+startat+'/`\verb+endat+', `\verb+start+'/`\verb+endat+', `\verb+start+'/`\verb+duration+'.
 
-%\newpage
+\newpage
 \section{Examples}\label{examples}
 \begin{enumerate}
 \item A short circular MPEG movie, taken from \href{http://www.linux-video.net/Samples/}{\tt http://www.linux-video.net/} \href{http://www.linux-video.net/Samples/}{\tt Samples/}
@@ -406,7 +409,7 @@ The duration of the media segment to be played. The trailing `\verb+s+' is manda
 \end{minipage}
 
 %\enlargethispage{15ex}\thispagestyle{empty}
-\item Another MPEG movie, loaded on the fly from \href{http://www.linux-video.net/Samples/}{\tt http://www.linux-video} \href{http://www.linux-video.net/Samples/}{\tt .net/Samples/}. Hence, a working Internet connection is required. This time, we force the QuickTime plugin to be used instead of MediaPlayer (Windows boxes only). Well, the latter seems to be bugged. Quod erat expectandum.
+\item Another MPEG movie, loaded on the fly from \href{http://www.linux-video.net/Samples/}{\tt http://www.linux-video} \href{http://www.linux-video.net/Samples/}{\tt .net/Samples/}. Hence, a working Internet connection is required. This time, we force the QuickTime plug-in to be used instead of MediaPlayer (Windows boxes only). Well, the latter seems to be bugged. Quod erat expectandum.
 
 \begin{minipage}{0.5\linewidth}
 {\tt%