Debian Codegraph @

texmf-dist/doc/optex/pdfextra/pdfextra-doc.tex

raw
1 % vim: tw=80
2 \load [doc, pdfextra]
3 \catcode`\.=11
4
5 % table notes (http://petr.olsak.net/optex/optex-tricks.html#tnote)
6 \newcount\tnotenum
7 \def\tnotelist{}
8 \def\tnote#1{\incr\tnotenum $^{\rm\_romannumeral\tnotenum}$\global\addto\tnotelist{{#1}}}
9 \def\tnoteprint{\typoscale[920/920]\par \tnotenum=0
10 \ea\foreach\tnotelist
11 \do{\advance\tnotenum by1 \par $^{\rm\_romannumeral\tnotenum}$##1 }\par
12 \global\tnotenum=0 \gdef\tnotelist{}%
13 }
14
15 \let\_cslinkcolor\Blue
16
17 % allow hyperlinking of \OpTeX's control sequences (see doc.opm)
18 \let\_pdfextra_extdocaction\_pdfextra_urlaction
19 \let\_extdoclinkcolor\Blue
20 \def\_Xindex#1#2{\sdef{,#1}{}\slet{el:#1}{optexdoclink}}
21 \def\optexdoclink{\hlink[extdoc:\optexdocurl\#cs:\_tmpa]{\csstring\\\_tmpb}}
22 \def\optexdocurl{http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf}
23 \isfile{optex-doc.eref}\iftrue \input{optex-doc.eref}\fi
24
25 % allow hyperlinks to TeX's control sequences (TeX in a Nutshell)
26 \def\Xeref#1{\sdef{,#1}{}\slet{el:#1}{texdoclink}}
27 \def\texdoclink{\hlink[extdoc:\texdocurl\#cs:\_tmpa]{\csstring\\\_tmpb}}
28 \def\texdocurl{http://petr.olsak.net/ftp/olsak/optex/tex-nutshell.pdf}
29 \isfile{tex-nutshell.eref}\iftrue \input{tex-nutshell.eref}\fi
30
31
32 \insertoutline{PDF extra}
33 \tit PDF extra -- extra PDF features for \OpTeX/
34
35 \hfill Version \_pdfextra_version
36
37 \centerline{\it Michal Vlasák, 2021}
38 \bigskip
39
40 \noindent
41 `PDFextra` is a third party package for \OpTeX/. It aims to provide access to
42 more advanced PDF features, which are currently not supported in \OpTeX/ --
43 especially interactive and multimedia features. The development is hosted at
44 \url{https://github.com/vlasakm/pdfextra}.
45
46 In the spirit of \OpTeX/ you may use these macros in any form you want. Either
47 by installing this package and doing `\load[pdfextra]` in \OpTeX/, or just by
48 copying some useful parts of this package into your documents / packages.
49 \OpTeX/ namespacing is used, but it can be easily stripped, if you wish to
50 incorporate these macros into other macro packages. The code currently depends
51 on \LuaTeX/, but mostly uses only pdf\TeX/ primitives and a few simple macros
52 from \OpTeX/. Additionally, the package can be used in plain LuaTeX and
53 LuaLaTeX (in a limited form), see section~\ref[user:plain+latex].
54
55 User documentation (`pdfextra-doc.tex`) and technical documentation interleaved
56 with source code (`pdfextra.opm`) are all typeset in this PDF file. Some
57 examples of usage are in the user documentation, but file
58 `pdfextra-example.tex` contains more examples.
59
60 \insertoutline{Contents}\outlines{0}
61 \notoc\nonum \sec Contents
62 \maketoc
63
64 \vfil\break
65
66 \chap User documentation
67
68 \sec Defining files
69
70 Many commands provided by this package require you to supply a file <name>. This
71 is because many commands either work directly (like inserting attachments or
72 multimedia) or can optionally use files (like inserting JavaScript).
73 The \"right" way to use <name> is to first define the <name> with:\nl\indent
74 \^`\filedef``/<type>[<name>]{<path or URL>}`.
75
76 Where <name> is the name you will use to refer to this file. It is currently
77 limited to ASCII only (as all \"<name>s" required by this package).
78 Interpretation of <path or URL>
79 depends on the type, which may be:
80
81 \begitems
82 * `e`, \"embedded file". The file with path <path> will be embedded to the PDF
83 file. A file that is embedded this once, can later be used many times in
84 different contexts, e.g. you may use it to attach a video as an attachment but
85 also have it play on page 1 and even other pages. This is the best way, because
86 the resulting PDF file is self contained.
87 * `x`, \"external file". <path> can only be a path to the current directory.
88 To refer to the file only <path> is used, sort of like a reference. This way
89 the file you want to refer to {\em has} to be present in the same directory as
90 the PDF file when it is {\em viewed}!
91 * `u`, \"URL file". <URL> is the URL of the file you want to refer to.
92 \enditems
93
94 All these create the same type of object, which ideally could be used
95 interchangibly everywhere a {\em file specification} is required in PDF. This is
96 sadly not always true. The limitations to only certain types of `\filedef`'s
97 will be mentioned in due sections. But as a rule of thumb, most of the time you
98 want to embed the files into PDF. The external/URL references are good for
99 refering to external files, although other methods are also possible there.
100
101 Because most of the times you want <name> to be embedded file, you may omit the
102 prior definition and instead use the <path> itself. The file will be
103 autoembedded.
104
105 Examples:
106
107 \begtt
108 \filedef/u[doc-internet]{http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf}
109 \filedef/x[doc-local]{optex-doc.pdf}
110 \filedef/e[doc-embedded]{optex-doc.pdf}
111 \endtt
112
113 \label[user:multimedia]
114 \sec Multimedia
115
116 It is possible to insert video, audio and 3D files for playback/display inside
117 a PDF file (on a page). There are several different PDF mechanisms for
118 inserting multimedia. For audio/video this package uses the so called
119 \"Renditions", which currently have the best support in PDF viewers (fully
120 works in Acrobat and Foxit, partly in Evince and Okular). Rich Media
121 annotations are used for 3D art (works only in Acrobat Reader), although it is
122 possible to also insert audio/video using this mechanism it is very restricting
123 and Renditions are recommended.
124
125 Use command \^`\render``[<name>][<optional key-value parameters>]{<appearance>}` for
126 inserting audio/video with Renditions or
127 \^`\RM``[<name>][<optional key-value parameters>]{<appearance>}` for inserting
128 audio/video/3D as Rich Media annnotation.
129 The result of this command is similiar to what `\inspic`
130 produces\fnote{But because annotations are involved, transformations using PDF
131 literals will not work as expected.}. Both commands expect <name> to be
132 \~`\filedef`'d name of the file to play/display. As usual, fallback for
133 interpreting <name> as path (and embedding it) is in place. It is recommended
134 to only use embedded files with both mechanisms (Rich Media requires it,
135 Renditions with other than embedded files do not work in Acrobat). Optional
136 key-value parameters may be used to customize default values. They may be left
137 out enitrely (including brackets). Last parameter, <appearance>, defines so
138 called \"normal apperance", which is shown before the annotation is activated
139 (audio/video starts playing or 3D scene is displayed). The dimensions of
140 resulting multimedia annotation will be taken from <appearance>. Most likely
141 you want to use a \"poster" picture (inserted with `\inspic`) as appearance --
142 the dimensions will be taken from it and e.g. aspect ratio will be nicely
143 preserved.
144
145 Customization of Renditions is possible using key-value parameters, but beware
146 that it mostly doesn't work in Evince and Okular (Acrobat and Foxit are fine in
147 this regard). The available parameters are in Table~\ref[tab:kv-renditions].
148 Most customizations of Rich Media concern 3D art. Available parameters are
149 listed in Table~\ref[tab:kv-rm].
150
151 \midinsert
152 \label[tab:kv-renditions]
153 \caption/t Key value parameters available for Renditions (\~`\render`)
154 \cskip
155 \centerline{\table{lllp{72mm\fL}}{
156 Key & Possible values & Default & Description \crll
157 `controls` & `true` or `false` & `false` & Whether to display audio/video player controls. \crl
158 `volume` & decimal betwen 0 and 100 & 100 & Audio volume. \crl
159 `repeat` & integer $\geq$ 0 & 1 & Number of repetitions (0 means loop forever). \crl
160 `background` & \OpTeX/ color & `\White` & Color used for part of the annotation not covered by video player (for wrong aspect ratios). \crl
161 `opacity` & decimal between 0 and 1 & 1 & Opacity of `background`. \crl
162 `aactions` & `\renditionautoplay` & (none) & Can be used for autoplay on page open. \crl
163 `name` & ascii string & `<name>` & Name for use with actions and scripts. \crll
164 }}
165 \endinsert
166
167 \midinsert
168 \label[tab:kv-rm]
169 \caption/t Key value parameters available for Rich Media (\~`\RM`)
170 \cskip
171 \centerline{\table{lp{31mm\fL}lp{75mm\fL}}{
172 Key & Possible values & Default & Description \crll
173 `activation` & `explicit` or `auto` & `explicit` & Whether to automatically activate the annotation on page open or display normal apperance until user clicks. \crl
174 `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
175 `toolbar` & `true` or `false` & `true` & Whether to show 3D toolbar (with view and other options). \crl
176 `views` & comma separated list of view <name>s & `<name>` & List of names of 3D views to be used. The default is to try a view of same <name>. Beware that unknown views are silently ignored. \crl
177 `scripts` & comma separated list of script <name>s & (none) & List of names of JavaScript script file <name>s to be used. \crl
178 `name` & ascii string & `<name>` & Name for use with actions and scripts. \crll
179 }}
180 \endinsert
181
182 The weird `name` key is only required if one media file is used
183 more than once and control using actions or JavaScript scripts is needed.
184
185 Examples of video insertion:
186
187 \begtt
188 % embed file under name "video"
189 \filedef/e[video]{example-movie.mp4}
190 % insert video into page using Renditions mechanism with controls and autoplay
191 \render[video][
192 name=bigvideo,
193 controls=true,
194 aactions=\renditionautoplay,
195 ]{\picwidth=\hsize \inspic{example-image.pdf}}
196
197 % render the same file again, but with different dimensions, no controls
198 % and explicit activation
199 \render[video]{\inspic{example-image.pdf}}
200 \endtt
201
202 When displaying 3D there are more things involved. First, only U3D and PRC can
203 be included in PDF files. The simplest way to show the 3D scene on page is without
204 any optional parameters:
205 \par\nobreak\begtt
206 \RM[part.prc]{\picwidth=\hsize \inspic{part.png}}
207 \endtt
208
209 The resulting view will be what is defined in the 3D file. But it is possible
210 to customize it, by creating custom view. Or even more of them -- they will be
211 available in the user interface for easy switching, first one is considered
212 default. Parameters not defined in a custom view often take what is in the 3D
213 file as default value. \^`\DDDview``[<view name>][<key-value parameters>]` is
214 the command for defining 3D views. The brackets surrounding key-value
215 parameters have to be included even if no key-value parameters are used. The
216 available parameters are explained in Table~\ref[tab:kv-3dview].
217
218 \midinsert
219 \label[tab:kv-3dview]
220 \caption/t Key value parameters available for 3D views (\~`\DDDview`)
221 \cskip
222 \centerline{\table{lp{38mm\fL}lp{55mm\fL}}{
223 Key & Possible values & Default & Description \crll
224 `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
225 `scale` & decimal number & 1 & Scaling to use when orthogonal projection is used. \crl
226 `FOV` & number between 0 and 180 & 30 & Field of view for use with perspective projection. \crl
227 `background` & \OpTeX/ color & `\White` & Color used as background in the 3D scene. \crl
228 `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
229 `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
230 `method` & `media9`, `manual`, `u3d` & `media9` & Method used for defining 3D camera position and orientation. \crll
231 }}
232 \tnoteprint
233 \endinsert
234
235 The value of `method` key influences what other key-value
236 parameters are available. For details about the manual method see the technical
237 documentation~(\ref[mm-3dviews]). The `u3d` method works only with U3D files
238 (not with PRC files) and requires you to know the internal \"path" of the view
239 contained in the file and is hence not always useful (especially when the paths
240 are weirdly constructed by exporting applications). But if you know the path
241 you can use \"`method=u3d, u3dpath=<path>`". All Unicode characters are allowed in
242 <path>.
243
244 The most useful method of specifying the camera position/orientation is
245 `method=media9`. The same method is also used in a number of other packages
246 (movie15, rmannot, Con\TeX/t). Its input are key-value parameters, listed in
247 Table~\ref[tab:kv-media9]. For illustration of the parameters check the
248 documentation\fnote{\url{https://mirrors.ctan.org/macros/latex/contrib/media9/doc/media9.pdf\#figure.8}}
249 of media9.
250
251 \midinsert
252 \label[tab:kv-media9]
253 \caption/t Key value parameters available for media9 method of 3D views (\^`\DDDview`)
254 \cskip
255 \centerline{\table{lp{38mm\fL}lp{50mm\fL}}{
256 Key & Possible values & Default & Description \crll
257 `coo` & three space separated (decimal) numbers & `0 0 0` & \"Center of orbit". Coordinates of the point camera is supposed to look at. \crl
258 `roo` & (decimal) number & `0` & Distance of camera from `coo`. \crl
259 `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
260 }}
261 \endinsert
262
263 You can construct simple views only by using these few parameters. When talking
264 about meanings/names of different views it is needed to know the real placement
265 of the 3D object in the 3D world. But for a reasonably orientated object in the
266 center (`coo=0 0 0`) constructing simple views is very easy (keep in mind
267 `method=media9` is default):
268
269 \begtt
270 \DDDview[front][
271 projection=ortho,
272 roo=400,
273 ]
274 \DDDview[left][
275 projection=ortho,
276 roo=400,
277 c2c=-1 0 0,
278 ]
279 \DDDview[top][
280 projection=ortho,
281 roo=400,
282 c2c=0 0 1,
283 ]
284 \DDDview[isometric][
285 projection=ortho,
286 roo=500,
287 c2c=-1 -1 1,
288 ]
289 \endtt
290
291 We can then perhaps use these views in \^`\RM`:
292
293 \begtt
294 % Auto activated 3D Rich Media annotation. White background just ensures
295 % the right dimensions. Comma in `views` is escaped using "{}".
296 \RM[part.prc][
297 activation=auto,
298 views={front, left},
299 ]{{\White\vrule width\hsize height\vsize}}
300
301 \RM[part.prc][ % the same 3D file, now with different views
302 name=part2,
303 activation=auto,
304 views={top, isometric},
305 ]{{\White\vrule width\hsize height\vsize}}
306 \endtt
307
308 If you want to deduce the view parameters automatically it is possible. You can
309 just not specify any view, but include the `3Dmenu.js` script from media9
310 package. It enables you to right click the annotation and select \"Get Current
311 View" (or even \"Generate Default View" which finds the view all by itself). A
312 window with generated parameters will show up. You can then copy the ones this
313 package understands (`c2c`, `coo`, `roo`) and use them. You don't have to be
314 excessive with precision, because after calculation everything gets rounded to
315 6 decimal places anyways.
316
317 \begtt
318 % using 3Dmenu.js to generate 3D view parameters automatically
319 \RM[part.prc][
320 name=part3,
321 activation=auto,
322 scripts=3Dmenu.js,
323 ]{{\White\vrule width\hsize height\vsize}}
324 \endtt
325
326 The use of `scripts` isn't limited to this though, there are many other
327 possibilities. First, you can use as many scripts as you want
328 (`scripts={script1.js, script2.js, ...}`), but be careful that 3D JavaScript is
329 kind of special, and has to come from embedded files (here we
330 were using the auto-embedding, but we could have used e.g.
331 \~`\filedef/e[3dmenu]{3Dmenu.js}` and then \"`3dmenu`" instead). For creating
332 your own scripts check out the Acrobat 3D JavaScript
333 API\fnote{\url{https://wwwimages.adobe.com/content/dam/acom/en/devnet/acrobat/pdfs/AcrobatDC_js_3d_api_reference.pdf}}.
334 It is possible to do different transformations and achieve animations using
335 \"time events". The implicit \"context" of 3D scripts can be accessed from
336 normal JavaScript actions (see~\ref[user:actions-3djs]). Vice versa 3D scripts
337 may access the global JavaScript environment using `host` object.
338
339 More examples of 3D Rich Media, including usage of 3D JavaScript, are available
340 in the example file `pdfextra-example.tex`. They show how it is possible to
341 port the examples used by media9.
342
343 \sec Actions
344
345 Actions are very important aspect of interactivity in the context of PDF. There
346 are a few very useful types of actions, like \"goto" actions which jump to
347 other part of document. There are also a few ways how to {\em execute} actions.
348 The most usual is a clickable area on page, but clickable bookmarks (\"document
349 outline") also execute actions behind the scenes. \OpTeX/ supports only basic
350 \"goto" and \"URI" actions using `\ilink` (used for `\ref`, `\cite`, etc.) and
351 `\ulink` (used for `\url`).
352
353 This package offers generalization of this mechanism. The core of it is a way
354 of specifying an action. This syntax is called <action spec> and is used for
355 example by `\hlink` command, which can replace both `\ilink` and `\ulink`.
356 <action spec> is a comma separated list of `<type>:<arguments>`. where <type>
357 refers to the action type and the syntax of arguments is dependant on <type>.
358 Leading spaces are ignored, trailing aren't. You probably won't often use the
359 possiblity of specifying multiple actions, but it is for chaining execution of
360 several actions.
361
362 \^`\pdfaction``[<action spec>]` is available for lower level creation of
363 different actions, but for clickable areas on page you will use
364 \^`\hlink``[<action spec>]{<text>}` with a very similiar syntax. Although note,
365 that `\hlink`'s interface is also not really high level and wrapping it inside
366 macros like `\ref` or `\url` might be beneficial. <text> will be typeset
367 directly and the area it occupies will be clickable. Clicking it executes
368 action defined by <action spec>. Line breaks inside <text> will be possible, in
369 that case several clickable rectangles will be created, one for each line.
370 Normally in text you want the areas to be of the same height and depth
371 (calculated from `\baselineskip`), to achieve sort of a lining, uniform effect.
372 If you want to define big clickable buttons, you may need to turn off the
373 lining effect using \^`\nolininglinks`. It respects groups, but a counterpart
374 (\^`\lininglinks`) is also available.
375
376 There are a few predefined action types (<type>): `url`, `extref`, `extpgref`,
377 `named`, `transition`, `js`, `goto3dview` and `rendition`. They will be explained in a
378 moment. Any unrecognized <type> is understood as an \"internal link", where
379 `<type>:<link>` is the destination of the link. Hence it is possible to
380 use `\hlink` as `\ilink` for example with \OpTeX/'s normal types
381 of internal links. For example:
382 \begtt
383 See section~\hlink[ref:section]{2.2.13} or page~\hlink[pg:5]{5}.
384 \endtt
385 `\ulink` may be replaced like this:
386 \begtt
387 Visit CTAN's \hlink[url:https://www.ctan.org/]{website}.
388 \endtt
389
390 Before we really get into different types of actions, there is a nicer command
391 for setting the initial (\"open") action of PDF document, which is executed
392 when the document is opened. It defaults to opening the page with the zoom
393 level according to viewing user's preferences. But you can change this using
394 \^`\openaction``[<action spec>]`:
395
396 \begtt
397 \openaction[pg:2]
398 \endtt
399
400 \secc External references
401 There are two actions analogous to internal links that can be used to link to
402 external documents. `[extref:<name>:<named destination>]` can be used to refer
403 to named locations in a PDF document prepared by `\filedef` with <name>.
404 `[extpgref:<name>:<page number>]` is similiar but refers to a page number.
405 Although it would be nice, these actions aren't well supported by all viewers.
406
407 Example:
408
409 \begtt
410 \hlink[extref:doc-internet:ref:langphrases]{OpTeX documentation,
411 section \"Multilingual phrases and quotation marks".}
412 \hlink[extpgref:doc-internet:12]{OpTeX documentation, page 12.}
413 \endtt
414
415 (Note that \"`:`" in \"`ref:langphrase`" is not part of the syntactic rule, it
416 is just the value of <named destination> in this case.)
417
418 A little bit of customization is possible, see~\ref[actions-jump].
419
420 Because of the poor support you may find luck with the less universal url action with `#fragment`:
421
422 \begtt
423 \hlink[url:http://petr.olsak.net/ftp/olsak/optex/optex-doc.pdf#ref:langphrases]
424 {OpTeX documentation, section \"Multilingual phrases and quotation marks".}
425 \endtt
426
427 \secc Named actions
428 There are four defined in PDF standard, but viewers may support more. All in
429 examples:
430
431 \begtt
432 \hlink[named:NextPage]{Go to next page,}
433 \hlink[named:PrevPage]{go to previous page,}
434 \hlink[named:FirstPage]{go to first page,}
435 \hlink[named:LastPage]{go to last page.}
436 \endtt
437
438 \secc Transition actions
439
440 Transition actions generally make sense only when chained {\em after} jump
441 actions. The specified transition/animation will occur, before destination is
442 opened, but it will not override a transition defined for the particular page.
443 The syntax is `[transition:<transition spec>]`. See~\ref[user:transitions] for
444 more information about `<transition spec>`.
445
446 Example:
447 \begtt
448 \hlink[ref:yellow-slide, transition:Box:3:/M /O]
449 {Go to yellow slide with long outward Box transition}
450 \endtt
451
452 \secc JavaScript actions
453
454 They allow executing pieces of JavaScript code using syntax:
455 `[js:<name or script>]`. If <name or script> is a validly `\filedef`'d the script from file
456 <name> will be executed (only embedded files are valid). Otherwise <script> will
457 be used directly. Apart from reuse in different documents, scripts loaded from
458 files may be encoded in UTF-16BE and hence support Unicode, inline <script>s
459 current don't.
460
461 Examples:
462
463 \begtt
464 \openaction[js:{%
465 app.alert("Javascript alert, open action");
466 console.println("printing to console from openaction");
467 }]
468
469 \filedef/e[jstest]{test.js}
470 \hlink[js:jstest]{JavaScript action from file}
471 \endtt
472
473 (Note how braces were used to guard the comma in JavaScript code from being
474 interpreted as a action separator.)
475
476 In these actions you may want to use your own functions which should be defined
477 before user has a chance of activating any other JavaScript actions. This is the
478 purpose of \"document level" JavaScript actions. They function exactly the same
479 way as normal JavaScript actions, but have names (although meaningless, they
480 must be unique) and are executed in order of definition. Use
481 \^`\dljavascript``[<name>]{<name or script>}` for defining these actions:
482
483 \begtt \adef![#1]{\url{#1}}
484 \filedef/e[preamble]{preamble.js}
485 \dljavascript[preamble]{preamble}
486
487 \dljavascript[initialization]{%
488 var data = 42;
489 function getRandomNumber() {
490 return 4; // chosen by fair dice roll, ![https://xkcd.com/221/]
491 }
492 console.println("initialized with seed " + getRandomNumber());
493 }
494 \endtt
495
496 The JavaScript API available is not the same as the one in the web browsers. It
497 is instead specified by Adobe:
498 \url{https://wwwimages.adobe.com/content/dam/acom/en/devnet/acrobat/pdfs/js_api_reference.pdf}.
499
500 \label[user:actions-3djs]
501 \secc 3D JavaScript actions
502
503 There are no \"special" JavaScript actions for dealing with 3D. Normal
504 JavaScript actions are used. You just have to access the 3D context of the
505 annotation you want to control. For annotation with <name> the context is made
506 available in \^`\DDDcontext{<name>}`. Under this context object you find all
507 global definitions from the respective 3D scripts. For example if a \"`turn`"
508 function is defined, it is possible to call it like this:
509
510 \begtt
511 \hlink[js:\DDDcontext{part3}.turn();]{Turn by 90 degrees along $x$ axis.}
512 \endtt
513
514 \secc GoTo3Dview actions
515
516 GoTo3Dview actions allow changing the view of the 3D scene to one of the
517 predefined views (those listed by `views` comma separated list of \~`\RM`). The
518 syntax is `[goto3dview:<name>:<view>]`. <name> is name of the annotation whose
519 view we want to change and <view> is the intended view. You can refer to last
520 inserted Rich Media annotation using empty name. For <view> you can either use
521 \"`(<view name>)`" (e.g. \"`(part)`"), index of the view in the view list (zero
522 based, e.g.\ \"`0`" for the first view) or one of the special values: \"`/N`"
523 (next), \"`/P`" (previous), \"`/F`" (first) \"`/L`" (\"last").
524
525 \begtt
526 % let's define an annotation with a few views
527 \RM[part.prc][
528 activation=auto,
529 views={front, left, top, isometric},
530 ]{{\White\vrule width\hsize height\vsize}}
531
532 % try the different methods of reffering to views
533 \hlink[goto3dview::/N]{Next view},
534 \hlink[goto3dview::(left)]{left view} and
535 \hlink[goto3dview:part.prc:3]{third view}.
536 \endtt
537
538 \secc Rendition actions
539
540 Rendition actions can be used to control playback of \"Rendition annotations".
541 They use the syntax `[rendition:<name>:<operation>]`, where <name> refers to
542 the name of the rendition to control and <operation> is one of `play`, `stop`,
543 `pause` or `resume`. As a convenience, you can refer to last inserted rendition
544 using empty name. If a file has been \~`\render`ed more than once with the same
545 name, the action will influence the first instance.
546
547 Beware that currently these actions do not work in Evince and Okular (but do in
548 Acrobat and Foxit).
549
550 Examples:
551
552 \begtt
553 % rendition with name=video, that we want to control
554 \render[video]{\inspic{example-image.pdf}}
555
556 % we want the rendition action to have yellow border and red content
557 \def\_renditionborder{1 1 0}
558 \let\_renditionlinkcolor\Red
559
560 To start playing the video, click \hlink[rendition::play]{\"Play"}.
561 After that you can \hlink[rendition:video]{pause}.
562 \endtt
563
564 \label[user:transitions]
565 \sec Transitions and other page attributes
566
567 In PDF there are a few settings that can be set as {\em page attributes}. This
568 means that they apply only to said page. For setting these page attributes,
569 there are two options:
570
571 \begitems
572 * value for \"current page" (or rather the page where the command appears),
573 * default value used if \"current page" value is not set.
574 \enditems
575
576 While this package contains mechanism to handle all page attributes, not that
577 many are useful for end user. The interesting ones remaining are:
578
579 \begitems
580 * Transitions and page durations. When page has the transition attribute any
581 jump to this page will display the requested animation (customized by the
582 corresponding parameters). Page duration is the time before PDF viewer will auto
583 advance to the next page. \^`\transition``[<transition spec>]` sets transition
584 for the \"current page", \^`\transitions` sets the default.
585 `<transition spec>` has three parts:\nl\indent
586 `<animation type>:<duration>:<raw PDF attributes>`\nl
587 \noindent <animation type> is one of `Split`, `Blinds`, `Box`, `Wipe`,
588 `Dissolve`, `Glitter`, `Fly`, `Push`, `Cover`, `Uncover` and `Fade`, or the
589 special value `R` which essentially means no animation and instantaneous
590 transition (regardless of the set duration of transition). <duration> is the
591 duration of transition in seconds (integer or decimal number).
592 <raw PDF attributes> may be used to customize
593 the animations (for example `/M` can set the direction of motion of `Split`,
594 `Box` and `Fly`, e.g. `/M /I` for inward motion). For the raw PDF attributes
595 refer to the standard
596 itself\fnote{\url{https://wwwimages2.adobe.com/content/dam/acom/en/devnet/pdf/pdfs/PDF32000_2008.pdf\#G11.2295795}}.
597 `:<raw PDF attributes>` or even `:<duration>:<raw PDF attributes>` may be omitted.
598 Default values specified by PDF standard will be used in that case (1 second
599 duration and default values for all attributes). Page durations can be set
600 either using \^`\defaultpageduration``[<duration>]` or
601 \^`\pageduration``[<duration>]`, where duration is in seconds (default is no auto
602 advancement, i.e. $\infty$).
603 Examples:
604
605 \begtt
606 % unless stated otherwise all pages will have Wipe animation
607 % with 1 second duration
608 \transitions[Wipe:1]
609
610 % but this page has a 1 second Fade animation
611 \transition[Fade]
612
613 \pg+ % (if using \slides)
614
615 % and this page has 3 second Split animation
616 % with vertical direction and inward motion
617 \transition[Split:3:/Dm /V /M /I]
618 \endtt
619
620 Note that transitions are only displayed when in {\em full-screen mode}. You
621 can use \~`\fullscreen` to have the document automatically open in full-screen
622 mode.
623
624 * Additional actions. It is possible to define actions which will respond to
625 page events: page open (`/O`) and page close (`/C`). They can be set using
626 \^`\defaultpageactions``[<additional actions spec>]` (the default for all pages) and
627 \^`\pageactions``[<additional actions spec>]` (current page override).
628 <additional actions spec> consists of braced pairs of \"event" (O or C in this
629 case) and <action spec>. Example:
630
631 \begtt
632 \pageactions[
633 {O} {js:{app.alert("Page open, random = " + getRandomNumber());}}
634 {C} {js:{app.alert("Page close!");}}
635 ]
636 \endtt
637
638 \enditems
639
640 \sec Attachments
641
642 Every file embedded into a PDF file may optionally be presented in the user
643 interface as an embedded file. This allows readers of the document to save or
644 open the file.
645
646 PDF allows two ways of presenting attachments -- using annotations (the
647 attachments is represented by a rectangular icon on a page) or global array of
648 attachments (attachments are visible in PDF viewers toolbar). The first method
649 is intended more for document reviewers than for primary insertion. Hence this
650 package supports only the second type.
651
652 You may add an embedded file to the global attachments array using
653 \^`\attach``[<name>]`. As usual, name is either a <name> defined with
654 `\filedef` or alternatively a path to file which will be embedded (and
655 `\filedef`d) automatically. It is not possible to `\attach` files referenced by
656 path or URL.
657
658 If you want to automatically display toolbar with embedded files, consider
659 using `\showattached` (see section~\ref[user:document-view]).
660
661 \label[user:document-view]
662 \sec Document view
663
664 You can choose what is shown when document is opened with commands:
665
666 \begitems
667 * \^`\fullscreen` (the document is opened in full-screen mode),
668 * \^`\showoutlines` (show bookmarks/outlines toolbar)
669 * \^`\showattached` (show attachments in toolbar)
670 \enditems
671
672 The commands are mutually exclusive and only the first appearing one will be respected.
673
674 You can request two page view (odd pages on the right) using
675 \^`\duplexdisplay`. It is useful for more natural display of double sided
676 documents. Because it may not be desirable to automatically apply this, it is
677 independent of `\margins`.
678
679 \label[user:plain+latex]
680 \sec Usage in plain \LuaTeX/ or LuaLa\TeX/
681
682 You can use this package also from plain LuaTeX by adding to your document:
683
684 \begtt
685 \input pdfextra
686 \endtt
687
688 \noindent or for LuaLa\TeX/:
689
690 \begtt
691 \usepackage{pdfextra}
692 \endtt
693
694 See the file `pdfextra-example-latex.tex` for the adaptation of the \OpTeX/
695 examples to \LaTeX/.
696
697 The usage of the macros described in this document is the same, but there are
698 limitations:
699
700 \begitems
701 * {\em Color}. Where this package expects \"\OpTeX/ color" key value argument
702 (e.g. `\Blue`), you have to use an RGB triplet instead (e.g. `0.0 0.0 0.0` or
703 the shorter `0 0 0`).
704
705 But for text color setting, you can get away with wrapping commands from
706 La\TeX/'s `color` package, e.g. to customize link border/color:
707
708 \begtt
709 \sdef{_renditionlinkcolor}{\color[red]}
710 \endtt
711
712 * {\em Initialization}. In \OpTeX/ you normally have to initialize hyperlinks
713 with the command\nl
714 `\hyperlinks<color for internal links><color for external links>`.\nl
715 This is not required by this package. You can instead set the color by setting
716 `\_linkcolor` (fallback for all link types), `\_ilinkcolor` / `\_elinkcolor`
717 (internal / external links). E.g. if you have the \LaTeX/ `color` package
718 loaded, you can get blue links like this:
719
720 \begtt
721 \sdef{_linkcolor}{\color[blue]}
722 \endtt
723
724 In addition to the above this means all links will be blue except \"rendition"
725 links.
726
727 * {\em Openaction}. If the package `hyperref` is used, then `\openaction` will
728 not work.
729
730 * {\em Labels / hyperlink destinations}. \OpTeX/ uses very simple and consistent
731 scheme for labels / hyperlink destinations:
732
733 \begitems
734 * `ref:<label>` -- result of `\label[<label>]`
735 * `toc:<tocrefnum>` -- result of `\chap`/`\sec`/`\secc` titles
736 * `pg:<gpageno>` -- created on each page with global numbering from 1
737 * `cite:<bibpart>/<bibnum>` -- bibliography references,
738 * `fnt:<gfnotenum>` -- link form text to footnote
739 * `fnf:<gfnotenum>` -- link from footnote to text
740 * `url:<url>` -- used by `\url` or `\ulink`,
741 \enditems
742
743 Hence these labels / destinations can be used with `\hlink`, e.g. to make text
744 `page 5` a link to page 5, one can use:
745
746 \begtt
747 \hlink[pg:5]{page 5}
748 \endtt
749
750 This is not possible in plain \LuaTeX/ (no destinations are created) or
751 LuaLa\TeX/ (different and incompatible destination names). You would have to
752 create your own destinations adhering to the naming convention
753 `<type>:<arguments>` to be able to use `\hlink` as intended for some links.
754
755 \enditems
756
757 \chap Technical documentation
758
759 This is the technical documentation. It is intended for those who want to know
760 how this package works internally. Casual users shouldn't need to read this. But
761 if you would like to customize anything or perhaps just use some part of this
762 package, feel free to copy paste and use anything you want in \OpTeX/'s spirit.
763
764 This documentation is interleaved within the source itself, both are contained
765 in a single file, `pdfextra.opm` (according to \OpTeX/ conventions). The user
766 documentation is instead contained in `pdfextra-doc.tex`, which itself
767 `\input`'s the documented source file `pdfextra.opm` so that the user and
768 technical documentation is available in a single PDF file, `pdfextra-doc.pdf`.
769
770 \printdoc pdfextra.opm
771
772 \bye