summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/ocgx2
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2017-03-30 21:32:38 +0000
committerKarl Berry <karl@freefriends.org>2017-03-30 21:32:38 +0000
commit0e46115a9e4b82fb0937ed78d10fef17016d34fe (patch)
treec952efa573d89d57f9f63a01f48e0a6ed092d915 /Master/texmf-dist/doc/latex/ocgx2
parentac3830965b467b1923d14cf499dcd03d39868082 (diff)
ocgx2 (30mar17)
git-svn-id: svn://tug.org/texlive/trunk@43648 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/ocgx2')
-rw-r--r--Master/texmf-dist/doc/latex/ocgx2/ChangeLog13
-rw-r--r--Master/texmf-dist/doc/latex/ocgx2/README44
-rw-r--r--Master/texmf-dist/doc/latex/ocgx2/README.md168
3 files changed, 213 insertions, 12 deletions
diff --git a/Master/texmf-dist/doc/latex/ocgx2/ChangeLog b/Master/texmf-dist/doc/latex/ocgx2/ChangeLog
index b14bae15848..fdf2ee2934d 100644
--- a/Master/texmf-dist/doc/latex/ocgx2/ChangeLog
+++ b/Master/texmf-dist/doc/latex/ocgx2/ChangeLog
@@ -1,3 +1,16 @@
+2017-03-30
+ * v0.24 : ocgx2.sty
+ * fix: \ocglinkprotect{...} messing up the graphics state (CTM)
+
+2017-03-30
+ * v0.23 : ocgx2.sty
+ * v0.10 : ocgbase.sty
+ * fix: nested ocgcolorlinks over multiple pages
+
+2017-03-26
+ * v0.22 : ocgx2.sty
+ * fix: nested ocgcolorlinks
+
2017-03-23
* v0.21 : ocgx2.sty
* v0.9 : ocgbase.sty
diff --git a/Master/texmf-dist/doc/latex/ocgx2/README b/Master/texmf-dist/doc/latex/ocgx2/README
index 8e6c2c7b9e1..c1c4dd797ce 100644
--- a/Master/texmf-dist/doc/latex/ocgx2/README
+++ b/Master/texmf-dist/doc/latex/ocgx2/README
@@ -1,7 +1,7 @@
==================================
The `ocgx2' LaTeX Package
- Version 0.22 [2017/03/26]
+ https://github.com/agrahn/ocgx2
(C) 2015--\today Alexander Grahn
==================================
@@ -21,23 +21,25 @@ packages and adds support for all known engines and back-ends including:
* (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 that can extend over line and
- page breaks
-
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
+To enable dvipdfmx support, pass `dvipdfmx' globally as a class option.
+
+ * New features:
+
+ + PDF layers extending over page breaks
+ + grouping PDF layers into Radio Button Groups
+ + 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. With
+ pdfLaTeX/LuaLaTeX, OCG links can be nested.
+
+Coloured OCG links are enabled with
\usepackage{hyperref} % do NOT set [ocgcolorlinks] here!
\usepackage[ocgcolorlinks]{ocgx2}
@@ -127,6 +129,24 @@ been provided:
See the `ocg-p' package manual for the meaning of `triggerocg=...'.
+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}}!}
+
+Alternatively, the whole link can be placed inside
+
+ \hypersetup{breaklinks=false}...\hypersetup{breaklinks=true}
+
+to temporarily disable breakable links.
+
* * *
diff --git a/Master/texmf-dist/doc/latex/ocgx2/README.md b/Master/texmf-dist/doc/latex/ocgx2/README.md
new file mode 100644
index 00000000000..7468aebd3c8
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/ocgx2/README.md
@@ -0,0 +1,168 @@
+# The `ocgx2` LaTeX Package
+
+© 2015--`\today`, Alexander Grahn
+
+https://github.com/agrahn/ocgx2
+
+## 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 &rArr; dvips &rArr; ps2pdf/Distiller
+- (Xe)LaTeX &rArr; (x)dvipdfmx
+- pdfLaTeX, LuaLaTeX
+
+Also, it adds some features, 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, a re-implementation of **`hyperref`**'s
+**`ocgcolorlink`** option.
+
+To enable dvipdfmx support, pass `dvipdfmx` globally as a class option.
+
+----
+
+*New features:*
+
++ layers extending across **page breaks**
++ grouping layers into **Radio Button Groups**
++ 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**. Moreover, with pdfLaTeX/LuaLaTeX, OCG
+coloured links can be **nested**.
+
+Coloured OCG links are enabled with
+
+````latex
+\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:
+````latex
+\usepackage[tikz]{ocgx2}
+````
+instead of
+````latex
+\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.
+
+## Usage
+
+````latex
+\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
+
+showingui
+radiobtngrp = <group name>
+tikz
+ocgcolorlinks
+````
+**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:
+````latex
+\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:
+````latex
+\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=...`.
+
+----
+
+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
+````latex
+\ocglinkprotect{...}
+````
+
+For example:
+````latex
+\href{http://ctan.org}{Visit me on \ocglinkprotect{\includegraphics{ctan-lion}}!}
+````
+
+Alternatively, the whole link can be placed inside
+````latex
+\hypersetup{breaklinks=false}...\hypersetup{breaklinks=true}
+````
+to temporarily disable breakable links.
+
+## License
+
+This material is subject to the [LaTeX Project Public License](http://mirrors.ctan.org/help/Catalogue/licenses.lppl.html
+).
+