summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/texpower/manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/texpower/manual.tex')
-rw-r--r--Master/texmf-dist/doc/latex/texpower/manual.tex2264
1 files changed, 2264 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/texpower/manual.tex b/Master/texmf-dist/doc/latex/texpower/manual.tex
new file mode 100644
index 00000000000..472db32a79a
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/texpower/manual.tex
@@ -0,0 +1,2264 @@
+%%
+%% This is file `manual.tex',
+%% generated with the docstrip utility.
+%%
+%% The original source files were:
+%%
+%% texpower-doc.dtx (with options: `manual,docu,enddoc')
+%%
+%% --------------------------------------------------------------
+%% TeXPower bundle - dynamic online presentations with LaTeX
+%% Copyright (C) 1999-2004 Stephan Lehmke
+%%
+%% This program is free software; you can redistribute it and/or
+%% modify it under the terms of the GNU General Public License
+%% as published by the Free Software Foundation; either version 2
+%% of the License, or (at your option) any later version.
+%%
+%% This program is distributed in the hope that it will be useful,
+%% but WITHOUT ANY WARRANTY; without even the implied warranty of
+%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+%% GNU General Public License for more details.
+%% --------------------------------------------------------------
+%%
+%% The list of all files belonging to the TeXPower bundle is
+%% given in the file `00readme.txt'.
+%%
+\ProvidesFile{manual.tex}%
+ [2004/07/27 TeXPower manual]
+%-----------------------------------------------------------------------------------------------------------------
+% File: manual.tex
+%
+% (Preliminary) documentation of the TeXPower bundle.
+%
+%-----------------------------------------------------------------------------------------------------------------
+% Autor: Stephan Lehmke <Stephan.Lehmke@cs.uni-dortmund.de>
+%
+% v0.0.1 Mar 20, 2000: First version for the pre-alpha release of TeXPower.
+%
+% v0.0.2 Apr 11, 2000: Now producing a document which is meant for printing on paper.
+%
+
+\documentclass[12pt]{scrartcl}
+
+%-----------------------------------------------------------------------------------------------------------------
+% We need some more packages...
+%
+\usepackage[nottoc]{tocbibind}
+
+\usepackage{textcomp}% Just for \textregistered. Comment out if you like.
+
+\usepackage{url}
+
+% The following package makes code look a little nicer, but it may not be present on all systems.
+
+\IfFileExists{cmtt.sty}{\usepackage[override]{cmtt}}{}
+
+% Loading the soul package enables the \highlighttext command.
+
+\IfFileExists{soul.sty}{\usepackage{soul}}
+
+% One more Text emphasis command...
+
+\let\name=\textsc
+
+% We input the xr package for external references.
+
+\usepackage{xr-hyper}
+
+%-----------------------------------------------------------------------------------------------------------------
+% Load hyperref.
+%
+\usepackage[bookmarksopen,colorlinks]{hyperref}
+
+%-----------------------------------------------------------------------------------------------------------------
+% Finally, the texpower package is loaded.
+%
+\usepackage{texpower}
+
+%-----------------------------------------------------------------------------------------------------------------
+% The configuration file allows user-specific settings.
+
+\input{__TPcfg}
+
+%-----------------------------------------------------------------------------------------------------------------
+% Setting up indexing and custom indexing commands
+\input{__TPindexing}
+
+%-----------------------------------------------------------------------------------------------------------------
+% We use references from the full demo file.
+
+%\externaldocument{fulldemo}[http://texpower.sourceforge.net/doc/fulldemo.pdf]
+\externaldocument{fulldemo}
+
+
+%-----------------------------------------------------------------------------------------------------------------
+% The code in the manual (doc tag) is meant for the document class seminar. Thus, it contains some
+% seminar-specific commands which are replaced by dummies here.
+
+\let\newslide=\relax
+
+%-----------------------------------------------------------------------------------------------------------------
+% The following command produces the title for this document.
+
+\newcommand{\makeslidetitle}[1]
+{%
+ \hypersetup{pdftitle={#1}}
+ \title{The \TeX Power bundle\\{\normalfont #1}}
+ \author
+ {%
+ Stephan Lehmke\\\url{mailto:Stephan.Lehmke@udo.edu}
+ \and
+ Hans Fr.\ Nordhaug\\\url{mailto:hansfn@users.sourceforge.net}%
+ }
+ \maketitle
+
+ \tableofcontents
+
+ \subsubsection*{}
+}
+
+
+%-----------------------------------------------------------------------------------------------------------------
+% As the documentation text contains a lot of stuff in boxes, we use \sloppy to avoid stuff projecting into the margin.
+
+\sloppy
+
+%-----------------------------------------------------------------------------------------------------------------
+% Finally, everything is set up. Here we go...
+%
+
+\begin{document}
+%
+%-----------------------------------------------------------------------------------------------------------------
+%
+% Documentation of the TeXPower bundle.
+%
+% Autor: Stephan Lehmke <Stephan.Lehmke@cs.uni-dortmund.de>
+%
+% v0.0.1 Mar 20, 2000: First version for the pre-alpha release of TeXPower.
+%
+% v0.0.2 Mar 29, 2000: Added `usage and basic options' section.
+%
+% v0.0.3 Apr 04, 2000: Added `Color Emphasis and Highlighting' section.
+%
+% v0.0.4 Apr 12, 2000: A lot of small additions in preparation of the update to TeXpower v0.0.7.
+%
+% v0.0.5 May 31, 2000: Updated for TeXpower v0.0.8.
+%
+% v0.0.6 Jun 09, 2000: Some updates for TeXpower v0.0.8b.
+%
+% v0.0.6a Jun 13, 2000: Some updates for TeXpower v0.0.8c.
+%
+% v0.0.6b Jun 23, 2000: Some updates for TeXpower v0.0.8e.
+%
+% v0.0.6c Jul 25, 2000: Some updates for TeXpower v0.0.8g. Colors section rewritten for new color management kernel.
+%
+% v0.0.7 May 15, 2003: Added index and updates for TeXpower v0.0.9d.
+%
+% v0.0.8 July 27, 2004: Added the "Miscellaneous commands" section. Moved the tpslifonts doc into tpslifonts.dtx.
+%
+%-----------------------------------------------------------------------------------------------------------------
+%
+\def\docversion{v0.0.8 of July 27, 2004}
+\def\tpversion{v0.1b of July 27, 2004}
+
+\makeslidetitle
+{%
+ Documentation%
+ \thanks{Documentation \docversion\ for \TeX Power \tpversion\ (alpha).}%
+ }%
+
+The \TeX Power bundle contains style and class files for creating dynamic online presentations with \LaTeX.
+
+The heart of the bundle is the package \code{texpower.sty} which implements some commands for presentation effects. This
+includes setting page transitions, color highlighting and displaying pages incrementally.
+
+For finding out how to achieve special effects (as shown in the \nameref{Sec:Ex}),
+please look at the comments inside the files ending with \code{example.tex} and \code{demo.tex}
+and read this manual to find out what's going on.
+
+\newslide
+
+For your own first steps with \TeX Power, the simple demo file \code{simpledemo.tex} is the best starting
+place. There, some basic applications of the dynamic features provided by the \code{texpower} package are
+demonstrated. You can make your own dynamic presentations by modifying that demo to your convenience.
+
+\code{simpledemo.tex} uses the \code{article} document class for maximum
+compatibility. There are other simple demos named
+\code{slidesdemo.tex}, \code{foilsdemo.tex}, \code{seminardemo.tex},
+\code{pp4sldemo.tex}, \code{pdfslidemo.tex}, \code{pdfscrdemo.tex},
+\code{prosperdemo.tex}, and \code{ifmslidemo.tex}
+which demonstrate how to combine \TeX Power with the
+most popular presentation-making document classes and packages.
+
+\newslide
+
+The other, more sophisticated examples demonstrate the expressive power of the
+\code{texpower} package. Look at the commented code of these examples to find out how to achieve special effects and
+create your own presentation effects with \TeX Power.
+
+For the first \emph{alpha} release, this documentation will be completed. For the first \emph{beta} release, when the
+code is a little more stable, the \code{texpower} package will be made into a properly documented \code{.dtx} file.
+
+\newslide
+
+%-----------------------------------------------------------------------------------------------------------------
+%
+\section{Usage and general options}
+The \code{texpower} package is loaded by putting
+\begin{center}
+ \present{\commandapp{usepackage}{texpower}}
+\end{center}
+into the preamble of a document.
+
+There are no specific restrictions as to which document classes can be used.
+
+It should be stressed that \TeX Power is \underl{not} (currently) a complete presentation package. It just adds dynamic
+presentation effects (and some other gimmicks specifically interesting for dynamic presentations) and should always be
+combined with a document class dedicated to designing presentations (or a package like
+\href{ftp://ftp.dante.de/tex-archive/help/Catalogue/entries/pdfslide.html}{\code{pdfslide}}).
+
+Some of the presentation effects created by \code{texpower} require special capabilities of the viewer which is used for
+presenting the resulting document. The target for the development of \code{texpower} has so far been
+\href{http://www.adobe.com/products/acrobat/readermain.html}%
+{\concept{Adobe Acrobat\textsuperscript{\textregistered} Reader}}, which means the
+document should (finally) be produced in \code{pdf} format. The produced
+\code{pdf} documents should display well in
+\href{http://www.cs.wisc.edu/~ghost/gsview/}{\concept{GSview}} also, but that
+viewer doesn't support page transitions and duration.
+
+There are no specific restrictions as to which way the \code{pdf} format is produced. All demos and examples
+have been tested with pdf\LaTeX{} and standard \LaTeX, using
+\code{dvips} and \href{http://www.adobe.com/products/acrobat/}%
+{\concept{Adobe Acrobat\textsuperscript{\textregistered} Distiller}}
+or \code{dvips} and \code{ps2pdf} (from the \href{http://www.ghostscript.com/}%
+{\concept{Ghostscript suite}}) for generating \code{pdf}.
+
+\newslide
+
+\subsection{General options}\label{Sec:GenOpt}
+\begin{description}
+\item[\present{option: \code{display}}.]\indexpckopt{texpower}{display} Enable `dynamic' features. If not set, it is assumed that the document is to be
+ printed, and all commands for dynamic presentations, like \macroname{pause} or \macroname{stepwise} have no effect.
+
+\item[\present{option: \code{printout} (default)}.]\indexpckopt{texpower}{printout} Disable `dynamic' features. As this is the default behaviour,
+ setting this option explicitly is useful only if the option \code{display} is set by default for instance in the
+ \code{tpoptions.cfg} file (see section \ref{Sec:Config}).
+
+\item[\present{option: \code{verbose}}.]\indexpckopt{texpower}{verbose} Output some administrative info.
+\end{description}
+Some font options are listed in section \ref{Sec:BaseFont}.
+
+\newslide
+
+\subsection{Side effects of page contents duplication}\label{Sec:Dupl}
+In the implementation of the \macroname{pause} and \macroname{stepwise} commands, it is neccessary to duplicate some
+material on the page.
+
+This way, not only `visible' page contents will be duplicated, but also some `invisible' control code stored in
+\concept{whatsits} (see the \TeX book for an explanation of this concept). Duplicating whatsits can lead to undesirable
+side effects.
+
+For instance, a \macroname{section} command creates a whatsit for writing the table of contents entry. Duplicating this
+whatsit will also duplicate the toc entry.
+
+\newslide
+
+So, whatsit items effecting file access are inhibited when duplicating page material.
+
+A second type of whatsits is created by \TeX's \macroname{special} command which is used for instance for color
+management. Some drivers, like \code{dvips} and \code{textures}, use a color stack which is controlled by
+\macroname{special} items included in the dvi file. When page contents are duplicated, then these \macroname{special}s
+are also duplicated, which can seriously mess up the color stack.
+
+\newslide
+
+\code{texpower} implements a `color stack correction' method by maintaining a stack of color corrections, which should
+counteract this effect. Owing to potential performance problems, this method is turned off by default.
+\begin{description}
+\item[\present{option: \code{fixcolorstack}}]\indexpckopt{texpower}{fixcolorstack} switches on color stack correction. Use it if you experience strange color
+ switches in your document.
+\end{description}
+
+\newslide
+
+\subsection{Setting the base font}\label{Sec:BaseFont}
+\code{texpower} offers no options for setting the base font of the document.
+Use the \code{tpslifonts} package in stead. Read more in section \ref{Sec:TPslifonts}.
+
+Further, there are packages like \code{cmbright} or \code{beton} which change the whole set of fonts to something less
+fragile than cmr.
+
+\newslide
+
+\subsection{Switches}
+There are some boolean registers provided and set automatically by \code{texpower}.
+
+\begin{description}
+\item[\present{boolean: \code{psspecialsallowed}}]\indexpckswitch{texpower}{psspecialsallowed} True if PostScript\textsuperscript{\textregistered} specials may be
+ used.
+
+ \code{texpower} tries to find out whether or not PostScript\textsuperscript{\textregistered} specials may be used in
+ the current document. For instance, pdf\LaTeX{} can't interpret arbitrary specials. This switch is set automatically
+ and can be used inside a document to enable/disable parts which need PostScript\textsuperscript{\textregistered}
+ specials.
+
+\newslide
+
+\item[\present{boolean: \code{display}}]\indexpckswitch{texpower}{display} True if \code{display} option was given.
+
+ This switch indicates whether `dynamic' features of \code{texpower} are enabled. Use it inside your document
+ to distinguish between the `presented' and the printed version of your document.
+
+\item[\present{boolean: \code{TPcolor}}]\indexpckswitch{texpower}{TPcolor} True if any of the color highlighting options (see section
+ \ref{Sec:ColorEmphasis}) were given.
+
+ This switch indicates whether `color' features of \code{texpower} are enabled (compare section
+ \ref{Sec:ColorEmphasis}). You can use it inside your document to distinguish between a `colored' and a `monochrome'
+ version of your document.
+\end{description}
+
+\newslide
+
+\subsection{Configuration files}\label{Sec:Config}
+\code{texpower} loads three configuration files (if present):
+\begin{description}
+\item[\present{file: \code{tpoptions.cfg}}]\indexcode{tpoptions.cfg}
+ is loaded before options are processed. Can be used to set default options
+ in a system-specific way. See the comments inside the file
+ \code{tpoptions.cfg} which is part of the \TeX Power bundle
+ for instructions.
+
+\item[\present{file: \code{tpsettings.cfg}}]\indexcode{tpsettings.cfg}
+ is loaded at the end of \code{texpower}. Here, you can do some
+ system-specific settings. See the comments inside the
+ file \code{tpsettings.cfg} which is part of the
+ \TeX Power bundle for instructions.
+
+\item[\present{file: \code{tpcolors.cfg}}]\indexcode{tpcolors.cfg}
+ is loaded if \code{TPcolor} is true. The file defines the standard
+ colors/colorsets (see section \ref{Sec:ColorEmphasis}). See the
+ comments inside the file \code{tpcolors.cfg} which is part of the
+ \TeX Power bundle for instructions.
+\end{description}
+
+\newslide
+
+\subsection{Miscellaneous commands}\label{Sec:MiscCmd}
+Some important commands that don't fit in the latter sections:
+\begin{description}
+\item[\present{\commandapp{currentpagevalue}{\carg{value}}}]\indexmacro{currentpagevalue}
+ sets how to find the number of the current page, \commandapp{value}{page} is default.
+ Used to name the hyper target on the first subpage of every page. Also used in the
+ TeXPower navigation buttons.
+\item[\present{\commandapp{pausesafecounter}{\carg{counter}}}]\indexmacro{pausesafecounter}
+ is used to add counters that are to be restored to their original value after \macroname{pause}. The \code{page}
+ counter is always restored. In addition the \code{slide} counter is restored if the \code{seminar} class is used. If
+ you need more counters to be restored after \macroname{pause}, use \macroname{pausesafecounter}.
+\end{description}
+
+\newslide
+
+\subsection{Dependencies on other packages}
+\code{textpower} always loads the packages \code{ifthen} and \code{calc}, as the extended command syntax provided by
+these is indispensable for the macros to work. They are in the \code{base} and \code{tools} area of the \LaTeX{}
+distribution, respectively, so I hope they are available on all systems.
+
+Furthermore, \code{texpower} loads the package \code{color} if any color-specific options are set (see section
+\ref{Sec:ColorEmphasis}).
+
+Further packages are \emph{not} loaded automatically by \code{texpower} to avoid incompatibilities, although some
+features of \code{texpower} are enabled \emph{only} if a certain package is loaded. If you wish to use these features,
+you are responsible for loading the respective package yourself.
+
+If some necessary package is \emph{not} loaded, \code{texpower} will issue a warning and disable the respective
+features.
+
+The following packages are neccessary for certain features of \code{texpower}:
+\begin{description}
+\item[\present{package: \code{hyperref}}]\indexfile{hyperref}{package}
+ is neccessary for page transition effects to work (see section
+ \ref{Sec:PageTrans}).
+
+ In particular, the \macroname{pageDuration} (see section \ref{Sec:PageDuration}) command only works if the version of
+ hyperref loaded is at least v6.70a (where the \code{pdfpageduration} key was introduced).
+
+ Commands which work only when \code{hyperref} is loaded are marked with \textbf{\textsf{h}} in the description.
+
+\newslide
+
+\item[\present{package: \code{soul}}]\indexfile{soul}{package}
+ is neccessary for the implementation of the commands \macroname{hidetext} and
+ \macroname{highlighttext} (see section \ref{Sec:displaycustom}).
+
+ Commands which work only when \code{soul} is loaded are marked with \textbf{\textsf{s}} in the description.
+\end{description}
+
+\newslide
+
+\subsection{What else is part of the \TeX Power bundle?}
+Besides the package \code{texpower} (which is described here), there are four
+more packages, \code{tpslifonts}, \code{fixseminar}, \code{automata} and
+\code{tplists}, and one document class,
+\code{powersem}, in the \TeX Power bundle which so far have no documentation
+of their own. They will be described in this section until they are turned
+into \code{dtx} files producing their own documentation.
+
+See the file \code{00readme.txt} which is part of the \TeX Power bundle for a short description of all files.
+
+\newslide
+
+\minisec{The document class \code{powersem}}\indexfile{powersem}{class}
+This is planned to provide a more `modern' version of \code{seminar} which can be used for creating dynamic
+presentations.
+
+Currently, this document class doesn't do much more than load \code{seminar} and apply some fixes, but it is planned to
+add some presentation-specific features (like navigation panels).
+
+\newslide
+
+There are three new options which are specific for \code{powersem}, all other options are passed to \code{seminar}:
+\begin{description}
+\item[\present{option: \code{display}}]\indexpckopt{powersem}{display}
+ Turns off all features of \code{seminar} (notes, vertical centering of slides)
+ which can disturb dynamic presentations.
+
+\item[\present{option: \code{calcdimensions}}]\indexpckopt{powersem}{calcdimensions}
+ \code{seminar} automatically calculates the slide dimensions
+ \macroname{slidewidth} and \macroname{slideheight} only for the default \code{letter} and for its own option
+ \code{a4}. For all the other paper sizes which are possible with the \code{KOMA} option, the slide dimensions are not
+ calculated automatically.
+
+ The \code{calcdimensions} option makes \code{powersem} calculate the slide dimensions automatically from paper size
+ and margins.
+
+\newslide
+
+\item[\present{option: \code{truepagenumbers}}]\indexpckopt{powersem}{truepagenumbers}
+ The truepagenumbers option makes powersem count pages with the counter page, independently of the counter slide. This
+ enables proper working of TeXPowers navigation buttons (some of which calculate relative page numbers) even when the
+ counter slide is reset frequently (for slide numberings of the type \verb|<l>.<n>.<m>|).
+
+\item[\present{option: \code{KOMA}}]\indexpckopt{powersem}{KOMA} Makes
+ \code{seminar} load \code{scrartcl} (from the KOMA-Script bundle) instead of
+ \code{article} as its base class. All new features of \code{scrartcl} are then available also for slides.
+
+\item[\present{option: \code{UseBaseClass}}]\indexpckopt{powersem}{UseBaseClass}
+ Makes \code{seminar} load the class \macroname{baseclass} (initially \code{article}) instead of
+ \code{article} as its base class.
+
+\item[\present{option: \code{reportclass}}]\indexpckopt{powersem}{reportclass}
+ Makes \code{seminar} load the class \macroname{baseclass} (initially \code{report}) instead of
+ \code{article}.
+
+\item[\present{option: \code{bookclass}}]\indexpckopt{powersem}{bookclass}
+ Makes \code{seminar} load the class \macroname{baseclass} (initially \code{book}) instead of
+ \code{article}.
+
+\end{description}
+
+There is one change in \code{powersem} which will lead to incompatibilities with \code{seminar}. \code{seminar} has the
+unfortunate custom of \emph{not} exchanging \macroname{paperwidth} and \macroname{paperheight} when making landscape
+slides, as for instance \code{typearea} and \code{geometry} do.
+
+This leads to problems with setting the paper size for \code{pdf} files, as done for instance by the \code{hyperref}
+package.
+
+\code{powersem} effectively turns off \code{seminar}'s papersize management and leaves this to the base class (with the
+pleasant side effect that you can use e.\,g.\ \commandapp[KOMA,a0paper]{documentclass}{powersem} for making posters).
+
+In consequence, the \code{portrait} option of \code{seminar} is turned on by \code{powersem} to avoid confusing
+\code{seminar}. You have to explicitly use the \code{landscape} option (and a base class or package which understands
+this option) to get landscape slides with powersem.
+
+\newslide
+
+\minisec{The package \code{fixseminar}}\indexfile{fixseminar}{package}
+Unfortunately, there are some fixes to seminar which can \emph{not} be applied in \code{powersem} because they have to
+be applied after \code{hyperref} is loaded (if this package should be loaded).
+
+The package \code{fixseminar} applies these fixes, so this package should be loaded after \code{hyperref} (if
+\code{hyperref} is loaded at all, otherwise \code{fixseminar} can be loaded anywhere in the preamble).
+
+\newslide
+
+It applies two fixes:
+\begin{itemize}
+\item In case \code{pdflatex} is being run, the lengths \macroname{pdfpageheight} and \macroname{pdfpagewidth} have to
+ be set in a `magnification-sensitive' way.
+
+\item \code{hyperref} introduces some code at the beginning of every page which can produce spurious vertical space,
+ which in turn disturbs building dynamic pages. This code is `fixed' so it cannot produce vertical space.
+\end{itemize}
+
+\newslide
+
+\minisec{The package \code{tpslifonts}}
+\indexfile{tpslifonts}{package}\label{Sec:TPslifonts}
+Presentations to be displayed `online' with a video beamer have special needs concerning font configuration owing to low
+`screen' resolution and bad contrast caused by possibly bad light conditions combined with color highlighting.
+
+This package tries to cater to these needs by offering a holistic configuration of all document fonts, including text,
+typewriter, and math fonts. Special features are `smooth scaling' of Type1 fonts and careful design size selection for
+optimal readability.
+
+\newslide
+
+For more information on package options and used fonts (and on implementation) read the documentation coming with the
+package - check the \code{tpslifonts} directory.
+
+\minisec{The package \code{automata}}\indexfile{automata}{package}
+Experimental package for drawing automata in the sense of theoretical computer
+science (using PSTricks) and animating them with TeXPower. Only DFA and Mealy
+automata are supported so far.
+
+\newslide
+
+\minisec{The package \code{tplists}}\indexfile{tplists}{package}
+Experimental package providing easy dynamic lists. Currently there are stepped, flipped and dimmed versions of itemize
+and enumerate (and corresponding lists from the \code{eqlist} and \code{paralist} package). For more information
+and an example read the start of the file \code{tplists.sty}.
+
+\newslide
+
+%-----------------------------------------------------------------------------------------------------------------
+%
+\section{The \macroname{pause} command}\label{Sec:pause}
+\present{\macroname{pause}}\indexmacro{pause} is derived from the \macroname{pause} command from the package
+\href{http://www-sp.iti.informatik.tu-darmstadt.de/software/ppower4/pp4sty.zip}{\code{texpause}} which is part of the
+\href{http://www-sp.iti.informatik.tu-darmstadt.de/software/ppower4/}{PPower4 suite} by
+\href{mailto:guntermann@iti.informatik.tu-darmstadt.de}{Klaus Guntermann}.
+
+ It will ship out the current page, start a new page and copy whatever was on the current page onto the new page, where
+ typesetting is resumed.
+
+ \ifthenelse{\boolean{display}}{Here, let's do a little demo\pause}{}
+
+ This will create the effect of a \concept{pause} in the presentation, i.\,e.\ the presentation stops because the
+ current page ends at the point where the \macroname{pause} command occurred and is resumed at this point when the
+ presenter switches to the next page.
+
+ \newslide
+
+ \minisec{Things to pay attention to}
+ \begin{enumerate}
+ \item \macroname{pause} should appear in \concept{vertical mode} only, i.\,e.\ between paragraphs or at places where
+ ending the current paragraph doesn't hurt.
+
+ \item This means \macroname{pause} is forbidden in all \concept{boxed} material (including \code{tabular}),
+ \concept{headers/footers}, and \concept{floats}.
+
+ \item \macroname{pause} shouldn't appear either in environments which have to be \emph{closed} to work properly, like
+ \code{picture}, \code{tabbing}, and (unfortunately) environments for \concept{aligned math formulas}.
+
+ \item \macroname{pause} does work in all environments which mainly influence paragraph formatting, like \code{center},
+ \code{quote} or all \concept{list} environments.
+
+ \newslide
+
+ \item \macroname{pause} doesn't really have problems with automatic page breaking, but beware of \emph{overfull}
+ pages/slides. In this case, it may occur that only the last page(s)/slide(s) of a sequence are overfull, which
+ changes vertical spacing, making lines `wobble' when switching to the last page/slide of a sequence.
+
+ \newslide
+
+ \item The duplication of page material done by \macroname{pause} can lead to unwanted side effects. See section
+ \ref{Sec:Dupl} for further explanations. In particular, if you should experience strange color switches when using
+ \macroname{pause} (and you are \underl{not} using \code{pdftex}), turn on color stack correction with the option
+ \code{fixcolorstack}. In addition you should be aware of \macroname{pausesafecounter}, see section
+ \ref{Sec:MiscCmd}.
+
+ \end{enumerate}
+
+ A lot of the restrictions for the use of pause can be avoided by using \macroname{stepwise} (see next section).
+
+ \newslide
+
+ %-----------------------------------------------------------------------------------------------------------------
+ %
+ \section{The \macroname{stepwise} command}
+ \present{\commandapp{stepwise}{\carg{contents}}}\indexmacro{stepwise} is a command for displaying some part of a \LaTeX{} document (which
+ is contained in \carg{contents}) `step by step'. As of itself, \macroname{stepwise} doesn't do very much. If
+ \carg{contents} contains one or more constructs of the form \present{\commandapp{step}{\carg{stepcontents}}}\indexmacro{step}, the
+ following happens:
+ \begin{enumerate}
+ \item The current contents of the page are saved (as with \macroname{pause}).
+
+ \item As many pages as there are \macroname{step} commands in \carg{contents} are produced.
+
+ Every page starts with what was on the current page when \macroname{stepwise} started.
+
+ \newslide
+
+ The first page also contains everything in \carg{contents} which is \emph{not} in \carg{stepcontents} for any
+ \macroname{step} command.
+
+ The second page additionally contains the \carg{stepcontents} for the \emph{first} \macroname{step} command, and so
+ on, until all \carg{stepcontents} are displayed.
+
+ \item When all \carg{stepcontents} are displayed, \macroname{stepwise} ends and typesetting is resumed (still on the
+ current page).
+ \end{enumerate}
+
+ \parstepwise{This will create the effect that the \macroname{step} commands are executed `\step{step} \step{by}
+ \step{step}'.}
+
+ \newslide
+
+ \minisec{Things to pay attention to}
+ \begin{enumerate}
+ \item \macroname{stepwise} should appear in \concept{vertical mode} only, i.\,e.\ between paragraphs, just like
+ \macroname{pause}.
+
+ \item Don't put \macroname{pause} or nested occurrences of \macroname{stepwise} into \carg{contents}.
+
+ \item Structures where \macroname{pause} does not work (like \code{tabular} or aligned equations) can go
+ \emph{completely} into \carg{contents}, where \macroname{step} can be used freely (see \nameref{Sec:Ex}).
+
+ \item As \carg{contents} is read as a macro argument, constructs involving \concept{catcode} changes (like
+ \macroname{verb} or language switches) won't work in \carg{contents}. Using a suggestion by \name{Ross
+ Moore}, I hope to remedy this until the \emph{alpha} release.
+
+\newslide
+
+ \item Several instances of \macroname{stepwise} may occur on one page, also combined with \macroname{pause} (outside
+ of \carg{contents}).
+
+ But beware of page breaks in \carg{contents}. This will really mess things up.
+
+ Overfull pages/slides are also a problem, just like with \macroname{pause}. See the description of \macroname{pause}
+ (section \ref{Sec:pause}) concerning this and also concerning side effects of duplicating page material.
+
+ \item \macroname{step} can go in \carg{stepcontents}. The order of execution of \macroname{step} commands is just the
+ order in which they appear in \carg{contents}, independent of nesting within each other.
+
+ \newslide
+
+ \item As \carg{contents} is executed several times, \LaTeX{} constructs changing \concept{global counters}, accessing
+ \concept{files} etc.\ are problematic. This concerns sections, numbered equations, labels, hyperlinks and the like.
+
+ Counters are taken care of explicitly by \macroname{stepwise}, so equation numbers are no problem.
+
+ Commands accessing toc files and such (like \macroname{section}) are taken care of by the whatsit suppression
+ mechanism (compare section \ref{Sec:Dupl}).
+
+ Labels and hyperlinks work sort of (giving a lot of warnings though).
+
+ I will try to remedy remaining problems until the first \emph{alpha} release.
+ \end{enumerate}
+
+ \newslide
+
+ \subsection{\macroname{boxedsteps} and \macroname{nonboxedsteps}}\label{Sec:boxedsteps}%
+ By default, \carg{stepcontents} belonging to a \macroname{step} which is not yet `active' are ignored altogether. This
+ makes it possible to include e.\,g.\ tabulators \code{\&} or line breaks into \carg{stepcontents} without breaking
+ anything.
+
+ Sometimes, however, this behaviour is undesirable, for instance when stepping through an equation `from outer to
+ inner', or when filling in blanks in a paragraph. Then, the desired behaviour of a \macroname{step} which is not yet
+ `active' is to create an appropriate amount of \emph{blank space} where \carg{stepcontents} can go as soon as it is
+ activated.
+
+ \newslide
+
+ The simplest and most robust way of doing this is to create an empty box (aka \macroname{phantom}) with the same
+ dimensions as the text to be hidden.
+
+ This behaviour is toggled by the following commands. See section \ref{Sec:displaycustom} for more sophisticated
+ (albeit more fragile) variants.
+ \begin{description}
+ \item[\present{\macroname{boxedsteps}}]\indexmacro{boxedsteps} makes \macroname{step} create a blank box the size of \carg{stepcontents} when
+ inactive and put \carg{stepcontents} into a box when active.
+ \item[\present{\macroname{nonboxedsteps}}]\indexmacro{nonboxedsteps} makes \macroname{step} ignore \carg{stepcontents} when inactive and leave
+ \carg{stepcontents} alone when active (default).
+ \end{description}
+
+ \newslide
+
+ \minisec{Things to pay attention to}
+ \begin{enumerate}
+ \item The settings effected by \macroname{boxedsteps} and \macroname{nonboxedsteps} are \emph{local}, i.\,e.\ whenever
+ a group closes, the setting is restored to its previous value.
+
+ \item Putting stuff into boxes can break things like tabulators (\code{\&}). It can also mess up math spacing, which
+ then has to be corrected manually. Compare the following examples:
+
+ \parstepwise{%
+ \begin{displaymath}
+ \left(\frac{a+b}{c}\right)\qquad\left(\frac{a\step{+b}}{c}\right)\qquad\left(\frac{a\restep{{}+b}}{c}\right)
+ \end{displaymath}%
+ }%
+ \end{enumerate}
+
+ \newslide
+
+ \subsection{Custom versions of \macroname{stepwise}}%
+ Sometimes, it might happen that vertical spacing is different on every page of a sequence generated by
+ \macroname{stepwise}, making lines `wobble'.
+
+ This is caused by interactions between different ways vertical spacing is added to the page. Hopefully, problems
+ caused this way can be reduced until the first \emph{alpha} release.
+
+ \newslide
+
+ There are two custom versions of \macroname{stepwise} which should produce better vertical spacing.
+ \begin{description}
+ \item[\present{\commandapp{liststepwise}{\carg{contents}}}]
+ \indexmacro{liststepwise} works exactly like \macroname{stepwise}, but adds
+ an `invisible rule' before \carg{contents}. Use for list environments and
+ aligned equations.
+ \item[\present{\commandapp{parstepwise}{\carg{contents}}}]
+ \indexmacro{parstepwise} works like \macroname{liststepwise}, but
+ \macroname{boxedsteps} is turned on by default. Use for texts where
+ \macroname{step}s are to be filled into blank spaces.
+ \end{description}
+
+ \newslide
+
+ \subsection{Starred versions of \macroname{stepwise} commands}\label{Sec:StarredStepwise}%
+ Usually, the first page of a sequence produced contains \emph{only} material which is \emph{not} part of any
+ \carg{stepcontents}. The first \carg{stepcontents} are displayed on the second page of the sequence.
+
+ For special effects (see example \ref{Sec:Exhl}), it might be desirable to have the first \carg{stepcontents} active
+ even on the first page of the sequence.
+
+ All variants of \macroname{stepwise} have a starred version (e.\,g.\ \macroname{stepwise*}) which does exactly that.
+
+ \newslide
+
+ \subsection{The optional argument of \macroname{stepwise}}%
+ Every variant of \macroname{stepwise} takes an optional argument, like this
+ \begin{center}
+ \present{\commandapp[\carg{settings}]{stepwise}{\carg{contents}}}.
+ \end{center}
+ \carg{settings} will be placed right before the internal loop which produces the sequence of pages. It can
+ contain settings of parameters which modify the behaviour of \macroname{stepwise} or \macroname{step}. \carg{settings}
+ is placed inside a group so all changes are local to this call of \macroname{stepwise}.
+
+ Some internal macros and counters which can be adjusted are explained in the following.
+
+ \newslide
+
+ \subsection{Customizing the way \carg{stepcontents} is diplayed}\label{Sec:displaycustom}%
+ Internally, there are three macros (taking one argument each) which control how \carg{stepcontents} is displayed:
+ \macroname{displaystepcontents}\indexmacro{displaystepcontents},
+ \macroname{hidestepcontents}\indexmacro{hidestepcontents}, and
+ \macroname{activatestep}\indexmacro{activatestep}. Virtually, every
+ \commandapp{step}{\carg{stepcontents}} is replaced by
+ \begin{description}
+ \item[\present{\commandapp{hidestepcontents}{\carg{stepcontents}}}]\mbox{}\\ when this step is not yet active.
+ \item[\present{\commandapp{displaystepcontents}{\commandapp{activatestep}{\carg{stepcontents}}}}] when this step is
+ activated \emph{for the first time}.
+ \item[\present{\commandapp{displaystepcontents}{\carg{stepcontents}}}]\mbox{}\\
+ when this step has been activated before.
+ \end{description}
+
+ By redefining these macros, the behaviour of \macroname{step} is changed accordingly. You can redefine them inside
+ \carg{contents} to provide a change affecting one \macroname{step} only, or in the optional argument of
+ \macroname{stepwise} to provide a change for all \macroname{step}s inside \carg{contents}.
+
+ In the \nameref{Sec:Ex}, it is demonstrated how special effects can be achieved by redefining these macros.
+
+ \macroname{activatestep} is set to \macroname{displayidentical} by default, the default settings of
+ \macroname{hidestepcontents} and \macroname{displaystepcontents} depend on whether \macroname{boxedsteps} or
+ \macroname{nonboxedsteps} (default) is used.
+
+ \newslide
+
+ \code{texpower} offers nine standard definitions.
+
+ For interpreting \macroname{displaystepcontents}:
+ \begin{description}
+ \item[\present{\macroname{displayidentical}}]\indexmacro{displayidentical}
+ Simply expands to its argument. The same as \LaTeX s
+ \macroname{@ident}. Used by \macroname{nonboxedsteps} (default).
+
+ \item[\present{\macroname{displayboxed}}]\indexmacro{displayboxed}
+ Expands to an \macroname{mbox} containing its argument. Used by
+ \macroname{boxedsteps}.
+ \end{description}
+
+ \newslide
+
+ For interpreting \macroname{hidestepcontents}:
+ \begin{description}
+ \item[\present{\macroname{hideignore}}]\indexmacro{hideignore}
+ Expands to nothing. The same as \LaTeX s \macroname{@gobble}. Used by
+ \macroname{nonboxedsteps} (default).
+
+ \item[\present{\macroname{hidephantom}}]\indexmacro{hidephantom}
+ Expands to a \macroname{phantom} containing its argument. Used by
+ \macroname{boxedsteps}.
+
+ \item[\present{\macroname{hidevanish}}]\indexmacro{hidevanish}
+ In a colored document, makes its argument `vanish' by setting all colors to
+ \macroname{vanishcolor} (defaults to \code{pagecolor}; compare section
+ \ref{Sec:Colorcommands}). Note that this will give weird results with
+ structures backgrounds.
+
+ For monochrome documents, there is no useful interpretation for this command, so it is disabled.
+
+ \newslide
+
+ \item[{\present[s]{\macroname{hidetext}}}]\indexmacro{hidetext}
+ Produces blank space of the same dimensions as the space that would be
+ occupied if its argument would be typeset in the current paragraph. Respects automatic hyphenation and line breaks.
+
+ This command needs the \href{ftp://ftp.dante.de/tex-archive/help/Catalogue/entries/soul.html}{\code{soul}} package
+ to work, which is not loaded by \code{texpower} itself. Consult the documentation of
+ \href{ftp://ftp.dante.de/tex-archive/help/Catalogue/entries/soul.html}{\code{soul}} concerning restrictions on
+ commands implemented using \code{soul}. If you don't load the \code{soul} package yourself, there is no useful
+ definition for this command, so it defaults to \macroname{hidephantom}.
+
+ \newslide
+
+ \item[\present{\macroname{hidedimmed}}]\indexmacro{hidedimmed}
+ In a colored document, displays its argument with dimmed colors (compare
+ section \ref{Sec:Colors}). Note that this doesn't make the argument completely invisible.
+
+ For monochrome documents, there is no useful interpretation for this command, so it is disabled.
+ \end{description}
+
+ \newslide
+
+ For interpreting \macroname{activatestep}:
+ \begin{description}
+ \item[\present{\macroname{highlightboxed}}]\indexmacro{highlightboxed}
+ If the \code{colorhighlight} option (see section \ref{Sec:ColorEmphasis})
+ is set, expands to a \highlightboxed{box with colored background} containing its argument. Otherwise, expands to an
+ \macroname{fbox} containing its argument. It is made sure that the resulting box has the same dimensions as the
+ argument (the outer frame may overlap surrounding text).
+
+ There is a new length register \present{\macroname{highlightboxsep}}
+ \indexmacro{highlightboxsep} which acts like \macroname{fboxsep} for the
+ resulting box and defaults to \code{0.5\macroname{fboxsep}}.
+
+ \newslide
+
+ \item[{\present[s]{\macroname{highlighttext}}}]\indexmacro{highlighttext}
+ If the \code{colorhighlight} option (see section \ref{Sec:ColorEmphasis})
+ is set, puts its argument \highlighttext{on colored background}. Otherwise, underlines its
+ argument. It is made sure that the resulting text has the same dimensions as the argument (the outer frame may
+ overlap surrounding text).
+
+ \present{\macroname{highlightboxsep}} is used to determine the extent of the coloured box(es) used as background.
+
+ This command needs the \href{ftp://ftp.dante.de/tex-archive/help/Catalogue/entries/soul.html}{\code{soul}} package
+ to work (compare the description of \macroname{hidetext}). If you don't load the \code{soul} package yourself, there
+ is no useful definition for this command, so it is disabled.
+
+ \newslide
+
+ \item[\present{\macroname{highlightenhanced}}]\indexmacro{highlightenhanced}
+ In a colored document, displays its argument \highlightenhanced{with
+ enhanced colors} (compare section \ref{Sec:Colors}).
+
+ For monochrome documents, there is no useful interpretation for this command, so it is disabled.
+ \end{description}
+
+ \newslide
+
+ \subsection{Variants of \macroname{step}}
+ There are a couple of custom versions of \macroname{step} which make it easier to achieve special effects needed
+ frequently.
+ \begin{description}
+ \item[\present{\macroname{bstep}}]\indexmacro{bstep}
+ Like \macroname{step}, but is \emph{always} boxed (see section
+ \ref{Sec:boxedsteps}). \commandapp{bstep}{\carg{stepcontents}} is
+ implemented in principle as
+ \code{\{\macroname{boxedsteps}\commandapp{step}{\carg{stepcontents}}\}}.
+
+ In aligned equations where \macroname{stepwise} is used for being able to put tabulators into \carg{stepcontents},
+ but where nested occurrences of \macroname{step} should be boxed to assure correct sizes of growing braces or such,
+ this variant of \macroname{step} is more convenient than using \macroname{boxedsteps} for every nested occurrence
+ of \macroname{step}.
+
+ \item[\present{\commandapp{switch}{\carg{ifinactive}\}\{\carg{ifactive}}}]
+ \indexmacro{switch} is a variant of \macroname{step} which,
+ instead of making its argument appear, switches between \carg{ifinactive}
+ and \carg{ifactive} when activated.
+
+ In fact, \commandapp{step}{\carg{stepcontents}} is in principle implemented by
+ \begin{tabbing}
+ \macroname{switch}\=\code{\{\commandapp{hidestepcontents}{\carg{stepcontents}}\}}\\
+ \>\code{\{\commandapp{displaystepcontents}{\carg{stepcontents}}\}}
+ \end{tabbing}
+
+ This command can be used, for instance, to add an \macroname{underbrace} to a formula, which is difficult using
+ \macroname{step}.
+
+ Beware of problems when \carg{ifinactive} and \carg{ifactive} have different dimensions.
+
+ \newslide
+
+ \item[\present{\macroname{dstep}}]\indexmacro{dstep}
+ A variant of \macroname{step} which takes \underl{no} argument, but simply
+ switches colors to `dimmed' (compare section \ref{Sec:Colors}) if not
+ active. Not that the scope of this color change will
+ last until the next outer group closes. This command does nothing in a monochrome document.
+
+ \item[\present{\macroname{vstep}}]\indexmacro{vstep}
+ A variant of \macroname{step} which takes \underl{no} argument, but simply
+ switches all colors to \macroname{vanishcolor} (defaults to
+ \code{pagecolor}; compare section \ref{Sec:Colorcommands}) if not
+ active. Not that the scope of this color change will last until the next outer group closes. This command does
+ nothing in a monochrome document.
+
+ \item[\present{\macroname{steponce}}]\indexmacro{steponce}
+ % \steponce[<activatefirst>]{<stepcontents>}
+ Like \macroname{step}, but goes inactive again in the subsequent step.
+
+ \item[\present{\macroname{multistep}}]\indexmacro{multistep}
+ is a shorthand macro for executing several steps successively. In
+ fact, it would better be called \macroname{multiswitch}, because it's
+ functionality is based on \macroname{switch}, it only acts like a
+ (simplified) \macroname{step} command which is executed `several times'.
+ The syntax is
+ \begin{center}
+ \commandapp[\carg{activatefirst}]{multistep}{\carg{n}\}\{\carg{stepcontents}}
+ \end{center}
+ where \carg{n} is the number of steps. Only one instance of
+ \carg{stepcontents} is displayed at a time. Inside \carg{stepcontents}, a
+ counter \code{substep} can be evaluated which tells the number of the
+ current instance. In the starred form the last instance of
+ \carg{stepcontents} stays visible.
+
+ \item[\present{\macroname{movie}}]\indexmacro{movie}
+ works like \macroname{multistep}, but between \macroname{steps}, pages are
+ advanced automatically every \carg{dur} seconds. The syntax is
+ \begin{center}
+ \commandapp{movie}{\carg{n}\}\{\carg{dur}\}[\carg{stop}]\{\carg{stepcontents}}
+ \end{center}
+ where \carg{n} is the number of steps. The additional optional argument
+ \carg{stop} gives the code (default: \macroname{stopAdvancing})
+ \indexmacro{stopAdvancing} which stops the animation.
+ (\macroname{movie} accepts the same first optional argument as
+ \macroname{multistep} but it was left out above.)
+
+
+ \item[\present{\macroname{overlays}}]\indexmacro{overlays}
+ is another shorthand macro for executing several steps successively. In
+ contrast to \macroname{multistep}, it doesn't print things \emph{after}
+ each other, but \emph{over} each other. The syntax is
+ \begin{center}
+ \commandapp[\carg{activatefirst}]{overlays}{\carg{n}\}\{\carg{stepcontents}}
+ \end{center}
+ where \carg{n} is the number of steps. Inside \carg{stepcontents}, a
+ counter \code{substep} can be evaluated which tells the number of the
+ current instance.
+ \newslide
+
+ \item[\small%
+ \present{\macroname{restep}}\indexmacro{restep},
+ \present{\macroname{rebstep}}\indexmacro{rebstep},
+ \present{\macroname{reswitch}}\indexmacro{reswitch},
+ \present{\macroname{redstep}}\indexmacro{redstep},
+ \present{\macroname{revstep}}\indexmacro{revstep}.]\mbox{}\\
+ Frequently, it is desirable for two or more steps to appear at the same
+ time, for instance to fill in arguments at
+ several places in a formula at once (see example \ref{Sec:ExEq}).
+
+ \present{\commandapp{restep}{\carg{stepcontents}}} is identical with \commandapp{step}{\carg{stepcontents}}, but is
+ activated at the same time as the previous occurrence of \macroname{step}.
+
+ \present{\macroname{rebstep}}, \present{\macroname{reswitch}}, \present{\macroname{redstep}}, and
+ \present{\macroname{revstep}} do the same for \macroname{bstep}, \macroname{switch}, \macroname{dstep}, and
+ \macroname{vstep}.
+ \end{description}
+
+ \newslide
+
+ \subsection{Optional arguments of \macroname{step}}%
+ Sometimes, letting two \macroname{step}s appear at the same time (with \macroname{restep}) is not the only desirable
+ modification of the order in which \macroname{step}s appear. \macroname{step}, \macroname{bstep} and
+ \macroname{switch} take two optional arguments for influencing the mode of activation, like this:
+ \begin{center}
+ \present{\commandapp[{\carg{activatefirst}][\carg{whenactive}}]{step}{\carg{stepcontents}}}.
+ \end{center}
+ Both \carg{activatefirst} and \carg{whenactive} should be conditions in the syntax of the \macroname{ifthenelse}
+ command (see the documentation of the
+ \href{ftp://ftp.dante.de/tex-archive/help/Catalogue/entries/ifthen.html}{\code{ifthen}} package for details).
+
+ \newslide
+
+ \present{\carg{activatefirst}} checks whether this \macroname{step} is to be activated \emph{for the first time}. The
+ default value is \present{\commandapp{value}{step}=\commandapp{value}{stepcommand}} (see section \ref{Sec:Internals}
+ for a list of internal values). By using \commandapp{value}{step}=\carg{$n$}, this \macroname{step} can be forced to
+ appear as the $n$th one. See example \ref{Sec:ExPar} for a demonstration of how this can be used to make
+ \macroname{step}s appear in arbitrary order.
+
+ \present{\carg{whenactive}} checks whether this \macroname{step} is to be considered active \emph{at all}. The default
+ behaviour is to check whether this \macroname{step} has been activated before (this is saved internally for every
+ step). See example \ref{Sec:ExFooling} for a demonstration of how this can be used to make \macroname{step}s appear
+ and disappear after a defined fashion.
+
+ \minisec{If you know what you're doing\dots}
+ Both optional arguments allow two syntctical forms:
+ \begin{enumerate}
+ \item enclosed in square brackets \code{[]} like explained above.
+ \item enclosed in braces \code{()}. In this case, \carg{activatefirst} and \carg{whenactive} are \emph{not} treated as
+ conditions in the sense of \macroname{ifthenelse}, but as conditionals like those used internally by \LaTeX. That
+ means, \carg{activatefirst} (when enclosed in braces) can contain arbitrary \TeX{} code which then takes two
+ arguments and expands to one of them, depending on whether the condition is fulfilled or not fulfilled. For
+ instance, \commandapp[{\carg{activatefirst}}]{step}{\carg{stepcontents}} could be replaced by
+ \macroname{step}\code{(\commandapp{ifthenelse}{\carg{activatefirst}})\{\carg{stepcontents}\}}.
+
+ See example \ref{Sec:ExBackwards} for a simple application of this syntax.
+ \end{enumerate}
+
+ Internally, the default for the treatment of \carg{whenactive} is \code{(\macroname{if@first@TP@true})}, where
+ \macroname{if@first@TP@true} is an internal condition checking whether this \macroname{step} has been activated before.
+
+ \newslide
+
+ \subsection{Finding out what's going on}\label{Sec:Internals}%
+ Inside \carg{settings} and \carg{contents}, you can refer to the following internal state variables which provide
+ information about the current state of the process executed by \macroname{stepwise}:
+ \begin{description}
+ \item[\present{counter: \code{firststep}}]
+ \indexstepwise{firststep}{counter}
+ The number from which to start counting steps (see counter \code{step}
+ below). Is $0$ by default and $1$ for starred versions (section \ref{Sec:StarredStepwise}) of \macroname{stepwise}.
+ You can set this in \carg{settings} for special effects (see example \ref{Sec:ExBackwards}).
+
+ \item[\present{counter: \code{totalsteps}}]
+ \indexstepwise{totalsteps}{counter}
+ The total number of \macroname{step} commands occurring in \carg{contents}.
+
+ \newslide
+
+ \item[\present{counter: \code{step}}]
+ \indexstepwise{step}{counter}
+ The number of the current iteration, i.\,e.\ the number of the current page in
+ the sequence of pages produced by \macroname{stepwise}. Runs from \commandapp{value}{firststep} to
+ \commandapp{value}{totalsteps}.
+
+ \item[\present{counter: \code{stepcommand}}]
+ \indexstepwise{stepcommand}{counter}
+ The number of the \macroname{step} command currently being executed.
+
+ \item[\present{boolean: \code{firstactivation}}]
+ \indexstepwise{firstactivation}{boolean}
+ \code{true} if this \macroname{step} is active for the first time,
+ \code{false} otherwise.
+
+ \item[\present{boolean: \code{active}}]\indexstepwise{active}{boolean}
+ \code{true} if this \macroname{step} is currently active, \code{false}
+ otherwise.
+ \end{description}
+ \code{stepcommand}, \code{firstactivation}, and \code{active} are useful only inside \carg{stepcontents}.
+
+
+ \newslide
+
+ \subsection{\macroname{afterstep}}\indexmacro{afterstep}%
+ It might be neccessary to set some parameters which affect the appearance of the \emph{page} (like page transitions)
+ inside \carg{stepcontents}. However, the \macroname{step} commands are usually placed deeply inside some structure, so
+ that all \emph{local} settings are likely to be undone by groups closing before the page is completed.
+
+ \present{\commandapp{afterstep}{\carg{settings}}} puts \carg{settings} right before the end of the page, after the
+ current step is performed.
+
+ \newslide
+
+ \minisec{Things to pay attention to}
+ \begin{enumerate}
+ \item There can be only one effective value for \carg{settings}. Every occurrence of \macroname{afterstep} overwrites
+ this value globally.
+
+ \item \macroname{afterstep} will \emph{not} be executed in \carg{stepcontents} if the corresponding \macroname{step}
+ is not active, even if \carg{stepcontents} is displayed owing to a redefinition of \macroname{hidestepcontents},
+ like in example \ref{Sec:Exhl}.
+
+ \item As \carg{settings} is put immediately before the page break, there is no means of restoring the original value
+ of whatever has been set. So if you set something via \macroname{afterstep} and want it to be reset in some later
+ step, you have to reset it explicitly with another call of \macroname{afterstep}.
+ \end{enumerate}
+
+ \newslide
+
+ %-----------------------------------------------------------------------------------------------------------------
+ %
+ \section{Page transitions and automatic advancing}\label{Sec:PageTrans}
+ \subsection{Page transitions}
+ I am indepted to \href{mailto:dongen@cs.ucc.ie}{\name{Marc van Dongen}} for allowing me to include a suite of commands
+ written by him and posted to the \href{http://www-sp.iti.informatik.tu-darmstadt.de/software/ppower4/}{PPower4}
+ mailing list which set page transitions (using
+ \href{ftp://ftp.dante.de/tex-archive/help/Catalogue/entries/hyperref.html}{\code{hyperref}s} \macroname{hypersetup}).
+
+ These commands work only if the \code{hyperref} package is loaded.
+
+ \newslide
+
+ The following page transition commands are defined:\pause
+ \begin{description}
+ \item[{\present[h]{\macroname{pageTransitionSplitHO}}}]
+ \indexmacro{pageTransitionSplitHO}
+ Split Horizontally to the outside. \pageTransitionSplitHO\pause
+
+ \item[{\present[h]{\macroname{pageTransitionSplitHI}}}]
+ \indexmacro{pageTransitionSplitHI}
+ Split Horizontally to the inside. \pageTransitionSplitHI\pause
+
+ \item[{\present[h]{\macroname{pageTransitionSplitVO}}}]
+ \indexmacro{pageTransitionSplitVO}
+ Split Vertically to the outside. \pageTransitionSplitVO\pause
+
+ \item[{\present[h]{\macroname{pageTransitionSplitVI}}}]
+ \indexmacro{pageTransitionSplitVI}
+ Split Vertically to the inside. \pageTransitionSplitVI\pause
+
+ \item[{\present[h]{\macroname{pageTransitionBlindsH}}}]
+ \indexmacro{pageTransitionBlindsH}
+ Horizontal Blinds. \pageTransitionBlindsH\pause
+
+ \item[{\present[h]{\macroname{pageTransitionBlindsV}}}]
+ \indexmacro{pageTransitionBlindsV}
+ Vertical Blinds. \pageTransitionBlindsV
+
+ \newslide
+
+ \item[{\present[h]{\macroname{pageTransitionBoxO}}}]
+ \indexmacro{pageTransitionBoxO}
+ Growing Box. \pageTransitionBoxO\pause
+
+ \item[{\present[h]{\macroname{pageTransitionBoxI}}}]
+ \indexmacro{pageTransitionBoxI}
+ Shrinking Box. \pageTransitionBoxI\pause
+
+ \item[{\present[h]{\commandapp{pageTransitionWipe}{\carg{angle}}}}]
+ \indexmacro{pageTransitionWipe}\mbox{}\\
+ Wipe from one edge of the page to the facing edge.
+
+ \stepwise
+ {%
+ \carg{angle} is a number between $0$ and $360$ which specifies the direction (in degrees) in which to wipe.
+
+ Apparently, only the values \afterstep{\pageTransitionWipe{0}}$0$, \step{\afterstep{\pageTransitionWipe{90}}$90$,}
+ \step{\afterstep{\pageTransitionWipe{180}}$180$,} \step{$270$ are supported.}%
+ }%
+ \pageTransitionWipe{270}\pause
+
+ \item[{\present[h]{\macroname{pageTransitionDissolve}}}]
+ \indexmacro{pageTransitionDissolve}
+ Dissolve. \pageTransitionDissolve
+
+ \newslide
+
+ \item[{\present[h]{\commandapp{pageTransitionGlitter}{\carg{angle}}}}]
+ \indexmacro{pageTransitionGlitter}\mbox{}\\
+ Glitter from one edge of the page to the facing edge.
+
+ \stepwise
+ {%
+ \carg{angle} is a number between $0$ and $360$ which specifies the direction (in degrees) in which to glitter.
+
+ Apparently, only the values \afterstep{\pageTransitionGlitter{0}}$0$,
+ \step{\afterstep{\pageTransitionGlitter{270}}$270$,} \step{$315$ are supported.}%
+ }%
+ \pageTransitionGlitter{315}\pause
+
+ \item[{\present[h]{\macroname{pageTransitionReplace}}}]
+ \indexmacro{pageTransitionReplace}
+ Simple Replace (the default).
+ \end{description}
+
+ \pageTransitionReplace
+
+ \newslide
+
+ \minisec{Things to pay attention to}
+ \begin{enumerate}
+ \item The setting of the page transition is a property of the \emph{page}, i.~e.\ whatever page transition is in
+ effect when a page break occurs, will be assigned to the corresponding pdf page.
+
+ \item The setting of the page transition is undone when a group ends.
+
+ Make sure no \LaTeX{} environment is ended between a \macroname{pageTransition} setting and the next page break. In
+ particular, in \carg{stepcontents}, \macroname{afterstep} should be used (see example \ref{Sec:ExPic}).
+
+ \newslide
+
+ \item Setting page transitions works well with \macroname{pause}. Here, \macroname{pause} acts as a page break,
+ i.\,e.\ a different page transition can be set before every occurrence of \macroname{pause}.
+ \end{enumerate}
+
+ \newslide
+
+ \subsection{Automatic advancing of pages}\label{Sec:PageDuration}
+ If you have loaded a sufficiently new version of the
+ \href{ftp://ftp.dante.de/tex-archive/help/Catalogue/entries/hyperref.html}{\code{hyperref}} package (which allows to
+ set \code{pdfpageduration}), then the following command is defined which enables automatic advancing of \code{pdf}
+ pages.
+
+ \present[h]{\commandapp{pageDuration}{\carg{dur}}}\indexmacro{pageDuration}
+ causes pages to be advanced automatically every \carg{dur}
+ seconds. \carg{dur} should be a non-negative fixed-point number.
+
+ \pageDuration{2}\pause
+
+ Depending on the \code{pdf} viewer, this will happen only in full-screen mode.
+
+ See example \ref{Sec:ExFooling} for a demonstration of this effect.
+
+ \stopAdvancing
+
+ \newslide
+
+ The same restrictions as for \concept{page transitions} apply. In particular, the page duration setting is undone by
+ the end of a group, i.\,e.\ it is useless to set the page duration if a \LaTeX{} environment ends before the next page
+ break.
+
+ There is no `neutral' value for \carg{dur} ($0$ means advance as fast as possible). You can make automatic advancing
+ stop by calling \commandapp{pageDuration}{}. \code{texpower} offers the custom command
+ \begin{center}
+ \present[h]{\macroname{stopAdvancing}}\indexmacro{stopAdvancing}
+ \end{center}
+ to do this.
+
+ \newslide
+
+ %-----------------------------------------------------------------------------------------------------------------
+ %
+ \section{Color management, color emphasis and highlighting}\label{Sec:ColorEmphasis}
+ \TeX Power tries to find out whether you are making a colored document. This is assumed if
+ \begin{itemize}
+ \item the \href{ftp://ftp.dante.de/tex-archive/help/Catalogue/entries/color.html}{\code{color}} package has been
+ loaded before the \code{texpower} package or
+ \item a color-related option (see sections \ref{Sec:ColBgdOpt} and \ref{Sec:ColorOptions}) is given to the
+ \code{texpower} package (in this case, the
+ \href{ftp://ftp.dante.de/tex-archive/help/Catalogue/entries/color.html}{\code{color}} package is loaded
+ automatically).
+ \end{itemize}
+ If this is the case, \TeX Power installs an extensive color management scheme on top of the kernel of the
+ \href{ftp://ftp.dante.de/tex-archive/help/Catalogue/entries/color.html}{\code{color}} package.
+
+ In the following, some new concepts established by this management scheme are explained. Sections \ref{Sec:ColBgdOpt}
+ and \ref{Sec:ColorOptions} list options for color activation, section \ref{Sec:Colorcommands} lists some new
+ highlighting commands, and section \ref{Sec:Colors} gives the names and meaning of \TeX Power's predefined colors.
+
+ Note that parts of the kernel of the
+ \href{ftp://ftp.dante.de/tex-archive/help/Catalogue/entries/color.html}{\code{color}} package are overloaded for
+ special purposes (getting driver-independent representations of defined colors to be used by \macroname{colorbetween}
+ (\ref{Sec:MiscColorCommands}), for instance), so it is recommended to execute color definition commands like
+ \macroname{definecolor} \emph{after} the \code{texpower} package has been loaded (see also the next section on
+ \macroname{defineTPcolor}).
+
+ \newslide
+
+ \subsection{Standard colors}\label{Sec:StdCols}
+ \TeX Power maintains a list of \concept{standard colors} which are recognized and handled by \TeX Power's color
+ management. Some commands like \macroname{dimcolors} (see section \ref{Sec:ColorVariants}) affect \emph{all} standard
+ colors. There are some predefined colors which are in this list from the outset (see section \ref{Sec:Colors}).
+
+ If colors defined by the user are to be recognized by \TeX Power, they have to be included in this list. The easiest
+ way is to use the following command for defining them.
+
+ \newslide
+
+ \present{\commandapp{defineTPcolor}{\carg{name}\}\{\carg{model}\}\{\carg{def}}}
+ \indexmacro{defineTPcolor} acts like \macroname{definecolor}
+ \indexmacro{defineTPcolor} from the \code{color} package, but the color
+ \carg{name} is also added to the list of standard colors.
+
+ If you want to make a color a standard color which is defined elsewhere (by a document class, say), you can simply add
+ it to the list of standard colors with the command
+ \present{\commandapp{addTPcolor}{\carg{name}}}\indexmacro{addTPcolor}.
+
+ \newslide
+
+ \subsection{Color sets}
+ Every standard color may be defined in one or several \concept{color sets}. There are two fundamentally different
+ types of color set:
+ \begin{description}
+ \item[The current color set.] This contains the current definition of every standard color which is actually used at
+ the moment. Every standard color should be defined at least in the current color set. The current color set is not
+ distinguished by a special name.
+
+ \newslide
+
+ \item[Named color sets.] These are `containers' for a full set of color definitions (for the standard colors) which
+ can be activated by respective commands (see below). The color sets are distinguished by their names. Color
+ definitions in a named color set are not currently available, they have to be made available by activating the named
+ color set.
+
+ There are four predefined color sets named \code{whitebg}\indexcode{whitebg},
+ \code{lightbg}\indexcode{lightbg}, \code{darkbg}\indexcode{darkbg},
+ \code{blackbg}\indexcode{blackbg}, each of which contains a full set of (predefined)
+ standard colors customized for a white, light, dark, black background
+ color, respectively.
+ \end{description}
+
+ \newslide
+
+ There are the following commands for manipulating color sets:
+ \begin{description}
+ \item[\present{\commandapp{usecolorset}{\carg{name}}}]\indexmacro{usecolorset}
+ Make the color set named \carg{name} the current color set.
+ \emph{All standard colors in the current color set which are also in color set \carg{name} are overwritten.}
+
+ The standard color \code{textcolor} is set automatically after activating color set \carg{name}.
+
+ \item[\present{\commandapp{dumpcolorset}{\carg{name}}}]\indexmacro{dumpcolorset}
+ Copy the definitions of \emph{all} standard colors in the
+ current color set into color set named \carg{name}. All standard colors in color set \carg{name} will be
+ overwritten.
+ \end{description}
+
+ \newslide
+
+ Using \commandapp{defineTPcolor}{\carg{name}} or \commandapp{definecolor}{\carg{name}} will define the color
+ \carg{name} in the \emph{current} color set. To define a color in color set \carg{cset}, use
+ \present{\commandapp[\carg{cset}]{defineTPcolor}{\carg{name}}}.
+
+ \newslide
+
+ \minisec{Things to pay attention to}
+ \begin{enumerate}
+ \item Color sets are not really `\TeX{} objects', but are distinguished by color name suffixes. This means, a color
+ named \code{foo} is automatically in the current color set. Executing \commandapp[\carg{cset}]{defineTPcolor}{foo}
+ means executing \macroname{definecolor} for a specific color the name of which is a combination of \code{foo} and
+ \carg{cset}.
+
+ Consequently, \macroname{usecolorset} and \macroname{dumpcolorset} do not copy color sets as composite objects, but
+ simply all colors the names of which are generated from the list of standard colors.
+
+ \newslide
+
+ \item The command \commandapp{usecolorset}{\carg{name}} overwrites only those colors which have been defined in color
+ set \carg{name}. If a standard color is defined in the current color set, but not in color set \carg{name}, it is
+ preserved (but if \commandapp{dumpcolorset}{\carg{name}} is executed later, then it will also be copied back into
+ the color set \carg{name}).
+ \end{enumerate}
+
+ \newslide
+
+ \subsection{Color Background Options}\label{Sec:ColBgdOpt}
+ For activating the predefined color sets, there are shorthands
+ \macroname{whitebackground}\indexmacro{whitebackground},
+ \macroname{lightbackground}\indexmacro{lightbackground},
+ \macroname{darkbackground}\indexmacro{darkbackground},
+ \macroname{blackbackground}\indexmacro{blackbackground} which execute
+ \macroname{usecolorset} and additionally set the background color to its current value.
+
+ \newslide
+
+ When one of the following options is given, the respective command is executed automatically at the beginning of the
+ document.
+ \begin{description}
+ \item[\present{option: \code{whitebackground} (default)}]
+ \indexpckopt{texpower}{whitebackground}
+ Set standard colors to match a white background color.
+
+ \item[\present{option: \code{lightbackground}}]
+ \indexpckopt{texpower}{lightbackground}
+ Set standard colors to match a light (but not white) background color.
+
+ \item[\present{option: \code{darkbackground}}]
+ \indexpckopt{texpower}{darkbackground}
+ Set standard colors to match a dark (but not black) background color.
+
+ \item[\present{option: \code{blackbackground}}]
+ \indexpckopt{texpower}{blackbackground}
+ Set standard colors to match a black background color.
+ \end{description}
+
+ \newslide
+
+ \subsection{Color variants}\label{Sec:ColorVariants}
+ In addition to color sets, \TeX Power implements a concept of \concept{color variant}. Currently, every color has three
+ variants: \concept{normal}, \concept{dimmed}, and \concept{enhanced}. The normal variant is what is usually seen, text
+ written in the dimmed variant appears ``faded into the background'' and text written in the enhanced variant appears
+ to ``stick out''.
+
+ \newslide
+
+ When switching variants, for every color one of two cases can occur:
+ \begin{enumerate}
+ \item A \concept{designated color} for this variant has been defined.
+
+ For color \carg{color} the designated name of the \concept{dimmed}
+ \indexcode{dimmed color variant} variant is \code{d\carg{color}}, the designated
+ name of the \concept{enhanced}\indexcode{enhanced color variant} variant is
+ \code{e\carg{color}}.
+
+ If a color by that name exists at the time the variant is switched to, then variant switching is executed by
+ replacing color \carg{color} with the designated color.
+
+ \newslide
+
+ \item A \concept{designated color} for this variant has not been defined.
+
+ If a color by the designated name does not exist at the time a color variant is switched to, then variant switching
+ is executed by \concept{automatically} calculating the color variant from the original color.
+
+ The method for calculation depends on the variant:
+
+ \newslide
+
+ \begin{description}
+ \item[dimmed.] The dimmed variant is calculated by \concept{interpolating} between \code{pagecolor} and the color to
+ be dimmed, using the \macroname{colorbetween} command (see \ref{Sec:MiscColorCommands}).
+
+ There is a command \present{\macroname{dimlevel}}\indexmacro{dimlevel}
+ which contains the parameter \carg{weight} given to \macroname{colorbetween}
+ (default: \code{0.7}). This default can be overridden by either redefining
+ \macroname{dimlevel} or giving an alternative \carg{weight} as an optional
+ argument to the color dimming command (see below).
+
+ \newslide
+
+ \item[enhanced.] The enhanced variant is calculated by \concept{extrapolating} the color to be enhanced (relative to
+ \code{pagecolor}).
+
+ There is a command \present{\macroname{enhancelevel}}\indexmacro{enhancelevel}
+ which gives the \concept{extent} of the extrapolation (default: \code{0.5}).
+ The same holds for overriding this default as for \macroname{dimlevel}.
+ \end{description}
+ \end{enumerate}
+
+ \newslide
+
+ The following commands switch color variants:
+ \begin{description}
+ \item[\present{\commandapp[\carg{level}]{dimcolor}{\carg{color}}}]
+ \indexmacro{dimcolor} switches color \carg{color} to the \concept{dimmed}
+ variant. If given, \carg{level} replaces the value of \macroname{dimlevel} in automatic calculation of the dimmed
+ variant (see above).
+
+ \item[\present{\code{\macroname{dimcolors}[\carg{level}]}}]
+ \indexmacro{dimcolors} switches \emph{all} standard colors to the \concept{dimmed}
+ variant. The optional argument \carg{level} acts as for \macroname{dimcolor}.
+
+ \newslide
+
+ \item[\present{\commandapp[\carg{level}]{enhancecolor}{\carg{color}}}]
+ \indexmacro{enhancecolor} switches color \carg{color} to the
+ \concept{enhanced} variant. If given, \carg{level} replaces the value of \macroname{enhancelevel} in automatic
+ calculation of the enhanced variant (see above).
+
+ \item[\present{\code{\macroname{enhancecolors}[\carg{level}]}}]
+ \indexmacro{enhancecolors} switches \emph{all} standard colors to the
+ \concept{enhanceed} variant. The optional argument \carg{level} acts as for \macroname{enhancecolor}.
+ \end{description}
+
+ \newslide
+
+ \minisec{Things to pay attention to}
+ \begin{enumerate}
+ \item While automatic calculation of a \concept{dimmed} color will almost always yield the desired result
+ (interpolating between colors by calculating a weighted average is trivial), automatic calculation of an
+ \concept{enhanced} color by `extrapolating' is tricky at best and will often lead to unsatisfactory results. This is
+ because the idea of making a color `stronger' is very hard to formulate numerically.
+
+ \newslide
+
+ The following effects of the current algorithm should be kept in mind:
+ \begin{itemize}
+ \item if the background color is light, enhancing a color will make it darker;
+ \item if the background color is dark, enhancing a color will make it lighter;
+ \item sometimes, the numerical values describing an enhanced color have to be \concept{bounded} to avoid exceeding
+ the allowed range, diminishing the enhancing effect. For instance, if the background color is black and the color
+ to be enhanced is a `full-powered' yellow, there is no way of enhancing it by simple numeric calculation.
+ \end{itemize}
+
+ \newslide
+
+ As a conclusion, for best results it is recommended to provide custom \code{e} variants of colors to be enhanced. By
+ default, \TeX Power does not provide dedicated enhanced colors, but the file \code{tpsettings.cfg} contains complete
+ sets of enhanced variants for the standard colors in the different color sets, which you can uncomment and
+ experiment with as convenient.
+
+ \newslide
+
+ \item Currently, switching to a different color variant is done by simply overwriting the current definitions of all
+ standard colors. This means
+ \begin{itemize}
+ \item there is no way of `undimming' a color once it has been dimmed,
+ \item a dimmed color can not be enhanced and vice versa.
+ \end{itemize}
+ Maybe this will be solved in a slightly more clever way in subsequent releases of \TeX Power.
+
+ \newslide
+
+ Hence, it is recommended to
+ \begin{itemize}
+ \item restrict the \concept{scope} of a global variant switching command like \macroname{dimcolors},
+ \macroname{enhancecolors} or \macroname{dstep} by enlcosing it into a \LaTeX{} group (like \code{\{\dots\}}) or
+ \item use \macroname{dumpcolorset} before the command to save the current definitions of all colors, to be restored
+ with \macroname{usecolorset}.
+
+ At the very beginning of a \macroname{stepwise} command, \TeX Power executes \commandapp{dumpcolorset}{stwcolors},
+ so you can restore the colors anywhere in the argument of \macroname{stepwise} by saying
+ \commandapp{usecolorset}{stwcolors}.
+ \end{itemize}
+
+ \newslide
+
+ \item Some rudimentary attempts are made to keep track of which color is in what variant, to the effect that
+ \begin{itemize}
+ \item a color which is not in the normal variant will neither be dimmed nor enhanced;
+ \item when \macroname{usecolorset} overwrites a color with its normal variant, this is registered.
+ \end{itemize}
+ Still, it is easy to get in trouble by mixing variant changes with color set changes (say, if not all standard
+ colors are defined in a color set, or if a color set is dumped when not all colors are in normal variant), so it is
+ recommended not to use or dump color sets when outside the normal variant (unless for special applications like
+ undoing a variant change by \commandapp{usecolorset}{stwcolors}).
+ \end{enumerate}
+
+
+ \newslide
+
+ \subsection{Miscellaneous color management commands}\label{Sec:MiscColorCommands}
+ \begin{description}
+ \item[\present{\commandapp[\carg{tset}]{replacecolor}{\carg{tcolor}\}[\carg{sset}]\{\carg{scolor}}}]
+ \indexmacro{} makes
+ \carg{tcolor} have the same definition as \carg{scolor} (if \carg{scolor} is defined at all), where \carg{tcolor}
+ and \carg{scolor} are color names as given in the first argument of \macroname{definecolor}. If (one of)
+ \carg{tset} and \carg{sset} are given, the respective color is taken from the respective color set, otherwise from
+ the current color set.
+
+ If \carg{scolor} is not defined (in color set \carg{sset}), \carg{tcolor} is left alone.
+
+ \newslide
+
+ \item[\present{\commandapp[\carg{weight}]{colorbetween}{\carg{src1}\}\{\carg{src2}\}\{\carg{target}}}]
+ \indexmacro{colorbetween} calculates a
+ `weighted average' between two colors. \carg{src1} and \carg{src2} are the names of the two colors. \carg{weight}
+ (default: $0.5$) is a fixed-point number between $0$ and $1$ giving the `weight' for the interpolation between
+ \carg{src1} and \carg{src2}. \carg{target} is the name to be given to the resulting mixed color.
+
+ If \carg{weight} is $1$, then \carg{target} will be identical to \carg{src1} (up to color model conversions, see
+ below), if \carg{weight} is $0$, then \carg{target} will be identical to \carg{src2}, if \carg{weight} is $0.5$
+ (default), then \carg{target} will be exactly in the middle between \carg{src1} and \carg{src2}.
+
+ \macroname{colorbetween} supports the following color models: \code{rgb}, \code{RGB}, \code{gray}, \code{cmyk},
+ \code{hsb}. If both colors are of the same model, the resulting color is also of the respective model. If
+ \carg{src1} and \carg{src2} are from \emph{different} models, then \carg{target} will \emph{always} be an \code{rgb}
+ color. The only exception is the \code{hsb} color model: As I don't know how to convert \code{hsb} to \code{rgb},
+ mixing \code{hsb} with another color model will always raise an error.
+
+ \newslide
+
+ \item[\present{\commandapp{mkfactor}{\carg{expr}\}\{\carg{macroname}}}]
+ \indexmacro{mkfactor} is a helper command for automatically
+ generating the fixed point numbers between $0$ and $1$ which are employed by the color calculation commands.
+ \carg{expr} can be any expression which can stand behind \code{*} in expressions allowed by the
+ \href{ftp://ftp.dante.de/tex-archive/help/Catalogue/entries/calc.html}{\code{calc}} package (for instance:
+ \code{\commandapp{value}{counter}/\commandapp{value}{maxcounter}} or \macroname{ratio} or whatever).
+ \carg{macroname} should be a valid macro name. \carg{expr} is converted into a fixed-point representation which is
+ then assigned to \carg{macroname}.
+
+ \newslide
+
+ \item[\present{\code{\macroname{vanishcolors}[\carg{color}]}}]
+ \indexmacro{vanishcolors} is similar to the color variant command
+ \macroname{dimcolors}, but instead of dimming colors, all standard colors are replaced by a single color given by
+ the new command \present{\macroname{vanishcolor}} (default: \code{pagecolor}). Hence, the result of calling
+ \macroname{vanishcolors} should be that all text vanishes, as it is written in the background color (this doesn't
+ work with structured backgrounds, of course).
+
+ For getting a color different from the default \code{pagecolor}, you can either redefinine \macroname{vanishcolor}
+ or give an alternative \carg{color} as an optional argument to \macroname{vanishcolors}.
+
+ There is no dedicated command for making a single color vanish. To achieve this, use
+ \commandapp{replacecolor}{\carg{color}\}\{\macroname{vanishcolor}}.
+ \end{description}
+
+
+ \subsection{Color Emphasis and Highlighting}\label{Sec:ColorOptions}
+ \code{texpower} offers some support for text emphasis and highlighting with colors (instead of, say, font
+ changes). These features are enabled by the following options:
+ \begin{description}
+ \item[\present{option: \code{coloremph}}]\indexpckopt{texpower}{coloremph}
+ Make \macroname{em} and \macroname{emph} switch colors instead of fonts.
+
+ \item[\present{option: \code{colormath}}]\indexpckopt{texpower}{colormath}
+ Color all mathematical formulae.
+
+ \item[\present{option: \code{colorhighlight}}]\indexpckopt{texpower}{colorhighlight}
+ Make new highlighting and emphasis commands defined by \code{texpower}
+ use colors.
+ \end{description}
+
+ \minisec{Things to pay attention to}
+ \begin{enumerate}
+ \item You need the \code{color} package to use any of the color features.
+
+ \item To implement the options \code{coloremph} and \code{colormath}, it is neccessary to redefine some \LaTeX{}
+ internals. This can lead to problems and incompatibilities with other packages. Use with caution.
+
+ \item If the \code{colorhighlight} option is \emph{not} given, new highlighting and emphasis commands defined by
+ \code{texpower} are realized otherwise. Sometimes, however, there is no good alternative to colors, so different
+ emphasis commands can become disabled or indistinguishable.
+
+ \newslide
+
+ \item Because of font changes, emphasized or highlighted text can have different dimensions whether or not the options
+ \code{coloremph}, \code{colormath}, and \code{colorhighlight} are set. Prepare for different line and page breaks
+ when changing one of these options.
+
+ \item Color emphasis and highlighting makes use of the predefined standard colors described in section
+ \ref{Sec:Colors}. See sections \ref{Sec:StdCols} to \ref{Sec:ColBgdOpt} for further information on standard colors,
+ color sets, and customization.
+ \end{enumerate}
+
+ \newslide
+
+ \subsection{New commands for emphasis and highlighting elements}\label{Sec:Colorcommands}
+ Some things like setting the page or text color, making emphasised text or math colored are done automatically when
+ the respective options are set. There are some additional new commands for creating emphasis and highlighting
+ elements.
+
+ \minisec{Concerning math:}
+ \begin{description}
+ \item[\present{\macroname{origmath}}]\indexmacro{origmath}
+ When the \code{colormath} option is given, \emph{everything} which appears in
+ math mode is colored accordingly. Sometimes, however, math mode is used for something besides mathematical formulae.
+ Some \LaTeX{} commands which internally use math mode (like \code{tabular} or \macroname{textsuperscript}) are
+ redefined accordingly when the \code{colormath} option is given (this is a potential source of trouble; beware of
+ problems\dots).
+
+ If you need to use math mode for something which is not to be colored (like a symbol for \code{itemize}), you can
+ use the \macroname{origmath} command which works exactly like \macroname{ensuremath} but doesn't color its argument.
+ If a nested use of math mode should occur in the argument of \macroname{origmath}, it will again be colored.
+ \end{description}
+
+ \newslide
+
+ \minisec{Documenting \TeX{} code:}
+ \begin{description}
+ \item[\present{\macroname{code}}]\indexmacro{code}
+ Simple command for typesetting \code{code} (like shell commands).
+
+ \item[\present{\macroname{macroname}}]\indexmacro{macroname}
+ For \macroname{macro names}. Like \macroname{code}, but with a \macroname{} in
+ front.
+
+ \item[\present{\commandapp[\carg{opt arg}]{commandapp}{\carg{command}\}\{\carg{arg}}}]
+ \indexmacro{commandapp} For \TeX{} commands. \carg{arg}
+ stands for the command argument, \carg{opt arg} for an optional argument.
+
+ \item[\present{\macroname{carg}}]\indexmacro{carg}
+ For \carg{macro arguments}.
+ \end{description}
+
+ \newslide
+
+ \minisec{Additional emphasis commands:}
+ \begin{description}
+ \item[\present{\macroname{underl}}]\indexmacro{underl}
+ Additional \underl{emphasis} command. Can be used like \macroname{emph}. Defaults
+ to \textbf{bold face} if the \code{colorhighlight} option is not given.
+
+ \item[\present{\macroname{concept}}]\indexmacro{concept}
+ Additional \concept{emphasis} command, especially for new concepts. Can be
+ augmented by things like automatic index entry creation. Also defaults to \textbf{bold face} if the
+ \code{colorhighlight} option is not given.
+
+ \item[\present{\macroname{inactive}}]\indexmacro{inactive}
+ Additional \inactive{emphasis} command, this time for `de-emphasising'. There is
+ no sensible default if the \code{colorhighlight} option is not given, as base \LaTeX{} doesn't offer an appropriate
+ font. In this case, \macroname{inactive} defaults to \macroname{monochromeinactive}, which does nothing.
+
+ You can (re-)define \macroname{monochromeinactive} to provide some sensible behaviour in the absence of colors, for
+ instance striking out if you're using the
+ \href{ftp://ftp.dante.de/tex-archive/help/Catalogue/entries/soul.html}{\code{soul}} package.
+ \end{description}
+
+
+ \minisec{Color Highlighting:}
+ \begin{description}
+ \item[\present{\macroname{present}}]\indexmacro{present}
+ Highlighting command which puts its argument into a \present{box with colored
+ background}. Defaults to an \fbox{\macroname{fbox}} if the \code{colorhighlight} option is not given.
+
+ See section \ref{Sec:displaycustom} for some further highlighting commands.
+ \end{description}
+
+ \newslide
+
+ \subsection{Predefined standard colors}\label{Sec:Colors}
+ In previous subsections, it has been mentioned that \TeX Power predefines some standard colors which have appropriate
+ values in the predefined color sets \code{whitebg}, \code{lightbg}, \code{darkbg}, and \code{blackbg} (see sections
+ \ref{Sec:StdCols} to \ref{Sec:ColBgdOpt} for further information on standard colors, color sets, and customization).
+ \begin{description}
+ \item[\present{color: \code{pagecolor}}]\indexcode{pagecolor}
+ Background color of the page. Is set automatically at the beginning of the
+ document if color management is active.
+
+ \item[\present{color: \code{textcolor}}]\indexcode{textcolor}
+ Color of normal text. Is set automatically at the beginning of the
+ document if color management is active.
+
+ \item[\present{color: \code{emcolor}}]\indexcode{emcolor}
+ Color used for \emph{emphasis} if the \code{coloremph} option is set.
+
+ \item[\present{color: \code{altemcolor}}]\indexcode{altemcolor}
+ Color used \emph{for \emph{double} emphasis} if the \code{coloremph} option
+ is set.
+
+ \item[\present{color: \code{mathcolor}}]\indexcode{mathcolor}
+ Color used for math $a^2+b^2=c^2$ if the \code{colormath} option is set.
+
+ \item[\present{color: \code{codecolor}}]\indexcode{codecolor}
+ Color used by the \macroname{code} command if the \code{colorhighlight}
+ option is set.
+
+ \item[\present{color: \code{underlcolor}}]\indexcode{underlcolor}
+ Color used by the \underl{\macroname{underl} command} if the
+ \code{colorhighlight} option is set.
+
+ \item[\present{color: \code{conceptcolor}}]\indexcode{conceptcolor}
+ Color used by the \concept{\macroname{concept} command} if the
+ \code{colorhighlight} option is set.
+
+ \newslide
+
+ \item[\present{color: \code{inactivecolor}}]\indexcode{inactivecolor}
+ Color used by the \inactive{\macroname{inactive} command} if the
+ \code{colorhighlight} option is set.
+
+ \item[\present{color: \code{presentcolor}}]\indexcode{presentcolor}
+ Color used as background color by the \present{\macroname{present}}
+ command if the \code{colorhighlight} option is set.
+
+ \item[\present{color: \code{highlightcolor}}]\indexcode{highlightcolor}
+ Color used as background color by the
+ \highlightboxed{\macroname{highlightboxed}} and \macroname{highlighttext} commands (see section
+ \ref{Sec:displaycustom}) if the \code{colorhighlight} option is set.
+ \end{description}
+
+\ifthenelse{\boolean{TPcolor}}
+{%
+ \newslide
+
+ \whitebackground
+
+ \minisec{Color tables}
+
+ \newlength{\widthfirstcol}
+ \settowidth{\widthfirstcol}{\textbf{\footnotesize white background}}
+
+ \vspace*{\fill}
+ \begin{center}
+ \begin{tabular}{|p{\widthfirstcol}*{3}{|p{2cm}}|}
+ \cline{2-4}
+ \multicolumn{1}{l|}{\textbf{\footnotesize white background}}&standard&dimmed&enhanced\\\hline
+ \code{textcolor}&\textcolor{textcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{textcolor}\textcolor{textcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{textcolor}\textcolor{textcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{emcolor}&\textcolor{emcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{emcolor}\textcolor{emcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{emcolor}\textcolor{emcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{altemcolor}&\textcolor{altemcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{altemcolor}\textcolor{altemcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{altemcolor}\textcolor{altemcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{mathcolor}&\textcolor{mathcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{mathcolor}\textcolor{mathcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{mathcolor}\textcolor{mathcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{codecolor}&\textcolor{codecolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{codecolor}\textcolor{codecolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{codecolor}\textcolor{codecolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{underlcolor}&\textcolor{underlcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{underlcolor}\textcolor{underlcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{underlcolor}\textcolor{underlcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{conceptcolor}&\textcolor{conceptcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{conceptcolor}\textcolor{conceptcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{conceptcolor}\textcolor{conceptcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{inactivecolor}&\textcolor{inactivecolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{inactivecolor}\textcolor{inactivecolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{inactivecolor}\textcolor{inactivecolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{presentcolor}&\textcolor{presentcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{presentcolor}\textcolor{presentcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{presentcolor}\textcolor{presentcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{highlightcolor}&\textcolor{highlightcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{highlightcolor}\textcolor{highlightcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{highlightcolor}\textcolor{highlightcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \end{tabular}
+ \end{center}
+
+ \newslide
+
+ \lightbackground
+
+ \vspace*{\fill}
+ \begin{center}
+ \begin{tabular}{|p{\widthfirstcol}*{3}{|p{2cm}}|}
+ \cline{2-4}
+ \multicolumn{1}{l|}{\textbf{\footnotesize light background}}&standard&dimmed&enhanced\\\hline
+ \code{textcolor}&\textcolor{textcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{textcolor}\textcolor{textcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{textcolor}\textcolor{textcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{emcolor}&\textcolor{emcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{emcolor}\textcolor{emcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{emcolor}\textcolor{emcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{altemcolor}&\textcolor{altemcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{altemcolor}\textcolor{altemcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{altemcolor}\textcolor{altemcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{mathcolor}&\textcolor{mathcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{mathcolor}\textcolor{mathcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{mathcolor}\textcolor{mathcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{codecolor}&\textcolor{codecolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{codecolor}\textcolor{codecolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{codecolor}\textcolor{codecolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{underlcolor}&\textcolor{underlcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{underlcolor}\textcolor{underlcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{underlcolor}\textcolor{underlcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{conceptcolor}&\textcolor{conceptcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{conceptcolor}\textcolor{conceptcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{conceptcolor}\textcolor{conceptcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{inactivecolor}&\textcolor{inactivecolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{inactivecolor}\textcolor{inactivecolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{inactivecolor}\textcolor{inactivecolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{presentcolor}&\textcolor{presentcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{presentcolor}\textcolor{presentcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{presentcolor}\textcolor{presentcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{highlightcolor}&\textcolor{highlightcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{highlightcolor}\textcolor{highlightcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{highlightcolor}\textcolor{highlightcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \end{tabular}
+ \end{center}
+
+ \newslide
+
+ \darkbackground
+
+ \vspace*{\fill}
+ \begin{center}
+ \begin{tabular}{|p{\widthfirstcol}*{3}{|p{2cm}}|}
+ \cline{2-4}
+ \multicolumn{1}{l|}{\textbf{\footnotesize dark background}}&standard&dimmed&enhanced\\\hline
+ \code{textcolor}&\textcolor{textcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{textcolor}\textcolor{textcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{textcolor}\textcolor{textcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{emcolor}&\textcolor{emcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{emcolor}\textcolor{emcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{emcolor}\textcolor{emcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{altemcolor}&\textcolor{altemcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{altemcolor}\textcolor{altemcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{altemcolor}\textcolor{altemcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{mathcolor}&\textcolor{mathcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{mathcolor}\textcolor{mathcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{mathcolor}\textcolor{mathcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{codecolor}&\textcolor{codecolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{codecolor}\textcolor{codecolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{codecolor}\textcolor{codecolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{underlcolor}&\textcolor{underlcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{underlcolor}\textcolor{underlcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{underlcolor}\textcolor{underlcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{conceptcolor}&\textcolor{conceptcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{conceptcolor}\textcolor{conceptcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{conceptcolor}\textcolor{conceptcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{inactivecolor}&\textcolor{inactivecolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{inactivecolor}\textcolor{inactivecolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{inactivecolor}\textcolor{inactivecolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{presentcolor}&\textcolor{presentcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{presentcolor}\textcolor{presentcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{presentcolor}\textcolor{presentcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{highlightcolor}&\textcolor{highlightcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{highlightcolor}\textcolor{highlightcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{highlightcolor}\textcolor{highlightcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \end{tabular}
+ \end{center}
+
+ \newslide
+
+ \blackbackground
+
+ \vspace*{\fill}
+ \begin{center}
+ \begin{tabular}{|p{\widthfirstcol}*{3}{|p{2cm}}|}
+ \cline{2-4}
+ \multicolumn{1}{l|}{\textbf{\footnotesize black background}}&standard&dimmed&enhanced\\\hline
+ \code{textcolor}&\textcolor{textcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{textcolor}\textcolor{textcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{textcolor}\textcolor{textcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{emcolor}&\textcolor{emcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{emcolor}\textcolor{emcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{emcolor}\textcolor{emcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{altemcolor}&\textcolor{altemcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{altemcolor}\textcolor{altemcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{altemcolor}\textcolor{altemcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{mathcolor}&\textcolor{mathcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{mathcolor}\textcolor{mathcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{mathcolor}\textcolor{mathcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{codecolor}&\textcolor{codecolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{codecolor}\textcolor{codecolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{codecolor}\textcolor{codecolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{underlcolor}&\textcolor{underlcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{underlcolor}\textcolor{underlcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{underlcolor}\textcolor{underlcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{conceptcolor}&\textcolor{conceptcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{conceptcolor}\textcolor{conceptcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{conceptcolor}\textcolor{conceptcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{inactivecolor}&\textcolor{inactivecolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{inactivecolor}\textcolor{inactivecolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{inactivecolor}\textcolor{inactivecolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{presentcolor}&\textcolor{presentcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{presentcolor}\textcolor{presentcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{presentcolor}\textcolor{presentcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \code{highlightcolor}&\textcolor{highlightcolor}{\rule{2cm}{\heightof{l}}}&\dimcolor{highlightcolor}\textcolor{highlightcolor}{\rule{2cm}{\heightof{l}}}&\enhancecolor{highlightcolor}\textcolor{highlightcolor}{\rule{2cm}{\heightof{l}}}\\\hline
+ \end{tabular}
+ \end{center}
+}{}
+
+ \newslide
+
+ \ifthenelse{\boolean{TPcolor}}{\lightbackground}{}
+
+ %-----------------------------------------------------------------------------
+ %
+ \section{Structured page backgrounds and panels}\label{Sec:PageBackPanel}
+ \subsection{Structured page backgrounds}
+
+ \present{\commandapp[\carg{options}]{backgroundstyle}{\carg{style}}}
+ \indexmacro{backgroundstyle}
+ is the central command for structured page backgrounds. It works like
+ \macroname{pagestyle} and other commands of this type. This means
+ \carg{style} is a symbolic name specifying the general method by which the
+ page background is constructed.
+
+ The detailed construction is influenced by parameters which can be set in
+ \carg{options}. If given, the optional parameter \carg{options} should
+ contain a list of settings in ``keyval'' manner. The keyval method
+ % (which is used by the \includegraphics command from the graphicx package,
+ %for instance)
+ is based on associating a symbolic name with every parameter. \carg{options}
+ is then a comma-separated list of parameter settings of the form
+ \carg{name}=\carg{value}, where \carg{name} is the symbolic name of the
+ parameter to be set and \carg{value} is the value it is to be set to.
+
+ Not every \carg{style} evaluates every parameter. In the following, a
+ description of all styles, together with lists of the parameters employed, is
+ given. It is followed by a list of all parameters. Note that some parameter
+ names internally access the same parameter. For instance, parameters
+ \code{startcolor} and \code{startcolordef} both set the start color of a color
+ gradient. In case of conflict, the last setting in the list \carg{options}
+ will prevail. It is noted in the list of parameters which other parameters
+ are overwritten.
+
+ \newslide
+
+ \carg{style} may have one of the following values:
+ \begin{description}
+ \item[\present{Style: \code{none}}]
+ \indexmacroopt{backgroundstyle}{none}%
+ No background. This means the page background is whatever it would be if
+ \macroname{backgroundstyle} wasn't used at all (for instance, a plain area
+ of color pagecolor if one of the color options has been given).
+
+ Parameters used: none.
+
+ \item[\present{Style: \code{plain}}]
+ \indexmacroopt{backgroundstyle}{plain}%
+ Plain background. This means the page background is whatever it would be if
+ \macroname{backgroundstyle} wasn't used at all (as for no background). In
+ addition to background style \code{none}, the background style \code{plain}
+ does produce panel backgrounds. The colors and dimensions of a \code{top
+ panel}, \code{bottom panel}, \code{left panel}, and \code{right panel} can
+ be specified.
+
+ \begin{flushleft}
+ Parameters used: \code{hpanels}, \code{autopanels}, \code{toppanelcolor},
+ \code{bottompanelcolor}, \code{leftpanelcolor}, \code{rightpanelcolor},
+ \code{toppanelcolordef}, \code{bottompanelcolordef}, \code{leftpanelcolordef},
+ \code{rightpanelcolordef}, \code{toppanelheight}, \code{bottompanelheight},
+ \code{leftpanelwidth}, \code{rightpanelwidth}.
+ \end{flushleft}
+
+ \item[\present{Style: \code{vgradient}}]
+ \indexmacroopt{backgroundstyle}{vgradient}%
+ Vertical gradient. The page background is constructed using the
+ \macroname{vgradrule}\indexmacro{vgradrule} command. In addition to the
+ usual parameters of gradient rules, the vgradient background style allows
+ to leave space for headers, footers, or panels. The colors and dimensions
+ of a \code{top panel}, \code{bottom panel}, \code{left panel}, and
+ \code{right panel} can be specified. The gradient rule fills the
+ rectangular space left between the specified panels.
+
+ \begin{flushleft}
+ Parameters used: \code{stripes}, \code{firstgradprogression},
+ \code{startcolor}, \code{startcolordef}, \code{endcolor}, \code{endcolordef}
+ in addition to the parameters used for style \code{plain}.
+ \end{flushleft}
+
+ \item[\present{Style: \code{hgradient}}]
+ \indexmacroopt{backgroundstyle}{hgradient}%
+ Horizontal gradient. The page background is constructed using the
+ \macroname{hgradrule}\indexmacro{hgradrule} command. See the description of
+ \macroname{vgradient} concerning panels.
+
+ Parameters used: See list for style \code{vgradient}.
+
+ \item[\present{Style: \code{doublevgradient}}]
+ \indexmacroopt{backgroundstyle}{doublevgradient}%
+ Double vertical gradient. The page background is constructed using the
+ \macroname{dblvgradrule}\indexmacro{dblvgradrule} command. See the
+ description of \macroname{vgradient} concerning panels.
+
+ \begin{flushleft}
+ Parameters used: \code{gradmidpoint}, \code{secondgradprogression},
+ \code{midcolor}, \code{midcolordef} in addition to the parameters used for
+ style \code{vgradient} (and \code{plain}).
+ \end{flushleft}
+
+ \item[\present{Style: \code{doublehgradient}}]
+ \indexmacroopt{backgroundstyle}{doublehgradient}%
+ Double horizontal gradient. The page background is constructed using the
+ \macroname{dblhgradrule}\indexmacro{dblhgradrule} command. See the description of
+ \macroname{vgradient} concerning panels.
+
+ Parameters used: See list for \code{doublevgradient}.
+
+ \end{description}
+ Now, a list of all parameters and their meaning. In the following,
+ \begin{itemize}\setlength{\itemsep}{0cm}
+ \item[\carg{n}] denotes a (calc expression for a) nonnegative integer
+ \item[\carg{i}] denotes a (calc expression for an) integer
+ \item[\carg{r}] denotes a fixed-point number
+ \item[\carg{l}] denotes a (calc expression for a) length
+ \item[\carg{c}] denotes the name of a defined color
+ \item[\carg{cm}] denotes a valid color model name (in the sense of the color
+ package)
+ \item[\carg{cd}] denotes a valid color definition (in the sense of the color
+ package) wrt a given \carg{cm} parameter
+ \item[\carg{t}] denotes a `truth value' in the sense of the ifthen package:
+ either true or false. As usual for keyval, if =\carg{t} is omitted, the
+ default true is assumed.
+ \end{itemize}
+ \begin{description}
+ \item[\present{Option: \code{stripes=}\carg{n}}] Set the \carg{stripes}
+ parameter of gradient rules to \carg{n}.\\
+ Default: \macroname{bgndstripes}. \\
+ Used by: \code{vgradient}, \code{hgradient}, \code{doublevgradient},
+ \code{doublehgradient}.
+
+ \item[\present{Option: \code{gradmidpoint=}\carg{r}}] Set the \carg{midpoint}
+ parameter of double gradient rules to \carg{r}.\\
+ Default: \macroname{bgndgradmidpoint}\\
+ Used by: doublevgradient, doublehgradient
+
+ \item[\present{Option: \code{firstgradprogression=}\carg{i}}]
+ Set the first gradient progression of gradient rules to \carg{i}.\\
+ Default: \macroname{bgndfirstgradprogression}\\
+ Used by: vgradient, hgradient, doublevgradient, doublehgradient
+
+ \item[\present{Option: \code{secondgradprogression=}\carg{i}}]
+ Set the second gradient progression of double gradient rules to \carg{i}.\\
+ Default: \macroname{bgndsecondgradprogression}\\
+ Used by: doublevgradient, doublehgradient
+
+ \item[\present{Option: \code{startcolor=}\carg{c}}]
+ Set the \carg{startcolor} parameter of gradient rules to \carg{c}.\\
+ Default: If neither startcolor nor startcolordef is given, the color
+ bgndstartcolor is used as startcolor.\\
+ Used by: vgradient, hgradient, doublevgradient, doublehgradient\\
+ Overwrites: startcolordef
+
+ \item[\present{Option: \code{startcolordef=\{\carg{cm}\}\{\carg{cd}\}}}]
+ Set the \carg{startcolor} parameter of gradient rules to color foo, which
+ is obtained by \macroname{definecolor\{foo\}\{\carg{cm}\}\{\carg{cd}\}}.
+ Note that the two pairs of curly braces are mandatory.\\
+ Default: If neither startcolor nor startcolordef is given, the color
+ bgndstartcolor is used as startcolor.\\
+ Used by: vgradient, hgradient, doublevgradient, doublehgradient\\
+ Overwrites: startcolor
+
+ \item[\present{Option: \code{endcolor=}\carg{c}}]
+ Set the \carg{endcolor} parameter of gradient rules to \carg{c}.\\
+ Default: If neither endcolor nor endcolordef is given, the color
+ bgndendcolor is used as endcolor.\\
+ Used by: vgradient, hgradient, doublevgradient, doublehgradient\\
+ Overwrites: endcolordef
+
+ \item[\present{Option: \code{endcolordef=\{\carg{cm}\}\{\carg{cd}\}}}]
+ Set the \carg{endcolor} parameter of gradient rules to color foo, which
+ is obtained by \macroname{definecolor\{foo\}\{\carg{cm}\}\{\carg{cd}\}}.
+ Note that the two pairs of curly braces are mandatory.\\
+ Default: If neither endcolor nor endcolordef is given, the color
+ bgndendcolor is used as endcolor.\\
+ Used by: vgradient, hgradient, doublevgradient, doublehgradient\\
+ Overwrites: endcolor
+
+ \item[\present{Option: \code{midcolor=}\carg{c}}]
+ Set the \carg{midcolor} parameter of double gradient rules to \carg{c}.\\
+ Default: If neither midcolor nor midcolordef is given, the color
+ bgndmidcolor is used as midcolor.\\
+ Used by: doublevgradient, doublehgradient\\
+ Overwrites: midcolordef
+
+ \item[\present{Option: \code{midcolordef=\{\carg{cm}\}\{\carg{cd}\}}}]
+ Set the \carg{midcolor} parameter of double gradient rules to color foo,
+ which is obtained by \macroname{definecolor\{foo\}\{\carg{cm}\}\{\carg{cd}\}}.
+ Note that the two pairs of curly braces are mandatory.\\
+ Default: If neither midcolor nor midcolordef is given, the color
+ bgndmidcolor is used as midcolor.\\
+ Used by: doublevgradient, doublehgradient\\
+ Overwrites: midcolor
+
+ \item[\present{Option: \code{hpanels=}\carg{t}}]
+ Specifies the `direction' of panels produced. hpanels=true means the top
+ and bottom panel span the full width of the screen. In the space left in
+ the middle, the left panel, the background itself, and the right panel are
+ displayed. hpanels=false means the left and right panel span the full
+ height of the screen. In the space left in the middle, the top panel,
+ the background itself, and the bottom panel are
+ displayed.\\
+ Default: hpanels=true is the default for plain, hgradient and
+ doublehgradient. hpanels=false is the default for vgradient and
+ doublevgradient.\\
+ Used by: plain, vgradient, hgradient, doublevgradient, doublehgradient
+
+ \item[\present{Option: \code{autopanels=}\carg{t}}]
+ Specifies whether the default values of the parameters toppanelheight,
+ bottompanelheight, leftpanelwidth, rightpanelwidth should be calculated
+ automatically from the contents of declared panels. The automatism used
+ is analogous to that of \macroname{DeclarePanel*}. Note that for panel
+ arrangement, both the width and the height of all declared panels are
+ overwritten. If you don't want this, calculate the panel parameters
+ yourself and set autopanels=false. In this case, the current panel
+ dimensions of declared panels are used as defaults for toppanelheight,
+ bottompanelheight, leftpanelwidth, rightpanelwidth.\\
+ Default: true.\\
+ Used by: plain, vgradient, hgradient, doublevgradient, doublehgradient
+
+ \item[\present{Option: \code{\carg{pos}panelheight=}\carg{l}}]
+ Set the height/width of the space left for the top / bottom / left / right
+ panel to \carg{l}. Note that the remaining dimensions of panels, for
+ instance the width of the top panel, are always calculated automatically,
+ depending on the setting of the hpanels parameter.\\
+ Default: If a respective panel has been defined using
+ \macroname{DeclarePanel}, the default used depends on the setting of the
+ autopanels parameter. If autopanels=true, the correct dimension is
+ calculated from the contents of the panel. The respective one of
+ \macroname{toppanelheight}, \macroname{bottompanelheight},
+ \macroname{leftpanelwidth}, \macroname{rightpanelwidth} is overwritten
+ with the result. If autopanels=false, then the respective setting of
+ \macroname{toppanelheight}, \macroname{bottompanelheight},
+ \macroname{leftpanelwidth}, \macroname{rightpanelwidth} is taken as the
+ default. If a panel has not been declared, the appropriate one of
+ \macroname{bgndtoppanelheight}, \macroname{bgndbottompanelheight},
+ \macroname{bgndleftpanelwidth}, \macroname{bgndrightpanelwidth} is used
+ as default. \\
+ Used by: plain, vgradient, hgradient, doublevgradient, doublehgradient
+
+ \item[\present{Option: \code{\carg{pos}panelcolor=}\carg{c}}]
+ Set the color of the space left for the top / bottom / left / right panel
+ to \carg{c}.\\
+ Default: The standard colors toppanelcolor, bottompanelcolor, leftpanelcolor,
+ rightpanelcolor are used as defaults.\\
+ Used by: plain, vgradient, hgradient, doublevgradient, doublehgradient\\
+ Overwrites: toppanelcolordef bottompanelcolordef leftpanelcolordef
+ rightpanelcolordef
+
+ \item[\present{Option: \code{\carg{pos}panelcolordef=\{\carg{cm}\}\{\carg{cd}\}}}]
+ Set the color of the space left for the top / bottom / left / right panel
+ to color foo, which is obtained by
+ \macroname{definecolor\{foo\}\{\carg{cm}\}\{\carg{cd}\}}.
+ Note that the two pairs of curly braces are mandatory. \\
+ Default: See the description of top/bottom/left/rightpanelcolor.\\
+ Used by: plain, vgradient, hgradient, doublevgradient, doublehgradient\\
+ Overwrites: toppanelcolor bottompanelcolor leftpanelcolor rightpanelcolor
+
+ \end{description}
+
+ \newslide
+
+ \subsection{Panel-specific user level commands}
+ If you're using a package that has it own panel (as
+ \href{ftp://ftp.dante.de/tex-archive/help/Catalogue/entries/pdfscreen.html}%
+ {\code{pdfscreen}}) don't even consider using the following.
+
+ \present{\commandapp[\carg{name}]{DeclarePanel}{\carg{pos}\}\{\carg{contents}}}
+ \indexmacro{DeclarePanel}
+ declares the contents \carg{contents} of the panel at position \carg{pos}.
+ Afterwards, on every page the panel contents are set in a parbox of
+ dimensions and position specified by \carg{pos}panelwidth,
+ \carg{pos}panelheight, \macroname{panelmargin} and \carg{pos}panelshift for
+ top and bottom panels and \carg{pos}panelraise for left and right panels. The
+ parbox is constructed anew on every page, so all changes influencing panel
+ contents or parameters (like a \macroname{thepage} in the panel contents) are
+ respected.
+
+ The panel contents are set in color \carg{pos}paneltextcolor. There is
+ another standard color \carg{pos}panelcolor, which is however not activated by
+ \macroname{DeclarePanel} but by selecting an appropriate background style.
+
+ Note that \macroname{backgroundstyle} must be called after the panel
+ declaration.
+
+ \newslide
+
+ Pages are constructed as follows: first the page background, then
+ the panels, and then the page contents. \emph{Hence, panels overwrite the background
+ and the page contents overwrite the panels.} The user is supposed to make sure
+ themselves that there is enough space left on the page for the panels
+ (document class specific settings). The panel declaration is global. A panel
+ can be `undeclared' by using \macroname{DeclarePanel\{\carg{pos}\}\{\}}.
+
+ If the optional argument \carg{name} is given, the panel contents and
+ (calculated) size will also be stored under the given name, to be restored
+ later with \macroname{restorepanels}. This is nice for switching between
+ different sets of panels.
+
+ \newslide
+
+ For an example look at the files \code{simplepanel.tex} and \code{panelexample.tex}.
+ A very simple example follows:
+
+ \begin{verbatim}
+\DeclarePanel{left}{%
+ \textsf{Your Name}
+
+ \vfill
+
+ \button{\Acrobatmenu{PrevPage}}{Back}
+ \button{\Acrobatmenu{NextPage}}{Next} }
+\end{verbatim}
+
+ \newslide
+
+ There is a starred version which will (try to) automatically calculate the
+ \indexmacro{DeclarePanel*} `flexible' dimension of each panel. For top and
+ bottom panels this is the height, for left and right panels this is the width.
+ Make sure the panel contents are `valid' at the time \macroname{DeclarePanel*}
+ is called so the calculation can be carried out in a meaningful way.
+
+ While the automatic calculation of the height of top and bottom panels is
+ trivial (using \macroname{settoheight}), there is a sophisticated procedure
+ for calculating a `good' width for the parbox containing the panel. Owing to
+ limitations set by TeX, there are certain limits to the sophistication of the
+ procedure.
+
+ \newslide
+
+ For instance, any `whatsits' (specials (like color changes), file
+ accesses (like \macroname{label}), or hyper anchors)
+ or rules which are inserted directly in the vertical list of the parbox
+ `block' the analysis, so the procedure can't `see' past them (starting at the
+ bottom of the box) when analysing the contents of the parbox.
+
+ The user should make sure such items are set in horizontal mode (by using
+ \macroname{leavevmode} or enclosing stuff in boxes). Furthermore, only
+ overfull and underfull hboxes which occur while setting the parbox are
+ considered when judging which width is `best'. This will reliably make the
+ width large enough to contain `wide' objects like tabulars, logos and buttons,
+ but might not give optimal results for justified text. vboxes occurring
+ directly in the vbox are ignored.
+
+ \newslide
+
+ Note further that hboxes with fixed width
+ (made by \macroname{hbox} to...) which occur directly in the vbox may disturb
+ the procedure, because the fixed width cannot be recovered. These hboxes will
+ be reformatted with the width of the vbox, generating an extremely large
+ badness, unsettling the calculation of maximum badness. To avoid this such
+ hboxes should be either contained in a vbox or set in horizontal mode with
+ appropriate glue at the end.
+
+ \newslide
+
+ \subsection{Navigation buttons}
+ The following provides only the very basics for navigation buttons. If you're
+ using a package that has it's own naviagtion buttons (as
+ \href{ftp://ftp.dante.de/tex-archive/help/Catalogue/entries/pdfscreen.html}%
+ {\code{pdfscreen}}) don't even consider using the following.
+
+ \present{\macroname{button\{\carg{navcommand}\}\{\carg{text}\}}}
+ \indexmacro{button}
+ creates a button labelled \carg{text} which executes \carg{navcommand} when
+ pressed. The command takes four optional arguments (left out above):
+ \carg{width}, \carg{height}, \carg{depth} and \carg{alignment} in that order.
+ \carg{navcommand} can be for instance \commandapp{Acrobatmenu}{\carg{command}} or
+ \commandapp{hyperlink}{\carg{target}} (note that \carg{navcommand} should take
+ one (more) argument specifying the sensitive area which is provided by
+ \macroname{button}). If given, the optional parameters \carg{width}, \carg{height}, and
+ \carg{depth} give the width, height and depth, respectively, of the framed
+ area comprising the button (excluding the shadow, but including the
+ frame). Default are the `real' width, height and depth, respectively, of
+ \carg{text}, plus allowance for the frame. If given, the optional parameter
+ \carg{alignment} (one of l,c,r) gives the alignment of \carg{text} inside the
+ button box (makes sense only if \carg{width} is given).
+
+ The button appearence is defined by some configurable button parameters:
+ \begin{description}
+ \item[\present{\macroname{buttonsep}}]
+ \indexmacro{buttonsep}
+ Space between button label and border. (Default: \macroname{fboxsep})
+
+ \item[\present{\macroname{buttonrule}}]
+ \indexmacro{buttonrule}
+ Width of button frame. (Default: \code{0pt})
+
+ \item[\present{\macroname{buttonshadowhshift}}]
+ \indexmacro{buttonshadowhshift}
+ Horizontal displacement of button shadow. (Default: 0.3\macroname{fboxsep})
+
+ \item[\present{\macroname{buttonshadowvshift}}]
+ \indexmacro{buttonshadowvshift}
+ Vertical displacement of button shadow. (Default: 0.3\macroname{fboxsep})
+ \end{description}
+
+ A list of predefined buttons follows:
+ \begin{description}
+
+ \item[\present{\macroname{backpagebutton[\carg{width}]}}]
+ \indexmacro{backpagebutton}
+ Last subpage of previous page.
+
+ \item[\present{\macroname{backstepbutton[\carg{width}]}}]
+ \indexmacro{backstepbutton}
+ Previous step.
+
+ \item[\present{\macroname{gobackbutton[\carg{width}]}}]
+ \indexmacro{gobackbutton}
+ `Undo action' (go back to whatever was before last action).
+
+ \item[\present{\macroname{nextstepbutton[\carg{width}]}}]
+ \indexmacro{nextstepbutton}
+ Next step.
+
+ \item[\present{\macroname{nextpagebutton[\carg{width}]}}]
+ \indexmacro{nextpagebutton}
+ First subpage of next page.
+
+ \item[\present{\macroname{nextfullpagebutton[\carg{width}]}}]
+ \indexmacro{nextfullpagebutton}
+ Last subpage of next page.
+
+ \item[\present{\macroname{fullscreenbutton[\carg{width}]}}]
+ \indexmacro{fullscreenbutton}
+ Toggle fullscreen mode.
+
+ \end{description}
+
+\clearpage
+\printindex
+\end{document}
+\endinput
+%%
+%% End of file `manual.tex'.