From 026c602a4aa6f2b6eeca3bcbdd714425e07ad829 Mon Sep 17 00:00:00 2001
From: Frank Fuhlbrück
Date: Wed, 24 Apr 2024 11:31:24 +0200
Subject: v.0.17: fix bugs with embedded+beamer; better documenation

---
 exercisesheets.tex | 584 ++++++++++++++++++++++++++++++-----------------------
 1 file changed, 330 insertions(+), 254 deletions(-)

(limited to 'exercisesheets.tex')

diff --git a/exercisesheets.tex b/exercisesheets.tex
index 30cbd1c..eb89c48 100644
--- a/exercisesheets.tex
+++ b/exercisesheets.tex
@@ -29,9 +29,50 @@
 \lstset{%
   language=[LaTeX]TeX,
   basicstyle=\ttfamily\color{blue!50!black},
+  texcs={def,let,renewcommand,long,begin,end,usepackage,ifdef},
+  texcsstyle=\color{blue!60!gray},
   keywordstyle=\bfseries,
-  morekeywords={subject},
-  identifierstyle=,
+  keywords={
+    beamersolution,
+    exshset,
+    exercise,
+    hint,
+    includeexercise,
+    inexlabel,
+    ifnonoralsolutions,
+    iforalsolutions,
+    ifsamplesolutions,
+    ifsolutions,
+    Lexercise,
+    loadexercise,
+    maintask,
+    newframe,
+    points,
+    restatetask,
+    restatetaskbeamer,
+    sheet,
+    solution,
+    subexnref,
+    subexlref,
+    subtask,
+    subtasks,
+    TODO,
+  },
+  keywordstyle=[2]\optionstyle,
+  keywords=[2]{
+    bonus,
+    firstline,
+    framed,
+    inplace,
+    name,
+    only,
+    optional,
+    options,
+    oral,
+    strings,
+    solutionsby,
+  },
+  identifierstyle=,%{}\color{red!60!gray},
   texcl,
   commentstyle=\itshape,
   showstringspaces=false,
@@ -47,20 +88,27 @@
 \newcommand{\exsh}{\texttt{exercisesheets}\xspace}
 
 \newcommand{\param}[1]{$\langle${\normalfont\itshape #1\/}$\rangle$}
-\newcommand{\opt}[1]{\textcolor{green!50!black}{#1}}
-\newcommand{\option}[1]{{\normalfont\texttt{\color{blue!50!black}#1}}}
+\newcommand{\maybe}[1]{\textcolor{green!50!black}{#1}}
+\newcommand{\mand}[1]{\textcolor{blue!50!black}{#1}}
+\newcommand{\codestyle}{\normalfont\ttfamily\color{blue!50!black}}
+\newcommand{\optionstyle}{\normalfont\ttfamily\color{red!50!black}}
+\newcommand{\option}[1]{{\optionstyle #1}}
+\newcommand{\optitem}[1][]{\item[{\codestyle #1}]}
+\newcommand{\vers}[1]{{\normalfont\ttfamily\color{black!90} #1}}
+\newcommand{\versitem}[1][]{\item[v. \vers{#1}]}
+\newcommand{\filename}[1]{{\normalfont\ttfamily\color{magenta!80!black}#1}}
+\newcommand{\binary}[1]{{\normalfont\ttfamily\color{yellow!50!black}#1}}
+\newcommand{\luadisp}[1]{{\normalfont\ttfamily\color{cyan!50!black}#1}}
 
 \usepackage[english,iso]{isodate}
 \title{The \exsh Package}
 \author{Sebastian Kuhnert\and Frank Fuhlbrück}
-\date{Version 0.16, \printdateTeX{2024/03/07}}
+\date{Version 0.17, \printdateTeX{2024/04/23}}
 
 \begin{document}
 \maketitle
 
-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 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.
+The \exsh package provides a way to typeset exercise sheets as used in university courses and school classes. It evolved from a set of macros an environments that were finally combined into this package. Starting from Version \vers{0.7}, there was an alternative variant designed for use with the beamer class, which is integrated into the main package since version \vers{0.11}. Not all combinations of options have been tested with the beamer variant. From version \vers{0.16} on, there is an embedded mode that allows using exercise in lecture notes etc. without requiring page breaks. Since the package includes a loading mechanism for exercises in external files, the same exercises can be reused in different contexts.
 
 
 \subsection*{Licence}
@@ -72,16 +120,33 @@ Frank Fuhlbrück
 \footnote{\href{mailto:frank@fuhlbrueck.net}{frank@fuhlbrueck.net}}.
 
 
+\section{Reading this Document}
+
+\begin{itemize}
+  \item All macros and environments defined by this package are
+    printed in bold like this: \lstinline|\points| and
+    \lstinline|\begin{sheet}\end{sheet}|.
+  \item Key-value style options with a mandatory argument are
+    printed like this: {\codestyle \option{only}=\param{list of ranges}}, while optional (usually boolean) arguments
+    look like this: {\codestyle \option{embedded}\maybe{=\param{true/false}}}.
+\end{itemize}
+
+
+
+
 \section{Related Classes and Packages}
 
 \subsection{Packages with Similar Functionality}
 \begin{itemize}
  \item The \texttt{exercise} package offers similar functionality, though the
   concept is a bit different: That package provides explicit commands for
-  sub-exercises while \exsh relies on other means like the \texttt{enumerate}
+  sub-exercises while \exsh (in its standard setting)
+  relies on other means like the \texttt{enumerate}
   environment for this. An advantage of the \texttt{exercise} package is that
   answers can be delayed. On the other hand \exsh's environment based user
   interface is a bit cleaner and you have to care less about package internals.
+  \item The \texttt{xsim} (and its predecessor \texttt{exsheets}) package also offers a similar set of features for the average user. It also has a mechanism for hiding certain exercises and solutions that works a bit differently than the mechanism of
+  this package. There is (to my knowledge) no explicit beamer support.
 \end{itemize}
 
 \subsection{Recommended Additional Packages}
@@ -94,11 +159,11 @@ Frank Fuhlbrück
   omitted.
  \item The use of \texttt{enumitem} or \texttt{paralist} is recommended. Top
   level enumerating lists are then modified to have the form (a), (b), \dots{},
-  which is useful in exercise definitions.
+  which is useful in exercise definitions (you can override this).
  \item If the \texttt{varioref} package is used, appropriate label formats are
   installed for exercises and sub-exercises.
  \item If the \texttt{xcolor} package is loaded, to-do markers generated with
-  \verb|\TODO| are printed in red.
+  \lstinline|\TODO| are printed in red.
 \end{itemize}
 
 \subsection{Packages Loaded by \exsh}
@@ -108,9 +173,9 @@ Frank Fuhlbrück
  \item \texttt{scrlfile} (part of \KOMAScript{})
  \item \texttt{pgfkeys} (part of PGF 2.0)
  \item \texttt{ifthen}
- \item \texttt{amsmath} (for \verb|\numberwithin|)
+ \item \texttt{amsmath} (for \lstinline|\numberwithin|)
  \item \texttt{iflualatex}
- \item \texttt{refcount} (for \verb|\getrefnumber|)
+ \item \texttt{refcount} (for \lstinline|\getrefnumber|)
 \end{itemize}
 
 
@@ -121,12 +186,12 @@ The beamer variant is integrated now and automatically activated
 if the current document class is beamer.
 
 \begin{lstlisting}
-\usepackage(*\opt{[\param{options}]}*){exercisesheets}
+\usepackage(*\maybe{[\param{options}]}*){exercisesheets}
 \end{lstlisting}
 
 The following options are available:
 \begin{description}
- \item[\option{only=\param{list of ranges}}] When given, only the mentioned
+ \optitem[{\option{only}=\mand{\param{list of ranges}}}] When given, only the mentioned
   sheets will be included in the output. This is useful to speed up compilation
   times for big documents. Some efforts are made that sheet and exercise
   numbering remain consistent and references to exercises and enumerated lists
@@ -138,15 +203,15 @@ The following options are available:
   the last sheet in the document (this may require an additional \LaTeX{} run).
   Examples:
   \begin{description}
-   \item[\option{only=3}] Only include the 3rd sheet of the document.
-   \item[\option{only=\{1,3,5,7\}}] Only include the sheets 1, 3, 5 and 7.
-   \item[\option{only=last}] Only include the last sheet of the document.
-   \item[\option{only=\{3-5,8-last\}}] Exclude the sheets 1, 2, 6 and 7.
-   \item[\option{only=\{-2,5-\}}] Exclude the sheets 3 and 4.
+   \optitem[{\option{only}=3}] Only include the 3rd sheet of the document.
+   \optitem[{\option{only}=\{1,3,5,7\}}] Only include the sheets 1, 3, 5 and 7.
+   \optitem[{\option{only}=last}] Only include the last sheet of the document.
+   \optitem[{\option{only}=\{3-5,8-last\}}] Exclude the sheets 1, 2, 6 and 7.
+   \optitem[{\option{only}=\{-2,5-\}}] Exclude the sheets 3 and 4.
   \end{description}
- \item[\option{all}] Typeset all sheets (equivalent to \option{only=-}). This is
+ \optitem[{\option{all}}] Typeset all sheets (equivalent to \option{only=-}). This is
   the default.
- \item[\option{solutions\opt{=\param{true/false/oral/nonoral/sample oral/sample nonoral/sample all}}}] By default,
+ \optitem[{\option{solutions\maybe{=\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}
@@ -158,83 +223,82 @@ The following options are available:
   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}}}]
+ \optitem[{\option{gradingguides\maybe{=\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
+ \optitem[{\option{solutionsby}=\mand{\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.
- \item[\option{language=\param{lang}}] Set the language of the sheet and
+ \optitem[{\option{language}=\mand{\param{lang}}}] Set the language of the sheet and
   exercise heads to \param{lang}. If the \texttt{babel} package is loaded this
   is not necessary, as the main document language will be automatically
   detected. Currently \option{english}, \option{german} and \option{ngerman} are
   supported. Other translations are welcome: Please contact the author.
- \item[\option{pointsfloatright}] Use an alternative mechanism to place points for Sub-Exercises.
+ \optitem[{\option{pointsfloatright}}] Use an alternative mechanism to place points for Sub-Exercises.
   If this option is used, the points label for a Sub-Exercise is placed at the (right) end of the current line.
   It is especially useful if used in a context like \texttt{$\backslash$item$\backslash$points$\{3\}$}.
   This option exploits (and partially breaks) RTL-Support.
- \item[\option{exercisespath}] Set the (relative) path of the
+ \optitem[{\option{exercisespath}}] Set the (relative) path of the
   directory containing exercises to be included via
-  \verb|\includeexercise|.
- \item[\option{patchenumerate}\opt{=\param{true/false}}] Sets
+  \lstinline|\includeexercise|.
+ \optitem[{\option{patchenumerate}\maybe{=\param{true/false}}}] Sets
   enumerate item labels for the first four levels, starting with
   a), b) etc. for the top-level (sub-exercises). Depending on other
-  loaded packages (\verb|enumitem|, \verb|paralist|) the mechanism
+  loaded packages (\lstinline|enumitem|, \lstinline|paralist|) the mechanism
   slightly differs. This option is active by default.
- \item[\option{settitle}\opt{=\param{true/false}}] If set to true
+ \optitem[{\option{settitle}\maybe{=\param{true/false}}}] If set to true
   (which is the default),
-  the document \verb|\title| will be automatically set to the value
-  of \option{strings/sheets} and the value of \option{strings/
-  solutions} will be
-  appended if \option{solutions} is not \option{false}.
- \item[\option{patchpagenumbers}\opt{=\param{true/false}}] If true
+  the document \lstinline|\title| will be automatically set to the value
+  of \option{strings/sheets} and the value of \option{strings/solutions} will be
+  appended if \option{solutions} is not \lstinline|false|.
+ \optitem[{\option{patchpagenumbers}\maybe{=\param{true/false}}}] If true
   (default), pages will be numbered within sheets and page numbers
-  get a prefix of the form ``\param{sheet number}\verb|-|''.
- \item[\option{usestartsection}\opt{=\param{true/false}}] If true
-  (default), the command \verb|\@startsection| is used to create
+  get a prefix of the form ``{\codestyle\param{sheet number}-}''.
+ \optitem[{\option{usestartsection}\maybe{=\param{true/false}}}] If true
+  (default), the command \lstinline|\@startsection| is used to create
   the header of any exercise as a section, which (among other
   things) adds an entry to the TOC (if existent) at level 1
-  (usually corresponding to \verb|\section|).
- \item[\option{embedded}\opt{=\param{true/false}}] Default: false.
+  (usually corresponding to \lstinline|\section|).
+ \optitem[{\option{embedded}\maybe{=\param{true/false}}}] Default: false.
   Embedded mode allows for exercise ``sheets'' which do not
   interfere with a surrounding document. More explicitly, it does
-  not interfere with \verb|secnumdepth|, defines special counters
-  \verb|exshsheet| and \verb|exshexercise| to use them for
+  not interfere with \lstinline|secnumdepth|, defines special counters
+  \lstinline|exshsheet| and \lstinline|exshexercise| to use them for
   \option{sheet counter} and \option{exercise counter},
   respectively and sets all of \option{patchenumerate},
   \option{settitle}, \option{patchpagenumbers} and
-  \option{usestartsection} to \option{false}.
+  \option{usestartsection} to \lstinline|false|.
   An internally defined macro which basically does no extra
   formatting or adding anything to the TOC is used as
-  \option{sheet sectioning cmd} instead of the usual \verb|part|.
+  \option{sheet sectioning cmd} instead of the usual \lstinline|\part|.
   Finally,
   the \option{sheet start page action} and the
-  \option{sheet end page action} are both set to \verb|\relax|.
+  \option{sheet end page action} are both set to \lstinline|\relax|.
   If you want to override any of this, do it after setting
-  \option{embedded} to \option{true}.
- \item{\option{minskips\opt{=\param{true/false}}}} Default: false.
+  \option{embedded} to \lstinline|true|.
+ \item{\option{minskips\maybe{=\param{true/false}}}} Default: false.
   If true, the values of
   \option{above sheet title skip},
   \option{below sheet header skip},
   \option{above first exercise skip} and
   \option{below exercise title skip} are all set to 0pt.
- \item[\option{showtodos} / \option{hidetodos}]
-  \verb|\TODO| markers
+ \optitem[{\option{showtodos} / \option{hidetodos}}]
+  \lstinline|\TODO| markers
   are hidden by default, this option switches their behavior. This
-  option is usually set within \verb|\ifsamplesolutions| or
+  option is usually set within \lstinline|\ifsamplesolutions| or
   similar.
- \item[\option{beamercompatibility}\opt{=\param{true/false}}]
-  This options (which only is effective in the non-beamer version)
+ \optitem[{\option{beamercompatibility}\maybe{=\param{true/false}}}]
+  This option (which only is effective in the non-beamer version)
   defines several beamer macros with as trivial
-  effects as possible, e.g., \verb|\pause| becomes \verb|\relax|
+  effects as possible, e.g., \lstinline|\pause| becomes \lstinline|\relax|
   and overlay specifications are mostly ignored. Be careful to use
-  this option after loading \verb|enumitem| etc. as the enumerate
+  this option after loading \lstinline|enumitem| etc. as the enumerate
   and itemize environment are defined to swallow overlay
   specifications without effect, this also holds for
-  \verb|\item<1->|. If you load \verb|exercisesheets| before them
-  use \verb|\exshset| afterwards.
+  \lstinline|\item<1->|. If you load \lstinline|exercisesheets| before them
+  use \lstinline|\exshset| afterwards.
   The current list of redefinitions is as
   follows:
 \begin{lstlisting}
@@ -261,9 +325,9 @@ The following options are available:
     \@ifnextchar[\exsh@ovrlenumerate\exsh@origenumerate}
 \end{lstlisting}
 
-\item[\option{filenameasexercisename}\opt{=\param{true/false}}]
+\optitem[{\option{filenameasexercisename}\maybe{=\param{true/false}}}]
 This option (set to false by default) causes
-\verb|\includeexercise| to
+\lstinline|\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
@@ -286,14 +350,15 @@ either), a warning is issued.
 
 Please do not include a \lstinline|\title| in your document, as \exsh will
 automatically generate an appropriate one (this may require an additional
-\LaTeX{} run).
+\LaTeX{} run). If you want to set the title yourself, set the
+option \option{settitle} to \lstinline|false|.
 
 All this information is included in the PDF meta-data if the \texttt{hyperref}
 package is loaded with the option \texttt{pdfusetitle}.
 
 There is also a related option:
 \begin{description}
- \item[\option{exauthor=\param{list of names}}] If you want to use the
+ \optitem[{\option{exauthor}=\mand{\param{list of names}}}] If you want to use the
  \lstinline|\author| macro for the general author of a course but
  there are different authors for individual exercises or all
  exercises in general, you can set this key. Currently only
@@ -304,7 +369,7 @@ There is also a related option:
 \subsection{Defining Exercise Sheets}
 \label{sec:sheet}
 \begin{lstlisting}
-\begin{sheet}(*\opt{[\param{options}]}*)
+\begin{sheet}(*\maybe{[\param{options}]}*)
   (*\param{sheet contents}*)
 \end{sheet}
 \end{lstlisting}
@@ -317,35 +382,35 @@ Section~\ref{sec:exercises-solutions}).
 
 The following \param{options} are supported:
 \begin{description}
- \item[\option{date=\param{date}}] Set the date the sheet was/will be issued. This
+ \optitem[{\option{date}=\mand{\param{date}}}] Set the date the sheet was/will be issued. This
   information is included in the sheet header. By default, this information is
   omitted. See also the \option{semester} option.
- \item[\option{note=\param{note}}] Include \param{note} in the sheet header.
+ \optitem[{\option{note}=\mand{\param{note}}}] Include \param{note} in the sheet header.
   Useful to inform students when the sheet is due. If you want a note consisting
   of more than one line split at a particular position, use
-  \verb|\protect\linebreak|.
- \item[\option{title=\param{title}}]
+  \lstinline|\protect\linebreak|.
+ \optitem[{\option{title}=\mand{\param{title}}}]
   Directly set the sheet title. When this option is used, different
   page numbering conventions are used. This is useful to
   typeset exams (combined with the next option).
- \item[\option{number within sheet\opt{=\param{true/false}}}]
+ \optitem[{\option{number within sheet\maybe{=\param{true/false}}}}]
   Deviate from the usual numbering theme and
   restart from one for exercises on the sheet. The previous
   counter value is restored after the sheet, so you can insert
   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 the beamer
+ \optitem[{\option{author}=\mand{\param{author}}}] Set the author included in the sheet
+  head. By default, the value passed to \lstinline|\author| is used.
+ \optitem[{\option{exauthor}=\mand{\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 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{beamerwithfootline\opt{=\param{true/false}}}]
+ \optitem[{\option{subject}=\mand{\param{subject}}}] Set the subject included in the sheet
+  head. By default, the value passed to \lstinline|\subject| is used.
+ \optitem[{\option{semester}=\mand{\param{semester}}}] Set the semester included in the
+  sheet head. By default, the value passed to \lstinline|\date| is used.
+ \optitem[{\option{beamerwithheadline\maybe{=\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. If you specify the embedded option the current default headers and footers will be used if you omit this option. Otherwise omitting it will imply an empty headline.
+ \optitem[{\option{beamerwithfootline\maybe{=\param{true/false}}}}]
  The same for the footer.
- \item[\option{beameruseblocks\opt{=\param{true/false}}}]
+ \optitem[{\option{beameruseblocks\maybe{=\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
@@ -356,19 +421,19 @@ The following \param{options} are supported:
 \subsection{Defining Exercises and Solutions}
 \label{sec:exercises-solutions}
 \begin{lstlisting}
-\begin{exercise}(*\opt{[\param{options}]}*)
+\begin{exercise}(*\maybe{[\param{options}]}*)
   (*\param{exercise text}*)
-  \begin{solution}(*\opt{[\param{solution options}]}*)
+  \begin{solution}(*\maybe{[\param{solution options}]}*)
     (*\param{solution text}*)
   \end{solution}
-  \begin{beamersolution}(*\opt{[\param{solution options}]}*)
+  \begin{beamersolution}(*\maybe{[\param{solution options}]}*)
     (*\param{solution text}*)
   \end{beamersolution}
 \end{exercise}
 \end{lstlisting}
 
 This inserts an exercise into the current document. All
-\option{beamersolution}s are ignored, if the
+\lstinline|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}
@@ -377,56 +442,56 @@ to turn this off).
 The following options are
 supported:
 \begin{description}
- \item[\option{name=\param{text}}] Use \param{text} as the name of the exercise.
+ \optitem[{\option{name}=\mand{\param{text}}}] Use \param{text} as the name of the exercise.
   Useful for exercises that prove a famous theorem.
- \item[\option{firstline=\param{text}}] Save some space by text \param{text}
+ \optitem[{\option{firstline}=\mand{\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|
+ \optitem[{\option{savetasks\maybe{=\param{true/false}}}}] Saves the main task and each sub task
+  for later use with \lstinline|\restatetask[|%
+  \param{which}], where \param{which} is either \lstinline|main|
   (default) or the number of a sub task.
- \item[\option{points=\param{number/oral/sum}}] Assign this
+ \optitem[{\option{points}=\mand{\param{number/oral/sum}}}] Assign this
   exercise \param{number} points. By default, exercises are
   unlabelled. \param{oral} works the same way as the option
   \option{oral}. The value \param{sum} displays the sum of all
-  occurrences of \verb|\points| within the exercise: Ordinary and
+  occurrences of \lstinline|\points| within the exercise: Ordinary and
   bonus points are treated separately. If there are only bonus
   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
+  undo this, either delete the \filename{.aux} file or explicitly use
+  \lstinline|\points[bonus=false]{\param{number}}| for at least one
   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
+ \optitem[{\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
+ \optitem[{\option{pointsinfo}=\mand{\param{text}}}] Supply \param{text} as additional
   information to be displayed after the points.
- \item[\option{optional}] Shortcut for \option{pointsinfo=optional} with
+ \optitem[{\option{optional}}] Shortcut for \option{pointsinfo=optional} with
   automatic translation and abbreviation (if requested).
- \item[\option{bonus}] Change \enquote{points} to \enquote{bonus points} (with
+ \optitem[{\option{bonus}}] Change \enquote{points} to \enquote{bonus points} (with
   automatic translation and abbreviation).
-  \item[\option{abbrev}] Use abbreviated labels.
- \item[\option{exercisemark=\param{symbol}}] Mark the exercise
+  \optitem[{\option{abbrev}}] Use abbreviated labels.
+ \optitem[{\option{exercisemark}=\mand{\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
+ \optitem[{\option{difficult}}] Shortcut for \option{exercisemark=*}.
+ \optitem[{\option{solutions\maybe{=\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
+ \optitem[{\option{sample}}] Include this exercise (and its solution) in while compiling
  sample solutions.
- \item[\option{beamersolution}] For beamer variant only. If this option
+ \optitem[{\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 beamer variant only, simply ignored
+ \lstinline|beamersolution|s are typeset.
+ \optitem[{\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
+ more frames. Use \lstinline|\newframe| to start a new frame. This
  option is especially helpful if you provide your own definitions
- of \verb|\only| etc. and/or use the \option{beamercompatibility}.
- for non-beamer compilation. \verb|\newframe|
- is already defined as \verb|\relax| in  non-beamer \exsh,
+ of \lstinline|\only| etc. and/or use the \option{beamercompatibility}.
+ for non-beamer compilation. \lstinline|\newframe|
+ is already defined as \lstinline|\relax| in  non-beamer \exsh,
  even without invoking \option{beamercompatibility}.
- \item[\option{fragile}] For beamer variant only and only
+ \optitem[{\option{fragile}}] For beamer variant only and only
  used combined with framed, simply ignored elsewhere. Frames are
- declared as \texttt{fragile} und parsing of \verb|\newframe|
+ declared as \texttt{fragile} und parsing of \lstinline|\newframe|
  etc. is done via Lua\LaTeX. Thus Lua\LaTeX is required
  (and this requires font setup via fontspec etc.), but
  you do not have to use any Lua code yourself. Mostly useful
@@ -459,13 +524,13 @@ is actually skipped later.
 \subsection{Including Hints}
 
 \begin{lstlisting}
-\begin{hint}(*\opt{[\param{options}]}*)
+\begin{hint}(*\maybe{[\param{options}]}*)
   (*\param{hint text}*)
 \end{hint}
 \end{lstlisting}
 
 \begin{lstlisting}
-\begin{hint*}(*\opt{[\param{options}]}*)
+\begin{hint*}(*\maybe{[\param{options}]}*)
   (*\param{hint text}*)
 \end{hint*}
 \end{lstlisting}
@@ -487,7 +552,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 4+6
+\begin{exercise}[(*\option{points}*)=sum]%sum produces 4+6
   \begin{enumerate}
    \item Part 1 \points{oral}
    \item Part 2 \points[optional]{oral}
@@ -501,22 +566,22 @@ TODO markers (s.a.) the warning will be issued nevertheless.
 \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,
+\lstinline|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 original 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|. If you want to reuse the main or any subtasks
-you may use \verb|\restatetask| or \verb|\restatetaskbeamer|
+use other counters then \lstinline|enumi|, which is also only possible
+if sub-exercises are not simply \lstinline|\item|s in
+\lstinline|enumerate|. If you want to reuse the main or any subtasks
+you may use \lstinline|\restatetask| or \lstinline|\restatetaskbeamer|
 (this shows noting if not compiled with beamer). There is also
-a starred version (\verb|\restatetask*| /
-\verb|\restatetaskbeamer*|) for each of them, which adds a newline.
+a starred version (\lstinline|\restatetask*| /
+\lstinline|\restatetaskbeamer*|) for each of them, which adds a newline.
 All four have an optional argument that allows to restate
 a subtask instead of the main task. This argument is either
-\option{main}, a number of a \textbf{previous} subtask or
-\option{cur} for the current subtask. Using \option{headerrestate}
+\lstinline|main|, a number of a \textbf{previous} subtask or
+\lstinline|cur| for the current subtask. Using \option{headerrestate}
 for your solution will automatically restate the current
 task within the beamer solution header (does noting without
 beamer).
@@ -524,14 +589,14 @@ beamer).
 
 
 \begin{lstlisting}
-\begin{exercise}[points=oral]
+\begin{exercise}[(*\option{points}*)=oral]
   \begin{maintask}
     A and B are true.
   \end{maintask}
   \begin{subtasks}
     \subtask{A is true}
       \begin{solution}[framed]
-        We want to show: \restatestask %A and B are true.
+        We want to show: \restatetask %A and B are true.
         \newframe
         Out first step is to show: \restatetask[cur] %A is true
       \end{solution}
@@ -541,8 +606,8 @@ beamer).
       \end{solution}
     \subtask{B is true}
       \begin{solution}[framed]
-        We already know: \restatestask[1] and
-        \restatestask[2], therefore B is also true.
+        We already know: \restatetask[1] and
+        \restatetask[2], therefore B is also true.
       \end{solution}
   \end{subtasks}
 \end{exercise}
@@ -551,16 +616,16 @@ beamer).
 \subsection{Labels and References within an Exercise}
 While the global reference labels set via varioref (if loaded)
 are nice for references to subexercises far away, always mentioning
-the exercise number seems superfluous. Furthermore, for usage in indices etc. you might want to use the arabic representation instead. This is what the commands \verb|\subexnref| and
-\verb|\subexlref| are designed for. However, both of them still
+the exercise number seems superfluous. Furthermore, for usage in indices etc. you might want to use the arabic representation instead. This is what the commands \lstinline|\subexnref| and
+\lstinline|\subexlref| are designed for. However, both of them still
 require an ordinary label, which is not allowed in
-exercises loaded with \verb|\loadexercise*|.
-For this purpose \verb|\inexlabel| can be used which is just a
+exercises loaded with \lstinline|\loadexercise*|.
+For this purpose \lstinline|\inexlabel| can be used which is just a
 normal label that is not redefined to produce an error.
-Furthermore, we define a counter \verb|subex| (which is
+Furthermore, we define a counter \lstinline|subex| (which is
 currently just an alias for enumi, but this might change). You can
 use this counter (alias) with common commands like
-\verb|\arabic| or \verb|\alph|.
+\lstinline|\arabic| or \lstinline|\alph|.
 
 \begin{lstlisting}
 \begin{exercise}
@@ -588,7 +653,7 @@ Options can be given at different places.
  \item As package options: This is convenient for global options but suffers
   from shortcomings in way \LaTeX{} processes options: Macros are expanded and
   spaces are stripped.
- \item By the independent \verb|\exshset| command. This is especially useful in
+ \item By the independent \lstinline|\exshset| command. This is especially useful in
   the preamble to set options that would be garbled by the \LaTeX{} option
   handling routine. It also allows to change an option for the rest of the
   current scope.
@@ -607,30 +672,30 @@ For some languages, predefined sets of strings are provided and automatically
 activated. If your language is not supported or if you want to change (some of)
 the used strings, you can do so with the following options:
 \begin{description}
- \item[\option{strings/sheet=\param{string}}]
- \item[\option{strings/sheets=\param{string}}]
- \item[\option{strings/solutions=\param{string}}]
- \item[\option{strings/solutionsby=\param{string}}]
- \item[\option{strings/exercise=\param{string}}]
- \item[\option{strings/solution=\param{string}}]
- \item[\option{strings/hint=\param{string}}]
- \item[\option{strings/oral=\param{string}}]
- \item[\option{strings/oral abbrev=\param{string}}]
- \item[\option{strings/point=\param{string}}]
- \item[\option{strings/points=\param{string}}]
- \item[\option{strings/points abbrev=\param{string}}]
- \item[\option{strings/bonus point=\param{string}}]
- \item[\option{strings/bonus points=\param{string}}]
- \item[\option{strings/bonus points abbrev=\param{string}}]
- \item[\option{strings/optional=\param{string}}]
- \item[\option{strings/optional abbrev=\param{string}}]
+ \optitem[{\option{strings/sheet}=\mand{\param{string}}}]
+ \optitem[{\option{strings/sheets}=\mand{\param{string}}}]
+ \optitem[{\option{strings/solutions}=\mand{\param{string}}}]
+ \optitem[{\option{strings/solutionsby}=\mand{\param{string}}}]
+ \optitem[{\option{strings/exercise}=\mand{\param{string}}}]
+ \optitem[{\option{strings/solution}=\mand{\param{string}}}]
+ \optitem[{\option{strings/hint}=\mand{\param{string}}}]
+ \optitem[{\option{strings/oral}=\mand{\param{string}}}]
+ \optitem[{\option{strings/oral abbrev}=\mand{\param{string}}}]
+ \optitem[{\option{strings/point}=\mand{\param{string}}}]
+ \optitem[{\option{strings/points}=\mand{\param{string}}}]
+ \optitem[{\option{strings/points abbrev}=\mand{\param{string}}}]
+ \optitem[{\option{strings/bonus point}=\mand{\param{string}}}]
+ \optitem[{\option{strings/bonus points}=\mand{\param{string}}}]
+ \optitem[{\option{strings/bonus points abbrev}=\mand{\param{string}}}]
+ \optitem[{\option{strings/optional}=\mand{\param{string}}}]
+ \optitem[{\option{strings/optional abbrev}=\mand{\param{string}}}]
 \end{description}
 
 Example: Give an introduction that should only be included in the version with
 solutions:
 
 \begin{lstlisting}
-\begin{solution}[strings/solution=Introduction]
+\begin{solution}[(*\option{strings/solution}*)=Introduction]
   (*\param{introduction text}*)
 \end{solution}
 \end{lstlisting}
@@ -646,104 +711,104 @@ be changed in the following way:
 The available \param{font element}s are listed below together with their default
 values:
 \begin{description}
- \item[\option{sheet header font}] The basic font for subject, author, semester,
+ \optitem[{\option{sheet header font}}] The basic font for subject, author, semester,
   date, note and solution authors in the sheet headers.\\
-  Default: \verb|\normalfont\normalsize|
- \item[\option{subject font}] The font for the subject in the sheet header.\\
-  Default: \verb|\scshape|
- \item[\option{author font}] The font for the author in the sheet header.\\
-  Default: \verb|\scshape|
- \item[\option{semester font}] The font for the semester in the sheet header.\\
+  Default: \lstinline|\normalfont\normalsize|
+ \optitem[{\option{subject font}}] The font for the subject in the sheet header.\\
+  Default: \lstinline|\scshape|
+ \optitem[{\option{author font}}] The font for the author in the sheet header.\\
+  Default: \lstinline|\scshape|
+ \optitem[{\option{semester font}}] The font for the semester in the sheet header.\\
   Default: empty, i.\,e.\ no change.
- \item[\option{date font}] The font for the date in the sheet header.\\
+ \optitem[{\option{date font}}] The font for the date in the sheet header.\\
   Default: empty, i.\,e.\ no change.
- \item[\option{solutionsby font}] The font for the information who has produced
+ \optitem[{\option{solutionsby font}}] The font for the information who has produced
   the solutions provided below the sheet title.\\
-  Default: \verb|\itshape|
- \item[\option{sheet note font}] The font for the note provided below the sheet
+  Default: \lstinline|\itshape|
+ \optitem[{\option{sheet note font}}] The font for the note provided below the sheet
   title.\\
-  Default: \verb|\itshape\bfseries|
- \item[\option{sheet title font}] The font for the sheet title itself.\\
-  Default: \verb|\Large\bfseries|
- \item[\option{exercise title font}] The font for the exercise title.\\
-  Default: \verb|\bfseries|
- \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: \lstinline|\itshape\bfseries|
+ \optitem[{\option{sheet title font}}] The font for the sheet title itself.\\
+  Default: \lstinline|\Large\bfseries|
+ \optitem[{\option{exercise title font}}] The font for the exercise title.\\
+  Default: \lstinline|\bfseries|
+ \optitem[{\option{points font}}] The font for the number of points in the exercise
+  head (relative to the exercise title) and for \lstinline|\points|.\\
+  Default: \lstinline|\itshape|
+ \optitem[{\option{main task font}}] The font for the
+  \lstinline|maintask| environment.\\
   Default: empty, i.\,e.\ no change.
- \item[\option{subtask font}] The font for each
-  \verb|\subtask|.\\
+ \optitem[{\option{subtask font}}] The font for each
+  \lstinline|\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. \\
+ \optitem[{\option{task restate font}}] The font used for
+  \lstinline|\restatetask|.\\
+  Default: \lstinline|\itshape|
+ \optitem[{\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:}.\\
-  Default: \verb|\itshape|
- \item[\option{solution font}] The font for solutions.\\
+ \optitem[{\option{hint title font}}] The font for the string \enquote{Hint:}.\\
+  Default: \lstinline|\itshape|
+ \optitem[{\option{solution font}}] The font for solutions.\\
   Default: empty, i.\,e.\ no change.
- \item[\option{solution title font}] The font for the string
+ \optitem[{\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|
+  Default: \lstinline|\bfseries|
+ \optitem[{\option{grading guide font}}] The font for grading guides.\\
+  Default: \lstinline|\itshape|
+ \optitem[{\option{todo marker font}}] The font for the string \enquote{TODO}.\\
+  Default: \lstinline|\ifdef{\color}{\color{red}}{}\bfseries|
 \end{description}
 
 \subsection{Controlling the Spacing, Page Handling and Separations between Elements}
 
 The following options allow fine-tuning of the spacing:
 \begin{description}
- \item[\option{below slide headline skip=\param{dimen}}] The distance between
+ \optitem[{\option{below slide headline skip}=\mand{\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
+ \optitem[{\option{above sheet title skip}=\mand{\param{dimen}}}] The distance between
   author/date and sheet title.\\
   Default: \texttt{4ex}
- \item[\option{above sheet note skip=\param{dimen}}] The distance above the
+ \optitem[{\option{above sheet note skip}=\mand{\param{dimen}}}] The distance above the
   sheet note.\\
   Default: \texttt{.7ex}
- \item[\option{above solutionsby skip=\param{dimen}}] The distance above the
+ \optitem[{\option{above solutionsby skip}=\mand{\param{dimen}}}] The distance above the
   solution author.\\
   Default: \texttt{1ex}
- \item[\option{below sheet header skip=\param{dimen}}] The distance below the
+ \optitem[{\option{below sheet header skip}=\mand{\param{dimen}}}] The distance below the
   sheet header.\\
   Default: \texttt{4ex plus 1ex minus .5ex}
- \item[\option{above exercise skip=\param{dimen}}] The distance above
+ \optitem[{\option{above exercise skip}=\mand{\param{dimen}}}] The distance above
   exercises.\\
   Default: \texttt{3ex plus 1ex minus .5ex}
- \item[\option{below exercise title skip=\param{dimen}}] The distance below
+ \optitem[{\option{below exercise title skip}=\mand{\param{dimen}}}] The distance below
   exercise titles.\\
   Default: \texttt{\textbackslash parskip}
- \item[\option{above solution skip=\param{dimen}}] The distance above
+ \optitem[{\option{above solution skip}=\mand{\param{dimen}}}] The distance above
   solutions.\\
   Default: \texttt{1ex}
- \item[\option{above hint skip=\param{dimen}}] The distance above hints.\\
+ \optitem[{\option{above hint skip}=\mand{\param{dimen}}}] The distance above hints.\\
   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
+ \optitem[{\option{sheet start page action}=\mand{\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
+  Default: \lstinline|\clearpage|
+ \optitem[{\option{sheet end page action}=\mand{\param{macro}}}] Executed at the end
   of each sheet.\\
-  Default: \texttt{\string\clearpage}
+  Default: \lstinline|\clearpage|
 \end{description}
 
 The following option controls what follows after the string
 \option{strings/solution} within a solution header. Using this, you can disable a solution header completely or, for instance, add
 a horizontal bar below each solution title.
 \begin{description}
- \item[\option{solution title separator=\param{content}}] Inserted directly after \option{strings/solution} in a solution title:\\
-  Default: \verb|:\par|
+ \optitem[{\option{solution title separator}=\mand{\param{content}}}] Inserted directly after \option{strings/solution} in a solution title:\\
+  Default: \lstinline|:\par|
 \end{description}
 
 \subsection{Controlling the Sectioning (beta)}
@@ -753,29 +818,29 @@ the respective counters and commands. This is impractical, if you
 want to include exercise ``sheets'' as, e.g., a subsection within
 a section of a book or article. While the page handling options
 already allow to dismiss page breaks, sectioning commands might
-still break your layout or structure. Since version \verb|0.15| you
+still break your layout or structure. Since version \vers{0.15} you
 can use your own counters and commands to start sheets and
-(to a certain degree) exercises. Exercise are currently still
-started by \verb|\@startsection| with the counter set to
+(to a certain degree) exercises. Exercises are currently still
+started by \lstinline|\@startsection| with the counter set to
 \option{exercise counter}, but the level set to 1 (e.g. section).
 This will likely change with one of the next versions, but needs
 some testing. Thus, if you use any of these options, watch for
 undesired consequences and report them via gitlab if possible.
 
 \begin{description}
- \item[\option{sheet sectioning cmd=\param{macro}}] This macro is
+ \optitem[{\option{sheet sectioning cmd}=\mand{\param{macro}}}] This macro is
  called only in one place in the following way:
- \verb|\macro[short title{long title}|, so it
+ \lstinline|\macro[short title]{long title}|, so it
  must take one argument in [brackets] and one normal argument.\\
-  Default: \verb|\part|
- \item[\option{sheet counter=\param{counter}}] This counter will be
+  Default: \lstinline|\part|
+ \optitem[{\option{sheet counter}=\mand{\param{counter}}}] This counter will be
  incremented wit every sheet. There was always an internal counter
- \verb|sheetid| used to distinguish sheets for hyperref even if
- \verb|part|s value changed. Do not use this counter here, as it will have strange effects (incremented twice).\\
-  Default: \verb|part|
- \item[\option{exercise counter=\param{counter}}] This counter will
+ \lstinline|sheetid| used to distinguish sheets for hyperref even if
+ \lstinline|part|s value changed. Do not use this counter here, as it will have strange effects (incremented twice).\\
+  Default: \lstinline|part|
+ \optitem[{\option{exercise counter}=\mand{\param{counter}}}] This counter will
  be incremented wit every exercise (usually within each sheet).
-  Default: \verb|section|
+  Default: \lstinline|section|
 \end{description}
 
 \subsection{Special Code for Solutions}
@@ -783,6 +848,7 @@ undesired consequences and report them via gitlab if possible.
 \ifsolutions{(*\param{if true}*)}{(*\param{if false}*)}
 \iforalsolutions{(*\param{if true}*)}{(*\param{if false}*)}
 \ifnonoralsolutions{(*\param{if true}*)}{(*\param{if false}*)}
+\ifsamplesolutions{(*\param{if true}*)}{(*\param{if false}*)}
 \end{lstlisting}
 
 There are also special options for conditionals to be used in the arguments of
@@ -811,7 +877,7 @@ Example 1: Only include points for sub-exercises when solutions are typeset:
 
 Example 2: Modify the sheet header spacing in the non-solution version:
 \begin{lstlisting}
-\begin{sheet}[ifsolutions={}{above title skip=2ex}]% usually 4ex
+\begin{sheet}[(*\option{ifsolutions}*)={}{(*\option{above title skip}*)=2ex}]% usually 4ex
   \dots
 \end{sheet}
 \end{lstlisting}
@@ -819,10 +885,10 @@ Example 2: Modify the sheet header spacing in the non-solution version:
 \subsection{Using Hooks}
 There are several hooks used by \exsh:
 \begin{description}
- \item[\option{every sheet}] This is used at the beginning of every sheet.
- \item[\option{every exercise}] This is used at the beginning of every exercise.
- \item[\option{every solution}] This is used at the beginning of every solution.
- \item[\option{every hint}] This is used at the beginning of every hint.
+ \optitem[{\option{every sheet}}] This is used at the beginning of every sheet.
+ \optitem[{\option{every exercise}}] This is used at the beginning of every exercise.
+ \optitem[{\option{every solution}}] This is used at the beginning of every solution.
+ \optitem[{\option{every hint}}] This is used at the beginning of every hint.
 \end{description}
 
 Hooks can be used to influence the behaviour of the respective environments.
@@ -830,20 +896,20 @@ 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}}]
+ \optitem[{\option{custom skip macro}=\mand{\param{macro}}}]
 \end{description}
 
-If an exercise is not printed, some macros like \texttt{\string\label{}}
+If an exercise is not printed, some macros like \lstinline|\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
+nested \lstinline|\ifstrequal|s and then either
 executes a custom skipper, replaces your macro with
-the standard version or uses \texttt{\string\expandafter} to
+the standard version or uses \lstinline|\expandafter| to
 deliver the expanded version of your macro to
-\texttt{\string\exshskipcontinue}.
+\lstinline|\exshskipcontinue|.
 
 Example:
 \begin{lstlisting}
@@ -868,7 +934,7 @@ Example:
 \section{The Lua Interface}
 \label{sec:lua}
 
-Since version 0.11 there is a Lua interface for the exercise
+Since version \vers{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
@@ -914,86 +980,96 @@ This also works well in combination with a makefile that generates
 \texttt{solutions.tex} as a temporary file.
 
 \subsection{Compatibilty with make4ht and tex4ebook}
-Since version \verb|0.15| this package can be used with make4ht and tex4ebook in non-beamer mode. Some code for the sheet and exercise header already provides a similar alignment as when producing PDF files. If your goal is an exercise (or solution) document within a single HTML file that looks as similar to the PDF as possible, consider \url{https://tex.stackexchange.com/questions/605478/}, \url{https://tex.stackexchange.com/questions/662445} and \url{https://tex.stackexchange.com/questions/630992}.
+Since version \vers{0.15} this package can be used with make4ht and tex4ebook in non-beamer mode. Some code for the sheet and exercise header already provides a similar alignment as when producing PDF files. If your goal is an exercise (or solution) document within a single HTML file that looks as similar to the PDF as possible, consider \url{https://tex.stackexchange.com/questions/605478/}, \url{https://tex.stackexchange.com/questions/662445} and \url{https://tex.stackexchange.com/questions/630992}.
 
 \section{Changelog}
 \label{sec:changelog}
 
 \begin{itemize}
-    \item[v. 0.16:]  2024-03-07
+    \versitem[0.17:]  2024-04-23
+      \begin{itemize}
+        \item Make embedded mode work better with beamer. This
+        includes not overriding headlines and footlines and
+        incrementing the frame counter for non-frames.
+        \item issue an explicit warning if \string\subtask is outside of a subtasks environment
+        \item clearify documentation and use consistent styling
+        \item additional example for embedding exercises
+      \end{itemize}
+    \versitem[0.16:]  2024-03-07
       \begin{itemize}
         \item Embedded mode and most of the additional options it
         automatically sets.
       \end{itemize}
-    \item[v. 0.15.1:]  2023-12-14
+    \versitem[0.15.1:]  2023-12-14
       \begin{itemize}
-        \item bugfix: beamer support was broken in 0.15 due to
+        \item bugfix: beamer support was broken in \vers{0.15} due to
         a missing macro.
       \end{itemize}
-    \item[v. 0.15:]  2023-11-30
+    \versitem[0.15:]  2023-11-30
       \begin{itemize}
         \item new option \option{solution title separator}
-        (initially set to\verb|:\par|). Among other things, this
+        (initially set to\lstinline|:\par|). Among other things, this
         allows for solutions without any caption or header by
         setting \option{solution title separator},~
         \option{solution title font} as well as
-        \option{strings/solution} to \verb|\relax|.
-        \item initial support for \verb|make4ht| and
-        \verb|tex4ebook| by avoiding certain behavior when these
+        \option{strings/solution} to \lstinline|\relax|.
+        \item initial support for \binary{make4ht} and
+        \binary{tex4ebook} by avoiding certain behavior when these
         modes are used. Note that both are incompatible with beamer
         mode.
         \item initial decoupling of exercise and sheet from
         sections and parts using the new options (defaults in
-        parenthesis) \option{sheet sectioning cmd} (\verb|\part|),
-        \option{sheet counter} (\verb|part|) and
-        \option{exercise counter} (\verb|section|).
+        parenthesis) \option{sheet sectioning cmd} (\lstinline|\part|),
+        \option{sheet counter} (\lstinline|part|) and
+        \option{exercise counter} (\lstinline|section|).
       \end{itemize}
-    \item[v. 0.14:]  2023-02-06
+    \versitem[0.14:]  2023-02-06
       \begin{itemize}
         \item new option \option{headerrestate} to restate
         the current (if in subexercise) or main task within
         a solutions header
-        \item bugfix: \verb|\restatetask| etc. give meaningful error if \option{savetasks} is not set.
+        \item bugfix: \lstinline|\restatetask| etc. give meaningful error if \option{savetasks} is not set.
       \end{itemize}
-    \item[v. 0.13.1:]  2022-11-22
+    \versitem[0.13.1:]  2022-11-22
       \begin{itemize}
-        \item bugfix: \verb|\detokenize| filenames when
+        \item bugfix: \lstinline|\detokenize| filenames when
           \option{filenameasexercisename} is active as otherwise,
           e.g., underscores would not be allowed in filenames.
       \end{itemize}
-    \item[v. 0.12.2:]  2022-10-20
-    \item[v. 0.13:]  2022-11-07
+    \versitem[0.12.2:]  2022-10-20
+    \versitem[0.13:]  2022-11-07
       \begin{itemize}
-        \item bugfix: \verb|\begingroup| and \verb|\endgroup|
-          within \verb|\subtask| now contain everything up to the
-          next \verb|\subtask|.
-        \item \verb|\restatestask| has now a starred version that
+        \item bugfix: \lstinline|\begingroup| and \lstinline|\endgroup|
+          within \lstinline|\subtask| now contain everything up to the
+          next \lstinline|\subtask|.
+        \item \lstinline|\restatetask| has now a starred version that
           adds a newline and beamer versions for both the
           regular and the starred version. Furthermore, there
           is an argument \option{cur} to restate the current
           subtask (the one just given before). This is only
           defined within the aforementioned group, i.e.,
-          throws an error after \verb|\end{subtasks}|.
+          throws an error after \lstinline|\end{subtasks}|.
       \end{itemize}
-    \item[v. 0.12.2:]  2022-10-20
+    \versitem[0.12.2:]  2022-10-20
       \begin{itemize}
-        \item bugfix: dofile with \verb|kpse.find_file|
+        \item bugfix: \luadisp{dofile} with
+        \luadisp{kpse.find\_file}
         \item docs: document option \option{fragile}
       \end{itemize}
-  \item[v. 0.12.1:]  2022-10-19
+  \versitem[0.12.1:]  2022-10-19
       \begin{itemize}
-        \item bugfix for \verb|\begin{enumerate}[<+->]|
+        \item bugfix for \lstinline|\begin{enumerate}[<+->]|
       \end{itemize}
-  \item[v. 0.12:]  2022-09-02
+  \versitem[0.12:]  2022-09-02
       \begin{itemize}
         \item new option \option{beamerwithfootline}
       \end{itemize}
-  \item[v. 0.11:]  2022-02-11
+  \versitem[0.11:]  2022-02-11
       \begin{itemize}
         \item Local references and the subex counter
         \item Lua interface (not documented yet, see example and example file)
         \item Framed solutions can now be fragile, however this
-        also require Lua\LaTeX (but not using the Lua Interface).
+        also requires Lua\LaTeX (but not using the Lua Interface).
         \item beamer version is now included (no separate package)
         \item some bug fixes
       \end{itemize}
-- 
cgit v1.2.3

