diff options
Diffstat (limited to 'macros/luatex/optex/pdfextra/pdfextra-doc.tex')
-rw-r--r-- | macros/luatex/optex/pdfextra/pdfextra-doc.tex | 122 |
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 |