From aeb7b734f147a5da64140d20aabf275f98398d4a Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 14 May 2021 21:30:55 +0000 Subject: optex/base vs. optex/pdfextra git-svn-id: svn://tug.org/texlive/trunk@59201 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/pdfextra/LICENSE | 12 - Master/texmf-dist/doc/latex/pdfextra/README.md | 35 - .../pdfextra/examples/pdfextra-example-part.prc | Bin 58592 -> 0 bytes .../latex/pdfextra/examples/pdfextra-example.pdf | Bin 385845 -> 0 bytes .../latex/pdfextra/examples/pdfextra-example.tex | 341 ---- .../texmf-dist/doc/latex/pdfextra/pdfextra-doc.pdf | Bin 230095 -> 0 bytes .../texmf-dist/doc/latex/pdfextra/pdfextra-doc.tex | 684 ------- Master/texmf-dist/doc/optex/README | 131 -- Master/texmf-dist/doc/optex/base/README | 131 ++ Master/texmf-dist/doc/optex/base/omls.tex | 832 ++++++++ Master/texmf-dist/doc/optex/base/optex-doc.pdf | Bin 0 -> 1405606 bytes Master/texmf-dist/doc/optex/base/optex-doc.tex | 114 ++ Master/texmf-dist/doc/optex/base/optex-math.tex | 1665 ++++++++++++++++ Master/texmf-dist/doc/optex/base/optex-techdoc.tex | 290 +++ Master/texmf-dist/doc/optex/base/optex-userdoc.tex | 2042 ++++++++++++++++++++ Master/texmf-dist/doc/optex/omls.tex | 832 -------- Master/texmf-dist/doc/optex/optex-doc.pdf | Bin 1405606 -> 0 bytes Master/texmf-dist/doc/optex/optex-doc.tex | 114 -- Master/texmf-dist/doc/optex/optex-math.tex | 1665 ---------------- Master/texmf-dist/doc/optex/optex-techdoc.tex | 290 --- Master/texmf-dist/doc/optex/optex-userdoc.tex | 2042 -------------------- Master/texmf-dist/doc/optex/pdfextra/LICENSE | 12 + Master/texmf-dist/doc/optex/pdfextra/README.md | 35 + .../pdfextra/examples/pdfextra-example-part.prc | Bin 0 -> 58592 bytes .../optex/pdfextra/examples/pdfextra-example.pdf | Bin 0 -> 385845 bytes .../optex/pdfextra/examples/pdfextra-example.tex | 341 ++++ .../texmf-dist/doc/optex/pdfextra/pdfextra-doc.pdf | Bin 0 -> 230095 bytes .../texmf-dist/doc/optex/pdfextra/pdfextra-doc.tex | 684 +++++++ 28 files changed, 6146 insertions(+), 6146 deletions(-) delete mode 100644 Master/texmf-dist/doc/latex/pdfextra/LICENSE delete mode 100644 Master/texmf-dist/doc/latex/pdfextra/README.md delete mode 100644 Master/texmf-dist/doc/latex/pdfextra/examples/pdfextra-example-part.prc delete mode 100644 Master/texmf-dist/doc/latex/pdfextra/examples/pdfextra-example.pdf delete mode 100644 Master/texmf-dist/doc/latex/pdfextra/examples/pdfextra-example.tex delete mode 100644 Master/texmf-dist/doc/latex/pdfextra/pdfextra-doc.pdf delete mode 100644 Master/texmf-dist/doc/latex/pdfextra/pdfextra-doc.tex delete mode 100644 Master/texmf-dist/doc/optex/README create mode 100644 Master/texmf-dist/doc/optex/base/README create mode 100644 Master/texmf-dist/doc/optex/base/omls.tex create mode 100644 Master/texmf-dist/doc/optex/base/optex-doc.pdf create mode 100644 Master/texmf-dist/doc/optex/base/optex-doc.tex create mode 100644 Master/texmf-dist/doc/optex/base/optex-math.tex create mode 100644 Master/texmf-dist/doc/optex/base/optex-techdoc.tex create mode 100644 Master/texmf-dist/doc/optex/base/optex-userdoc.tex delete mode 100644 Master/texmf-dist/doc/optex/omls.tex delete mode 100644 Master/texmf-dist/doc/optex/optex-doc.pdf delete mode 100644 Master/texmf-dist/doc/optex/optex-doc.tex delete mode 100644 Master/texmf-dist/doc/optex/optex-math.tex delete mode 100644 Master/texmf-dist/doc/optex/optex-techdoc.tex delete mode 100644 Master/texmf-dist/doc/optex/optex-userdoc.tex create mode 100644 Master/texmf-dist/doc/optex/pdfextra/LICENSE create mode 100644 Master/texmf-dist/doc/optex/pdfextra/README.md create mode 100644 Master/texmf-dist/doc/optex/pdfextra/examples/pdfextra-example-part.prc create mode 100644 Master/texmf-dist/doc/optex/pdfextra/examples/pdfextra-example.pdf create mode 100644 Master/texmf-dist/doc/optex/pdfextra/examples/pdfextra-example.tex create mode 100644 Master/texmf-dist/doc/optex/pdfextra/pdfextra-doc.pdf create mode 100644 Master/texmf-dist/doc/optex/pdfextra/pdfextra-doc.tex (limited to 'Master/texmf-dist/doc') diff --git a/Master/texmf-dist/doc/latex/pdfextra/LICENSE b/Master/texmf-dist/doc/latex/pdfextra/LICENSE deleted file mode 100644 index 7468558136b..00000000000 --- a/Master/texmf-dist/doc/latex/pdfextra/LICENSE +++ /dev/null @@ -1,12 +0,0 @@ -Copyright (C) 2021 Michal Vlasák - -Permission to use, copy, modify, and/or distribute this software for any -purpose with or without fee is hereby granted. - -THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH -REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY -AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, -INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM -LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR -OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR -PERFORMANCE OF THIS SOFTWARE. diff --git a/Master/texmf-dist/doc/latex/pdfextra/README.md b/Master/texmf-dist/doc/latex/pdfextra/README.md deleted file mode 100644 index c47262b1f58..00000000000 --- a/Master/texmf-dist/doc/latex/pdfextra/README.md +++ /dev/null @@ -1,35 +0,0 @@ -# PDF Extra - -PDF Extra provides extra PDF features for OpTeX. - -As a minimalistic package OpTeX doesn't support "advanced" features of PDF file -format in the base. This third party package aims to provide them. Summary of -supported features: - - - insertion of multimedia (audio, video, 3D); - - hyperlinks and other actions, - - trigger events; - - transitions; - - attachments. - -The repository of PDF Extra is at https://github.com/vlasakm/pdfextra. - -# Documentation - -See `pdfextra-doc.pdf` for documentation. It contains user documentation as -well as technical documentation interleaved with source code. - -# Installation instructions - -Put `pdfextra.opm` where `optex` can find it. - -Or just copy paste anything you want. - -# Usage - -In OpTex do: `\load [pdfextra]`. - -# License - -This package is available under the Zero-Clause BSD license. See `LICENSE` for -more information. diff --git a/Master/texmf-dist/doc/latex/pdfextra/examples/pdfextra-example-part.prc b/Master/texmf-dist/doc/latex/pdfextra/examples/pdfextra-example-part.prc deleted file mode 100644 index 812479dcbb0..00000000000 Binary files a/Master/texmf-dist/doc/latex/pdfextra/examples/pdfextra-example-part.prc and /dev/null differ diff --git a/Master/texmf-dist/doc/latex/pdfextra/examples/pdfextra-example.pdf b/Master/texmf-dist/doc/latex/pdfextra/examples/pdfextra-example.pdf deleted file mode 100644 index abb2e9c4c5a..00000000000 Binary files a/Master/texmf-dist/doc/latex/pdfextra/examples/pdfextra-example.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/latex/pdfextra/examples/pdfextra-example.tex b/Master/texmf-dist/doc/latex/pdfextra/examples/pdfextra-example.tex deleted file mode 100644 index 6093bf7def5..00000000000 --- a/Master/texmf-dist/doc/latex/pdfextra/examples/pdfextra-example.tex +++ /dev/null @@ -1,341 +0,0 @@ -% 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] - -%\pdfobjcompresslevel=0 -%\pdfcompresslevel=0 - -% 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}} - -% Maybe add action 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" -% trigger event of page's actions -\pageactions[ - {O} {js:{app.alert("Random number for you is " + getRandomNumber());}} -] - -% "previous page" link 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) -\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` 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 turn at initialization time. -\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 deduction with same name. -\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 previews mostly sets dimensions, because it will not be -% shown much. (Except in viewers that don't support 3D Rich Media -- 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}} - -% And define the action buttons using this new custom action. -\hlink[diceview:/N]{Next view} -\hlink[diceview:(Back)]{View \"Back"} -\hlink[diceview:5]{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 -% conotext. -\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.) -\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 diff --git a/Master/texmf-dist/doc/latex/pdfextra/pdfextra-doc.pdf b/Master/texmf-dist/doc/latex/pdfextra/pdfextra-doc.pdf deleted file mode 100644 index e5a6b8e30de..00000000000 Binary files a/Master/texmf-dist/doc/latex/pdfextra/pdfextra-doc.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/latex/pdfextra/pdfextra-doc.tex b/Master/texmf-dist/doc/latex/pdfextra/pdfextra-doc.tex deleted file mode 100644 index 38f6cd97952..00000000000 --- a/Master/texmf-dist/doc/latex/pdfextra/pdfextra-doc.tex +++ /dev/null @@ -1,684 +0,0 @@ -% vim: tw=80 -\load [doc, pdfextra] -\catcode`\.=11 - -\hyperlinks\Green\Green - -% table notes (http://petr.olsak.net/optex/optex-tricks.html#tnote) -\newcount\tnotenum -\def\tnotelist{} -\def\tnote#1{\incr\tnotenum $^{\rm\_romannumeral\tnotenum}$\global\addto\tnotelist{{#1}}} -\def\tnoteprint{\typoscale[920/920]\par \tnotenum=0 - \ea\foreach\tnotelist - \do{\advance\tnotenum by1 \par $^{\rm\_romannumeral\tnotenum}$##1 }\par - \global\tnotenum=0 \gdef\tnotelist{}% -} - -% use `\hlink` instead of OpTeX `\*link` s -\protected\def\_link[#1]#2#3{\hlink[#1]{#3}} -\protected\def\_ilink[#1]#2{\hlink[#1]{#2}} -\protected\def\_ulink[#1]#2{\hlink[url:#1]{#2}} -\public \link \ilink \ulink ; - -\let\_cslinkcolor\Blue - -% allow hyperlinking of \OpTeX's control sequences (see doc.opm) -\let\_pdfextra_opdocaction\_pdfextra_urlaction -\let\_pdfextra_opdoclinkcolor\Blue -\def\_Xindex#1#2{\sdef{,#1}{}\slet{el:#1}{optexdoclink}} -\def\optexdoclink{\hlink[opdoc:\optexdocurl\#cs:\_tmpa]{\csstring\\\_tmpb}} -\def\optexdocurl{http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf} -\isfile{optex-doc.eref}\iftrue \input{optex-doc.eref}\fi - -\insertoutline{PDF extra} -\tit PDF extra -- extra PDF features for \OpTeX/ - -\hfill Version \_pdfextra_version - -\centerline{\it Michal Vlasák, 2021} -\bigskip - -\noindent -`PDFextra` is a third party package for \OpTeX/. It aims to provide access to -more advanced PDF features, which are currently not supported in \OpTeX/ -- -especially interactive and multimedia features. The development is hosted at -\url{https://github.com/vlasakm/pdfextra}. - -In the spirit of \OpTeX/ you may use these macros in any form you want. Either -by installing this package and doing `\load[pdfextra]` in \OpTeX/, or just by -copying some useful parts of this package into your documents / packages. -\OpTeX/ namespacing is used, but it can be easily stripped, if you wish to -incorporate these macros into other macro packages. The code currently depends -on \LuaTeX/, but mostly uses only pdf\TeX/ primitives and a few simple macros -from \OpTeX/. - -User documentation (`pdfextra-doc.tex`) and technical documentation interleaved -with source code (`pdfextra.opm`) are all typeset in this PDF file. Some -examples of usage are in the user documentation, but file -`pdfextra-example.tex` contains more examples. - -\insertoutline{Contents}\outlines{0} -\notoc\nonum \sec Contents -\maketoc - -\vfil\break - -\chap User documentation - -\sec Defining files - -Many commands provided by this package require you to supply a file . This -is because many commands either work directly (like inserting attachments or -multimedia) or can optionally use files (like inserting JavaScript). -The \"right" way to use is to first define the with:\nl\indent -\^`\filedef``/[]{}`. - -Where is the name you will use to refer to this file. It is currently -limited to ASCII only (as all \"s" required by this package). -Interpretation of -depends on the type, which may be: - -\begitems - * `e`, \"embedded file". The file with path will be embedded to the PDF - file. A file that is embedded this once, can later be used many times in - different contexts, e.g. you may use it to attach a video as an attachment but - also have it play on page 1 and even other pages. This is the best way, because - the resulting PDF file is self contained. - * `x`, \"external file". can only be a path to the current directory. - To refer to the file only is used, sort of like a reference. This way - the file you want to refer to {\em has} to be present in the same directory as - the PDF file when it is {\em viewed}! - * `u`, \"URL file". is the URL of the file you want to refer to. -\enditems - -All these create the same type of object, which ideally could be used -interchangibly everywhere a {\em file specification} is required in PDF. This is -sadly not always true. The limitations to only certain types of `\filedef`'s -will be mentioned in due sections. But as a rule of thumb, most of the time you -want to embed the files into PDF. The external/URL references are good for -refering to external files, although other methods are also possible there. - -Because most of the times you want to be embedded file, you may omit the -prior definition and instead use the itself. The file will be -autoembedded. - -Examples: - -\begtt -\filedef/u[doc-internet]{http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf} -\filedef/x[doc-local]{optex-doc.pdf} -\filedef/e[doc-embedded]{optex-doc.pdf} -\endtt - -\label[user:multimedia] -\sec Multimedia - -It is possible to insert video, audio and 3D files for playback/display inside -a PDF file (on a page). There are several different PDF mechanisms for -inserting multimedia. For audio/video this package uses the so called -\"Renditions", which currently have the best support in PDF viewers (fully -works in Acrobat and Foxit, partly in Evince and Okular). Rich Media -annotations are used for 3D art (works only in Acrobat Reader), although it is -possible to also insert audio/video using this mechanism it is very restricting -and Renditions are recommended. - -Use command \^`\render``[][]{}` for -inserting audio/video with Renditions or -\^`\RM``[][]{}` for inserting -audio/video/3D as Rich Media annnotation. -The result of this command is similiar to what `\inspic` -produces\fnote{But because annotations are involved, transformations using PDF -literals will not work as expected.}. Both commands expect to be -\~`\filedef`'d name of the file to play/display. As usual, fallback for -interpreting as path (and embedding it) is in place. It is recommended -to only use embedded files with both mechanisms (Rich Media requires it, -Renditions with other than embedded files do not work in Acrobat). Optional -key-value parameters may be used to customize default values. They may be left -out enitrely (including brackets). Last parameter, , defines so -called \"normal apperance", which is shown before the annotation is activated -(audio/video starts playing or 3D scene is displayed). The dimensions of -resulting multimedia annotation will be taken from . Most likely -you want to use a \"poster" picture (inserted with `\inspic`) as appearance -- -the dimensions will be taken from it and e.g. aspect ratio will be nicely -preserved. - -Customization of Renditions is possible using key-value parameters, but beware -that it mostly doesn't work in Evince and Okular (Acrobat and Foxit are fine in -this regard). The available parameters are in Table~\ref[tab:kv-renditions]. -Most customizations of Rich Media concern 3D art. Available parameters are -listed in Table~\ref[tab:kv-rm]. - -\midinsert -\label[tab:kv-renditions] -\caption/t Key value parameters available for Renditions (\~`\render`) -\cskip -\centerline{\table{lllp{72mm\fL}}{ -Key & Possible values & Default & Description \crll -`controls` & `true` or `false` & `false` & Whether to display audio/video player controls. \crl -`volume` & decimal betwen 0 and 100 & 100 & Audio volume. \crl -`repeat` & integer $\geq$ 0 & 1 & Number of repetitions (0 means loop forever). \crl -`background` & \OpTeX/ color & `\White` & Color used for part of the annotation not covered by video player (for wrong aspect ratios). \crl -`opacity` & decimal between 0 and 1 & 1 & Opacity of `background`. \crl -`aactions` & `\renditionautoplay` & (none) & Can be used for autoplay on page open. \crl -`name` & ascii string & `` & Name for use with actions and scripts. \crll -}} -\endinsert - -\midinsert -\label[tab:kv-rm] -\caption/t Key value parameters available for Rich Media (\~`\RM`) -\cskip -\centerline{\table{lp{31mm\fL}lp{75mm\fL}}{ -Key & Possible values & Default & Description \crll -`activation` & `explicit` or `auto` & `explicit` & Whether to automatically activate the annotation on page open or display normal apperance until user clicks. \crl -`deactivation` & `explicit` or `auto` & `explicit` & Whether to automatically deactivate the annotation on page close or require explicit deactivation by user (from right click menu). \crl -`toolbar` & `true` or `false` & `true` & Whether to show 3D toolbar (with view and other options). \crl -`views` & comma separated list of view s & `` & List of names of 3D views to be used. The default is to try a view of same . Beware that unknown views are silently ignored. \crl -`scripts` & comma separated list of script s & (none) & List of names of JavaScript script file s to be used. \crl -`name` & ascii string & `` & Name for use with actions and scripts. \crll -}} -\endinsert - -The weird `name` key is only required if one media file is used -more than once and control using actions or JavaScript scripts is needed. - -Examples of video insertion: - -\begtt -% embed file under name "video" -\filedef/e[video]{example-movie.mp4} -% insert video into page using Renditions mechanism with controls and autoplay -\render[video][ - name=bigvideo, - controls=true, - aactions=\renditionautoplay, -]{\picwidth=\hsize \inspic{example-image.pdf}} - -% render the same file again, but with different dimensions, no controls -% and explicit activation -\render[video]{\inspic{example-image.pdf}} -\endtt - -When displaying 3D there are more things involved. First, only U3D and PRC can -be included in PDF files. The simplest way to show the 3D scene on page is without -any optional parameters: -\par\nobreak\begtt -\RM[part.prc]{\picwidth=\hsize \inspic{part.png}} -\endtt - -The resulting view will be what is defined in the 3D file. But it is possible -to customize it, by creating custom view. Or even more of them -- they will be -available in the user interface for easy switching, first one is considered -default. Parameters not defined in a custom view often take what is in the 3D -file as default value. \^`\DDDview``[][]` is -the command for defining 3D views. The brackets surrounding key-value -parameters have to be included even if no key-value parameters are used. The -available parameters are explained in Table~\ref[tab:kv-3dview]. - -\midinsert -\label[tab:kv-3dview] -\caption/t Key value parameters available for 3D views (\~`\DDDview`) -\cskip -\centerline{\table{lp{38mm\fL}lp{55mm\fL}}{ -Key & Possible values & Default & Description \crll -`projection` & `perspective` or `ortho` & `perspective` & Projection type to use (perspective distorts the view, e.g. parallel lines are not shown as such, but is more natural to human eye, orthogonal projection is what is generally used with technical parts). \crl -`scale` & decimal number & 1 & Scaling to use when orthogonal projection is used. \crl -`FOV` & number between 0 and 180 & 30 & Field of view for use with perspective projection. \crl -`background` & \OpTeX/ color & `\White` & Color used as background in the 3D scene. \crl -`rendermode` & {\typosize[9/10]`Solid`,\hfil\break`SolidWireframe`,\hfil\break`Transparent`,\hfil\break`TransparentWireframe`,\hfil\break`BoundingBox`,\hfil\break`TransparentBoundingBox`,\hfil\break`Wireframe`,\hfil\break`ShadedWireframe`,\hfil\break`Vertices`,\hfil\break`ShadedVertices`,\hfil\break`Illustration`,\hfil\break`SolidOutline`,\hfil\break`ShadedIllustration`} & (taken from 3D file) & Used rendering mode. See PDF standard\tnote{\url{https://www.adobe.com/content/dam/acom/en/devnet/pdf/pdfs/PDF32000_2008.pdf\#G12.2358303}} for more details. \crl -`lighting` & `White`, `Day`, `Night`, `Hard`, `Primary`, `Blue`, `Red`, `Cube`, `CAD`, `Headlamp` & (taken from 3D file) & Used lighting scheme. See PDF standard\tnote{\url{https://www.adobe.com/content/dam/acom/en/devnet/pdf/pdfs/PDF32000_2008.pdf\#G12.2358356}} for more details.\crl -`method` & `media9`, `manual`, `u3d` & `media9` & Method used for defining 3D camera position and orientation. \crll -}} -\tnoteprint -\endinsert - -The value of `method` key influences what other key-value -parameters are available. For details about the manual method see the technical -documentation~(\ref[mm-3dviews]). The `u3d` method works only with U3D files -(not with PRC files) and requires you to know the internal \"path" of the view -contained in the file and is hence not always useful (especially when the paths -are weirdly constructed by exporting applications). But if you know the path -you can use \"`method=u3d, u3dpath=`". All Unicode characters are allowed in -. - -The most useful method of specifying the camera position/orientation is -`method=media9`. The same method is also used in a number of other packages -(movie15, rmannot, Con\TeX/t). Its input are key-value parameters, listed in -Table~\ref[tab:kv-media9]. For illustration of the parameters check the -documentation\fnote{\url{https://mirrors.ctan.org/macros/latex/contrib/media9/doc/media9.pdf\#figure.8}} -of media9. - -\midinsert -\label[tab:kv-media9] -\caption/t Key value parameters available for media9 method of 3D views (\^`\DDDview`) -\cskip -\centerline{\table{lp{38mm\fL}lp{50mm\fL}}{ -Key & Possible values & Default & Description \crll -`coo` & three space separated (decimal) numbers & `0 0 0` & \"Center of orbit". Coordinates of the point camera is supposed to look at. \crl -`roo` & (decimal) number & `0` & Distance of camera from `coo`. \crl -`c2c` & three space separated (decimal) numbers & `0 -1 0` & \"Center of orbit to camera" vector. A directional vector (i.e. length doesn't matter). The direction the camera will be looking at is opposite of this vector. Default is view towards positive $y$.\crll -}} -\endinsert - -You can construct simple views only by using these few parameters. When talking -about meanings/names of different views it is needed to know the real placement -of the 3D object in the 3D world. But for a reasonably orientated object in the -center (`coo=0 0 0`) constructing simple views is very easy (keep in mind -`method=media9` is default): - -\begtt -\DDDview[front][ - projection=ortho, - roo=400, -] -\DDDview[left][ - projection=ortho, - roo=400, - c2c=-1 0 0, -] -\DDDview[top][ - projection=ortho, - roo=400, - c2c=0 0 1, -] -\DDDview[isometric][ - projection=ortho, - roo=500, - c2c=-1 -1 1, -] -\endtt - -We can then perhaps use these views in \^`\RM`: - -\begtt -% Auto activated 3D Rich Media annotation. White background just ensures -% the right dimensions. Comma in `views` is escaped using "{}". -\RM[part.prc][ - activation=auto, - views={front, left}, -]{{\White\vrule width\hsize height\vsize}} - -\RM[part.prc][ % the same 3D file, now with different views - name=part2, - activation=auto, - views={top, isometric}, -]{{\White\vrule width\hsize height\vsize}} -\endtt - -If you want to deduce the view parameters automatically it is possible. You can -just not specify any view, but include the `3Dmenu.js` script from media9 -package. It enables you to right click the annotation and select \"Get Current -View" (or even \"Generate Default View" which finds the view all by itself). A -window with generated parameters will show up. You can then copy the ones this -package understands (`c2c`, `coo`, `roo`) and use them. You don't have to be -excessive with precision, because after calculation everything gets rounded to -6 decimal places anyways. - -\begtt -% using 3Dmenu.js to generate 3D view parameters automatically -\RM[part.prc][ - name=part3, - activation=auto, - scripts=3Dmenu.js, -]{{\White\vrule width\hsize height\vsize}} -\endtt - -The use of `scripts` isn't limited to this though, there are many other -possibilities. First, you can use as many scripts as you want -(`scripts={script1.js, script2.js, ...}`), but be careful that 3D JavaScript is -kind of special, and has to come from embedded files (here we -were using the auto-embedding, but we could have used e.g. -\~`\filedef/e[3dmenu]{3Dmenu.js}` and then \"`3dmenu`" instead). For creating -your own scripts check out the Acrobat 3D JavaScript -API\fnote{\url{https://wwwimages.adobe.com/content/dam/acom/en/devnet/acrobat/pdfs/AcrobatDC_js_3d_api_reference.pdf}}. -It is possible to do different transformations and achieve animations using -\"time events". The implicit \"context" of 3D scripts can be accessed from -normal JavaScript actions (see~\ref[user:actions-3djs]). Vice versa 3D scripts -may access the global JavaScript environment using `host` object. - -More examples of 3D Rich Media, including usage of 3D JavaScript, are available -in the example file `pdfextra-example.tex`. They show how it is possible to -port the examples used by media9. - -\sec Actions - -Actions are very important aspect of interactivity in the context of PDF. There -are a few very useful types of actions, like \"goto" actions which jump to -other part of document. There are also a few ways how to {\em execute} actions. -The most usual is a clickable area on page, but clickable bookmarks (\"document -outline") also execute actions behind the scenes. \OpTeX/ supports only basic -\"goto" and \"URI" actions using `\ilink` (used for `\ref`, `\cite`, etc.) and -`\ulink` (used for `\url`). - -This package offers generalization of this mechanism. The core of it is a way -of specifying an action. This syntax is called and is used for -example by `\hlink` command, which can replace both `\ilink` and `\ulink`. - is a comma separated list of `:`. where -refers to the action type and the syntax of arguments is dependant on . -Leading spaces are ignored, trailing aren't. You probably won't often use the -possiblity of specifying multiple actions, but it is for chaining execution of -several actions. - -\^`\pdfaction``[]` is available for lower level creation of -different actions, but for clickable areas on page you will use -\^`\hlink``[]{}` with a very similiar syntax. Although note, -that `\hlink`'s interface is also not really high level and wrapping it inside -macros like `\ref` or `\url` might be beneficial. will be typeset -directly and the area it occupies will be clickable. Clicking it executes -action defined by . Line breaks inside will be possible, in -that case several clickable rectangles will be created, one for each line. -Normally in text you want the ares to be of the same height and depth -(calculated from `\baselineskip`), to achieve sort of a lining, uniform effect. -If you want to define big clickable buttons, you may need to turn off the -lining effect using \^`\nolininglinks`. It respects groups, but a counterpart -(\^`\lininglinks`) is also available. - -There are a few predefined action types (): `url`, `extref`, `extpgref`, -`named`, `transition`, `js`, `goto3dview` and `rendition`. They will be explained in a -moment. Any unrecognized is understood as an \"internal link", where -`:` is the destination of the link. Hence it is possible to -use `\hlink` as `\ilink` for example with \OpTeX/'s normal types -of internal links. For example: -\begtt -See section~\hlink[ref:section]{2.2.13} or page~\hlink[pg:5]{5}. -\endtt -`\ulink` may be replaced like this: -\begtt -Visit CTAN's \hlink[url:https://www.ctan.org/]{website}. -\endtt - -Before we really get into different types of actions, there is a nicer command -for setting the initial (\"open") action of PDF document, which is executed -when the document is opened. It defaults to opening the page with the zoom -level according to viewing user's preferences. But you can change this using -\^`\openaction``[]`: - -\begtt -\openaction[pg:2] -\endtt - -\secc External references -There are two actions analogous to internal links that can be used to link to -external documents. `[extref::]` can be used to refer -to named locations in a PDF document prepared by `\filedef` with . -`[extpgref::]` is similiar but refers to a page number. -Although it would be nice, these actions aren't well supported by all viewers. - -Example: - -\begtt -\hlink[extref:doc-internet:ref:langphrases]{OpTeX documentation, - section \"Multilingual phrases and quotation marks".} -\hlink[extpgref:doc-internet:12]{OpTeX documentation, page 12.} -\endtt - -(Note that \"`:`" in \"`ref:langphrase`" is not part of the syntactic rule, it -is just the value of in this case.) - -A little bit of customization is possible, see~\ref[actions-jump]. - -Because of the poor support you may find luck with the less universal url action with `#fragment`: - -\begtt -\hlink[url:http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf#ref:langphrases] - {OpTeX documentation, section \"Multilingual phrases and quotation marks".} -\endtt - -\secc Named actions -There are four defined in PDF standard, but viewers may support more. All in -examples: - -\begtt -\hlink[named:NextPage]{Go to next page,} -\hlink[named:PrevPage]{go to previous page,} -\hlink[named:FirstPage]{go to first page,} -\hlink[named:LastPage]{go to last page.} -\endtt - -\secc Transition actions - -Transition actions generally make sense only when chained {\em after} jump -actions. The specified transition/animation will occur, before destination is -opened, but it will not override a transition defined for the particular page. -The syntax is `[transition:]`. See~\ref[user:transitions] for -more information about ``. - -Example: -\begtt -\hlink[ref:yellow-slide, transition:Box:3:/M /O] - {Go to yellow slide with long outward Box transition} -\endtt - -\secc JavaScript actions - -They allow executing pieces of JavaScript code using syntax: -`[js:]`. If is a validly `\filedef`'d the script from file - will be executed (only embedded files are valid). Otherwise