CTAN sync 202109210302

4 files changed, 568 insertions, 0 deletions

diff --git a/macros/luatex/generic/pdfextra/examples/pdfextra-example-latex.tex b/macros/luatex/generic/pdfextra/examples/pdfextra-example-latex.tex
new file mode 100644
index 0000000000..dc5a31f9f1
--- /dev/null
+++ b/macros/luatex/generic/pdfextra/examples/pdfextra-example-latex.tex
@@ -0,0 +1,223 @@
+% Compiled with:
+% env TEXMFDOTDIR='..//:~/src/texlive/texmf-dist/source/latex/media9/files/' lualatex pdfextra-example-latex.tex
+\documentclass{article}
+
+\usepackage{hyperref}
+\usepackage{xcolor}
+\usepackage{graphicx}
+\usepackage{pdfextra}
+\sdef{_linkcolor}{\color{blue}}
+
+\begin{document}
+
+% Using document level JavaScript we can run initialization code right at the
+% start (this is more flexible than \openaction).
+\dljavascript[random]{
+  function getRandomNumber() {
+      return 4; % chosen by fair dice roll, ![https://xkcd.com/221/]
+  }
+  console.println("initialized with seed " + getRandomNumber());
+}
+
+
+
+% For external references we need to `\filedef` "external" and "url" files
+% beforehand:
+\filedef/u[doc-internet]{http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf}
+\filedef/x[doc-local]{optex-doc.pdf}
+
+% We then try to reference them using external references:
+\hlink[extref:doc-internet:ref:langphrases]{OpTeX documentation, section ``Multilingual phrases and quotation marks''.}
+\hlink[extpgref:doc-internet:12]{OpTeX documentation, page 12.}
+
+
+
+% Insert a video twice with different settings:
+\filedef/e[video]{example-movie.mp4}
+% Insert video into page using Renditions mechanism with controls and autoplay.
+\render[video][
+  controls=true,
+  aactions=\renditionautoplay,
+]{\includegraphics[width=\textwidth]{example-image.pdf}}
+
+% We set red text color, blue border (RGB triplet) for "rendition" links.
+\sdef{_renditionlinkcolor}{\color{red}}
+\sdef{_renditionborder}{0 1 0}
+% Then we add some buttons.
+\hlink[rendition::play]{play} \hlink[rendition::pause]{pause}
+\hlink[rendition::stop]{stop} \hlink[rendition::resume]{resume}
+
+% Render the same file again, but with different dimensions, no controls
+% and explicit activation.
+\render[video]{\includegraphics{example-image.pdf}}
+% This one can't have buttons, because it doesn't have its own name -- "video"
+% is used by the previous one.
+
+
+
+% Add already embedded video to the list of attachments shown in user
+% interface.
+\attach[video]
+
+
+% We are done for this page, who not go to the next one?
+%
+% \hlink typesets in group, so we locally disable lining links (our button is
+% bigger than normal line)
+\hlink[named:NextPage]{\nolininglinks\scalebox{2}[2]{NEXT PAGE}}
+
+
+
+\clearpage
+
+
+
+% Deliver fresh random number to everyone who sees this page using "page open"
+% ("O") trigger event of page's actions.
+\pageactions[
+  {O} {js:{app.alert("Random number for you is " + getRandomNumber());}}
+]
+
+
+% Link to previous page (predefined PDF action) with "Split" transition:
+\hlink[named:PrevPage, transition:Split]{Go to previous page (with transition).}
+
+
+
+\clearpage
+
+% A 3D Rich Media annotation with a custom view and script follows:
+
+% First we define the 3D file, so we can use same name for the view and have it
+% auto included.
+\filedef/e[example]{pdfextra-example-part.prc}
+
+% Then a simplistic "front" view.
+\DDDview[example][
+  projection=ortho,
+  roo=400,
+]
+
+% A 3D JavaScript script that will define function to use with action button.
+% (we write the script only now, so we don't have to carry around an extra file
+% in the package, you would normally have the contents in the file -- "turn.js"
+% in this case).
+\newwrite\js
+\immediate\openout\js=turn.js
+% rotate every node by angle degrees along $x$ axis
+\immediate\write\js{\detokenize{
+function turn(angle) {
+    angle = angle * Math.PI / 180;
+    for (var i = 0; i < scene.nodes.count; i++) {
+        var node = scene.nodes.getByIndex(i);
+	node.transform.rotateAboutXInPlace(angle);
+    }
+}
+}}
+\closeout\js
+
+% The annotation itself, with our script above.
+\RM[example][
+  activation=auto,
+  scripts=turn.js,
+]{\textcolor{white}{\vrule width\textwidth height\textwidth}}
+
+\hlink[js:\DDDcontext{example}.turn(10);]{Turn by 10 degrees along $x$ axis.}\par
+\hlink[js:\DDDcontext{example}.turn(30);]{Turn by 30 degrees along $x$ axis.}\par
+\hlink[js:\DDDcontext{example}.turn(90);]{Turn by 90 degrees along $x$ axis.}
+
+
+
+\clearpage
+
+
+% Here is the "epix" 3D model example from media9 documentation ported to
+% pdfextra.
+%
+% First we define a view with the same name as the future Rich Media
+% annotation. This view will then automatically be used if no `views` key is
+% specified. No need to be excessive with decimal numbers.
+\DDDview[epix][
+  FOV=30,
+  c2c=4 2 3,
+  coo=4.41 2.19 0,
+  roo=430,
+]
+
+% 3Dmenu is used often, lets use shortcut instead.
+\filedef/e[3dmenu]{3Dmenu.js}
+% We want to use the nice "epix" name for the view and annotation.
+\filedef/e[epix]{epix.prc}
+
+% Just to spice things up, we diverge a bit from media9 and define custom
+% background color. We can't use LaTeX's colors, so we use RGB triplet.
+\newcommand{\GreyBG}{0.9 0.9 0.9}
+
+% Define the 3D Rich Media annotation. One view is automatically detected from
+% name ("epix"). Scripts will run in specified order at initialization time
+% (when the annotation is activated).
+\RM[epix][
+  scripts={
+    asylabels.js,
+    3Dspintool.js,
+    3dmenu,
+  },
+  background=\GreyBG,
+]{\includegraphics[width=0.8\textwidth, height=0.8\textwidth]{epixposter.pdf}}
+
+
+
+\clearpage
+
+
+
+% Second media9 example is "dice" it has a lot of views, but they are simple.
+% This time we can't use the view name deduction from `\RM` name -- there is
+% more than one view.
+\DDDview[Front][roo=27]
+\DDDview[Back][roo=27, c2c=0 1 0]
+\DDDview[Left][roo=27, c2c=-1 0 0]
+\DDDview[Right][roo=27, c2c=1 0 0]
+\DDDview[Top][roo=27, c2c=0 0 1]
+\DDDview[Bottom][roo=27, c2c=0 0 -1]
+\DDDview[Fish Eye at Centre][fov=120]
+
+% We want to use all the defined views, as well as autoactivate the annotation.
+% This means that the preview mostly sets dimensions, because it will not be
+% shown much. (Only in viewers that don't support 3D Rich Media -- that is, all
+% except Acrobat).
+\RM[dice.u3d][
+  views={Front, Back, Left, Right, Top, Bottom, Fish Eye at Centre},
+  activation=auto,
+  scripts=3dmenu,
+]{\textcolor{red}{\vrule height.5\textwidth width.5\textwidth}}
+
+% A few buttons for switching views.
+\hlink[goto3dview::/N]{\frame{Next view}}
+\hlink[goto3dview::(Back)]{\frame{View ``Back''}}
+\hlink[goto3dview::5]{\frame{6th view in the list}}
+
+\clearpage
+
+
+% Last media9 example ported. It has its own JavaScript file for animation,
+% which can be customized at runtime using JavaScript actions that access 3D
+% context of the annotation.
+\filedef/e[malte]{malte.u3d}
+\DDDview[malte][c2c=1 1 1, roo=0.25]
+\RM[malte][
+  activation=auto,
+  scripts={3dmenu, malte.js},
+]{\textcolor{blue}{\vrule height 0.5\textwidth width 0.5\textwidth}}
+
+% Normal JavaScript actions, but we access functions defined globaly in the 3D
+% JavaScript context of "malte" Rich Media annotation.
+\hlink[js:\DDDcontext{malte}.cntrClockWise();]  {\includegraphics[height=1.44em]{boutona.pdf}}
+\hlink[js:\DDDcontext{malte}.pause();]          {\includegraphics[height=1.44em]{boutonb.pdf}}
+\hlink[js:\DDDcontext{malte}.clockWise();]      {\includegraphics[height=1.44em]{boutonc.pdf}}
+\hlink[js:\DDDcontext{malte}.scaleSpeed(1/1.1);]{\includegraphics[height=1.44em]{boutond.pdf}}
+\hlink[js:\DDDcontext{malte}.origSpeed();]      {\includegraphics[height=1.44em]{boutone.pdf}}
+\hlink[js:\DDDcontext{malte}.scaleSpeed(1.1);]  {\includegraphics[height=1.44em]{boutonf.pdf}}
+
+
+\end{document}
diff --git a/macros/luatex/generic/pdfextra/examples/pdfextra-example-part.prc b/macros/luatex/generic/pdfextra/examples/pdfextra-example-part.prc
new file mode 100644
index 0000000000..812479dcbb
--- /dev/null
+++ b/macros/luatex/generic/pdfextra/examples/pdfextra-example-part.prc
diff --git a/macros/luatex/generic/pdfextra/examples/pdfextra-example.pdf b/macros/luatex/generic/pdfextra/examples/pdfextra-example.pdf
new file mode 100644
index 0000000000..24ca714a75
--- /dev/null
+++ b/macros/luatex/generic/pdfextra/examples/pdfextra-example.pdf
diff --git a/macros/luatex/generic/pdfextra/examples/pdfextra-example.tex b/macros/luatex/generic/pdfextra/examples/pdfextra-example.tex
new file mode 100644
index 0000000000..6704ac4b98
--- /dev/null
+++ b/macros/luatex/generic/pdfextra/examples/pdfextra-example.tex
@@ -0,0 +1,345 @@
+% PDFextra example file.
+% This file, apart from other topics, shows how to port 3D examples from media9
+% (https://ctan.org/pkg/media9) documentation. You probably have to adjust path
+% searching to succesfully compile this example, e.g.:
+%
+% \begtt
+% env TEXMFDOTDIR=.:~/src/texlive/texmf-dist/source/latex/media9/files/ optex pdfextra-example.tex
+% \endtt
+
+% Basic \OpTeX/ settings:
+\enlang\enquotes
+\fontfam[lm]
+
+% Load the package from standard search path:
+\load[pdfextra]
+
+% Before using \hlink we must activate hyperlinks:
+\hyperlinks\Blue\Green
+
+% Maybe we want to greet the user and jump to page 2 right at the start?
+\openaction[
+  js:{%
+    app.alert("Javascript alert, open action");
+    console.println("printing to console from openaction");},
+  pg:2,
+]
+
+
+
+% Using document level JavaScript we can run initialization code right at the
+% start (this is more flexible than \openaction).
+\dljavascript[random]{
+  function getRandomNumber() {
+      return 4; % chosen by fair dice roll, ![https://xkcd.com/221/]
+  }
+  console.println("initialized with seed " + getRandomNumber());
+}
+
+
+
+% For external references we need to `\filedef` "external" and "url" files
+% beforehand:
+\filedef/u[doc-internet]{http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf}
+\filedef/x[doc-local]{optex-doc.pdf}
+
+% We then try to reference them using external references:
+\hlink[extref:doc-internet:ref:langphrases]{OpTeX documentation, section \"Multilingual phrases and quotation marks".}
+\hlink[extpgref:doc-internet:12]{OpTeX documentation, page 12.}
+
+
+
+% Insert a video twice with different settings:
+\filedef/e[video]{example-movie.mp4}
+% Insert video into page using Renditions mechanism with controls and autoplay.
+\render[video][
+  controls=true,
+  aactions=\renditionautoplay,
+]{\picwidth=\hsize \inspic{example-image.pdf}}
+
+% We set red text color, blue border (RGB triplet) for "rendition" links.
+\let\_renditionlinkcolor\Red
+\def\_renditionborder{0 1 0}
+% Then we add some buttons.
+\hlink[rendition::play]{play} \hlink[rendition::pause]{pause}
+\hlink[rendition::stop]{stop} \hlink[rendition::resume]{resume}
+
+% Render the same file again, but with different dimensions, no controls
+% and explicit activation.
+\render[video]{\inspic{example-image.pdf}}
+% This one can't have buttons, because it doesn't have its own name -- "video"
+% is used by the previous one.
+
+
+
+% Add already embedded video to the list of attachments shown in user
+% interface.
+\attach[video]
+
+
+% We are done for this page, who not go to the next one?
+%
+% \hlink typesets in group, so we locally disable lining links (our button is
+% bigger than normal line)
+\hlink[named:NextPage]{\nolininglinks\typoscale[2000/2000]\inoval{NEXT PAGE}}
+
+
+
+\vfil\break
+
+
+
+% Deliver fresh random number to everyone who sees this page using "page open"
+% ("O") trigger event of page's actions.
+\pageactions[
+  {O} {js:{app.alert("Random number for you is " + getRandomNumber());}}
+]
+
+% Link to OpTeX's page reference ("pg:1") with "Split" transition:
+\hlink[pg:1, transition:Split]{Go to previous page (with transition).}
+
+
+
+\vfil\break
+
+% A 3D Rich Media annotation with a custom view and script follows:
+
+% First we define the 3D file, so we can use same name for the view and have it
+% auto included.
+\filedef/e[example]{pdfextra-example-part.prc}
+
+% Then a simplistic "front" view.
+\DDDview[example][
+  projection=ortho,
+  roo=400,
+]
+
+% A 3D JavaScript script that will define function to use with action button.
+% (we write the script only now, so we don't have to carry around an extra file
+% in the package, you would normally have the contents in the file -- "turn.js"
+% in this case).
+\newwrite\js
+\immediate\openout\js=turn.js
+% rotate every node by angle degrees along $x$ axis
+\immediate\write\js{\detokenize{
+function turn(angle) {
+    angle = angle * Math.PI / 180;
+    for (var i = 0; i < scene.nodes.count; i++) {
+        var node = scene.nodes.getByIndex(i);
+	node.transform.rotateAboutXInPlace(angle);
+    }
+}
+}}
+\closeout\js
+
+% The annotation itself, with our script above.
+\RM[example][
+  activation=auto,
+  scripts=turn.js,
+]{\White\vrule width\hsize height\hsize}
+
+\hlink[js:\DDDcontext{example}.turn(10);]{Turn by 10 degrees along $x$ axis.}\par
+\hlink[js:\DDDcontext{example}.turn(30);]{Turn by 30 degrees along $x$ axis.}\par
+\hlink[js:\DDDcontext{example}.turn(90);]{Turn by 90 degrees along $x$ axis.}
+
+
+
+\vfil\break
+
+
+% Here is the "epix" 3D model example from media9 documentation ported to
+% pdfextra.
+%
+% First we define a view with the same name as the future Rich Media
+% annotation. This view will then automatically be used if no `views` key is
+% specified. No need to be excessive with decimal numbers.
+\DDDview[epix][
+  FOV=30,
+  c2c=4 2 3,
+  coo=4.41 2.19 0,
+  roo=430,
+]
+
+% 3Dmenu is used often, lets use shortcut instead.
+\filedef/e[3dmenu]{3Dmenu.js}
+% We want to use the nice "epix" name for the view and annotation.
+\filedef/e[epix]{epix.prc}
+
+% Just to spice things up, we diverge a bit from media9 and define custom
+% background color.
+\colordef\GreyBG{0.1\Black}
+
+% Define the 3D Rich Media annotation. One view is automatically detected from
+% name ("epix"). Scripts will run in specified order at initialization time
+% (when the annotation is activated).
+\RM[epix][
+  scripts={
+    asylabels.js,
+    3Dspintool.js,
+    3dmenu,
+  },
+  background=\GreyBG,
+]{\picwidth=0.8\hsize \picheight=0.8\hsize \inspic{epixposter.pdf}}
+
+
+
+\vfil\break
+
+
+
+% Second media9 example is "dice" it has a lot of views, but they are simple.
+% This time we can't use the view name deduction from `\RM` name -- there is
+% more than one view.
+\DDDview[Front][roo=27]
+\DDDview[Back][roo=27, c2c=0 1 0]
+\DDDview[Left][roo=27, c2c=-1 0 0]
+\DDDview[Right][roo=27, c2c=1 0 0]
+\DDDview[Top][roo=27, c2c=0 0 1]
+\DDDview[Bottom][roo=27, c2c=0 0 -1]
+\DDDview[Fish Eye at Centre][fov=120]
+
+% We want to use all the defined views, as well as autoactivate the annotation.
+% This means that the preview mostly sets dimensions, because it will not be
+% shown much. (Only in viewers that don't support 3D Rich Media -- that is, all
+% except Acrobat).
+\RM[dice.u3d][
+  views={Front, Back, Left, Right, Top, Bottom, Fish Eye at Centre},
+  activation=auto,
+  scripts=3dmenu,
+]{\Red \vrule height.5\hsize width.5\hsize}
+
+% A few buttons for switching views.
+\hlink[goto3dview::/N]{\frame{Next view}}
+\hlink[goto3dview::(Back)]{\frame{View \"Back"}}
+\hlink[goto3dview::5]{\frame{6th view in the list}}
+
+\vfil\break
+
+
+% Last media9 example ported. It has its own JavaScript file for animation,
+% which can be customized at runtime using JavaScript actions that access 3D
+% context of the annotation.
+\filedef/e[malte]{malte.u3d}
+\DDDview[malte][c2c=1 1 1, roo=0.25]
+\RM[malte][
+  activation=auto,
+  scripts={3dmenu, malte.js},
+]{\Blue \vrule height.5\hsize width0.5\hsize}
+
+{\picheight=1.44em
+% Normal JavaScript actions, but we access functions defined globaly in the 3D
+% JavaScript context of "malte" Rich Media annotation.
+\hlink[js:\DDDcontext{malte}.cntrClockWise();]{\inspic{boutona.pdf}}
+\hlink[js:\DDDcontext{malte}.pause();]{\inspic{boutonb.pdf}}
+\hlink[js:\DDDcontext{malte}.clockWise();]{\inspic{boutonc.pdf}}
+\hlink[js:\DDDcontext{malte}.scaleSpeed(1/1.1);]{\inspic{boutond.pdf}}
+\hlink[js:\DDDcontext{malte}.origSpeed();]{\inspic{boutone.pdf}}
+\hlink[js:\DDDcontext{malte}.scaleSpeed(1.1);]{\inspic{boutonf.pdf}}
+}
+
+
+\vfil\break
+
+
+% Lastly a showcase of transitions / page durations in \OpTeX/ slideshow.
+% Because transitions are displayed only in fullscreen mode, we could request
+% it by using `\fullscreen`. But we have more pages before this, so we didn't.
+
+% We just turn the rest of the document into slideshow.
+\slides
+\slideshow
+% To see the transitions better, we color each page with a background color.
+\global\pgbackground={\bgcolor \hrule height\pdfpageheight width\pdfpagewidth}
+\glet\bgcolor=\Yellow
+
+% Transitions on all pages where it is not said otherwise will be of type
+% "Wipe" and be 1 second long.
+\transitions[Wipe:1]
+
+% The slides will by default be shown for 3 seconds before advancing to the
+% next one.
+\defaultpageduration[3]
+% But the first slide has override to only be shown for 1 second.
+\pageduration[1]
+
+\tit Presentation
+
+\subtit Transistions and durations
+
+\pg;
+\glet\bgcolor=\Red
+% All transitions are defined on the page object and they are shown when we go
+% to that page. That means that we probably didn't see the "Wipe:1" animation
+% of the first slide, because we already were there. However, this second slide
+% with "Fade" is now shown correctly. (The first one also will, when we go
+% back to it.)
+\transition[Fade]
+
+\sec First slide
+
+Some\pg+
+% In a slideshow, by using \pg+ we are on a new PDF page with independently set
+% transition/duration. We can use this to disable page durations -- we have
+% seen the "single page override" in action on previous page, and the default
+% duration on this "page".
+\defaultpageduration[]
+
+% Also apply a long transition on this "page"/"slide"/"subslide".
+\transition[Dissolve:4]
+
+% More uses of currently set default values follow.
+text\pg+
+
+to\pg+
+
+test\pg+
+
+slideshow
+
+\pg;
+% Now show different transitions on differently colored pages:
+\glet\bgcolor=\Green
+\transition[Split:3:/Dm /V /M /I]
+
+\sec Second slide
+
+\transitions[Blinds:2]
+
+more\pg+
+
+text
+
+\transitions[Wipe]
+
+\pg;
+\glet\bgcolor=\Brown
+\transition[Dissolve]
+
+\sec Third slide
+
+\pg;
+\glet\bgcolor=\Red
+\transition[Box]
+
+\sec More
+
+\pg;
+\glet\bgcolor=\Yellow
+
+\sec slides
+
+\pg;
+\glet\bgcolor=\Red
+
+\sec using
+
+\pg;
+\glet\bgcolor=\Yellow
+
+\sec default transition
+
+bye\pg+
+
+bye
+
+\bye