update manual (Lua part still incomplete)

1 files changed, 104 insertions, 17 deletions

diff --git a/exercisesheets.tex b/exercisesheets.tex
index 7bdf84d..688482d 100644
--- a/exercisesheets.tex
+++ b/exercisesheets.tex
@@ -60,9 +60,7 @@
 
 The \exsh package provides a way to typeset exercise sheets as used in
 university courses. It evolved from a set of macros an environments that were
-finally combined into this package. Starting from Version 0.7, there
-is an alternative variant designed for use with the beamer class.
-This variant is called exercisesheets-beamer. Not all combinations of options have been testet with the beamer variant.
+finally combined into this package. Starting from Version 0.7, there was an alternative variant designed for use with the beamer class, which is integrated into the main package since version 0.11. Not all combinations of options have been tested with the beamer variant.
 
 
 \subsection*{Licence}
@@ -118,9 +116,8 @@ Frank Fuhlbrück
 \section{Basic Usage}
 
 \subsection{Package Loading}
-There are two versions of the package: one for article and similar
-classes and one for the beamer document class. If you want the latter,
-replace \enquote{exercisesheets} with \enquote{exercisesheets-beamer}.
+The beamer variant is integrated now and automatically activated
+if the current document class is beamer.
 
 \begin{lstlisting}
 \usepackage(*\opt{[\param{options}]}*){exercisesheets}
@@ -223,9 +220,18 @@ The following options are available:
   \def\itemize{\@ifnextchar[\exsh@ovrlitemize\exsh@origitemize}
   \let\exsh@origenumerate\enumerate
   \def\exsh@ovrlenumerate[##1]{\exsh@origenumerate}
-  \def\enumerate{\@ifnextchar[\exsh@ovrlenumerate\exsh@origenumerate}
+  \def\enumerate{%
+    \@ifnextchar[\exsh@ovrlenumerate\exsh@origenumerate}
 \end{lstlisting}
 
+\item[\option{filenameasexercisename}\opt{=\param{true/false}}] 
+This option (set to false by default) causes 
+\verb|\includeexercise| to
+set the name of an exercise as the filename (without extension).
+This has two purposes: If you have nice file names you can 
+automatically name the exercise. On the other hand this is helpful
+during exercise sheet composition because it shows the name of
+the corresponding file in the compiled file.
 \end{description}
 
 \subsection{Supplying Meta-Data}
@@ -292,14 +298,19 @@ The following \param{options} are supported:
   a special sheet.
  \item[\option{author=\param{author}}] Set the author included in the sheet
   head. By default, the value passed to \verb|\author| is used.
- \item[\option{exauthor=\param{exauthor}}] Only used by \exsh-beamer,
- see above.
+ \item[\option{exauthor=\param{exauthor}}] Only used by the beamer
+ variant, see above.
  \item[\option{subject=\param{subject}}] Set the subject included in the sheet
   head. By default, the value passed to \verb|\subject| is used.
  \item[\option{semester=\param{semester}}] Set the semester included in the
   sheet head. By default, the value passed to \verb|\date| is used.
- \item[\option{beamerwithheadline\opt{=\param{true/false}}}] Controls wether a headline with author, subject etc. is shown on beamer slides, similar to the regular sheets. This options is off by default as headlines (and footers) take a considerable amount
+ \item[\option{beamerwithheadline\opt{=\param{true/false}}}] Controls whether a headline with author, subject etc. is shown on beamer slides, similar to the regular sheets. This options is off by default as headlines (and footers) take a considerable amount
  off space.
+ \item[\option{beameruseblocks\opt{=\param{true/false}}}] 
+ Controls whether the exercise title is shown inside a 
+ beamer block (\param{true}) or a simple colorbox
+ (\param{false}, the default). Depending on your style a
+ block might look fancier, but it usually consume more space.
 \end{description}
 
 
@@ -318,9 +329,10 @@ The following \param{options} are supported:
 \end{lstlisting}
 
 This inserts an exercise into the current document. All
-\option{beamersolution}s are ignored, if the usual 
-\exsh package is loaded, but \exsh-beamer also processes
-normal solututions by default (set option \option{beamersolution}
+\option{beamersolution}s are ignored, if the
+\exsh package with any class but beamer, but using beamer
+\exsh also processes
+normal solutions by default (set option \option{beamersolution}
 to turn this off).
 
 The following options are
@@ -330,6 +342,10 @@ supported:
   Useful for exercises that prove a famous theorem.
  \item[\option{firstline=\param{text}}] Save some space by text \param{text}
   behind the exercise title.
+ \item[\option{savetasks\opt{=\param{true/false}}}] Saves the main task and each sub task
+  for later use with \verb|\restatestask[|%
+  \param{which}], where \param{which} is either \verb|main|
+  (default) or the number of a sub task.
  \item[\option{points=\param{number/oral/sum}}] Assign this 
   exercise \param{number} points. By default, exercises are 
   unlabelled. \param{oral} works the same way as the option
@@ -339,7 +355,8 @@ supported:
   points, the option \option{bonus} is automatically triggered. To 
   undo this, either delete the \verb|.aux| file or explicitly use 
   \verb|\points[bonus=false]{\param{number}}| for at least one
-  subexercise.
+  subexercise. Points can be summed up also during a single pass
+  by using the Lua interface. 
  \item[\option{oral}] Label this exercise as \emph{oral}. This supersedes and is
   superseded by the option \option{points}.
  \item[\option{pointsinfo=\param{text}}] Supply \param{text} as additional
@@ -356,10 +373,10 @@ supported:
   document (or sheet) default.
  \item[\option{sample}] Include this exercise (and its solution) in while compiling
  sample solutions.
- \item[\option{beamersolution}] For \exsh-beamer only. If this option
+ \item[\option{beamersolution}] For beamer variant only. If this option
  is set all normal solutions will not be included and only 
  \option{beamersolution}s are typeset.
- \item[\option{framed}] For \exsh-beamer only, simply ignored 
+ \item[\option{framed}] For beamer variant only, simply ignored 
  elsewhere. If this option
  is set for a normal solution, its content will be put on one or 
  more frames. Use \verb|\newframe| to start a new frame. This 
@@ -422,7 +439,7 @@ TODO markers (s.a.) the warning will be issued nevertheless.
 
 \subsection{Annotating Points for Sub-Exercises}
 \begin{lstlisting}
-\begin{exercise}[points=sum]%sum produces 7+6
+\begin{exercise}[points=sum]%sum produces 4+6
   \begin{enumerate}
    \item Part 1 \points{oral}
    \item Part 2 \points[optional]{oral}
@@ -433,6 +450,36 @@ TODO markers (s.a.) the warning will be issued nevertheless.
 \end{exercise}
 \end{lstlisting}
 
+\subsection{Explicitly Stating Tasks}
+In principle, \exsh aims to be very lightweight and there is not 
+much mandatory structure inside exercises. Furthermore, the
+\verb|enumi| counter is used for sub-exercise. There are, however,
+situations where we want more explicit structure, for instance to 
+have special font for the main task or the subtasks or to reuse
+some of the tasks later. This is especially handy if using the 
+beamer variant where the origial task and a part of the solution might be on different slides. In the future it might be possible to
+use other counters then \verb|enumi|, which is also only possible
+if sub-exercises are not simply \verb|\item|s in
+\verb|enumerate|.
+
+
+\begin{lstlisting}
+\begin{exercise}[points=sum]%sum produces 4+6
+  \begin{maintask}
+    This is the main task.
+  \end{maintask}
+  \begin{subtasks}
+    \subtask{first}
+    \subtask{second}
+  \end{subtasks}
+  \begin{solution}[framed]
+    We want to show: \restatestask %This is the main task.
+    \newframe
+    Out first step is to show: \restatetask[1] %first
+  \end{solution}
+\end{exercise}
+\end{lstlisting}
+
 
 \section{Advanced Usage}
 
@@ -526,6 +573,15 @@ values:
  \item[\option{points font}] The font for the number of points in the exercise
   head (relative to the exercise title) and for \verb|\points|.\\
   Default: \verb|\itshape|
+ \item[\option{main task font}] The font for the
+  \verb|maintask| environment.\\
+  Default: empty, i.\,e.\ no change.
+ \item[\option{subtask font}] The font for each
+  \verb|\subtask|.\\
+  Default: empty, i.\,e.\ no change.
+ \item[\option{task restate font}] The font used for
+  \verb|\restatestask|.\\
+  Default: \verb|\itshape|
  \item[\option{hint font}] The font for hints. \\
   Default: empty, i.\,e.\ no change.
  \item[\option{hint title font}] The font for the string \enquote{Hint:}.\\
@@ -545,6 +601,10 @@ values:
 
 The following options allow fine-tuning of the spacing:
 \begin{description}
+ \item[\option{below slide headline skip=\param{dimen}}] The distance between
+ haedline (if present) and slide content. Only used by beamer
+ variant, ignored elsewhere.\\
+  Default: \texttt{0mm}
  \item[\option{above sheet title skip=\param{dimen}}] The distance between
   author/date and sheet title.\\
   Default: \texttt{4ex}
@@ -668,6 +728,33 @@ Example:
 \exshset{custom skip macro={\customskip}}
 \end{lstlisting}
 
+\section{The Lua Interface}
+\label{sec:lua}
+
+Since version 0.11 there is a Lua interface for the exercise
+environment. This interface will offer roughly the same features. 
+Its main purpose will be allowing to reorder sub-exercises more 
+easily and to offer more dynamic options for the display of 
+solutions (one combined solution or single after each sub-
+exercise). %TODO finish
+
+\begin{lstlisting}
+\begin{Lexercise}
+  --use [[]] if you need \ or escape it in "": "\\"
+  firstline = [[Assume $\pi=4$.]],
+  points=10,
+  name="Pragmatic",
+  options=[[main task font={\itshape}]],
+  task  = [[
+    This is the main task specified via the Lua
+    interface.
+  ]],
+  solution=[[
+    This is a solution for the main task.
+  ]],
+\end{Lexercise}
+\end{lstlisting}
+
 \section{Usage Tips}
 \label{sec:usage-tips}