summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/ocgx2/README.txt
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-01-02 22:38:58 +0000
committerKarl Berry <karl@freefriends.org>2019-01-02 22:38:58 +0000
commite057511ee0bd3ecc87a47be76805cf26e8936d9b (patch)
tree376b735ab0de3ca14b4796d57f9d7f814578af80 /Master/texmf-dist/doc/latex/ocgx2/README.txt
parent96127255d3941d19fe21092832cd440feb3b389e (diff)
ocgx2 (2jan19)
git-svn-id: svn://tug.org/texlive/trunk@49580 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/ocgx2/README.txt')
-rw-r--r--Master/texmf-dist/doc/latex/ocgx2/README.txt182
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.