diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/ocgx2/README.txt')
-rw-r--r-- | Master/texmf-dist/doc/latex/ocgx2/README.txt | 182 |
1 files changed, 182 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/ocgx2/README.txt b/Master/texmf-dist/doc/latex/ocgx2/README.txt new file mode 100644 index 00000000000..e1788656734 --- /dev/null +++ b/Master/texmf-dist/doc/latex/ocgx2/README.txt @@ -0,0 +1,182 @@ +================================== + The `ocgx2' LaTeX Package + + https://gitlab.com/agrahn/ocgx2 + + (C) 2015--\today Alexander Grahn +================================== + + +1. Introduction +=============== + +This package serves as a drop-in replacement for the already existing +packages `ocgx' by Paul Gaborit and `ocg-p' by Werner Moshammer for the +creation of PDF Layers. + +It re-implements the functionality of the `ocg', `ocgx' and `ocg-p' +packages and adds support for all known engines and back-ends including + + * LaTeX --> dvips --> ps2pdf/Distiller + * (Xe)LaTeX --> (x)dvipdfmx + * pdfLaTeX, luaLaTeX + +To enable dvipdfmx support, pass `dvipdfmx' globally as a class option. + +Also, it adds some minor improvements and bug fixes, such as package +options, remembering option settings of re-opened ocgs, correct behaviour +of layer switching links that were themselves placed on layers, correct +listing of (nested) ocgs in the layers tab of PDF viewers, compatibility +with the `animate' and `media9' packages. + + * New features: + + + PDF layers extending over page breaks + + grouping PDF layers into Radio Button Groups + + additional keys for the TikZ interface of package `ocgx' + + re-implementing `hyperref's `ocgcolorlinks' option for creating + OCG coloured links, which are printed on paper in the default + text colour and which can, unlike the original `hyperref' + implementation, extend over line and page breaks. + + +2. Usage +======== + +\usepackage[<options>]{ocgx2} + +\begin{ocg}[<options>]{<layer name>}{<layer id>}{<initial visibility>} + ... material to be put on a PDF layer ... +\end{ocg} + +With <initial visibility> = ( on | true | 1 ) | ( off | false | 0 ) + +and <options> : viewocg = always | never | ifvisible + printocg = always | never | ifvisible + exportocg = always | never | ifvisible + + not in ocgx, ocg-p: + + showingui (to be preferred over `listintoolbar' of ocgx/ocg-p) + radiobtngrp = <group name> (string; environment-only option) + + tikz (package-only option) + ocgcolorlinks (package-only option) + +Package options have global scope. Environment options override package +options locally. + +Layers can be added to one or several Radio Button Groups using the new +option `radiobtngrp'. From all layers within a Radio Button Group only +one can be enabled at a time. Enabling a layer, e. g. in the Layers tab +of the PDF viewer, automatically hides the previously visible layer. +Option `radiobtngrp' can be used repeatedly for the same OCG in order +to add the layer to more than one Radio Button Group. + +`ocg' environments can be nested and span multiple pages. + +See the `ocg-p' manual about the environment usage and the meaning of +the remaining options: + + texdoc ocg-p + +Clickable links for switching PDF layer visibility are created with: + + \switchocg[<trigger>]{<layer IDs to toggle, space separated>}{<link text>} + \showocg[<trigger>]{<layer IDs to switch ON, space separated>}{<link text>} + \hideocg[<trigger>]{<layer IDs to switch OFF, space separated>}{<link text>} + \actionsocg[<trigger>]{<IDs to toggle>}{<IDs to switch ON>}{<IDs to switch OFF>}{<link text>} + +For details about their usage, read the `ocgx' package manual: + + texdoc ocgx + +By default, links are triggered on mouse-click. Other triggers are possible +with `ocgx2'. For this, `ocgx2' provides the optional argument [<trigger>] to +the commands listed above. Choose one of + + onmousenter, onmouseexit, onmousedown, onmouseup, onmouseall + +for <trigger>. In order to listen to more than one mouse event, use +`onmouseall'. Layer IDs in the mandatory argument(s) must then be grouped with +commas as follows: + + <mouse-enter group>, <mouse-exit group>, <mouse-down group>, <mouse-up group> + +Any of these groups may be left empty in order to configure only some +mouse triggers. Inside the groups, layer IDs are separated by space. + + +3. Package option `ocgcolorlinks' +================================= + +Is a re-implementation of the same `hyperref' option for creating OCG- +coloured links, which are printed on paper in the default text colour. + + \usepackage{hyperref} % do NOT set [ocgcolorlinks] here! + \usepackage[ocgcolorlinks]{ocgx2} + +Unlike the original `hyperref' implementation, OCG-coloured links are now +allowed to extend over line and page breaks. Moreover, with pdfLaTeX/LuaLaTeX, +OCG coloured links can be nested. + +Breakable OCG coloured links work best with normal text as link text. If +the link text is mixed with graphical content, such as from external files or +inline graphics (e. g. TikZ) and even \fbox-ed text, these graphical parts must +be enclosed in + + \ocglinkprotect{...} + +For example: + + \href{http://ctan.org}{Visit me on + \ocglinkprotect{\includegraphics{ctan-lion}}!} + + +4. Usage with TikZ +================== + +`ocgx2' uses code from file `tikzlibraryocgx.code.tex' by P. Gaborit to +enable TikZ styles for creating PDF Layers and clickable layer switching +links in the `tikzpicture' context. + +Just say: + + \usepackage[tikz]{ocgx2} + +instead of + + \usepackage{tikz} + \usetikzlibrary{ocgx} + +to enable these TikZ styles and read the `ocgx' documentation about +their usage: + + texdoc ocgx + +The key `/tikz/ocg/opts' was added to the list in section +`How to add TikZ scopes into OCGs' in the `ocgx' manual: + + /tikz/ocg/opts={<ocg options>} + +It allows passing `ocg'-environment options (`viewocg', `printocg', `exportocg', +`showingui', `radiobtngrp') to the TikZ scope. + +Moreover, TikZ objects to be turned into OCG switching hyperlinks (section "How +to transform nodes or paths into clickable links" in the `ocgx' manual) accept +the additional key + + /tikz/trigger ocg = onmousenter | onmouseexit | onmousedown | onmouseup + | onmouseall + +which makes them listen to various mouse events, as explained above. + + + * * * + + +This material is subject to the LaTeX Project Public License. See + + http://mirrors.ctan.org/macros/latex/base/lppl.txt + +for the details of that license. |