summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/ocgx2/README
blob: f8e57ece789fa6dc12f205b6986486c377fc6ac3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
==================================
 The `ocgx2' LaTeX Package

 Version 0.18 [2017/03/07]

 (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.

  * New features:

    +  layers extending across page breaks
    +  grouping layers into Radio Button Groups
    +  OCG coloured links for hyperref

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.

Coloured links in the PDF viewer that are printed on paper in the default text
colour are enabled with

  \usepackage{hyperref} % do NOT set [ocgcolorlinks] here!
  \usepackage[ocgcolorlinks]{ocgx2}

`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 /tikz/ocg/opts=<ocg options> parameter adds to the list in section
`How to add TikZ scopes into OCGs' in the `ocgx' manual. It allows
passing ocg environment options (see below) to the TikZ scope.


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
                listintoolbar= always | never | iffirstuse

    not in ocgx, ocg-p:

                showingui (same as `listintoolbar')
                radiobtngrp = <group name> (string; environment-only option)

                tikz  (package-only option, see above)
                ocgcolorlinks  (package-only option, see above)

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{<layer IDs to toggle, space separated>}{<link text>}
  \showocg{<layer IDs to switch ON, space separated>}{<link text>}
  \hideocg{<layer IDs to switch OFF, space separated>}{<link text>}
  \actionsocg{<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

For compatibility with the `ocg-p' package, the following commands have
been provided:

  \toggleocgs[triggerocg=...]{<layer IDs to toggle, space separated>}{<link text>}
  \showocgs[triggerocg=...]{<layer IDs to switch ON, space separated>}{<link text>}
  \hideocgs[triggerocg=...]{<layer IDs to switch OFF, space separated>}{<link text>}
  \setocgs[triggerocg=...]{<IDs to toggle>}{<IDs to switch ON>}{<IDs to switch OFF>}{<link text>}

See the `ocg-p' package manual for the meaning of `triggerocg=...'.


                     * * *


This material is subject to the LaTeX Project Public License version 1.3.

See

   http://mirrors.ctan.org/help/Catalogue/licenses.lppl.html

for the details of that license.