v.0.15: solutions headers, sectioning and html compatibility0.15

1 files changed, 129 insertions, 69 deletions

diff --git a/exercisesheets.tex b/exercisesheets.tex
index c41250f..68636f9 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.14, \printdateTeX{2023/02/06}}
+\date{Version 0.15, \printdateTeX{2023/11/30}}
 
 \begin{document}
 \maketitle
@@ -64,10 +64,10 @@ finally combined into this package. Starting from Version 0.7, there was an alte
 
 
 \subsection*{Licence}
-Copyright \textcopyright{} 2008--2022 Sebastian Kuhnert and Frank Fuhlbrück.
+Copyright \textcopyright{} 2008--2023 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 
+package is maintained, the Current Maintainer is
 Frank Fuhlbrück
 \footnote{\href{mailto:frank@fuhlbrueck.net}{frank@fuhlbrueck.net}}.
 
@@ -174,32 +174,32 @@ The following options are available:
  \item[\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 
-  directory containing exercises to be included via 
+  This option exploits (and partially breaks) RTL-Support.
+ \item[\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
   enumerate item labels for the first four levels, starting with
-  a), b) etc. for the top-level (sub-exercises). Depending on other 
+  a), b) etc. for the top-level (sub-exercises). Depending on other
   loaded packages (\verb|enumitem|, \verb|paralist|) the mechanism
   slightly differs. This option is active by default.
-  
- \item[\option{showtodos} / \option{hidetodos}] 
+
+ \item[\option{showtodos} / \option{hidetodos}]
   \verb|\TODO| markers
-  are hidden by default, this option switches their behavior. This 
-  option is usually set within \verb|\ifsamplesolutions| or 
+  are hidden by default, this option switches their behavior. This
+  option is usually set within \verb|\ifsamplesolutions| or
   similar.
- \item[\option{beamercompatibility}\opt{=\param{true/false}}] 
+ \item[\option{beamercompatibility}\opt{=\param{true/false}}]
   This options (which only is effective in the non-beamer version)
-  defines several beamer macros with as trivial 
+  defines several beamer macros with as trivial
   effects as possible, e.g., \verb|\pause| becomes \verb|\relax|
-  and overlay specifications are mostly ignored. Be careful to use 
-  this option after loading \verb|enumitem| etc. as the enumerate 
-  and itemize environment are defined to swallow overlay 
+  and overlay specifications are mostly ignored. Be careful to use
+  this option after loading \verb|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.
-  The current list of redefinitions is as 
+  The current list of redefinitions is as
   follows:
 \begin{lstlisting}
   \let\pause\relax
@@ -225,11 +225,11 @@ The following options are available:
     \@ifnextchar[\exsh@ovrlenumerate\exsh@origenumerate}
 \end{lstlisting}
 
-\item[\option{filenameasexercisename}\opt{=\param{true/false}}] 
-This option (set to false by default) causes 
+\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 
+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.
@@ -261,7 +261,7 @@ There is also a related option:
  \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
- exercisesheets-baemer uses this for the footline, while 
+ exercisesheets-baemer uses this for the footline, while
  \option{author} is used for the headline.
 \end{description}
 
@@ -288,14 +288,14 @@ The following \param{options} are supported:
   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}}] 
-  Directly set the sheet title. When this option is used, different 
+ \item[\option{title=\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}}}]   
+ \item[\option{number within sheet\opt{=\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 
+  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.
@@ -307,10 +307,10 @@ The following \param{options} are supported:
   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}}}] 
+ \item[\option{beamerwithfootline\opt{=\param{true/false}}}]
  The same for the footer.
- \item[\option{beameruseblocks\opt{=\param{true/false}}}] 
- Controls whether the exercise title is shown inside a 
+ \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.
@@ -349,17 +349,17 @@ supported:
   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 
+ \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
-  \option{oral}. The value \param{sum} displays the sum of all 
-  occurrences of \verb|\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 
+  \option{oral}. The value \param{sum} displays the sum of all
+  occurrences of \verb|\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
   subexercise. Points can be summed up also during a single pass
-  by using the Lua interface. 
+  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
@@ -377,22 +377,22 @@ supported:
  \item[\option{sample}] Include this exercise (and its solution) in while compiling
  sample solutions.
  \item[\option{beamersolution}] For beamer variant only. If this option
- is set all normal solutions will not be included and only 
+ 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 
+ \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 
- option is especially helpful if you provide your own definitions 
+ 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
+ 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| 
+ for non-beamer compilation. \verb|\newframe|
  is already defined as \verb|\relax| in  non-beamer \exsh,
  even without invoking \option{beamercompatibility}.
  \item[\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|
  etc. is done via Lua\LaTeX. Thus Lua\LaTeX is required
- (and this requires font setup via fontspec etc.), but 
+ (and this requires font setup via fontspec etc.), but
  you do not have to use any Lua code yourself. Mostly useful
  for listings and other verbatim stuff within solutions.
 \end{description}
@@ -411,13 +411,13 @@ environment.
 \includeexercise*(*\param{file name}*)
 \end{lstlisting}
 
-Both load the exercise from exercisespath/\param{file name}. Note 
-that the exercise environment must be contained in the file. The 
+Both load the exercise from exercisespath/\param{file name}. Note
+that the exercise environment must be contained in the file. The
 starred version is helpful for faster skipping of unused exercises.
 In this case, the file is not opened to search for labels. Whenever
 the exercise is not skipped and you use the starred version and also
-use labels within the exercise file, \exsh outputs an error. This is 
-done to ensure that references are not overlooked when the exercise 
+use labels within the exercise file, \exsh outputs an error. This is
+done to ensure that references are not overlooked when the exercise
 is actually skipped later.
 
 \subsection{Including Hints}
@@ -463,19 +463,19 @@ TODO markers (s.a.) the warning will be issued nevertheless.
 \end{lstlisting}
 
 \subsection{Explicitly Stating Tasks}
-In principle, \exsh aims to be very lightweight and there is not 
+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 
+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 
+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|
 (this shows noting if not compiled with beamer). There is also
-a starred version (\verb|\restatetask*| / 
+a starred version (\verb|\restatetask*| /
 \verb|\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
@@ -483,7 +483,7 @@ a subtask instead of the main task. This argument is either
 \option{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). 
+beamer).
 
 
 
@@ -505,7 +505,7 @@ beamer).
       \end{solution}
     \subtask{B is true}
       \begin{solution}[framed]
-        We already know: \restatestask[1] and 
+        We already know: \restatestask[1] and
         \restatestask[2], therefore B is also true.
       \end{solution}
   \end{subtasks}
@@ -516,14 +516,14 @@ beamer).
 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 
+\verb|\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
 normal label that is not redefined to produce an error.
 Furthermore, we define a counter \verb|subex| (which is
 currently just an alias for enumi, but this might change). You can
-use this counter (alias) with common commands like 
+use this counter (alias) with common commands like
 \verb|\arabic| or \verb|\alph|.
 
 \begin{lstlisting}
@@ -546,7 +546,7 @@ use this counter (alias) with common commands like
 
 \subsection{Setting Options}
 
-Options can be given at different places. 
+Options can be given at different places.
 \begin{enumerate}
  \item As local options to one of the environments.
  \item As package options: This is convenient for global options but suffers
@@ -658,7 +658,7 @@ values:
   Default: \verb|\ifdef{\color}{\color{red}}{}\bfseries|
 \end{description}
 
-\subsection{Controlling the Spacing and Page Handling}
+\subsection{Controlling the Spacing, Page Handling and Separations between Elements}
 
 The following options allow fine-tuning of the spacing:
 \begin{description}
@@ -702,6 +702,46 @@ at the end of each sheet:
   Default: \texttt{\string\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|
+\end{description}
+
+\subsection{Controlling the Sectioning (beta)}
+
+By default, exercises are sections and sheets are parts. They use
+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
+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
+\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
+ called only in one place in the following way:
+ \verb|\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
+ 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
+ be incremented wit every exercise (usually within each sheet).
+  Default: \verb|section|
+\end{description}
+
 \subsection{Special Code for Solutions}
 \begin{lstlisting}
 \ifsolutions{(*\param{if true}*)}{(*\param{if false}*)}
@@ -754,7 +794,7 @@ 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}}] 
+ \item[\option{custom skip macro=\param{macro}}]
 \end{description}
 
 If an exercise is not printed, some macros like \texttt{\string\label{}}
@@ -762,7 +802,7 @@ 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 
+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
@@ -793,9 +833,9 @@ Example:
 \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 
+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
 
@@ -834,14 +874,34 @@ If you leave out the \option{solutions} option in you main file, running
 solutions and \texttt{pdflatex solutions.tex} will create \texttt{solutions.pdf}
 with solutions.
 
-This also works well in combination with a make file that generates 
-\texttt{solutions.tex}.
+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}.
 
 \section{Changelog}
 \label{sec:changelog}
 
 \begin{itemize}
+    \item[v. 0.15:]  2023-11-30
+      \begin{itemize}
+        \item new option \option{solution title separator}
+        (initially set to\verb|:\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
+        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|).
+      \end{itemize}
     \item[v. 0.14:]  2023-02-06
       \begin{itemize}
         \item new option \option{headerrestate} to restate
@@ -861,7 +921,7 @@ This also works well in combination with a make file that generates
         \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 \verb|\restatestask| 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
@@ -886,7 +946,7 @@ This also works well in combination with a make file that generates
       \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 
+        \item Framed solutions can now be fragile, however this
         also require Lua\LaTeX (but not using the Lua Interface).
         \item beamer version is now included (no separate package)
         \item some bug fixes
@@ -896,9 +956,9 @@ This also works well in combination with a make file that generates
 
 \end{document}
 
-%%% Local Variables: 
+%%% Local Variables:
 %%% mode: latex
 %%% TeX-master: t
-%%% End: 
+%%% End:
 
 %%% Local IspellDict: british