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