summaryrefslogtreecommitdiff
path: root/macros/luatex/optex/pdfextra/pdfextra.opm
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/optex/pdfextra/pdfextra.opm')
-rw-r--r--macros/luatex/optex/pdfextra/pdfextra.opm144
1 files changed, 85 insertions, 59 deletions
diff --git a/macros/luatex/optex/pdfextra/pdfextra.opm b/macros/luatex/optex/pdfextra/pdfextra.opm
index b7cf70a981..bccf096484 100644
--- a/macros/luatex/optex/pdfextra/pdfextra.opm
+++ b/macros/luatex/optex/pdfextra/pdfextra.opm
@@ -1,17 +1,35 @@
% vim: tw=80
-\_def\_pdfextra_version{0.1}
+\_def\_pdfextra_version{0.2}
\_codedecl \RM {Extra PDF features (v\_pdfextra_version)}
+\_namespace{pdfextra}
+
\_doc
\sec Package initialization
+ We ensure that hyperlinking is active. Our fallback \`\_linkcolor` must
+ exist. We also use it for `\hyperlinks` if the user didn't enable
+ `\hyperlinks` yet (we don't want to override user setting).
+ \_cod
+
+\_ifdefined\_ilinkcolor\_else
+ \_ifdefined\_linkcolor
+ \_ea\_let\_ea\_linkcolor \_ifdefined\Blue\Blue\_else\_empty\_fi
+ \_else
+ \_let\_linkcolor\linkcolor
+ \_fi
+\_fi
+
+\_ifx\_dest\_destactive\_else
+ \_hyperlinks\_linkcolor\_linkcolor
+\_fi
+
+ \_doc
We are in the \OpTeX/ package namespace. A couple of shortcuts are defined
here: \`\.isdefined`, \`\.trycs`, \`\.cs` \`\.slet`, \`\.slet`, \`\.sdef` and
- \`\.xdef`. They all hard code the package name, because we already have too
+ \`\.sxdef`. They all hard code the package name, because we already have too
many levels of indirection.
\_cod
-\_namespace{pdfextra}
-
\_def\.isdefined#1{\_isdefined{_pdfextra_#1}}
\_def\.trycs#1{\_trycs{_pdfextra_#1}}
\_def\.cs#1{\_cs{_pdfextra_#1}}
@@ -67,7 +85,8 @@
\_doc
\`\.xaddto``\macro`{<text>} is a natural extension of \OpTeX's `\addto` that
- expands <text> and is global.
+ expands <text> and is global.\nl
+ \`\.tmp` is used throught the package for temporary values.
\_cod
\_def\.xaddto#1#2{\_edef\.tmp{#2}%
@@ -115,10 +134,6 @@
rough estimate we take the current page~-- this actually works well for
slides where page breaks are manual.
- `\.pageof` is expandable, but we want to let the user know, that the document
- needs to be processed twice. Therefore we use \LuaTeX's
- `\immediateassignment` to increment the counter of unresolved references.
-
When `.ref` file is read along with the defintion of `\.Xpageof` this package
has not been loaded yet. Hence we can't use namespaced variants of
`\.isdefined`, etc.
@@ -134,7 +149,6 @@
\_def\.pageof#1{%
\.trycs{pageof:#1}{%
- \_immediateassignment\_incr\_unresolvedrefs
\_the\_numexpr\_gpageno+1\_relax % best effort = current page num
}%
}
@@ -368,14 +382,12 @@
\_doc
\label[actions-link]
\secc Link annotations
- The main use of actions~-- annotations of `/Subtype /Link`.
- Annotation of this type creates an active rectangular area on the page that
- executes a PDF action (or chain of them in the general case).
- \`\hlinkactive``[<action spec>]<text>` is a natural extension of \OpTeX/'s
- `\linkactive`, that supports the classic \"jump" actions of types `ref`,
- `bib`, etc. But also other types of actions. No distinction between
- \"internal" (`\ilink`) and external (`\ulink`) links is made. The mechanism is
- completely generic.
+ The main use of actions~-- annotations of `/Subtype /Link`. Annotation of
+ this type creates an active rectangular area on the page that executes a PDF
+ action (or chain of them in the general case).
+ \`\hlink``[<action spec>]<text>` is macro that typesets <text> and makes area
+ occupied by it active according to <action spec>. All action types are
+ supported, the mechanism is completely generic.
The `\pdfstartlink`/`\pdfendlink` primitives are used to denote the part of
the page where <text> appears as active. \LuaTeX/ will then handle even the
@@ -383,7 +395,7 @@
multiple rectangular annotations to cover all `\hbox`es).
\_cod
-\_def\.hlinkactive[#1]#2{\_bgroup\_def\#{\_csstring\#}%
+\_def\.hlink[#1]#2{\_bgroup\_def\#{\_csstring\#}%
\_edef\.type{\.pdfactiontype[#1]}%
\_quitvmode\_pdfstartlink \.linkdimens
attr{\_pdfborder{\.type}}%
@@ -391,25 +403,25 @@
\_localcolor\.linkcolor{\.type}#2\_pdfendlink\_egroup
}
+\_nspublic \hlink ;
+
\_doc
- `\hlinkactive` itself is dormant before `\hyperlinks` occurs. Until then, a
- dummy \`\hlink` is used. \OpTeX/'s `\hyperlinks` is extended to hook `\hlink`
- activation. The colors of internal/external links are remembered for
- compatibility with \OpTeX/.
+ Use `\hlink` as the backing command for OpTeX's \"higher level" linking
+ commands (`\ilink` and `\ulink`).
+
+ The lower level ones (`\xlink` and its predecessor `\link` actually have
+ completely different semantics with regards to color, so we keep them as they
+ are.
\_cod
-\_def\.hlink[#1]#2{\_quitvmode{#2}}
-\_nspublic \hlink ;
+\_protected\_def\_ilink[#1]#2{\.hlink[#1]{#2}}
+\_protected\_def\_ulink[#1]#2{{\_escapechar=-1 \_ea}\_expanded
+ {\_noexpand\.hlink[url:\_detokenize{#1}]}{#2}}
-\_let\.oldhyperlinks\_hyperlinks
-\_def\_hyperlinks#1#2{%
- \.oldhyperlinks#1#2
- \_let\.ilinkcolor=#1%
- \_let\.elinkcolor=#2%
- \_let\.hlink=\.hlinkactive
- \_let\hlink=\.hlink
-}
-\_public \hyperlinks ;
+\_public \link \ilink \ulink ;
+
+%\_protected\_def\_link[#1]#2#3{\_hlink[#1]{#3}}
+%\_protected\_def\_xlink#1#2#3#4{\_hlink[#1:#2]{#4}}
\_doc
Two customizations of `\hlinks` are possible:
@@ -421,10 +433,12 @@
running text~-- it covers all space of a line using `\baselineskip`.
\`\nolininglinks` sets no dimensions, this is useful for buttons, that may
have larger height/depth than a line.
- * The color is determined from the type of link (that is the first action in
- <action spec>) by checking `\_<type>linkcolor` (compatible with \OpTeX/) or
- `\_pdfextra_<type>linkcolor`.
- As a fallback \`\.ilinkcolor` is used (set by `\hyperlinks`).
+ * The color is determined from the type of link (that is, the first action in
+ <action spec>) by checking `\_<type>linkcolor` (compatible with \OpTeX/).
+ As a fallback `\_ilinkcolor` is used (set by \OpTeX's `\hyperlinks`) for all links
+ except for URLs, where `\_elinkcolor` is used instead. If even these
+ fallback colors are not defined (`\hyperlinks` isn't used), then the most
+ generic `\_linkcolor` will be taken or no color will be set.
\enditems
\_cod
@@ -436,8 +450,10 @@
\_nspublic \lininglinks \nolininglinks ;
-\_def\.linkcolor#1{\_trycs{_#1linkcolor}{\.trycs{#1linkcolor}{\.ilinkcolor}}}
-\_def\.ilinkcolor{}
+\_def\.linkcolor#1{\_trycs{_#1linkcolor}{\_trycs{_ilinkcolor}{\_trycs{_linkcolor}{}}}}
+
+ % \_urllinkcolor = \_elinkcolor with fallbacks
+\_def\_urllinkcolor{\.linkcolor{e}}
\_doc
\secc Open action
@@ -683,7 +699,8 @@
\.pdfpageattributesetters Dur \defaultpageduration \pageduration {#1}
\_doc
- \sec Attachments and document level JavaScript
+ \label[nametrees]
+ \sec Name trees -- attachments and document level JavaScript
These don't have any last place to be in, so they are documented separately,
here. Attaching files using `/FileAttachment` annotations:
@@ -711,7 +728,7 @@
\`\dljavascript``[<name>]{<script>}` (adds action that executes <script>
after document is opened, <name> is more or less meaningless).
- Internally both commands construct lists of what ends up in the resulting name
+ Internally the commands construct lists of what ends up in the resulting name
array, i.e. pairs {\visiblesp `(<name>) <object number> 0 R `}. Intermediate
macros \`\.embeddedfiles` and \`\.dljavascripts` are used for this.
@@ -735,7 +752,23 @@
\_nspublic \dljavascript ;
\_doc
- Object creation, which is common to both, is handled by\nl\indent
+ Renditions (see \ref[mm-renditions]) also need their name tree. This package
+ mostly doesn't play well with Unicode filenames, that is why they are
+ forbidden. However, Renditions that are accessed from JavaScript have to be
+ named/present in a `/Renditions` name tree, with the names encoded in the PDF
+ encoding (UTF-16BE).\nl
+ The names and object references are collected in \`\.renditions`. Unicode
+ encoding is hacked with \`\.pdfstringtounicode`.
+ \_cod
+
+\_def\.pdfstringstrip(#1){#1}%
+\_def\.pdfstringtounicode#1#2{%
+ \_ea\_pdfunidef\_ea#1\_ea{\_ea\.pdfstringstrip\_expanded{\.cs{filename:#2}}}%
+}
+\_def\.renditions{}
+
+ \_doc
+ Object creation, which is common to all name trees, is handled by\nl\indent
\`\.makenamearray``<name tree name><name tree content>`.\nl
It doesn't do anything
for empty lists, to not bloat PDF files when this mechanism isn't used.
@@ -750,12 +783,13 @@
The lists themselves can only be written out to the PDF file at the very end
of the run. We use \OpTeX/'s `\_byehook`, which is run in `\_bye`. But `\bye`
itself may be predefined by the user, for example when using some of the
- \OpTeX/ tricks. We just hope that user keeps `\_byehook`.
+ \OpTeX/ tricks. We just hope that the user keeps `\_byehook`.
\_cod
\_addto\_byehook{%
\.makenamearray{EmbeddedFiles}\.embeddedfiles
\.makenamearray{JavaScript}\.dljavascripts
+ \.makenamearray{Renditions}\.renditions
}
\_doc
@@ -889,6 +923,7 @@
\_def\.boxedannot[#1:#2]#3#4#5{%
\_setbox0=\_hbox{#3}\_setbox2=\_null
\_ht2=\_ht0 \_wd2=\_wd0 \_dp2=\_dp0
+ \_preshipout0 \box0
\_immediate\_pdfxform0
% box with annotation both stretching to dimensions of appearance
\_hbox{\.setpageof{#1:#2}%
@@ -995,9 +1030,10 @@
\_ea\_readkv\_ea{\_ea\.renderdefaults\_ea,\_the\_opt}%
\.colortorgbdef\.bgcolor{\_kv{background}}%
% rendition object ("media specifaction")
+ \.pdfstringtounicode\.uiname\.name
\_pdfobj {<</Type /Rendition
/S /MR
- /N \.cs{filename:\.name}
+ /N \.uiname
/C <<%/Type /MediaClip
/S /MCD % subtype MediaClipData
/D \.cs{filespec:\.name}
@@ -1011,6 +1047,7 @@
/BE << /O \_kv{opacity} /B [\.bgcolor] >>
>>
>>}\_pdfrefobj\_pdflastobj
+ \.xaddto\.renditions{\.uiname \_the\_pdflastobj \_space 0 R }%
\.redefinename{rendition}%
\.sxdef{rendition:\.name}{\_the\_pdflastobj}%
% screen annotation ("screen space allocation")
@@ -1284,7 +1321,7 @@
\_doc
For scripting using JavaScript actions one needs to access the 3D context of
the 3D / Rich Media annotation. This requires the page number. We can't use
- `this.pageNum` from [TODO], because the script strictly doesn't have to be on
+ `this.pageNum`, because the script strictly doesn't have to be on
the same page. We use `\.pageof` (`\.setpageof` was done in `\.boxedannot`)
to retrieve the page number in next run. Also PDF indexes page numbers from
0. \`\DDDannot``{<name>}`. and \`\DDDcontext``{<name>}` allow this.
@@ -1593,12 +1630,12 @@
coo=0 0 0,
c2c=0 -1 0,
}
-\.sdef{3dview:media9}{\_edef\.coo{\_kv{coo}}\_edef\.c2c{\_kv{c2c}}\_edef\.viewparams{
+\.sdef{3dview:media9}{\_edef\.viewparams{
/MS /M
/C2W [\_directlua{
local function normalize(x, y, z)
local len = math.sqrt(x*x + y*y + z*z)
- if len ~= 0 then return x/len, y/len, z/len else return 0, 0, 0 end
+ if len \csstring\~= 0 then return x/len, y/len, z/len else return 0, 0, 0 end
end
local function cross(ux, uy, uz, vx, vy, vz)
return uy*vz - uz*vy, uz*vx - ux*vz, ux*vy - uy*vx
@@ -1689,14 +1726,3 @@
\_endnamespace
\_endcode
-
-This is the technical documentation. It is intended for those who want to know
-how this package works internally. Casual users shouldn't need to read this. But
-if you would like to customize anything or perhaps just use some part of this
-package, feel free to copy paste and use anything you want in \OpTeX/'s spirit.
-
-This documentation is interleaved within the source itself, both are contained
-in a single file, `pdfextra.opm` (according to \OpTeX/ conventions). The user
-documentation is instead contained in `pdfextra-doc.tex`, which itself
-`\input`'s the documented source file `pdfextra.opm` so that the user and
-technical documentation is available in a single PDF file, `pdfextra-doc.pdf`.