summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/stex/doc/packages/stex-notesslides.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/stex/doc/packages/stex-notesslides.tex')
-rw-r--r--macros/latex/contrib/stex/doc/packages/stex-notesslides.tex243
1 files changed, 243 insertions, 0 deletions
diff --git a/macros/latex/contrib/stex/doc/packages/stex-notesslides.tex b/macros/latex/contrib/stex/doc/packages/stex-notesslides.tex
new file mode 100644
index 0000000000..75fd9ee9e8
--- /dev/null
+++ b/macros/latex/contrib/stex/doc/packages/stex-notesslides.tex
@@ -0,0 +1,243 @@
+\begin{sfragment}{Introduction}
+ The \pkg{notesslides} document class is derived from |beamer.cls|~\cite{beamerclass:on},
+it adds a ``notes version'' for course notes that is more suited to printing than the one
+supplied by |beamer.cls|.
+
+The \pkg{notesslides} class takes the notion of a slide frame from Till Tantau's excellent
+\pkg{beamer} class and adapts its notion of frames for use in the \sTeX and \omdoc. To
+support semantic course notes, it extends the notion of mixing frames and explanatory
+text, but rather than treating the frames as images (or integrating their contents into
+the flowing text), the \pkg{notesslides} package displays the slides as such in the course
+notes to give students a visual anchor into the slide presentation in the course (and to
+distinguish the different writing styles in slides and course notes).
+
+In practice we want to generate two documents from the same source: the slides for
+presentation in the lecture and the course notes as a narrative document for home
+study. To achieve this, the \pkg{notesslides} class has two modes: \emph{slides mode} and
+\emph{notes mode} which are determined by the package option.
+\end{sfragment}
+
+\begin{sfragment}{Package Options}
+ The \pkg{notesslides} class takes a variety of class options:
+
+ \begin{variable}{slides,notes} The options |slides| and |notes| switch between slides
+ mode and notes mode (see \sref{sec:user:notesslides}).
+ \end{variable}
+
+ \begin{variable}{sectocframes} If the option |sectocframes| is given, then for the
+ |sfragment|s, special frames with the |sfragment| title (and number) are generated.
+ \end{variable}
+
+ \begin{variable}{frameimages,fiboxed}
+ If the option |frameimages| is set, then slide mode also shows the
+ |\frameimage|-generated frames (see \sref{sec:user:frameimage}). If also the |fiboxed|
+ option is given, the slides are surrounded by a box.
+ \end{variable}
+\end{sfragment}
+
+\begin{sfragment}[id=sec:user:notesslides]{Notes and Slides}
+
+\begin{environment}{frame}
+ Slides are represented with the |frame| environment just like in the \pkg{beamer} class,
+ see~\cite{Tantau:ugbc} for details.
+\end{environment}
+
+\begin{environment}{note}
+ The \pkg{notesslides} class adds the |note| environment for encapsulating the course
+ note fragments.
+\end{environment}
+
+\begin{dangerbox}
+ Note that it is essential to start and end the |notes| environment at the start of the
+ line -- in particular, there may not be leading blanks -- else {\LaTeX} becomes confused
+ and throws error messages that are difficult to decipher.
+\end{dangerbox}
+
+By interleaving the |frame| and |note| environments, we can build course notes as shown
+here:
+
+\begin{latexcode}
+\ifnotes\maketitle\else
+\frame[noframenumbering]\maketitle\fi
+
+\begin{note}
+ We start this course with ...
+\end{note}
+
+\begin{frame}
+ \frametitle{The first slide}
+ ...
+\end{frame}
+\begin{note}
+ ... and more explanatory text
+\end{note}
+
+\begin{frame}
+ \frametitle{The second slide}
+ ...
+\end{frame}
+...
+\end{latexcode}
+
+\begin{function}{\ifnotes}
+ Note the use of the |\ifnotes| conditional, which allows different treatment between
+ |notes| and |slides| mode -- manually setting |\notestrue| or |\notesfalse| is strongly
+ discouraged however.
+\end{function}
+
+\begin{dangerbox}
+ We need to give the title frame the |noframenumbering| option so that the frame
+ numbering is kept in sync between the slides and the course notes.
+\end{dangerbox}
+
+\begin{dangerbox}
+ The \pkg{beamer} class recommends not to use the |allowframebreaks| option on frames
+ (even though it is very convenient). This holds even more in the |notesslides| case: At
+ least in conjunction with |\newpage|, frame numbering behaves funnily (we have tried to
+ fix this, but who knows).
+\end{dangerbox}
+\end{sfragment}
+
+\begin{function}{\inputref*}
+ If we want to transclude a the contents of a file as a note, we can use a new variant
+ |\inputref*| of the |\inputref| macro: |\inputref*{foo}| is equivalent to
+ |\begin{note}\inputref{foo}\end{note}|.
+\end{function}
+
+\begin{environment}{nparagraph, nparagraph, ndefinition, nexample, nsproof, nassertion}
+ There are some environments that tend to occur at the top-level of |note|
+ environments. We make convenience versions of these: e.g. the |nparagraph| environment
+ is just an |sparagraph| inside a |note| environment (but looks nicer in the source,
+ since it avoids one level of source indenting). Similarly, we have the |nfragment|,
+ |ndefinition|, |nexample|, |nsproof|, and |nassertion| environments.
+\end{environment}
+
+\begin{sfragment}{Customizing Header and Footer Lines}
+ The \pkg{notesslides} package and class comes with a simple default theme named
+ \pkg{sTeX} that provided by the \pkg{beamterthemesTeX}. It is assumed as the default
+ theme for \sTeX-based notes and slides.
+ The result in |notes| mode (which is like the |slides| version except that the slide
+ hight is variable) is
+
+ \includegraphics[width=.95\textwidth]{\libfolder{img/notes-frame}}
+
+The footer line can be customized. In particular the logos.
+
+\begin{function} {\setslidelogo}
+ The default logo provided by the \pkg{notesslides} package is the {\sTeX} logo it can be
+ customized using |\setslidelogo{|\meta{logo name}|}|.
+\end{function}
+
+\begin{function}{\setsource}
+ The default footer line of the \pkg{notesslides} package mentions copyright and
+ licensing. In \pkg{notesslides} |\source| stores the author's name as the copyright
+ holder. By default it is the author's name as defined in the |\author| macro in the
+ preamble. |\setsource{|\meta{name}|}| can change the writer's name.
+\end{function}
+
+\begin{function}{\setlicensing}
+ For licensing, we use the Creative Commons Attribuition-ShareAlike license by default to
+ strengthen the public domain. If package |hyperref| is loaded, then we can attach a
+ hyperlink to the license logo. |\setlicensing[|\meta{url}|]{|\meta{logo name}|}| is used
+ for customization, where \meta{url} is optional.
+\end{function}
+\end{sfragment}
+
+\begin{sfragment}[id=sec:user:frameimages]{Frame Images}
+ Sometimes, we want to integrate slides as images after all -- e.g. because we already
+have a PowerPoint presentation, to which we want to add \sTeX notes.
+
+\begin{function}{\frameimage,\mhframeimage}
+ In this case we can use |\frameimage[|\meta{opt}|]{|\meta{path}|}|, where \meta{opt} are
+ the options of |\includegraphics| from the \pkg{graphicx} package~\cite{CarRah:tpp99}
+ and \meta{path} is the file path (extension can be left off like in
+ |\includegraphics|). We have added the |label| key that allows to give a frame label
+ that can be referenced like a regular |beamer| frame.
+
+The |\mhframeimage| macro is a variant of |\frameimage| with repository support. Instead
+of writing
+\begin{latexcode}
+\frameimage{\MathHub{fooMH/bar/source/baz/foobar}}
+\end{latexcode}
+ we can simply write (assuming that |\MathHub| is defined as above)
+\begin{latexcode}
+\mhframeimage[fooMH/bar]{baz/foobar}
+\end{latexcode}
+ Note that the |\mhframeimage| form is more semantic, which allows more advanced document
+management features in \textsf{MathHub}.
+\end{function}
+
+If |baz/foobar| is the ``current module'', i.e. if we are on the \textsf{MathHub} path
+\ldots|MathHub/fooMH/bar|\ldots, then stating the repository in the first optional
+argument is redundant, so we can just use
+\begin{latexcode}
+\mhframeimage{baz/foobar}
+\end{latexcode}
+\end{sfragment}
+
+\begin{function}{\textwarning}
+ The |\textwarning| macro generates a warning sign: \textwarning
+\end{function}
+
+\begin{sfragment}[id=sec:user:excursions]{Excursions}
+In course notes, we sometimes want to point to an ``excursion'' -- material that is either
+presupposed or tangential to the course at the moment -- e.g. in an appendix. The typical
+setup is the following:
+
+\begin{latexcode}
+\excursion{founif}{../fragments/founif.en}
+ {We will cover first-order unification in}
+...
+\begin{appendix}\printexcursions\end{appendix}
+\end{latexcode}
+
+It generates a paragraph that references the excursion whose source is in the file
+|../fragments/founif.en.tex| and automatically books the file for the |\printexcursions|
+command that is used here to put it into the appendix. We will look at the mechanics now.
+
+\begin{function}{\excursion}
+ The |\excursion{|\meta{ref}|}{|\meta{path}|}{|\meta{text}|}| is syntactic sugar for
+
+\begin{latexcode}
+\begin{nparagraph}[title=Excursion]
+ \activateexcursion{founif}{../ex/founif}
+ We will cover first-order unification in \sref{founif}.
+\end{nparagraph}
+\end{latexcode}
+\end{function}
+
+\begin{function}{\activateexcursion,\printexcursion,\excursionref}
+ Here |\activateexcursion{|\meta{path}|}| augments the |\printexcursions| macro by a call
+ |\inputref{|\meta{path}|}|. In this way, the |\printexcursions| macro (usually in the
+ appendix) will collect up all excursions that are specified in the main text.
+
+ Sometimes, we want to reference -- in an excursion -- part of another. We can use
+ |\excursionref{|\meta{label}|}| for that.
+\end{function}
+
+\begin{function}{\excursiongroup}
+ Finally, we usually want to put the excursions into an |sfragment| environment and add
+ an introduction, therefore we provide the a variant of the |\printexcursions| macro:
+ |\excursiongroup[id=|\meta{id}|,intro=|\meta{path}|]| is equivalent to
+\begin{latexcode}
+\begin{note}
+\begin{sfragment}[id=<id>]{Excursions}
+ \inputref{<path>}
+ \printexcursions
+\end{sfragment}
+\end{note}
+\end{latexcode}
+\end{function}
+\end{sfragment}
+
+\begin{dangerbox}
+ When option |book| which uses |\pagestyle{headings}| is given and semantic macros are
+ given in the |sfragment| titles, then they sometimes are not defined by the time the
+ heading is formatted. Need to look into how the headings are made. This is a problem of
+ the underlying \pkg{document-structure} package.
+\end{dangerbox}
+
+%%% Local Variables:
+%%% mode: latex
+%%% TeX-master: "../stex-manual"
+%%% End: