diff options
author | Karl Berry <karl@freefriends.org> | 2012-10-04 18:37:38 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2012-10-04 18:37:38 +0000 |
commit | 44ee0abf2e2a1ed4ed69374b15a65d8c0bdadd3e (patch) | |
tree | 2f0763052184c8121d070ae2c5955cdbd8bbc311 /Master/texmf-dist/source/latex/ocgx/ocgx-manual-en.tex | |
parent | bb68138f5309f867ed9b80a6850794104832254f (diff) |
ocgx
git-svn-id: svn://tug.org/texlive/trunk@27878 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/ocgx/ocgx-manual-en.tex')
-rw-r--r-- | Master/texmf-dist/source/latex/ocgx/ocgx-manual-en.tex | 417 |
1 files changed, 417 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/ocgx/ocgx-manual-en.tex b/Master/texmf-dist/source/latex/ocgx/ocgx-manual-en.tex new file mode 100644 index 00000000000..d6f8869c4bf --- /dev/null +++ b/Master/texmf-dist/source/latex/ocgx/ocgx-manual-en.tex @@ -0,0 +1,417 @@ +% Copyright (C) 2012 by Paul Gaborit +% +% This file may be distributed and/or modified +% +% 1. under the LaTeX Project Public License and/or +% 2. under the GNU Public License. + +\documentclass[a4paper]{ltxdoc} +\usepackage[vmargin=2cm,hmargin=3.5cm,nohead]{geometry} +\usepackage[latin1]{inputenc} +\usepackage[T1]{fontenc} +\usepackage{lmodern} +\usepackage{xcolor} +\usepackage{ifthen} +\usepackage{doc} +\usepackage{fancyvrb} +\usepackage{newverbs} +\usepackage{listings} +\lstdefinestyle{TeXcode}{ + fancyvrb=true, + language=[LaTeX]TeX, + basicstyle=\ttfamily, + keywordstyle=\color{blue}\bfseries, + commentstyle=\color{red!50!black}\itshape, + stringstyle=\ttfamily\color{green!50!black}, + showspaces=false, + showstringspaces=false, + backgroundcolor=\color{blue!10}, + fontadjust=true, + aboveskip=1ex, + belowskip=1ex, + emphstyle=\color{blue}\bfseries, + keepspaces=true, + flexiblecolumns=true, + emph={switchocg,showocg,hideocg,actionsocg,usetikzlibrary,node} +} +\makeatletter +\newenvironment{prog}[1]{\vspace{1ex}--- \texttt{\emph{#1}} ---}{} +\makeatother +\newcommand{\TeXexample}[3][]{% + \begin{minipage}{1.0\linewidth} + \ifthenelse{\equal{#1}{}}{\begin{prog}{#2}}{\begin{prog}{#2 (#1)}} + \lstinputlisting[style=TeXcode,aboveskip=0ex,#3]{#2} + \end{prog} + \end{minipage} +} + +\usepackage{url} +\usepackage[colorlinks]{hyperref} +\usepackage[english]{babel} +\usepackage[babel]{microtype} +\setlength{\parindent}{0pt} +\setlength{\parskip}{.4\baselineskip plus .5\baselineskip minus .2\baselineskip} +\usepackage{tikz} +\usetikzlibrary{shadows} +\usepackage[all]{nowidow} +\usepackage{ocgx} +\usepackage{filecontents} + +\newcounter{mynotes} +\newenvironment{note}{% + \vspace{5pt} + \tikzpicture + \node[%draw=black,line width=.1pt, + rounded corners=1em, + inner xsep=1.3em, inner ysep=.8em, + text width=\linewidth-2.6em-\pgflinewidth, + align=justify, + draw=cyan!50!black, + fill=white, + fill=yellow!20, + line width=1pt, + drop shadow={fill=cyan!50!black}, + ] (note) \bgroup% +}{% + \egroup; + \node[circle,overlay, + %fill=white,draw=cyan!50!black, + draw=white,fill=cyan!50!black,text=white, + line width=2pt, + drop shadow={fill=cyan!50!black}, + font=\small\bfseries,inner sep=4pt] + at (note.north west){\stepcounter{mynotes}\arabic{mynotes}}; + \endtikzpicture\par\vspace{.1em}% +} + + +\newverbcommand\code{\color{red}}{} +\newverbcommand\style{\hspace{-2em}\color{red}}{} +\newcommand\defaultvalue[1]{\hfill(#1)} +\newcommand\argument[1]{\textcolor{black}{\ttfamily #1}} +\newcommand\TikZ{Ti\emph{k}Z} + +\title{The \texttt{ocgx} package (version \ocgxversion)} +\author{% + Paul \textsc{Isambert} + \and% + Paul \textsc{Gaborit}\\\url{paul.gaborit@gmail.com}} +\date{\today} + +\begin{document} +\maketitle + +The \code+ocgx+ package extends and documents the \code+ocg+ package +(which comes with Asymptote) which allows you to create OCGs +(\emph{Optional Content Group}) in PDF documents. + +Every OCG includes \TeX{} material into a layer of the PDF file. Each of +these layers can be displayed or not. Links can enable or disable the +display of OCGs. + +The \code+ocgx+ package does not use Javascript embedded in the PDF +document to enable (to show) or disable (to hide) OCGs. + +\begin{note} + OCGs are usable with several PDF readers: to date, it has been + successfully tested with \emph{Acrobat Reader}, \emph{Foxit Reader}, + and \emph{Evince}. The management of OGCs by \emph{Evince} is not yet + fully debugged: it still sometimes crash! +\end{note} + +\section{Usage} + +Here is a simple example. + +\begin{filecontents*}{ocgx-example-1.tex} +\documentclass{article} +\usepackage{ocgx} +\begin{document} +\begin{ocg}{OCG 1}{ocg1}{1} + first example. +\end{ocg} + +\switchocg{ocg1}{Button.} +\end{document} +\end{filecontents*} + +\TeXexample{ocgx-example-1.tex}{} + +This document creates an OCG called \emph{ocg1} containing the text +``\emph{first example.}'' which is visible. You can show or hide this +OCG by clicking the link ``\emph{Button.}''. + +\subsection{Create OCGs} + +\begin{note} + The \code+ocg+ package written by Michael \textsc{Ritzert} comes + without documentation. In my knowledge, the only documentation for + this package is offered (by Kjell Magne Fauske) on the weblog of + TeXample.net: + \url{http://www.texample.net/weblog/2008/nov/02/creating-pdf-layers/}. +\end{note} + +The following code creates an OCG named \emph{OCG name} with +\emph{refocg} as internal reference. The content of this OCG is +``\emph{content...}''. This OCG is visible (the third argument is 1). + +\begin{filecontents*}{ocgx-example-2} +\begin{ocg}{OCG name}{refocg}{1} + content... +\end{ocg} +\end{filecontents*} +\TeXexample{ocgx-example-2}{} + +\DescribeEnv{ocg}% +The \code+ocg+ environment (provided by the package \code+ocg+) creates +OCGs. It requires three arguments. The first argument is the name of the +OCG as it appears in the PDF viewer. The second argument is the internal +name used to reference this OCG. The third argument is a flag that +indicates whether the OCG should be visible or not (1 for visible, 0 for +invisible). The content of the environment (any \TeX material) is added +into the OCG. + +\begin{note} + The same reference can be used with several \code+ocg+ environments (not + necessarily in the same page). All materials are grouped in the same + OCG. Only the first name provided will be used. +\end{note} + +\begin{note} + A reference of an OCG consists of letters (A-Z, a-z), numbers (0-9) + and possibly the \code+@+ character. +\end{note} + +\begin{note} + The content of the \code+ocg+ environment should not span across + multiple pages. Currently, nothing prevents you to try it but the + result will certainly not be the one you were expecting! +\end{note} + +\begin{note} + It is possible to nest an OCG in another OCG. To display the internal + OCG, both the internal and external OCGs need to be in the visible + state. +\end{note} + +\subsection{Manage the visibility of OCGs} + +\DescribeMacro{\switchocg}% +The \code+\switchocg+ macro turns its second argument into a clickable +link that toggles the visibility status of all listed OCGs (by their +reference) in its first argument: if an OCG was visible, it becomes +invisible, and conversely, if an OCG was invisible, it becomes visible. + +The following code creates the link \emph{toggle} that switches the +visibility status of OCGs whose references are \emph{ocg1} and +\emph{ocg2}: + +\begin{lstlisting}[style=TeXcode] +\switchocg{ocg1 ocg2}{toggle} +\end{lstlisting} + +\DescribeMacro{\showocg}% +The \code+\showocg+ macro turns its second argument into a clickable +link that make visible all OCGs whose references are listed in its first +argument: an invisible OCG becomes visible and an OCG already visible +remains visible. + +The following code creates the link \emph{show} which makes visible the +OCGs whoses references are \emph{ocg1} and \emph{ocg2}: + +\begin{lstlisting}[style=TeXcode] +\showocg{ocg1 ocg2}{show} +\end{lstlisting} + +\DescribeMacro{\hideocg}% +The \code+\hideocg+ macro turns its second argument into a clickable +link that make invisible all OCGs whose references are listed in its +first argument: a visible OCG becomes invisible and an OCG already +invisible remains invisible. + +The following code creates the link \emph{hide} which makes invisible +the OCGs whoses references are \emph{ocg1} and \emph{ocg2}: + +\begin{lstlisting}[style=TeXcode] +\hideocg{ocg1 ocg2}{hide} +\end{lstlisting} + +\DescribeMacro{\actionsocg}% +The \code+\actionsocg+ macro transforms its fourth argument into a +clickable link. Its three first arguments are lists of references of +OCGs. The first list contains references of OCGs which visibility status +is to be toggled. The second list contains references of OCGs to be set +visible. The third list contains references of OCGs to be set invisible. + +The following code creates the link \emph{actions} to toggle the +visibility status of the OCG named \emph{ocg1}, to make visible the OCG +named \emph{ocg3}, and to make invisible OCG named \emph{ocg2}: + +\begin{lstlisting}[style=TeXcode] +\actionsocg{ocg1}{ocg3}{ocg2}{actions} +\end{lstlisting} + +\subsection{Usage with \TikZ{}} + +You can use the \code+ocgx+ package with \TikZ{}. The package provides a +\TikZ{} library offering some specific styles to add material to OCGs, +or to transform a path (\code+\path+ or \code+\node+) into a clickable +link. To use it, simply add the following lines in your preamble: + +\begin{filecontents*}{ocgx-tikz-preamble} +\usepackage{tikz} +\usetikzlibrary{ocgx} +\end{filecontents*} +\TeXexample{ocgx-tikz-preamble}{} + +\subsubsection*{How to add \TikZ{} scopes into OCGs} + +\begin{list}{} +\item + + \noindent\style+/tikz/ocg+\argument{=\{\emph{<ocg options>}\}} + + The \code+ocg+ family is used to specify the options used to add a + scope into an OCG. + + \begin{list}{} + \item + + \noindent\style+/tikz/ocg/ref+\argument{=\emph{<refname>}}\defaultvalue{no + default} + + This option add the current scope to the OCG referenced by + \texttt{refname}. If this OCG does not exist, it is created with + \texttt{name} and visibility \texttt{status} specified by the + two options below. + + \noindent\style+/tikz/ocg/name+\argument{=\emph{<name>}}\defaultvalue{no + default, initially empty} + + It is the \texttt{\emph{name}} of the OCG as it appears in the PDF + viewer. If the OCG is already created, this option is useless. + + \noindent\style+/tikz/ocg/status+\argument{=\emph{<visibility>}}\defaultvalue{no + default, initially \texttt{visible}} + + Specify the initial visibility state of the OCG. Permissible values + are \texttt{visible}, and \texttt{invisible}. If the OCG is already + created, this option is useless. + + \end{list} + + \begin{note} + If you prefer, you can also use the \code+ogc+ environment in a + \code+tikzpicture+. The \code+pgfonlayer+ environment is special: + inside, you must reuse options below, or use a new \code+ocg+ + environment. + \end{note} + +\end{list} + +\subsubsection*{How to transform nodes or paths into clickable links} + +\begin{list}{} +\item + +\noindent\style+/tikz/switch ocg+\argument{=\{\emph{<OCGs list>}\}} + + This style transforms the current path or the current node in a link acting as + if it was produced by the macro \code+\switchocg+ (the visibility + status of referenced OCGs is reversed). + + \noindent\style+/tikz/show ocg+\argument{=\{\emph{<OCGs list>}\}} + + This style transforms the current path or the current node in a link acting as + if it was produced by the macro \code+\showocg+ (the referenced OCGs + are made visible). + + \noindent\style+/tikz/hide ocg+\argument{=\{\emph{<OCGs list>}\}} + + This style transforms the current path or the current node in a link acting as + if it was produced by the macro \code+\hideocg+ (the referenced OCGs + are made invisible). + + \noindent\style+/tikz/actions ocg+\argument{=\{\emph{<OCGs + list>}\}\{\emph{<OCGs list>}\}\{\emph{<OCGs list>}\}} + + This style transforms the current path or the current node in a link acting as + if it is produced by the macro \code+\actionsocg+ (the visibility + status of OCGs of the first list is reversed, the OCGs in the second + list are made visible and those of the third list are made invisible). + + \noindent\style+/tikz/switch ocg with mark on+\argument{=\{\emph{<ocg + reference>}\}\{\emph{<OCGs list>}\}} + + \noindent\style+/tikz/switch ocg with mark off+\argument{=\{\emph{<ocg + reference>>}\}\{\emph{<OCGs list>}\}} + + These styles transform the current path or the current node in a link acting + as if it is produced by the macro \code+\switchocg+ (the visibility + status of referenced OCGs in the list is reversed). + + A mark (currently a simple cross) is drawn over the current path or + node in an OCG whose reference is \texttt{\emph{ocg reference}}. The + visibility status of this OCG will be reversed as those of the entire + list. + + If the OCG whose reference is \texttt{\emph{ocg reference}} does not + exist, it is created with an empty name and its initial visibility + state is true with \code+on+ and false with \code+off+. + +\end{list} + +\begin{note} + Due to limitation of PDF, whatever the shape of the current path or + node is, it is its \emph{bounding box} that is used to make the link: + the link is always \emph{rectangular} and \emph{horizontal}! +\end{note} + +\subsubsection*{Example with \TikZ{}} + +\begin{filecontents*}{ocgx-example-3} +\begin{tikpicture} + \begin{scope}[ocg={name=TikZ example,ref=tikzex,status=visible} + \fill[orange] (0,0) circle (1); + \end{scope} + \node[draw,switch ocg=tikzref] at (2,0) {Switch}; +\end{tikpicture} +\end{filecontents*} +\TeXexample{ocgx-example-3}{} + + + +\section{Examples} + +The document \code+demo-ocgx.tex+ provides several examples of usage of +package \code+ocgx+ with \TikZ{} (and \code+beamer+). + +\section{Limits and bugs} + +\begin{enumerate} +\item Links are always horizontal rectangles! +\item An \code+ocg+ environment spanning across multiple pages are not + detected and don't work correctly. +\item The list of OCGs created by \code+ocg+ is seen by viewers as a + long flat list. Their possible hierarchy is not displayed. +\item The packages \code+ocg+ and \code+ocgx+ are not compatible with Plain-\TeX{}. +\end{enumerate} + +\section{Development and history} +This package is still experimental. It is released on CTAN. You can +donwload the latest version from \url{https://github.com/polgab/ocgx}. Any +help to participate in its development is welcome: contact the +maintainer (\url{paul.gaborit@gmail.com}). + +\paragraph{version 0.3} (2012-09-30) Complete documentation for part +\emph{Usage with TikZ} and correct TDS archive. + +\paragraph{version 0.2} (2012-09-27) First release on CTAN. +\end{document} + + + +%%% Local Variables: +%%% mode: latex +%%% TeX-master: t +%%% End: |