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

3 files changed, 122 insertions, 12 deletions

diff --git a/README b/README
index b9a3d35..04583a0 100644
--- a/README
+++ b/README
@@ -4,7 +4,7 @@ The exercisesheets 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.
 
-Copyright (c) 2008-2017 Sebastian Kuhnert, Frank Fuhlbrück
+Copyright (c) 2008-2019 Sebastian Kuhnert, Frank Fuhlbrück
 Licence: LPPL 1.3c or later
 Current Maintainer: Sebastian Kuhnert
 
diff --git a/exercisesheets.sty b/exercisesheets.sty
index 7e6bac8..7038d00 100644
--- a/exercisesheets.sty
+++ b/exercisesheets.sty
@@ -18,8 +18,8 @@
 %\NeedsTeXFormat{LaTeX2e}[1994/12/01]
 
 % don't forget to update the version and date in exercisesheets.tex
-\def\exsh@version{0.5k}
-\def\exsh@date{2017/12/11}
+\def\exsh@version{0.6}
+\def\exsh@date{2019/2/11}
 
 \ProvidesPackage{exercisesheets}[\exsh@date\space\exsh@version\space Typesetting of exercise sheets]
 \message{`Typesetting of exercise sheets' \exsh@version\space <\exsh@date>}
@@ -48,6 +48,8 @@
 \newif\ifexsh@oralsolutions
 \newif\ifexsh@nonoralsolutions
 \newif\ifexsh@samplesolutions
+\newif\ifexsh@forcesample %force printing sample sol. of wrong type
+\newif\ifexsh@gradingguides
 \newif\ifexsh@inplace
 \newif\ifexsh@sample
 \newif\ifexsh@hide%currently only set via sample in exercise env.
@@ -65,6 +67,10 @@
   solutions/sample all/.code=\exsh@solutionstrue\exsh@oralsolutionstrue\exsh@nonoralsolutionstrue\exsh@samplesolutionstrue,
   solutions/false/.code=\exsh@solutionsfalse\exsh@oralsolutionsfalse\exsh@nonoralsolutionsfalse,
   solutions/.default=true,
+  forcesample/.is if=exsh@forcesample,
+  forcesample/.default=true,
+  gradingguides/.is if=exsh@gradingguides,
+  gradingguides/.default=true,
   only/.initial={-},
   all/.style={/exsh/only={-}},all/.value forbidden,
   solutionsby/.code={\def\exsh@solutionsby{#1}},solutionsby/.value required,
@@ -126,6 +132,7 @@
   %
   % additional exercise info
   name/.initial={},
+  forcesample/.initial={false},
   firstline/.initial={},
   points/.initial={},
   oral/.style={/exsh/points=oral},oral/.value forbidden,
@@ -145,12 +152,14 @@
   optional/.value forbidden,
   exercisemark/.initial={},
   difficult/.style={/exsh/exercisemark=*},difficult/.value forbidden,
+  custom skip macro/.initial=\exsh@skipcustomstuff,
   %
   % translatable strings
   strings/sheet/.initial={},
   strings/sheets/.initial={},
   strings/solutions/.initial={},
   strings/solutionsby/.initial={},
+  strings/gradingguide/.initial={},
   strings/exercise/.initial={},
   strings/solution/.initial={},
   strings/idea/.initial={},
@@ -174,6 +183,7 @@
     \exsh@deforprovide{/exsh/strings/sheets}      {\"Ubungsbl\"atter}%
     \exsh@deforprovide{/exsh/strings/solutions}   {L\"osungsvorschl\"age}%
     \exsh@deforprovide{/exsh/strings/solutionsby} {L\"osungen von}%
+    \exsh@deforprovide{/exsh/strings/gradingguide}{Bepunktung}%
     \exsh@deforprovide{/exsh/strings/exercise}    {Aufgabe}%
     \exsh@deforprovide{/exsh/strings/solution}    {L\"osung}%
     \exsh@deforprovide{/exsh/strings/idea}        {L\"osungsidee}%
@@ -196,6 +206,7 @@
     \exsh@deforprovide{/exsh/strings/sheets}      {Exercise Sheets}%
     \exsh@deforprovide{/exsh/strings/solutions}   {Suggested Solutions}%
     \exsh@deforprovide{/exsh/strings/solutionsby} {Solutions by}%
+    \exsh@deforprovide{/exsh/strings/gradingguide}{Grading guideline}%
     \exsh@deforprovide{/exsh/strings/exercise}    {Exercise}%
     \exsh@deforprovide{/exsh/strings/solution}    {Solution}%
     \exsh@deforprovide{/exsh/strings/idea}        {Idea for solution}%
@@ -243,6 +254,7 @@
   hint title font/.initial=\itshape,
   solution font/.initial={},
   solution title font/.initial=\bfseries,
+  grading guide font/.initial=\itshape,
   todo marker font/.initial=\ifdef{\color}{\color{red}}{}\bfseries,
   %
   % skip values
@@ -255,6 +267,10 @@
   above solution skip/.initial={1ex},
   above hint skip/.initial={1ex},
   %
+  % page handling
+  sheet start page action/.initial={\clearpage},
+  sheet end page action/.initial={\clearpage},
+  %
   % conditionals
   ifsolutions/.code 2 args={\ifsolutions{\pgfkeysalso{#1}}{\pgfkeysalso{#2}}},
   iforalsolutions/.code 2 args={\iforalsolutions{\pgfkeysalso{#1}}{\pgfkeysalso{#2}}},
@@ -427,9 +443,9 @@
 }
 \newcounter{sheetid}% only used to disambiguate hyperref labels
 \newenvironment{sheet}[1][]{%
-  \clearpage
-  \stepcounter{sheetid}%
   \pgfkeys{exsh,every sheet,#1}%
+  \pgfkeysvalueof{/exsh/sheet start page action}%
+  \stepcounter{sheetid}%
   \ifthenelse{\equal{}{\pgfkeysvalueof{/exsh/title}}}{%
     \numdef\exsh@tmp{\value{part}+1}%
     \edef\exsh@temp{\expandonce{\pgfkeysvalueof{/exsh/strings/sheet}}\noexpand~\exsh@tmp}%
@@ -455,7 +471,7 @@
   \par
   \begingroup
   \ifnum\value{page}=1\thispagestyle{empty}\fi
-  \clearpage
+  \pgfkeysvalueof{/exsh/sheet end page action}%
   \endgroup
 }
 \listadd{\exsh@enums}{enumerate}
@@ -481,8 +497,10 @@
           \ifstrequal{#1}{\exsh@skipstuff@endfile}{\currfile@pop\exsh@skipstuff}{%
             \ifstrequal{#1}{\setcounter}{\expandafter\exsh@skipstuff\setcounter}{%
               \ifstrequal{#1}{\item}{\ifdef{\@enumctr}{\@hyper@itemtrue\refstepcounter{\@enumctr}}{}}{}%
-              \exsh@skipstuff}}}}}}%
+              \pgfkeysvalueof{/exsh/custom skip macro}{#1}}}}}}}%
 }
+\let\exshskipcontinue\exsh@skipstuff
+\long\def\exsh@skipcustomstuff#1{\exshskipcontinue}
 \def\exsh@skipstuff@end#1{%
   \expandafter\ifstrequal\expandafter{\exsh@skipwhat}{#1}{%
     \expandafter\end\expandafter{\exsh@skipwhat}%
@@ -741,6 +759,11 @@
       \let\next\exsh@skipsolution
     }%
   }%
+  \ifbool{exsh@forcesample}{%
+    \ifbool{exsh@samplesolutions}{%
+      \let\next\exsh@startsolution
+    }{}%
+  }{}%
   \next
 }{%
   \ifthenelse{\equal{oral}{\pgfkeysvalueof{/exsh/points}}}{%
@@ -817,6 +840,31 @@
   \ignorespaces
 }
 
+\newenvironment{gradingguide}[1][]{%
+  \pgfkeys{exsh,#1,grading guide font}%
+  \ifbool{exsh@gradingguides}{%
+    \let\next\exsh@startguide
+  }{%
+    \let\next\exsh@skipguide
+  }%
+  \next
+}{}
+
+\def\exsh@startguide{\@afterindentfalse
+  \linebreak
+  {\parindent \z@
+    \pgfkeysvalueof{/exsh/strings/gradingguide}: }\nobreak%
+  \@afterheading
+}%
+
+\long\def\exsh@skipguide#1{%
+  \ifstrequal{#1}{\end}{\exsh@endguide}{\exsh@skipguide}%
+}
+\def\exsh@endguide#1{%
+  \ifstrequal{#1}{gradingguide}{\end{gradingguide}}{\exsh@skipguide}%
+}
+
+
 \ifluatex%
   \ifdefined\luatextextdir
     \def\exsh@putatend#1{%
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}