summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ocgx/ocgx-manual-en.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/ocgx/ocgx-manual-en.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/ocgx/ocgx-manual-en.tex')
-rw-r--r--macros/latex/contrib/ocgx/ocgx-manual-en.tex430
1 files changed, 430 insertions, 0 deletions
diff --git a/macros/latex/contrib/ocgx/ocgx-manual-en.tex b/macros/latex/contrib/ocgx/ocgx-manual-en.tex
new file mode 100644
index 0000000000..c790c312b3
--- /dev/null
+++ b/macros/latex/contrib/ocgx/ocgx-manual-en.tex
@@ -0,0 +1,430 @@
+% 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,
+ upquote=true,
+ 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}} ---}{}
+\newenvironment{ocgXample}[1]{% name
+ \gdef\ocgXample@filename{#1}%
+ \@tempswafalse\filec@ntents{#1}%
+}
+{\endfilecontents\aftergroup\showocgXample}
+\newcommand\showocgXample{
+ \minipage{1.0\linewidth}%
+ \prog{\ocgXample@filename}
+ \lstinputlisting[style=TeXcode,aboveskip=0ex]\ocgXample@filename%
+ \endprog
+ \endminipage
+}
+
+\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}\par
+}
+\makeatother
+
+\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
+
+\tableofcontents
+
+\section*{Abstract}
+
+The \code+ocgx+ package extends the \code+ocg-p+ package 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},
+ \emph{PDF-XChange-Viewer}, 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{ocgXample}{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{ocgXample}
+
+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}
+
+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{ocgXample}{ocgx-example-2}
+\begin{ocg}{OCG name}{refocg}{1}
+ content...
+\end{ocg}
+\end{ocgXample}
+
+\DescribeEnv{ocg}%
+The \code+ocg+ environment (provided by the package \code+ocg-p+)
+creates OCGs. It requires three arguments. The first argument is the
+name of the OCG as it appears in the layer toolbar of the PDF
+viewer. The second argument is the internal name used to reference this
+OCG. The third argument sets the initial visibility of the OCG when the
+document is opened (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).
+\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{ocgXample}{ocgx-tikz-preamble}
+\usepackage{tikz}
+\usetikzlibrary{ocgx}
+\end{ocgXample}
+
+\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 packages \code+ocg-p+ and \code+ocgx+ are not compatible with
+ Plain-\TeX{}.
+\item While \code+ocg-p+ is usable with \code+pdflatex+ and
+ \code+xelatex+, \code+ocgx+ works only with \code+pdflatex+ (and
+ \code+lualatex+).
+\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.5} (2012-12-07) Now, the \code+ocgx+ package uses
+the new \code+ocg-p+ package instead of the \code+ocg+ package : the
+layers can be nested in the layer toolbar of the PDF viewer.
+
+\paragraph{version 0.4} (2012-11-14) Added dependancy to \texttt{calc}
+TikZ library. Fixed bug: bad lists in \code+\actionsocg+.
+
+\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: