path: root/Master/texmf-dist/doc/latex/texpower/manual.tex

%%
%% 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'.