summaryrefslogtreecommitdiff
path: root/macros/luatex/optex/pdfextra/pdfextra-doc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/optex/pdfextra/pdfextra-doc.tex')
-rw-r--r--macros/luatex/optex/pdfextra/pdfextra-doc.tex122
1 files changed, 105 insertions, 17 deletions
diff --git a/macros/luatex/optex/pdfextra/pdfextra-doc.tex b/macros/luatex/optex/pdfextra/pdfextra-doc.tex
index 38f6cd9795..292bb34ab2 100644
--- a/macros/luatex/optex/pdfextra/pdfextra-doc.tex
+++ b/macros/luatex/optex/pdfextra/pdfextra-doc.tex
@@ -2,8 +2,6 @@
\load [doc, pdfextra]
\catcode`\.=11
-\hyperlinks\Green\Green
-
% table notes (http://petr.olsak.net/optex/optex-tricks.html#tnote)
\newcount\tnotenum
\def\tnotelist{}
@@ -14,22 +12,23 @@
\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
+\let\_pdfextra_extdocaction\_pdfextra_urlaction
+\let\_extdoclinkcolor\Blue
\def\_Xindex#1#2{\sdef{,#1}{}\slet{el:#1}{optexdoclink}}
-\def\optexdoclink{\hlink[opdoc:\optexdocurl\#cs:\_tmpa]{\csstring\\\_tmpb}}
+\def\optexdoclink{\hlink[extdoc:\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
+% allow hyperlinks to TeX's control sequences (TeX in a Nutshell)
+\def\Xeref#1{\sdef{,#1}{}\slet{el:#1}{texdoclink}}
+\def\texdoclink{\hlink[extdoc:\texdocurl\#cs:\_tmpa]{\csstring\\\_tmpb}}
+\def\texdocurl{http://petr.olsak.net/ftp/olsak/optex/tex-nutshell.pdf}
+\isfile{tex-nutshell.eref}\iftrue \input{tex-nutshell.eref}\fi
+
+
\insertoutline{PDF extra}
\tit PDF extra -- extra PDF features for \OpTeX/
@@ -50,7 +49,8 @@ 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/.
+from \OpTeX/. Additionally, the package can be used in plain LuaTeX and
+LuaLaTeX (in a limited form), see section~\ref[user:plain+latex].
User documentation (`pdfextra-doc.tex`) and technical documentation interleaved
with source code (`pdfextra.opm`) are all typeset in this PDF file. Some
@@ -367,7 +367,7 @@ macros like `\ref` or `\url` might be beneficial. <text> will be typeset
directly and the area it occupies will be clickable. Clicking it executes
action defined by <action spec>. Line breaks inside <text> 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
+Normally in text you want the areas 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
@@ -482,7 +482,7 @@ must be unique) and are executed in order of definition. Use
\begtt \adef![#1]{\url{#1}}
\filedef/e[preamble]{preamble.js}
-\djavascript[preamble]{preamble}
+\dljavascript[preamble]{preamble}
\dljavascript[initialization]{%
var data = 42;
@@ -554,7 +554,7 @@ Examples:
\render[video]{\inspic{example-image.pdf}}
% we want the rendition action to have yellow border and red content
-\let\_renditionborder\Yellow
+\def\_renditionborder{1 1 0}
\let\_renditionlinkcolor\Red
To start playing the video, click \hlink[rendition::play]{\"Play"}.
@@ -671,14 +671,102 @@ You can choose what is shown when document is opened with commands:
The commands are mutually exclusive and only the first appearing one will be respected.
-You can set request two page view (odd pages on the right) using
+You can request two page view (odd pages on the right) using
\^`\duplexdisplay`. It is useful for more natural display of double sided
documents. Because it may not be desirable to automatically apply this, it is
independent of `\margins`.
+\label[user:plain+latex]
+\sec Usage in plain \LuaTeX/ or LuaLa\TeX/
+
+You can use this package also from plain LuaTeX by adding to your document:
+
+\begtt
+\input pdfextra
+\endtt
+
+\noindent or for LuaLa\TeX/:
+
+\begtt
+\usepackage{pdfextra}
+\endtt
+
+See the file `pdfextra-example-latex.tex` for the adaptation of the \OpTeX/
+examples to \LaTeX/.
+
+The usage of the macros described in this document is the same, but there are
+limitations:
+
+\begitems
+* {\em Color}. Where this package expects \"\OpTeX/ color" key value argument
+(e.g. `\Blue`), you have to use an RGB triplet instead (e.g. `0.0 0.0 0.0` or
+the shorter `0 0 0`).
+
+But for text color setting, you can get away with wrapping commands from
+La\TeX/'s `color` package, e.g. to customize link border/color:
+
+ \begtt
+ \sdef{_renditionlinkcolor}{\color[red]}
+ \endtt
+
+* {\em Initialization}. In \OpTeX/ you normally have to initialize hyperlinks
+with the command\nl
+`\hyperlinks<color for internal links><color for external links>`.\nl
+This is not required by this package. You can instead set the color by setting
+`\_linkcolor` (fallback for all link types), `\_ilinkcolor` / `\_elinkcolor`
+(internal / external links). E.g. if you have the \LaTeX/ `color` package
+loaded, you can get blue links like this:
+
+ \begtt
+ \sdef{_linkcolor}{\color[blue]}
+ \endtt
+
+In addition to the above this means all links will be blue except \"rendition"
+links.
+
+* {\em Openaction}. If the package `hyperref` is used, then `\openaction` will
+not work.
+
+* {\em Labels / hyperlink destinations}. \OpTeX/ uses very simple and consistent
+scheme for labels / hyperlink destinations:
+
+ \begitems
+ * `ref:<label>` -- result of `\label[<label>]`
+ * `toc:<tocrefnum>` -- result of `\chap`/`\sec`/`\secc` titles
+ * `pg:<gpageno>` -- created on each page with global numbering from 1
+ * `cite:<bibpart>/<bibnum>` -- bibliography references,
+ * `fnt:<gfnotenum>` -- link form text to footnote
+ * `fnf:<gfnotenum>` -- link from footnote to text
+ * `url:<url>` -- used by `\url` or `\ulink`,
+ \enditems
+
+ Hence these labels / destinations can be used with `\hlink`, e.g. to make text
+ `page 5` a link to page 5, one can use:
+
+ \begtt
+ \hlink[pg:5]{page 5}
+ \endtt
+
+ This is not possible in plain \LuaTeX/ (no destinations are created) or
+ LuaLa\TeX/ (different and incompatible destination names). You would have to
+ create your own destinations adhering to the naming convention
+ `<type>:<arguments>` to be able to use `\hlink` as intended for some links.
+
+\enditems
+
\chap Technical documentation
-\printdoctail pdfextra.opm
+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`.
+
\printdoc pdfextra.opm
\bye