Debian Codegraph @

texmf-dist/source/latex/ocgx/ocgx-manual-en.tex

raw
1 % Copyright (C) 2012 by Paul Gaborit
2 %
3 % This file may be distributed and/or modified
4 %
5 % 1. under the LaTeX Project Public License and/or
6 % 2. under the GNU Public License.
7
8 \documentclass[a4paper]{ltxdoc}
9 \usepackage[vmargin=2cm,hmargin=3.5cm,nohead]{geometry}
10 \usepackage[latin1]{inputenc}
11 \usepackage[T1]{fontenc}
12 \usepackage{lmodern}
13 \usepackage{xcolor}
14 \usepackage{ifthen}
15 \usepackage{doc}
16 \usepackage{fancyvrb}
17 \usepackage{newverbs}
18 \usepackage{listings}
19 \lstdefinestyle{TeXcode}{
20 fancyvrb=true,
21 language=[LaTeX]TeX,
22 basicstyle=\ttfamily,
23 upquote=true,
24 keywordstyle=\color{blue}\bfseries,
25 commentstyle=\color{red!50!black}\itshape,
26 stringstyle=\ttfamily\color{green!50!black},
27 showspaces=false,
28 showstringspaces=false,
29 backgroundcolor=\color{blue!10},
30 fontadjust=true,
31 aboveskip=1ex,
32 belowskip=1ex,
33 emphstyle=\color{blue}\bfseries,
34 keepspaces=true,
35 flexiblecolumns=true,
36 emph={switchocg,showocg,hideocg,actionsocg,usetikzlibrary,node}
37 }
38 \makeatletter
39 \newenvironment{prog}[1]{\vspace{1ex}--- \texttt{\emph{#1}} ---}{}
40 \newenvironment{ocgXample}[1]{% name
41 \gdef\ocgXample@filename{#1}%
42 \@tempswafalse\filec@ntents{#1}%
43 }
44 {\endfilecontents\aftergroup\showocgXample}
45 \newcommand\showocgXample{
46 \minipage{1.0\linewidth}%
47 \prog{\ocgXample@filename}
48 \lstinputlisting[style=TeXcode,aboveskip=0ex]\ocgXample@filename%
49 \endprog
50 \endminipage
51 }
52
53 \newcommand{\TeXexample}[3][]{%
54 \begin{minipage}{1.0\linewidth}
55 \ifthenelse{\equal{#1}{}}{\begin{prog}{#2}}{\begin{prog}{#2 (#1)}}%
56 \lstinputlisting[style=TeXcode,aboveskip=0ex,#3]{#2}%
57 \end{prog}
58 \end{minipage}\par
59 }
60 \makeatother
61
62 \usepackage{url}
63 \usepackage[colorlinks]{hyperref}
64 \usepackage[english]{babel}
65 \usepackage[babel]{microtype}
66 \setlength{\parindent}{0pt}
67 \setlength{\parskip}{.4\baselineskip plus .5\baselineskip minus .2\baselineskip}
68 \usepackage{tikz}
69 \usetikzlibrary{shadows}
70 \usepackage[all]{nowidow}
71 \usepackage{ocgx}
72 \usepackage{filecontents}
73
74 \newcounter{mynotes}
75 \newenvironment{note}{%
76 \vspace{5pt}
77 \tikzpicture
78 \node[%draw=black,line width=.1pt,
79 rounded corners=1em,
80 inner xsep=1.3em, inner ysep=.8em,
81 text width=\linewidth-2.6em-\pgflinewidth,
82 align=justify,
83 draw=cyan!50!black,
84 fill=white,
85 fill=yellow!20,
86 line width=1pt,
87 drop shadow={fill=cyan!50!black},
88 ] (note) \bgroup%
89 }{%
90 \egroup;
91 \node[circle,overlay,
92 %fill=white,draw=cyan!50!black,
93 draw=white,fill=cyan!50!black,text=white,
94 line width=2pt,
95 drop shadow={fill=cyan!50!black},
96 font=\small\bfseries,inner sep=4pt]
97 at (note.north west){\stepcounter{mynotes}\arabic{mynotes}};
98 \endtikzpicture\par\vspace{.1em}%
99 }
100
101
102 \newverbcommand\code{\color{red}}{}
103 \newverbcommand\style{\hspace{-2em}\color{red}}{}
104 \newcommand\defaultvalue[1]{\hfill(#1)}
105 \newcommand\argument[1]{\textcolor{black}{\ttfamily #1}}
106 \newcommand\TikZ{Ti\emph{k}Z}
107
108 \title{The \texttt{ocgx} package (version \ocgxversion)}
109 \author{%
110 Paul \textsc{Isambert}
111 \and%
112 Paul \textsc{Gaborit}\\\url{[email protected]}}
113 \date{\today}
114
115 \begin{document}
116 \maketitle
117
118 \tableofcontents
119
120 \section*{Abstract}
121
122 The \code+ocgx+ package extends the \code+ocg-p+ package which allows
123 you to create OCGs (\emph{Optional Content Group}) in PDF documents.
124
125 Every OCG includes \TeX{} material into a layer of the PDF file. Each of
126 these layers can be displayed or not. Links can enable or disable the
127 display of OCGs.
128
129 The \code+ocgx+ package does not use Javascript embedded in the PDF
130 document to enable (to show) or disable (to hide) OCGs.
131
132 \begin{note}
133 OCGs are usable with several PDF readers: to date, it has been
134 successfully tested with \emph{Acrobat Reader}, \emph{Foxit Reader},
135 \emph{PDF-XChange-Viewer}, and \emph{Evince}. The management of OGCs
136 by \emph{Evince} is not yet fully debugged: it still sometimes crash!
137 \end{note}
138
139 \section{Usage}
140
141 Here is a simple example.
142
143 \begin{ocgXample}{ocgx-example-1.tex}
144 \documentclass{article}
145 \usepackage{ocgx}
146 \begin{document}
147 \begin{ocg}{OCG 1}{ocg1}{1}
148 first example.
149 \end{ocg}
150
151 \switchocg{ocg1}{Button.}
152 \end{document}
153 \end{ocgXample}
154
155 This document creates an OCG called \emph{ocg1} containing the text
156 ``\emph{first example.}'' which is visible. You can show or hide this
157 OCG by clicking the link ``\emph{Button.}''.
158
159 \subsection{Create OCGs}
160
161 The following code creates an OCG named \emph{OCG name} with
162 \emph{refocg} as internal reference. The content of this OCG is
163 ``\emph{content...}''. This OCG is visible (the third argument is 1).
164
165 \begin{ocgXample}{ocgx-example-2}
166 \begin{ocg}{OCG name}{refocg}{1}
167 content...
168 \end{ocg}
169 \end{ocgXample}
170
171 \DescribeEnv{ocg}%
172 The \code+ocg+ environment (provided by the package \code+ocg-p+)
173 creates OCGs. It requires three arguments. The first argument is the
174 name of the OCG as it appears in the layer toolbar of the PDF
175 viewer. The second argument is the internal name used to reference this
176 OCG. The third argument sets the initial visibility of the OCG when the
177 document is opened (1 for visible, 0 for invisible). The content of the
178 environment (any \TeX material) is added into the OCG.
179
180 \begin{note}
181 The same reference can be used with several \code+ocg+ environments (not
182 necessarily in the same page). All materials are grouped in the same
183 OCG. Only the first name provided will be used.
184 \end{note}
185
186 \begin{note}
187 A reference of an OCG consists of letters (A-Z, a-z), numbers (0-9).
188 \end{note}
189
190 \begin{note}
191 The content of the \code+ocg+ environment should not span across
192 multiple pages. Currently, nothing prevents you to try it but the
193 result will certainly not be the one you were expecting!
194 \end{note}
195
196 \begin{note}
197 It is possible to nest an OCG in another OCG. To display the internal
198 OCG, both the internal and external OCGs need to be in the visible
199 state.
200 \end{note}
201
202 \subsection{Manage the visibility of OCGs}
203
204 \DescribeMacro{\switchocg}%
205 The \code+\switchocg+ macro turns its second argument into a clickable
206 link that toggles the visibility status of all listed OCGs (by their
207 reference) in its first argument: if an OCG was visible, it becomes
208 invisible, and conversely, if an OCG was invisible, it becomes visible.
209
210 The following code creates the link \emph{toggle} that switches the
211 visibility status of OCGs whose references are \emph{ocg1} and
212 \emph{ocg2}:
213
214 \begin{lstlisting}[style=TeXcode]
215 \switchocg{ocg1 ocg2}{toggle}
216 \end{lstlisting}
217
218 \DescribeMacro{\showocg}%
219 The \code+\showocg+ macro turns its second argument into a clickable
220 link that make visible all OCGs whose references are listed in its first
221 argument: an invisible OCG becomes visible and an OCG already visible
222 remains visible.
223
224 The following code creates the link \emph{show} which makes visible the
225 OCGs whoses references are \emph{ocg1} and \emph{ocg2}:
226
227 \begin{lstlisting}[style=TeXcode]
228 \showocg{ocg1 ocg2}{show}
229 \end{lstlisting}
230
231 \DescribeMacro{\hideocg}%
232 The \code+\hideocg+ macro turns its second argument into a clickable
233 link that make invisible all OCGs whose references are listed in its
234 first argument: a visible OCG becomes invisible and an OCG already
235 invisible remains invisible.
236
237 The following code creates the link \emph{hide} which makes invisible
238 the OCGs whoses references are \emph{ocg1} and \emph{ocg2}:
239
240 \begin{lstlisting}[style=TeXcode]
241 \hideocg{ocg1 ocg2}{hide}
242 \end{lstlisting}
243
244 \DescribeMacro{\actionsocg}%
245 The \code+\actionsocg+ macro transforms its fourth argument into a
246 clickable link. Its three first arguments are lists of references of
247 OCGs. The first list contains references of OCGs which visibility status
248 is to be toggled. The second list contains references of OCGs to be set
249 visible. The third list contains references of OCGs to be set invisible.
250
251 The following code creates the link \emph{actions} to toggle the
252 visibility status of the OCG named \emph{ocg1}, to make visible the OCG
253 named \emph{ocg3}, and to make invisible OCG named \emph{ocg2}:
254
255 \begin{lstlisting}[style=TeXcode]
256 \actionsocg{ocg1}{ocg3}{ocg2}{actions}
257 \end{lstlisting}
258
259 \subsection{Usage with \TikZ{}}
260
261 You can use the \code+ocgx+ package with \TikZ{}. The package provides a
262 \TikZ{} library offering some specific styles to add material to OCGs,
263 or to transform a path (\code+\path+ or \code+\node+) into a clickable
264 link. To use it, simply add the following lines in your preamble:
265
266 \begin{ocgXample}{ocgx-tikz-preamble}
267 \usepackage{tikz}
268 \usetikzlibrary{ocgx}
269 \end{ocgXample}
270
271 \subsubsection*{How to add \TikZ{} scopes into OCGs}
272
273 \begin{list}{}
274 \item
275
276 \noindent\style+/tikz/ocg+\argument{=\{\emph{<ocg options>}\}}
277
278 The \code+ocg+ family is used to specify the options used to add a
279 scope into an OCG.
280
281 \begin{list}{}
282 \item
283
284 \noindent\style+/tikz/ocg/ref+\argument{=\emph{<refname>}}\defaultvalue{no
285 default}
286
287 This option add the current scope to the OCG referenced by
288 \texttt{refname}. If this OCG does not exist, it is created with
289 \texttt{name} and visibility \texttt{status} specified by the
290 two options below.
291
292 \noindent\style+/tikz/ocg/name+\argument{=\emph{<name>}}\defaultvalue{no
293 default, initially empty}
294
295 It is the \texttt{\emph{name}} of the OCG as it appears in the PDF
296 viewer. If the OCG is already created, this option is useless.
297
298 \noindent\style+/tikz/ocg/status+\argument{=\emph{<visibility>}}\defaultvalue{no
299 default, initially \texttt{visible}}
300
301 Specify the initial visibility state of the OCG. Permissible values
302 are \texttt{visible}, and \texttt{invisible}. If the OCG is already
303 created, this option is useless.
304
305 \end{list}
306
307 \begin{note}
308 If you prefer, you can also use the \code+ogc+ environment in a
309 \code+tikzpicture+. The \code+pgfonlayer+ environment is special:
310 inside, you must reuse options below, or use a new \code+ocg+
311 environment.
312 \end{note}
313
314 \end{list}
315
316 \subsubsection*{How to transform nodes or paths into clickable links}
317
318 \begin{list}{}
319 \item
320
321 \noindent\style+/tikz/switch ocg+\argument{=\{\emph{<OCGs list>}\}}
322
323 This style transforms the current path or the current node in a link acting as
324 if it was produced by the macro \code+\switchocg+ (the visibility
325 status of referenced OCGs is reversed).
326
327 \noindent\style+/tikz/show ocg+\argument{=\{\emph{<OCGs list>}\}}
328
329 This style transforms the current path or the current node in a link acting as
330 if it was produced by the macro \code+\showocg+ (the referenced OCGs
331 are made visible).
332
333 \noindent\style+/tikz/hide ocg+\argument{=\{\emph{<OCGs list>}\}}
334
335 This style transforms the current path or the current node in a link acting as
336 if it was produced by the macro \code+\hideocg+ (the referenced OCGs
337 are made invisible).
338
339 \noindent\style+/tikz/actions ocg+\argument{=\{\emph{<OCGs
340 list>}\}\{\emph{<OCGs list>}\}\{\emph{<OCGs list>}\}}
341
342 This style transforms the current path or the current node in a link acting as
343 if it is produced by the macro \code+\actionsocg+ (the visibility
344 status of OCGs of the first list is reversed, the OCGs in the second
345 list are made visible and those of the third list are made invisible).
346
347 \noindent\style+/tikz/switch ocg with mark on+\argument{=\{\emph{<ocg
348 reference>}\}\{\emph{<OCGs list>}\}}
349
350 \noindent\style+/tikz/switch ocg with mark off+\argument{=\{\emph{<ocg
351 reference>>}\}\{\emph{<OCGs list>}\}}
352
353 These styles transform the current path or the current node in a link acting
354 as if it is produced by the macro \code+\switchocg+ (the visibility
355 status of referenced OCGs in the list is reversed).
356
357 A mark (currently a simple cross) is drawn over the current path or
358 node in an OCG whose reference is \texttt{\emph{ocg reference}}. The
359 visibility status of this OCG will be reversed as those of the entire
360 list.
361
362 If the OCG whose reference is \texttt{\emph{ocg reference}} does not
363 exist, it is created with an empty name and its initial visibility
364 state is true with \code+on+ and false with \code+off+.
365
366 \end{list}
367
368 \begin{note}
369 Due to limitation of PDF, whatever the shape of the current path or
370 node is, it is its \emph{bounding box} that is used to make the link:
371 the link is always \emph{rectangular} and \emph{horizontal}!
372 \end{note}
373
374 \subsubsection*{Example with \TikZ{}}
375
376 \begin{filecontents*}{ocgx-example-3}
377 \begin{tikpicture}
378 \begin{scope}[ocg={name=TikZ example,ref=tikzex,status=visible}
379 \fill[orange] (0,0) circle (1);
380 \end{scope}
381 \node[draw,switch ocg=tikzref] at (2,0) {Switch};
382 \end{tikpicture}
383 \end{filecontents*}
384 \TeXexample{ocgx-example-3}{}
385
386
387
388 \section{Examples}
389
390 The document \code+demo-ocgx.tex+ provides several examples of usage of
391 package \code+ocgx+ with \TikZ{} (and \code+beamer+).
392
393 \section{Limits and bugs}
394
395 \begin{enumerate}
396 \item Links are always horizontal rectangles!
397 \item An \code+ocg+ environment spanning across multiple pages are not
398 detected and don't work correctly.
399 \item The packages \code+ocg-p+ and \code+ocgx+ are not compatible with
400 Plain-\TeX{}.
401 \item While \code+ocg-p+ is usable with \code+pdflatex+ and
402 \code+xelatex+, \code+ocgx+ works only with \code+pdflatex+ (and
403 \code+lualatex+).
404 \end{enumerate}
405
406 \section{Development and history}
407 This package is still experimental. It is released on CTAN. You can
408 donwload the latest version from \url{https://github.com/polgab/ocgx}. Any
409 help to participate in its development is welcome: contact the
410 maintainer (\url{[email protected]}).
411
412 \paragraph{version 0.5} (2012-12-07) Now, the \code+ocgx+ package uses
413 the new \code+ocg-p+ package instead of the \code+ocg+ package : the
414 layers can be nested in the layer toolbar of the PDF viewer.
415
416 \paragraph{version 0.4} (2012-11-14) Added dependancy to \texttt{calc}
417 TikZ library. Fixed bug: bad lists in \code+\actionsocg+.
418
419 \paragraph{version 0.3} (2012-09-30) Complete documentation for part
420 \emph{Usage with TikZ} and correct TDS archive.
421
422 \paragraph{version 0.2} (2012-09-27) First release on CTAN.
423 \end{document}
424
425
426
427 %%% Local Variables:
428 %%% mode: latex
429 %%% TeX-master: t
430 %%% End: