custom page handling(instead of fixed \clearpage), custom skipping

1 files changed, 67 insertions, 5 deletions

diff --git a/exercisesheets.tex b/exercisesheets.tex
index fd8eee1..760c5f9 100644
--- a/exercisesheets.tex
+++ b/exercisesheets.tex
@@ -53,7 +53,7 @@
 \usepackage[english,iso]{isodate}
 \title{The \exsh Package}
 \author{Sebastian Kuhnert\and Frank Fuhlbrück}
-\date{Version 0.5k, \printdateTeX{2017/12/11}}
+\date{Version 0.6, \printdateTeX{2019/2/11}}
 
 \begin{document}
 \maketitle
@@ -63,7 +63,7 @@ university courses. It evolved from a set of macros an environments that were
 finally combined into this package.
 
 \subsection*{Licence}
-Copyright \textcopyright{} 2008--2017 Sebastian Kuhnert and Frank Fuhlbrück.
+Copyright \textcopyright{} 2008--2019 Sebastian Kuhnert and Frank Fuhlbrück.
 Permission is granted to copy, distribute and/or modify this software under the
 terms of the \LaTeX{} Project Public Licence, version 1.3c or later. This
 package is maintained, the Current Maintainer is Sebastian
@@ -140,13 +140,23 @@ The following options are available:
   \end{description}
  \item[\option{all}] Typeset all sheets (equivalent to \option{only=-}). This is
   the default.
- \item[\option{solutions\opt{=\param{true/false/oral/nonoral}}}] By default,
+ \item[\option{solutions\opt{=\param{true/false/oral/nonoral/sample oral/sample nonoral/sample all}}}] By default,
   solutions (provided in the \texttt{solution} environment) are not included in
   the output. By providing the option \option{solutions=true} (or just
   \option{solutions}) this can be changed. Choosing \option{solutions=oral}
   shows only solutions for exercises marked \option{oral} (useful for printouts
   taken to class). Choosing \option{solutions=nonoral} shows only solutions for
   exercises that are not marked \option{oral} (useful for correcting).
+  If you want to provided sample solutions for your students but only for some
+  of your exercises you can use the \texttt{sample} key to select those
+  exercises along with any options starting with sample here.
+  Note that non-sample exercises are skipped completely (not only their solutions) if you
+  choose an option starting with sample.
+ \item[\option{gradingguides\opt{=\param{true/false}}}]
+  Within \texttt{gradingguide} environments (usually used inside \texttt{solution}) you can
+  specify e.g. the amount of points to assign for certain solutions. This option
+  controls whether or not to include this guides in the output (e.g. solutions for
+  correcting contain them, but sample solutions for students don't).
  \item[\option{solutionsby=\param{name/names}}] Use this to give the authors of the
   solutions. They are credited at the beginning of each sheet, if the solutions
   are included in the output.
@@ -249,8 +259,10 @@ supported:
  \item[\option{exercisemark=\param{symbol}}] Mark the exercise
   with \param{symbol} in the left margin.
  \item[\option{difficult}] Shortcut for \option{exercisemark=*}.
- \item[\option{solutions\opt{=\param{true/false/oral/nonoral}}}] Use this to override the
+ \item[\option{solutions\opt{=\param{true/false/oral/nonoral/...}}}] Use this to override the
   document (or sheet) default.
+ \item[\option{sample}] Include this exercise (and its solution) in while compiling
+ sample solutions.
 \end{description}
 
 Solutions are only typeset, if the \option{solutions} option is in effect. There
@@ -403,11 +415,13 @@ values:
  \item[\option{solution title font}] The font for the string
   \enquote{Solution:}\\
   Default: \verb|\bfseries|
+ \item[\option{grading guide font}] The font for grading guides.\\
+  Default: \verb|\itshape|
  \item[\option{todo marker font}] The font for the string \enquote{TODO}.\\
   Default: \verb|\ifdef{\color}{\color{red}}{}\bfseries|
 \end{description}
 
-\subsection{Controlling the Spacing}
+\subsection{Controlling the Spacing and Page Handling}
 
 The following options allow fine-tuning of the spacing:
 \begin{description}
@@ -436,6 +450,17 @@ The following options allow fine-tuning of the spacing:
   Default: \texttt{1ex}
 \end{description}
 
+The following two options control the page handling at the beginning and
+at the end of each sheet:
+\begin{description}
+ \item[\option{sheet start page action=\param{macro}}] Executed at the beginning
+  of each sheet.\\
+  Default: \texttt{\string\clearpage}
+ \item[\option{sheet end page action=\param{macro}}] Executed at the end
+  of each sheet.\\
+  Default: \texttt{\string\clearpage}
+\end{description}
+
 \subsection{Special Code for Solutions}
 \begin{lstlisting}
 \ifsolutions{(*\param{if true}*)}{(*\param{if false}*)}
@@ -482,6 +507,43 @@ There are several hooks used by \exsh:
 Hooks can be used to influence the behaviour of the respective environments.
 Users of \texttt{tikz} should be familiar with the concept.
 
+\subsection{Control Skipping of Custom Macros in Skipped Exercises}
+\begin{description}
+ \item[\option{custom skip macro=\param{macro}}] 
+\end{description}
+
+If an exercise is not printed, some macros like \texttt{\string\label{}}
+are processed nevertheless. However, if you define your own macro
+using one of these, then this macro will be completely ignored
+if the exercise containing it is skipped. This option allows to
+define a custom handler for your macros. The most common use
+checks for your custom macros with 
+nested \texttt{\string\ifstrequal}s and then either
+executes a custom skipper, replaces your macro with
+the standard version or uses \texttt{\string\expandafter} to
+deliver the expanded version of your macro to
+\texttt{\string\exshskipcontinue}.
+
+Example:
+\begin{lstlisting}
+\def\mylabel#1{...}
+\def\myitem{...}
+\def\myitemtwo{...}
+\def\skipmylabel#1{...\exshskipcontinue}
+\long\def\customskip#1{
+  \ifstrequal{#1}{\mylabel}
+    {\skipmylabel}
+    {\ifstrequal{#1}{\myitem}
+      {\exshskipcontinue\item}
+      {\ifstrequal{#1}{\myitemtwo}
+        {\expandafter\exshskipcontinue\myitemtwo}
+        {\exshskipcontinue}
+      }
+    }
+}
+\exshset{custom skip macro={\customskip}}
+\end{lstlisting}
+
 \section{Usage Tips}
 \label{sec:usage-tips}