summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/xsim/doc
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/xsim/doc
Initial commit
Diffstat (limited to 'macros/latex/contrib/xsim/doc')
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.blanks.pdfbin0 -> 29952 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.blanks.tex23
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.boxed-headings.pdfbin0 -> 38376 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.boxed-headings.tex30
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.code-and-output.pdfbin0 -> 30541 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.code-and-output.tex53
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.collections.pdfbin0 -> 33206 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.collections.tex62
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.crossref.pdfbin0 -> 38749 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.crossref.tex60
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.description-list.pdfbin0 -> 41167 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.description-list.tex42
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.different-point-types.pdfbin0 -> 42153 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.different-point-types.tex52
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.difficulties.pdfbin0 -> 31555 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.difficulties.tex53
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.floating.pdfbin0 -> 37708 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.floating.tex50
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.golatex-80640.pdfbin0 -> 46308 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.golatex-80640.tex131
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.golatex-91339.pdfbin0 -> 65379 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.golatex-91339.tex94
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.grade-distribution.pdfbin0 -> 23204 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.grade-distribution.tex56
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.hints.pdfbin0 -> 45719 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.hints.tex59
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.listings.pdfbin0 -> 45738 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.listings.tex48
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.listofexercises.pdfbin0 -> 57220 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.listofexercises.tex81
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.multiplechoice.pdfbin0 -> 31016 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.multiplechoice.tex70
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.pointsums.pdfbin0 -> 28127 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.pointsums.tex30
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.randomexercises.pdfbin0 -> 23102 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.randomexercises.tex58
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-13635.pdfbin0 -> 86047 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-13635.tex70
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-155630.pdfbin0 -> 20045 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-155630.tex26
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-199360.pdfbin0 -> 56153 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-199360.tex60
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-299534.pdfbin0 -> 48094 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-299534.tex32
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-305110.pdfbin0 -> 36968 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-305110.tex67
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-308883.pdfbin0 -> 27155 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-308883.tex13
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-338165.pdfbin0 -> 56889 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-338165.tex72
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-350028.pdfbin0 -> 95065 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-350028.tex135
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-369065.pdfbin0 -> 65721 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-369065.tex77
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-369636.pdfbin0 -> 46504 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-369636.tex46
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-369803.pdfbin0 -> 55079 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-369803.tex50
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-370642.pdfbin0 -> 28426 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-370642.tex25
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-391530.pdfbin0 -> 25040 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-391530.tex67
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-395273.pdfbin0 -> 50580 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texsx-395273.tex74
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texwelt-15093.pdfbin0 -> 36256 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texwelt-15093.tex133
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texwelt-6698.pdfbin0 -> 43899 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.texwelt-6698.tex86
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.various.pdfbin0 -> 86646 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/examples/xsim.various.tex237
-rw-r--r--macros/latex/contrib/xsim/doc/xsim-manual.cls822
-rw-r--r--macros/latex/contrib/xsim/doc/xsim.history113
-rw-r--r--macros/latex/contrib/xsim/doc/xsim.ideas31
-rw-r--r--macros/latex/contrib/xsim/doc/xsim_manual.pdfbin0 -> 1163299 bytes
-rw-r--r--macros/latex/contrib/xsim/doc/xsim_manual.tex2288
75 files changed, 5576 insertions, 0 deletions
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.blanks.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.blanks.pdf
new file mode 100644
index 0000000000..dd26d67157
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.blanks.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.blanks.tex b/macros/latex/contrib/xsim/doc/examples/xsim.blanks.tex
new file mode 100644
index 0000000000..b479e961c2
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.blanks.tex
@@ -0,0 +1,23 @@
+\documentclass{article}
+\usepackage[utf8]{inputenc}
+\usepackage[ngerman]{babel}
+
+\usepackage{xsim,lipsum,xcolor}
+
+\xsimsetup{
+ solution/print = true ,
+ blank/filled-style = \underline{\textcolor{red}{#1}}
+}
+
+\begin{document}
+
+\begin{exercise}[points=3]
+ Erklären Sie den Begriff.
+
+ \blank[width=4\linewidth,linespread=1.5]{}
+\end{exercise}
+\begin{solution}
+ \blank[width=4\linewidth,linespread=1.5]{Die Lösung hier soll rot sein.}
+\end{solution}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.boxed-headings.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.boxed-headings.pdf
new file mode 100644
index 0000000000..99ba5bbc2a
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.boxed-headings.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.boxed-headings.tex b/macros/latex/contrib/xsim/doc/examples/xsim.boxed-headings.tex
new file mode 100644
index 0000000000..9ff47d9d99
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.boxed-headings.tex
@@ -0,0 +1,30 @@
+\documentclass{article}
+
+\usepackage{tcolorbox}
+\usepackage{xsim}
+\usepackage{needspace}
+
+\DeclareExerciseEnvironmentTemplate{custom}
+ {%
+ \Needspace*{5\baselineskip}
+ \begin{tcolorbox}
+ \textbf{\XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}.}%
+ \GetExercisePropertyT{subtitle}{ \textit{#1}}%
+ \end{tcolorbox}
+ \noindent
+ }
+ {\vspace{\baselineskip}}
+
+\xsimsetup{exercise/template = custom}
+
+\usepackage{lipsum}
+
+\begin{document}
+
+\begin{exercise}[subtitle=Foo bar baz]
+ \lipsum[1]
+\end{exercise}
+
+\lipsum[2]
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.code-and-output.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.code-and-output.pdf
new file mode 100644
index 0000000000..bbbcfbc18a
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.code-and-output.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.code-and-output.tex b/macros/latex/contrib/xsim/doc/examples/xsim.code-and-output.tex
new file mode 100644
index 0000000000..f753f13939
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.code-and-output.tex
@@ -0,0 +1,53 @@
+\documentclass{article}
+\usepackage{xsimverb,listings,xcolor}
+
+\lstdefinestyle{mystyle}{
+ language = [AlLaTeX]TeX ,
+ basicstyle = \ttfamily ,
+ columns = fullflexible ,
+ commentstyle = \color{gray!70} ,
+ keywordstyle = \color{red!70!black}
+}
+
+\makeatletter
+\NewDocumentEnvironment{example}{o}
+ {%
+ \XSIMgobblechars{2}%
+ \XSIMsetfilebegin{\@percentchar\space file `\jobname.tmp'}%
+ \XSIMsetfileend{\@percentchar\space bye bye}%
+ \IfNoValueTF{#1}
+ {\XSIMfilewritestart*{\jobname.tmp}}
+ {\XSIMfilewritestart{\jobname.tmp}}%
+ }
+ {%
+ \XSIMfilewritestop
+ \lstinputlisting[style=mystyle]{\jobname.tmp}%
+ \input{\jobname.tmp}
+ }
+
+\NewDocumentEnvironment{code}{o}
+ {%
+ \XSIMgobblechars{2}%
+ \IfNoValueTF{#1}
+ {\XSIMfilewritestart*{\jobname.tmp}}
+ {\XSIMfilewritestart{\jobname.tmp}}%
+ }
+ {%
+ \XSIMfilewritestop
+ \lstinputlisting[style=mystyle]{\jobname.tmp}%
+ }
+\makeatother
+
+\begin{document}
+
+\begin{example}
+ bla bla \LaTeX
+\end{example}
+
+\bigskip
+
+\begin{code}
+ blubber \LaTeX
+\end{code}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.collections.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.collections.pdf
new file mode 100644
index 0000000000..fd785cc057
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.collections.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.collections.tex b/macros/latex/contrib/xsim/doc/examples/xsim.collections.tex
new file mode 100644
index 0000000000..beca191005
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.collections.tex
@@ -0,0 +1,62 @@
+\documentclass{article}
+\usepackage{xsim}
+
+\DeclareExerciseCollection{foo-easy}
+\DeclareExerciseCollection{foo-medium}
+\DeclareExerciseTagging{difficulty}
+
+\usepackage{filecontents,lipsum}
+\begin{filecontents*}{foo.tex}
+\begin{exercise}[difficulty=easy,points=1]
+ foo one \lipsum[4]
+\end{exercise}
+\begin{solution}
+ foo one \lipsum[4]
+\end{solution}
+\begin{exercise}[difficulty=medium,points=1]
+ foo two \lipsum[4]
+\end{exercise}
+\begin{solution}
+ foo two \lipsum[4]
+\end{solution}
+\begin{exercise}[difficulty=easy,points=1]
+ foo three \lipsum[4]
+\end{exercise}
+\begin{solution}
+ foo three \lipsum[4]
+\end{solution}
+\end{filecontents*}
+
+\begin{document}
+
+\begin{exercise}
+ outside before
+\end{exercise}
+
+\collectexercises{foo-easy}
+\xsimsetup{difficulty=easy}
+\input{foo.tex}
+\collectexercisesstop{foo-easy}
+% collection `foo-easy' now contains all exercises of file `foo.tex' tagged
+% with `difficulty=easy'
+
+\collectexercises{foo-medium}
+\xsimsetup{difficulty=medium}
+\input{foo.tex}
+\collectexercisesstop{foo-medium}
+% collection `foo-medium' now contains all exercises of file `foo.tex'
+% tagged with `difficulty=medium'
+
+\section{Easy}
+\printcollection{foo-easy}
+
+\section{Medium}
+\printcollection{foo-medium}
+
+\printsolutions[difficulty=medium]
+
+\section{All Exercises and Their Solutions Again, in Order of Appearance}
+
+\printcollection[print=both]{all exercises}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.crossref.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.crossref.pdf
new file mode 100644
index 0000000000..8151a0cef3
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.crossref.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.crossref.tex b/macros/latex/contrib/xsim/doc/examples/xsim.crossref.tex
new file mode 100644
index 0000000000..fa2fbbb509
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.crossref.tex
@@ -0,0 +1,60 @@
+\documentclass{article}
+\usepackage{xsim,lipsum,hyperref}
+
+\DeclareExerciseHeadingTemplate{custom}
+ {\section{\XSIMtranslate{default-heading}}}
+
+\DeclareExerciseEnvironmentTemplate{custom}
+ {%
+ \IfInsideSolutionTF
+ {\label{sol:\ExerciseID}}
+ {\label{ex:\ExerciseID}}
+ \subsection*
+ {%
+ \XSIMmixedcase{\GetExerciseName}%
+ \IfInsideSolutionTF
+ {
+ to \GetExerciseParameter{exercise-name}%
+ ~\GetExerciseProperty{counter}%
+ }
+ {%
+ ~\GetExerciseProperty{counter}
+ \GetExercisePropertyT{subtitle}
+ { {\normalfont\itshape\PropertyValue}}%
+ }%
+ }
+ \noindent\llap{%
+ \footnotesize\sffamily
+ \IfInsideSolutionTF
+ {%
+ \XSIMmixedcase{\GetExerciseParameter{exercise-name}}
+ on page~\pageref{ex:\ExerciseID}.%
+ }
+ {%
+ \XSIMmixedcase{\GetExerciseParameter{solution-name}}
+ on page~\pageref{sol:\ExerciseID}.%
+ }%
+ \hspace*{\marginparsep}%
+ }%
+ }
+ {}
+\xsimsetup{
+ exercise/template = custom ,
+ solution/template = custom ,
+ print-solutions/headings-template = custom
+}
+
+\begin{document}
+
+\section{Exercises}
+\begin{exercise}
+ \lipsum[4]
+\end{exercise}
+\begin{solution}
+ \lipsum[4]
+\end{solution}
+
+\clearpage
+\printsolutions
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.description-list.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.description-list.pdf
new file mode 100644
index 0000000000..d506ad960b
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.description-list.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.description-list.tex b/macros/latex/contrib/xsim/doc/examples/xsim.description-list.tex
new file mode 100644
index 0000000000..f3c9ed6d74
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.description-list.tex
@@ -0,0 +1,42 @@
+\documentclass{article}
+\usepackage{xsim,lipsum}
+
+\DeclareExerciseEnvironmentTemplate{item}
+ {\item[\XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}]}
+ {}
+\xsimsetup{
+ exercise/template=item,
+ solution/template=item,
+ print-solutions/headings-template=none
+}
+
+\newenvironment{exercises}
+ {\section{Exercises}\description}
+ {\enddescription}
+
+\newenvironment{solutions}
+ {\section{Solutions}\description}
+ {\enddescription}
+
+\begin{document}
+
+\begin{exercises}
+ \begin{exercise}
+ \lipsum[4]
+ \end{exercise}
+ \begin{solution}
+ \lipsum[3]
+ \end{solution}
+ \begin{exercise}
+ \lipsum[12]
+ \end{exercise}
+ \begin{solution}
+ \lipsum[23]
+ \end{solution}
+\end{exercises}
+
+\begin{solutions}
+ \printsolutions
+\end{solutions}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.different-point-types.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.different-point-types.pdf
new file mode 100644
index 0000000000..b1de5d6325
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.different-point-types.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.different-point-types.tex b/macros/latex/contrib/xsim/doc/examples/xsim.different-point-types.tex
new file mode 100644
index 0000000000..0ac3536776
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.different-point-types.tex
@@ -0,0 +1,52 @@
+\documentclass{article}
+\usepackage{xsim}
+
+\DeclareExerciseGoal{A}
+\DeclareExerciseGoal{C}
+\DeclareExerciseGoal{E}
+
+\newcommand*\printA{\TotalExerciseGoal{A}{~A~point}{~A~points}}
+\newcommand*\printC{\TotalExerciseGoal{C}{~C~point}{~C~points}}
+\newcommand*\printE{\TotalExerciseGoal{E}{~E~point}{~E~points}}
+
+\usepackage{needspace}
+\DeclareExerciseEnvironmentTemplate{custom}
+ {%
+ \par\vspace{\baselineskip}
+ \Needspace*{2\baselineskip}
+ \noindent
+ \textbf{\GetExerciseProperty{counter}}%
+ \IfExercisePropertySetT{subtitle}
+ { \textit{\GetExerciseProperty{subtitle}}} %
+ \IfInsideSolutionF{%
+ \marginpar{%
+ (\IfExercisePropertySetTF{E}{\GetExerciseProperty{E}}{0}/%
+ \IfExercisePropertySetTF{C}{\GetExerciseProperty{C}}{0}/%
+ \IfExercisePropertySetTF{A}{\GetExerciseProperty{A}}{0})%
+ }%
+ }%
+ }
+ {}
+\xsimsetup{
+ exercise/template = custom ,
+ solution/template = custom
+}
+\renewcommand*\theexercise{\arabic{exercise}.}
+
+\begin{document}
+
+Reachable: \printA, \printC, and \printE.
+
+\begin{exercise}[E=1]
+ Differentiate $y=3x^2+5x+3$.
+\end{exercise}
+
+\begin{exercise}[E=2,C=1]
+ Find the equation of the tangent line to the function $y=x/2$ at $x=2$.
+\end{exercise}
+
+\begin{exercise}[C=1,A=2]
+ Prove that the derivative of a constant is zero.
+\end{exercise}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.difficulties.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.difficulties.pdf
new file mode 100644
index 0000000000..846f19e201
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.difficulties.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.difficulties.tex b/macros/latex/contrib/xsim/doc/examples/xsim.difficulties.tex
new file mode 100644
index 0000000000..02712f15d6
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.difficulties.tex
@@ -0,0 +1,53 @@
+\documentclass{article}
+
+\usepackage[clear-aux]{xsim}
+\DeclareExerciseTagging{difficulty}
+\xsimsetup{
+ difficulty={easy,hard}
+}
+
+\DeclareExerciseEnvironmentTemplate{custom}
+ {
+ \subsection*
+ {%
+ \XSIMmixedcase {\GetExerciseName}\nobreakspace
+ \GetExerciseProperty{counter}%
+ \IfExercisePropertySetT{difficulty}
+ { {\normalfont(\GetExerciseProperty{difficulty})}}%
+ \IfInsideSolutionF{%
+ \IfExercisePropertySetT{subtitle}
+ { {\normalfont\itshape\GetExerciseProperty{subtitle}}}%
+ }%
+ }%
+ \IfExercisePropertySetT{points}
+ {%
+ \marginpar
+ {%
+ \IfInsideSolutionF{\rule{1.2cm}{1pt}\slash}%
+ \GetExerciseProperty{points}%
+ \IfExercisePropertySetT{bonus-points}
+ {\nobreakspace(+\GetExerciseProperty{bonus-points})}
+ \nobreakspace\XSIMtranslate{point-abbr}%
+ }%
+ }%
+ }
+ {}
+
+\xsimsetup{exercise/template = custom}
+
+\begin{document}
+
+\begin{exercise}[difficulty=easy]
+ An easy question.
+\end{exercise}
+\begin{exercise}[difficulty=medium]
+ This one's a bit harder.
+\end{exercise}
+\begin{exercise}[difficulty=hard]
+ Now let’s see if you can solve this one.
+\end{exercise}
+\begin{exercise}[difficulty=medium]
+ This is medium but printed anyway
+\end{exercise}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.floating.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.floating.pdf
new file mode 100644
index 0000000000..e2e96537ef
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.floating.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.floating.tex b/macros/latex/contrib/xsim/doc/examples/xsim.floating.tex
new file mode 100644
index 0000000000..08448df35a
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.floating.tex
@@ -0,0 +1,50 @@
+% floating exercises:
+\documentclass{article}
+\usepackage{xsim,newfloat,caption,lipsum}
+
+\DeclareFloatingEnvironment[
+ fileext=loe,
+ listname={List of Exercises},
+ name=Exercise,
+ placement=htp,
+]{ex}
+
+\DeclareExerciseEnvironmentTemplate{float}
+ {%
+ \ex
+ \captionsetup{labelformat=empty,singlelinecheck=false,listformat=empty}
+ \IfExercisePropertySetTF{subtitle}{%
+ \XSIMexpandcode{%
+ \noexpand\caption{%
+ \noexpand\textbf{%
+ \XSIMmixedcase{\GetExerciseName}\nobreakspace
+ \GetExerciseProperty{counter}%
+ }: \GetExerciseProperty{subtitle}%
+ }%
+ }%
+ }{%
+ \caption{%
+ \textbf{%
+ \XSIMmixedcase{\GetExerciseName}\nobreakspace
+ \GetExerciseProperty{counter}%
+ }%
+ }%
+ }%
+ }
+ {\endex}
+
+\xsimsetup{exercise/template = float}
+
+\begin{document}
+
+\listofexs
+
+\begin{exercise}
+ \lipsum[4]
+\end{exercise}
+
+\begin{exercise}[subtitle=Let's have a look]
+ \lipsum[4]
+\end{exercise}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.golatex-80640.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.golatex-80640.pdf
new file mode 100644
index 0000000000..76cf1617cb
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.golatex-80640.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.golatex-80640.tex b/macros/latex/contrib/xsim/doc/examples/xsim.golatex-80640.tex
new file mode 100644
index 0000000000..5ccdff63a4
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.golatex-80640.tex
@@ -0,0 +1,131 @@
+% http://golatex.de/viewtopic,p,80640.html
+\documentclass[fontsize=12pt,parskip=half]{scrartcl}
+\usepackage[utf8]{inputenc}
+\usepackage[T1]{fontenc}
+\usepackage[ngerman]{babel}
+
+\newlength\breite
+\setlength\breite{160mm}
+\newlength\hoehe
+\setlength\hoehe{80mm}
+
+\usepackage[
+ hdivide={3.0cm,\breite,},
+ vdivide={2.2cm,,2.2cm}]{geometry}
+\usepackage[bitstream-charter]{mathdesign}
+
+\usepackage[babel]{microtype}
+
+\usepackage[inline]{enumitem}
+
+\usepackage{amsmath,siunitx}
+\sisetup{
+ locale = DE ,
+ per-mode = fraction
+}
+
+\usepackage{xsim,needspace,tikz,tcolorbox}
+
+\xsimsetup{
+ exercise/template = gitter ,
+ solution/template = gitter
+}
+
+\DeclareExerciseEnvironmentTemplate{gitter}
+ {%
+ \IfInsideSolutionT{%
+ \tcolorbox[
+ detach title ,
+ title = Lösung: ,
+ before upper = {\tcbtitle\space} ,
+ fonttitle = \bfseries ,
+ fontupper = \large ,
+ valign = center ,
+ colframe = black!50!white ,
+ colback = black!12!white ,
+ coltext = blue ,
+ coltitle = blue ,
+ height = \hoehe ,
+ width = \breite ,
+ sharp corners
+ ]
+ }%
+ }
+ {%
+ \IfInsideSolutionTF
+ {\endtcolorbox}
+ {%
+ \IfSolutionPrintF{%
+ \par
+ \begin{tikzpicture}[semitransparent]
+ \draw[step=4mm, line width=0.15mm, black!60!white] (0,0) grid
+ (\breite,\hoehe);
+ \end{tikzpicture}
+ \par
+ }
+ }%
+ }
+
+\begin{document}
+
+\begin{exercise}
+ Für die \textbf{Schülerausgabe} sollen Häuschen (Grid) mit Seitenlänge
+ \SI{4}{\mm} gesetzt werden.
+\end{exercise}
+\begin{solution}
+ Hier soll die Lösung stehen: $E=m\cdot c^2$.
+\end{solution}
+
+\xsimsetup{solution/print=true}
+
+\begin{exercise}
+ Für die \textbf{Lehrerausgabe} sollen statt Häuschen die Lösung in
+ z.\,B. einer Box geschrieben werden. Dafür soll die Lösung (bezogen auf
+ dieses Beispiel) auch in einer Box mit der exakten Breite \SI{160}{\mm} und
+ der exakten Höhe \SI{80}{\mm} gesetzt werden. Weiter soll natürlich die
+ Position der Lösungsbox und der Häuschenbox exakt identisch sein.
+\end{exercise}
+\begin{solution}
+ Hier soll die Lösung stehen: $E=m\cdot c^2$.
+\end{solution}
+
+\clearpage
+
+\begin{exercise}
+ Beschreiben Sie die \textbf{Satzgruppe des Pythagoras}.
+\end{exercise}
+\begin{solution}
+ \begin{align*}
+ \left.\begin{aligned}
+ c^2 &=a^2+b^2\\
+ a^2 &=p\cdot c\;\wedge\; b^2=q\cdot c\\
+ h^2 &=p\cdot q
+ \end{aligned}\right\}
+ \begin{gathered}
+ \text{Satzgruppe}\\
+ \text{des Pythagoras}
+ \end{gathered}
+ \end{align*}
+\end{solution}
+
+\begin{exercise}
+ Geben Sie die Formel der \textbf{gleichförmigen Bewegung} wieder. Gehen Sie
+ davon aus, dass Sie 1000~Meter in
+ \SI[parse-numbers=false]{3\frac{1}{2}}{Minuten} laufen.
+ \begin{enumerate*}[label=\bfseries\alph*)]
+ \item Mit welcher Geschwindigkeit legen Sie die Strecke zurück?
+ \item Geben Sie die Geschwindigkeit in \si{\km\per\hour} an.
+ \end{enumerate*}
+ \textbf{Hinweis:} Nehmen Sie zur Berechnung die vereinfachte Form und gehen
+ Sie davon aus, dass Ihre Geschwindigkeit konstant ist.
+\end{exercise}
+\begin{solution}
+ \begin{align*}
+ s &=v\cdot t+s_0 \\
+ 1000 &=v\cdot 210 \\
+ v &=\frac{\SI{1000}{\m}}{\SI{210}{\second}} \\
+ v &=\SI{4.76}{\m\per\second} = \SI{17.1}{\km\per\hour}
+ \end{align*}
+\end{solution}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.golatex-91339.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.golatex-91339.pdf
new file mode 100644
index 0000000000..97cb4659e0
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.golatex-91339.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.golatex-91339.tex b/macros/latex/contrib/xsim/doc/examples/xsim.golatex-91339.tex
new file mode 100644
index 0000000000..8ae03971c5
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.golatex-91339.tex
@@ -0,0 +1,94 @@
+% http://golatex.de/viewtopic,p,91339.html
+\documentclass[18pt,a4paper]{article}
+\usepackage[utf8]{inputenc}
+\usepackage[ngerman]{babel}
+
+\usepackage{xsim,tcolorbox}
+\usepackage{amsmath}
+\xsimsetup{
+ exercise/within = section ,
+ exercise/the-counter = \thesection.\arabic{exercise} ,
+ print-solutions/headings-template=none
+}
+\SetExerciseParameters{exercise}{
+ exercise-template = mine ,
+ solution-template = mine
+}
+
+\DeclareExerciseEnvironmentTemplate{mine}
+ {%
+ \tcolorbox[
+ % colors:
+ colback = white , colframe = black , coltitle = black ,
+ % rules:
+ boxrule = 0pt , toprule = 1pt , bottomrule = 1pt , arc = 0pt ,
+ % spacing:
+ boxsep = 0pt , left = 0pt , right = 0pt ,
+ % title:
+ detach title , before upper = \tcbtitle\par\noindent ,
+ fonttitle = \bfseries ,
+ title = \XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}
+ ]
+ }
+ {\endtcolorbox}
+
+\DeclareExerciseTranslation{German}{exercise}{Aufgabe}
+\DeclareExerciseTagging{difficulty}
+
+\begin{document}
+
+\section{Wellenausbreitung im Vakuum und in Materie}
+\subsection{Maxwellsche Gleichungen}
+
+\begin{align*}
+ \nabla \cdot \vec{E}\left(\vec{r}, t \right) =
+ \frac{\varrho\left(\vec{r}, t \right)}{\varepsilon_0}
+\end{align*}
+
+\begin{exercise}[difficulty=easy]
+Something stupid
+\end{exercise}
+\begin{solution}
+Here is a nonstupid solution for your problem
+\end{solution}
+
+\subsection{Empirischer Zugang zu Wellengleichungen}
+
+\begin{exercise}[difficulty=hard]
+Eine weitere Aufgabe
+\end{exercise}
+\begin{solution}
+Solution Number 2
+\end{solution}
+
+\subsection*{Lösungen}
+\printsolutions[section,difficulty=hard]
+
+\section{Wellenausbreitung im Vakuum und in Materie}
+\subsection{Maxwellsche Gleichungen}
+
+\begin{align*}
+ \nabla \cdot \vec{E}\left(\vec{r}, t \right) =
+ \frac{\varrho\left(\vec{r}, t \right)}{\varepsilon_0}
+\end{align*}
+
+\begin{exercise}[difficulty=easy]
+Something stupid
+\end{exercise}
+\begin{solution}
+Here is a nonstupid solution for your problem
+\end{solution}
+
+\subsection{Empirischer Zugang zu Wellengleichungen}
+
+\begin{exercise}[difficulty=hard]
+Eine weitere Aufgabe
+\end{exercise}
+\begin{solution}
+Solution Number 2
+\end{solution}
+
+\subsection*{Lösungen}
+\printsolutions[section]
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.grade-distribution.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.grade-distribution.pdf
new file mode 100644
index 0000000000..248358c4a1
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.grade-distribution.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.grade-distribution.tex b/macros/latex/contrib/xsim/doc/examples/xsim.grade-distribution.tex
new file mode 100644
index 0000000000..8e9731de24
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.grade-distribution.tex
@@ -0,0 +1,56 @@
+\documentclass{article}
+\usepackage{xsim}
+
+\xsimsetup{grades/split=;}
+
+\DeclareGradeDistribution{
+ 1 = 1 ;
+ 1,5 = .9167 ;
+ 2 = .8333 ;
+ 2,5 = .75 ;
+ 3 = .6667 ;
+ 3,5 = .5833 ;
+ 4 = .5
+}
+
+\begin{document}
+
+\begin{exercise}[points=4]
+\end{exercise}
+
+\begin{exercise}[points=4]
+\end{exercise}
+
+\begin{exercise}[points=4]
+\end{exercise}
+
+\begin{exercise}[points=4,bonus-points=10]
+\end{exercise}
+
+\begin{exercise}[points=4]
+\end{exercise}
+
+\begin{exercise}[points=4]
+\end{exercise}
+
+
+\goalsforgrade{points + bonus-points}{1,5}
+\goalsforgrade{points+bonus-points}{2}
+
+\pointsforgrade{1}
+\pointsforgrade{1,5}
+\pointsforgrade{2}
+\pointsforgrade{2,5}
+\pointsforgrade{3}
+\pointsforgrade{3,5}
+\pointsforgrade{4}
+
+\totalgoalforgrade{1}
+\totalgoalforgrade{1,5}
+\totalgoalforgrade{2}
+\totalgoalforgrade{2,5}
+\totalgoalforgrade{3}
+\totalgoalforgrade{3,5}
+\totalgoalforgrade{4}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.hints.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.hints.pdf
new file mode 100644
index 0000000000..a34fbd8f79
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.hints.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.hints.tex b/macros/latex/contrib/xsim/doc/examples/xsim.hints.tex
new file mode 100644
index 0000000000..10a0bffed9
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.hints.tex
@@ -0,0 +1,59 @@
+% https://tex.stackexchange.com/q/224408/
+\documentclass{article}
+\usepackage{xsim}
+
+\usepackage{needspace}
+
+\DeclareExerciseProperty{hint}
+
+% we'll use a description list for the hints:
+\newcommand\printhints{%
+ \begin{description}
+ \ForEachUsedExerciseByType{%
+ \def\ExerciseType{##1}%
+ \def\ExerciseID{##2}%
+ \GetExercisePropertyT{hint}
+ {%
+ \item[\XSIMmixedcase{\GetExerciseName}~##3]
+ ####1%
+ }%
+ }%
+ \end{description}
+}
+
+\newcommand\hint[1]{\SetExerciseProperty{hint}{#1}}
+
+\begin{document}
+
+\section{Problems}
+% set hint through option:
+\begin{exercise}[subtitle=Pythagoras,hint=This is a hint to the first problem.]
+ This is the first problem.
+\end{exercise}
+\begin{solution}
+ This is the solution to the first problem.
+\end{solution}
+
+\begin{exercise}[subtitle=Another Problem]
+ This is the second problem.
+\end{exercise}
+\begin{solution}
+ This is the solution to the second problem.
+\end{solution}
+
+% set hint with custom command:
+\begin{exercise}[subtitle=Yet Another Problem]
+ This is the third problem.
+ \hint{This is a hint to the third problem.}
+\end{exercise}
+\begin{solution}
+ This is the solution to the third problem.
+\end{solution}
+
+\section{Hints}
+\printhints
+
+\section{Solutions}
+\printsolutions[headings=false]
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.listings.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.listings.pdf
new file mode 100644
index 0000000000..0d388f2c70
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.listings.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.listings.tex b/macros/latex/contrib/xsim/doc/examples/xsim.listings.tex
new file mode 100644
index 0000000000..6dd302feb0
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.listings.tex
@@ -0,0 +1,48 @@
+% http://tex.stackexchange.com/questions/131546/
+\documentclass{article}
+
+\usepackage{xcolor}
+\usepackage{listings}
+\usepackage{xsim}
+
+\lstset{
+ frame=single,
+ xleftmargin=20pt,
+ numbers=left,
+ numberstyle=\small,
+ tabsize=2,
+ breaklines,
+ showspaces=false,
+ showstringspaces=false,
+ language=C,
+ basicstyle=\small\ttfamily,
+ commentstyle=\itshape\color{gray}
+}
+
+\begin{document}
+
+\begin{exercise}[points=6]
+Consider the following C program.
+\begin{lstlisting}
+#include <stdio.h>
+
+int main(int argc, char *argv[]) {
+ printf("hello, world\n");
+}
+\end{lstlisting}
+\end{exercise}
+\begin{solution}
+Consider the following C program.
+\begin{lstlisting}
+#include <stdio.h>
+
+int main(int argc, char *argv[]) {
+ printf("hello, world\n");
+}
+\end{lstlisting}
+\end{solution}
+
+\pagebreak
+\printsolutions
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.listofexercises.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.listofexercises.pdf
new file mode 100644
index 0000000000..8050ee8f90
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.listofexercises.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.listofexercises.tex b/macros/latex/contrib/xsim/doc/examples/xsim.listofexercises.tex
new file mode 100644
index 0000000000..c2a9a3fe36
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.listofexercises.tex
@@ -0,0 +1,81 @@
+% https://tex.stackexchange.com/q/94766/
+\documentclass[a4paper,10pt]{book}
+\usepackage[utf8]{inputenc}
+
+\usepackage{xsim}
+\xsimsetup{
+ exercise/within=chapter,
+ exercise/template=theorem ,
+ exercise/the-counter=\thechapter.\arabic{exercise}
+}
+
+\DeclareExerciseEnvironmentTemplate{theorem}
+ {%
+ \par\addvspace{\baselineskip}
+ \noindent
+ \XSIMexpandcode{\noexpand\label{\ExerciseType:\ExerciseID}}
+ \Large\textbf{%
+ \space\GetExerciseProperty{counter}%
+ \GetExercisePropertyT{subtitle}{ (\PropertyValue)}%
+ } \normalsize\itshape
+ }
+ {\par\addvspace{\baselineskip}}
+
+\usepackage{multicol}
+
+\newcommand\listofexercises{
+ \chapter*{List of Exercises}
+ \def\CurrentExerciseChapter{}%
+ \ForEachPrintedExerciseByType{
+ \global\let\LastExerciseChapter\CurrentExerciseChapter
+ \xdef\CurrentExerciseChapter{\ExercisePropertyGet{##1}{##2}{chapter}}%
+ \XSIMifeqF{\LastExerciseChapter}{\CurrentExerciseChapter}
+ {
+ \XSIMifblankF{\LastExerciseChapter}{\end{multicols}}
+ \begin{multicols}{2}%
+ [\contentsline{chapter}{Chapter \CurrentExerciseChapter}{}{}]
+ }
+ \contentsline
+ {section}
+ {%
+ Exercise \ExercisePropertyGet{##1}{##2}{counter}%
+ \XSIMifblankF{##4}{ (##4)}%
+ }
+ {\pageref{##1:##2}}{}%
+ }
+ \end{multicols}
+}
+
+% \usepackage{hyperref}
+% \newcommand\theHexercise{\thechapter.\arabic{exercise}}
+
+\begin{document}
+
+\chapter{kinetic}
+\begin{exercise}
+ 435-1
+\end{exercise}
+\begin{exercise}[subtitle=Foo Bar]
+ 435-2
+\end{exercise}
+\begin{exercise}
+ 435-3
+\end{exercise}
+
+\chapter{momentum}
+\begin{exercise}
+ 436-1
+\end{exercise}
+\begin{exercise}
+ 436-2
+\end{exercise}
+\begin{exercise}
+ 436-3
+\end{exercise}
+\begin{exercise}
+ 436-4
+\end{exercise}
+
+\listofexercises
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.multiplechoice.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.multiplechoice.pdf
new file mode 100644
index 0000000000..02dac6c4df
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.multiplechoice.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.multiplechoice.tex b/macros/latex/contrib/xsim/doc/examples/xsim.multiplechoice.tex
new file mode 100644
index 0000000000..e0db3eb0c5
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.multiplechoice.tex
@@ -0,0 +1,70 @@
+\documentclass{scrartcl}
+\usepackage[clear-aux]{xsim}
+
+\usepackage{enumitem,amssymb,fmtcount}
+\newlist{choices}{itemize}{1}
+\setlist[choices]{label=$\Box$}
+\newcommand*\choice{\item}
+
+\DeclareExerciseProperty{choices}
+\DeclareExerciseProperty*{multiple}
+\DeclareExerciseEnvironmentTemplate{mc}
+ {%
+ \UseExerciseTemplate{begin}{default}%
+ \IfExerciseBooleanPropertyTF{multiple}
+ {Select one or more correct answers}
+ {%
+ \GetExercisePropertyT{choices}
+ {Select \numberstringnum{#1} correct answer\ifnum#1>1 s\fi.}%
+ }%
+ \begin{choices}
+ }
+ {%
+ \end{choices}
+ \UseExerciseTemplate{end}{default}%
+ }
+
+\DeclareExerciseType{mc}{
+ exercise-env = multiplechoice ,
+ solution-env = correctchoices ,
+ exercise-name = Question ,
+ solution-name = Solution ,
+ exercise-template = mc ,
+ solution-template = mc ,
+ counter = exercise
+}
+
+\xsimsetup{
+ exercise/name = Question ,
+ solution/name = Solution
+}
+
+\begin{document}
+
+\section{Questions}
+\begin{multiplechoice}[choices=1]
+ \choice one
+ \choice two
+ \choice three
+ \choice four
+\end{multiplechoice}
+
+\begin{exercise}
+ Answer this question on a separate sheet.
+\end{exercise}
+
+\begin{multiplechoice}[multiple]
+ \choice one
+ \choice two
+ \choice three
+ \choice four
+\end{multiplechoice}
+
+\begin{multiplechoice}[choices=2]
+ \choice one
+ \choice two
+ \choice three
+ \choice four
+\end{multiplechoice}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.pointsums.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.pointsums.pdf
new file mode 100644
index 0000000000..aa822a1bd7
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.pointsums.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.pointsums.tex b/macros/latex/contrib/xsim/doc/examples/xsim.pointsums.tex
new file mode 100644
index 0000000000..29d7ac0cdc
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.pointsums.tex
@@ -0,0 +1,30 @@
+\documentclass{article}
+\usepackage{xsim,lipsum}
+
+\NewDocumentCommand\printcompletepoints{}{%
+ \TotalExerciseGoals{points + bonus-points}
+ {\,\XSIMtranslate{point}}
+ {\,\XSIMtranslate{points}}%
+}
+
+\NewDocumentCommand\pointsandbonus{}{%
+ \TotalExerciseGoal{points}{}{}%
+ \IfExerciseGoalsSumTF{bonus-points}{=0}
+ {}
+ {\,(+\,\TotalExerciseGoal{bonus-points}{}{})}%
+ \,\XSIMtranslate{points}%
+}
+
+\begin{document}
+
+\begin{exercise}[points=3,bonus-points=1]
+ \lipsum[4]
+\end{exercise}
+
+\begin{exercise}[points=8,bonus-points=3]
+ \lipsum[4]
+\end{exercise}
+
+\printtotalpoints\ vs.\@ \printcompletepoints\ vs.\@ \pointsandbonus
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.randomexercises.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.randomexercises.pdf
new file mode 100644
index 0000000000..773d34f495
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.randomexercises.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.randomexercises.tex b/macros/latex/contrib/xsim/doc/examples/xsim.randomexercises.tex
new file mode 100644
index 0000000000..60877b1a4a
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.randomexercises.tex
@@ -0,0 +1,58 @@
+\documentclass{article}
+\usepackage{xsim}
+
+\DeclareExerciseCollection{foo}
+
+\usepackage{filecontents}
+\begin{filecontents*}{random.tex}
+\begin{exercise}[ID=A]
+ exercise A
+\end{exercise}
+\begin{solution}
+ solution A
+\end{solution}
+\begin{exercise}[ID=B]
+ exercise B
+\end{exercise}
+\begin{solution}
+ solution B
+\end{solution}
+\begin{exercise}[ID=C]
+ exercise C
+\end{exercise}
+\begin{solution}
+ solution C
+\end{solution}
+\begin{exercise}[ID=D]
+ exercise D
+\end{exercise}
+\begin{solution}
+ solution D
+\end{solution}
+\begin{exercise}[ID=E]
+ exercise E
+\end{exercise}
+\begin{solution}
+ solution E
+\end{solution}
+\begin{exercise}[ID=F]
+ exercise F
+\end{exercise}
+\begin{solution}
+ solution F
+\end{solution}
+\end{filecontents*}
+
+\begin{document}
+
+\collectexercises{foo}
+\input{random.tex}
+\collectexercisesstop{foo}
+
+\section*{Exercises}
+\printrandomexercises[collection=foo,exclude=D]{3}
+
+\section*{Solutions}
+\printsolutions*
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-13635.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-13635.pdf
new file mode 100644
index 0000000000..af889a6709
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-13635.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-13635.tex b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-13635.tex
new file mode 100644
index 0000000000..3b52ce46b2
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-13635.tex
@@ -0,0 +1,70 @@
+% https://tex.stackexchange.com/q/13635/
+\documentclass{article}
+\usepackage{xsim}
+
+\DeclareExerciseEnvironmentTemplate{theorem:remark}
+ {
+ \par\addvspace{\baselineskip}
+ \noindent
+ \textit{%
+ \IfInsideSolutionF{\XSIMmixedcase{\GetExerciseName}~}%
+ \GetExerciseProperty{counter}}%
+ \GetExercisePropertyT{subtitle}{ \textup{(#1)}}%
+ . %
+ }
+ {\par\addvspace{\baselineskip}}
+
+\DeclareExerciseHeadingTemplate{exercises}{\subsection*{Exercises}}
+
+\xsimsetup{
+ exercise/template = theorem:remark ,
+ exercise/within = section ,
+ exercise/the-counter = \thesection.\arabic{exercise} ,
+ print-collection/headings = true ,
+ print-collection/headings-template = exercises
+}
+
+\DeclareExerciseCollection{prime numbers}
+\DeclareExerciseCollection{Zeta function}
+
+\begin{document}
+
+\collectexercises{prime numbers}
+\section{Prime Numbers}
+
+A \emph{prime number} is a positive integer other than $1$ that is only
+divisible by $1$ and itself.
+
+\begin{exercise}[subtitle=Euclid's Theorem]
+ \label{ex:euclid}
+ Show that there are infinitely many prime numbers.
+\end{exercise}
+
+As you will show in Exercise \ref{ex:euclid}, there are infinitely many
+primes. The number of primes that are smaller than a given natural number $n$
+is denoted $\pi(n)$.
+
+\begin{exercise}
+ Find an asymptotic formula for $\pi(n)$. \emph{Hint:} You might find
+ Exercise \ref{ex:zeta} helpful.
+\end{exercise}
+\collectexercisesstop{prime numbers}
+
+\printcollection{prime numbers}
+
+\collectexercises{Zeta function}
+\section{Zeta function}
+
+The zeta function is given by $\zeta(s) = \sum_{n=1}^\infty n^{-s}$, where $s$
+is a complex number with real part bigger than $1$.
+\begin{exercise}\label{ex:zeta}
+ Extend $\zeta$ as far as possible and find all zeros
+ of the function.
+\end{exercise}
+For example $\zeta(2) = \frac{\pi^2}{6}$.
+
+\collectexercisesstop{Zeta function}
+
+\printcollection{Zeta function}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-155630.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-155630.pdf
new file mode 100644
index 0000000000..6c9fc4482a
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-155630.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-155630.tex b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-155630.tex
new file mode 100644
index 0000000000..2edb7bfdad
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-155630.tex
@@ -0,0 +1,26 @@
+% https://tex.stackexchange.com/q/155630/
+\documentclass{article}
+\usepackage{xsim}
+
+\DeclareExerciseCollection{foo}
+
+\begin{document}
+
+\collectexercises{foo}
+\begin{exercise}
+ foo
+\end{exercise}
+\begin{exercise}
+ bar
+\end{exercise}
+\begin{exercise}
+ baz
+\end{exercise}
+\collectexercisesstop{foo}
+
+% shuffle around for a different version:
+\printexercise{exercise}{1}
+\printexercise{exercise}{3}
+\printexercise{exercise}{2}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-199360.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-199360.pdf
new file mode 100644
index 0000000000..9492549598
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-199360.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-199360.tex b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-199360.tex
new file mode 100644
index 0000000000..334275140a
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-199360.tex
@@ -0,0 +1,60 @@
+% http://tex.stackexchange.com/a/199360/
+\documentclass{scrartcl}
+\usepackage[clear-aux]{xsim}
+
+\usepackage{tcolorbox,blindtext}
+
+\DeclareExerciseEnvironmentTemplate{custom}
+ {%
+ \begin{tcolorbox}[
+ width = \textwidth ,
+ colbacktitle = \IfInsideSolutionTF{green}{red} ,
+ coltitle = black ,
+ title = {\XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}}]}
+ {\end{tcolorbox}}
+
+\xsimsetup{
+ exercise/template = custom ,
+ solution/template = custom
+}
+
+\begin{document}
+
+\begin{exercise}
+ First Question
+\end{exercise}
+\begin{solution}
+ Yes, it's a question
+\end{solution}
+
+\begin{exercise}[print=false,use]
+ Question: What is special about Brontosaurs?
+\end{exercise}
+\begin{solution}
+ They are thin at one end, thick in the middle and thin on the end again
+\end{solution}
+
+\begin{exercise}
+ Proof
+\begin{equation}
+ a^2 + b^2 = c^2
+\end{equation}
+\end{exercise}
+\begin{solution}
+ to be done
+\end{solution}
+
+\begin{exercise}
+ Cite a Latin Text
+\end{exercise}
+\begin{solution}
+ \textcolor{blue}{\blindtext}
+\end{solution}
+
+\begin{exercise}
+ \textcolor{red}{\textbf{Cite a Latin text again}}
+\end{exercise}
+
+\printsolutions*
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-299534.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-299534.pdf
new file mode 100644
index 0000000000..c006aeb34c
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-299534.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-299534.tex b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-299534.tex
new file mode 100644
index 0000000000..1c2be46df3
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-299534.tex
@@ -0,0 +1,32 @@
+% http://tex.stackexchange.com/q/299534/
+\documentclass{article}
+\usepackage{pythontex}
+\usepackage{xsim}
+
+\begin{document}
+
+\section{Test}
+
+\begin{exercise}[subtitle = Codeless Question,points=10]
+ A question without code, worth 10 points. Subtitle and point values are in
+ correct place.
+\end{exercise}
+\begin{solution}
+ Solution 1
+\end{solution}
+
+\begin{exercise}[subtitle = Codeful Question,points=15]
+Now with PythonTeX:
+\begin{pyblock}
+print("hello, world!")
+sum = 0
+for j in range(0,100):
+ sum += j
+print(sum)
+\end{pyblock}
+\end{exercise}
+\begin{solution}
+ Solution 2
+\end{solution}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-305110.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-305110.pdf
new file mode 100644
index 0000000000..fb92e875a9
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-305110.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-305110.tex b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-305110.tex
new file mode 100644
index 0000000000..c10928da0c
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-305110.tex
@@ -0,0 +1,67 @@
+% https://tex.stackexchange.com/q/305110
+\documentclass[12pt, a4paper]{book}
+\usepackage{xsim}
+
+\xsimsetup{
+ exercise/within = section ,
+ exercise/the-counter = \thesection.\arabic{exercise}
+}
+
+\begin{document}
+\part{EXCERCISES}
+\chapter{Topic 1}
+
+\section{Section}
+
+\begin{exercise}
+ I'm an excercise.
+\end{exercise}
+\begin{solution}
+ I'm a solution.
+\end{solution}
+
+\section{Section}
+
+\begin{exercise}
+ I'm an excercise.
+\end{exercise}
+\begin{solution}
+ I'm a solution.
+\end{solution}
+
+\chapter{Topic 2}
+
+\section{Section}
+\begin{exercise}
+ I'm an excercise.
+\end{exercise}
+\begin{solution}
+ I'm a solution.
+\end{solution}
+
+\section{Section}
+\begin{exercise}
+ I'm an excercise.
+\end{exercise}
+\begin{solution}
+ I'm a solution.
+\end{solution}
+
+\setcounter{chapter}{0}
+\part{SOLUTIONS}
+
+\chapter{Topic 1}
+\section{Section}
+\printsolutions[chapter=1,section=1]
+
+\section{Section}
+\printsolutions[chapter=1,section=2]
+
+\chapter{Topic 2}
+\section{Section}
+\printsolutions[chapter=2,section=1]
+
+\section{Section}
+\printsolutions[chapter=2,section=2]
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-308883.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-308883.pdf
new file mode 100644
index 0000000000..eb27dce140
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-308883.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-308883.tex b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-308883.tex
new file mode 100644
index 0000000000..74e762fa08
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-308883.tex
@@ -0,0 +1,13 @@
+% https://tex.stackexchange.com/q/308883/
+\documentclass{article}
+\usepackage{xsim,siunitx}
+\xsimsetup{goal-print={\num{#1}}}
+\sisetup{output-decimal-marker={,}}
+
+\begin{document}
+
+\begin{exercise}[points=2.5]
+ foo
+\end{exercise}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-338165.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-338165.pdf
new file mode 100644
index 0000000000..f6557530a1
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-338165.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-338165.tex b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-338165.tex
new file mode 100644
index 0000000000..e48d8880da
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-338165.tex
@@ -0,0 +1,72 @@
+% http://tex.stackexchange.com/q/338165
+\documentclass{article}
+\usepackage[T1]{fontenc}
+\usepackage{leading,microtype}
+\usepackage[french]{babel}
+
+\usepackage{tasks}
+\usepackage{xsim}
+\usepackage{tcolorbox}
+\tcbuselibrary{breakable, skins}
+\settasks{
+ counter-format = tsk.
+}
+
+\DeclareExerciseEnvironmentTemplate{boxed}
+ {%
+ \tcolorbox[
+ enhanced ,
+ attach boxed title to top center = {yshift=-7.5pt} ,
+ colback = white , colbacktitle = white ,
+ coltitle = black , colframe = black ,
+ boxed title style = { colframe = white } ,
+ fonttitle=\bfseries,
+ sharp corners=all,
+ breakable,
+ title=
+ \XSIMmixedcase{\GetExerciseName}%
+ \IfInsideSolutionF{%
+ ~\GetExerciseProperty{counter}%
+ \IfExercisePropertySetT{subtitle}{: \GetExerciseProperty{subtitle}}%
+ }%
+ ]
+ }
+ {\endtcolorbox}
+
+\xsimsetup{
+ exercise/template = boxed ,
+ solution/template = boxed ,
+ solution/print = true
+}
+
+\leading{15pt}
+
+\newcommand*\complement{\overline}
+\newcommand*\union{\cup}
+\newcommand*\intersection{\cap}
+\newcommand*\set[1]{\{#1\}}
+
+\begin{document}
+
+\begin{exercise}[subtitle=Set Calculus]
+ Soient $E=\set{1,2,3,4,5,6,7}$ et $A$, $B$, $C$ et $D$ quatre parties de E
+ d\'efinies par $A=\set{1,2,3,4}$, $B=\set{4,5,6,7}$, $C=\set{1,3,5,7}$ et
+ $D=\set{2,3,4,5,6}$.
+ \begin{tasks}(2)
+ \task Calculer $\complement{A}$.
+ \task Calculer $(A\union B) \intersection (C\union D)$.
+ \task Calculer $(A\intersection B) \union (C\intersection D)$.
+ \task Calculer $\complement{(\complement{A}\union B)} \union
+ \complement{(C\intersection D)}$.
+ \end{tasks}
+\end{exercise}
+\begin{solution}
+ \begin{tasks}(2)
+ \task $\set{5,6,7}$
+ \task $E$
+ \task $\set{3,4,5}$
+ \task $\set{1,2,3,4,6,7}$
+ \end{tasks}
+\end{solution}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-350028.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-350028.pdf
new file mode 100644
index 0000000000..ef781218a8
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-350028.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-350028.tex b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-350028.tex
new file mode 100644
index 0000000000..ebe090413c
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-350028.tex
@@ -0,0 +1,135 @@
+% http://tex.stackexchange.com/q/350028/
+\documentclass{book}
+
+\usepackage{xsimverb}
+\usepackage{xsim}
+\usepackage[most]{tcolorbox}
+\tcbuselibrary{skins,breakable}
+
+\DeclareExerciseEnvironmentTemplate{tcolorbox}
+ {%
+ \tcolorbox[
+ enhanced,
+ colframe=green!20!black,
+ colback=yellow!10!white,
+ coltitle=green!40!black,
+ fonttitle=\bfseries,
+ underlay={%
+ \begin{tcbclipinterior}
+ \shade[
+ inner color=\IfInsideSolutionTF{red!50!yellow}{green!80!yellow},
+ outer color=yellow!10!white]
+ (interior.north west) circle (2cm);
+ \draw[help lines,step=5mm,yellow!80!black,shift={(interior.north west)}]
+ (interior.south west) grid (interior.north east);
+ \end{tcbclipinterior}%
+ },
+ attach title to upper=\quad,
+ title = \XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}
+ \IfExercisePropertySetT{points}{%
+ (\GetExerciseProperty{points}
+ \IfExerciseGoalSingularTF{points}
+ {\XSIMtranslate{point}}
+ {\XSIMtranslate{points}})%
+ }]%
+ \IfInsideSolutionT{\label{solution:\ExerciseID}}%
+ }
+ {%
+ \endtcolorbox
+ \vspace*{\baselineskip}
+ \IfInsideSolutionTF
+ {%
+ \noindent Exercise~\GetExerciseProperty{counter} is on
+ page~\GetExerciseProperty{page}.%
+ }
+ {%
+ \noindent The solution of this exercise is on
+ page~\pageref{solution:\ExerciseID}.%
+ }%
+ \vspace{\baselineskip}
+ }
+
+\xsimsetup{
+ exercise/template = tcolorbox ,
+ solution/template = tcolorbox
+}
+
+\usepackage{fmtcount,etoolbox}
+\newrobustcmd*\mystringnum[2]{\csname#1stringnum\endcsname{#2}}
+\renewcommand*\thechapter{\mystringnum{number}{\value{chapter}}}
+\renewcommand*\thesection{\arabic{chapter}.\arabic{section}}
+
+% for the header: \MakeUppercase{\mystringnum{number}{1}}
+% => \mystringnum{NUMBER}{1}
+% => \NUMBERstringnum{1}
+% elsewhere: \mystringnum{number}{1}
+% => \numberstringnum{1}
+
+\usepackage{totcount}
+\regtotcounter{chapter}
+
+\newcounter{chapters}
+\setcounter{chapters}{1}
+\newcommand*\printsolutionsperchapter{%
+ \whileboolexpr
+ { test { \ifnumless {\value{chapters}} {\totvalue{chapter}+1} } }
+ {%
+ \printsolutions[chapter=\value{chapters},headings-template=per-chapter]
+ \stepcounter{chapters}%
+ }%
+}
+
+\begin{document}
+
+\chapter{The First Chapter}
+
+\begin{exercise}
+ Compute the derivative of the following function:
+ \begin{equation*}
+ f(x) = \sin((\sin x)^2)
+ \end{equation*}
+\end{exercise}
+\begin{solution}
+ The derivative is:
+ \begin{align*}
+ f’(x) &= ( \sin((\sin x)^2) )'
+ = \cos((\sin x)^2) \cdot 2\sin x \cos x
+ \end{align*}
+\end{solution}
+
+\begin{exercise}
+ Compute the derivative of the following function:
+ \begin{equation*}
+ f(x) = \sin((\sin x)^2)
+ \end{equation*}
+\end{exercise}
+\begin{solution}
+ The derivative is:
+ \begin{align*}
+ f’(x) &= ( \sin((\sin x)^2) )'
+ = \cos((\sin x)^2) \cdot 2\sin x \cos x
+ \end{align*}
+\end{solution}
+
+\chapter{The Second Chapter}
+
+\begin{exercise}
+ Compute the derivative of the following function:
+ \begin{equation*}
+ f(x) = (x^2+1) \sqrt{x^4+1}
+ \end{equation*}
+\end{exercise}
+\begin{solution}
+ The derivative is:
+ \begin{align*}
+ f’(x) &= ( (x^2+1) \sqrt{x^4+1} )'
+ = 2x\sqrt{x^4+1} + \frac{2x^3(x^2+1)}{\sqrt{x^4+1}}
+ \end{align*}
+\end{solution}
+
+\clearpage
+\section{Solutions of the Exercices}
+
+\printsolutionsperchapter
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369065.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369065.pdf
new file mode 100644
index 0000000000..6aa9ab572b
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369065.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369065.tex b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369065.tex
new file mode 100644
index 0000000000..b62b85127a
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369065.tex
@@ -0,0 +1,77 @@
+% https://tex.stackexchange.com/q/369065/
+\documentclass{article}
+\usepackage{xsim,tcolorbox,needspace}
+
+\xsimsetup{
+ exercise/within=section ,
+ exercise/the-counter = \thesection.\arabic{exercise} ,
+ exercise/template=cyan-box ,
+ exercise/name=Example ,
+ solution/template=red ,
+ solution/print=true
+}
+
+\DeclareExerciseEnvironmentTemplate{cyan-box}
+ {%
+ \begin{tcolorbox}[arc=0mm,boxrule=1pt,colback=white,colframe=cyan,leftrule=3mm]
+ \textsf{%
+ \MakeUppercase{%
+ \XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}%
+ }%
+ }%
+ \GetExercisePropertyT{subtitle}{ \textit{#1}}%
+ \quad
+ }
+ {\end{tcolorbox}}
+
+\DeclareExerciseEnvironmentTemplate{red}
+ {%
+ \par
+ \Needspace*{2\baselineskip}
+ \noindent
+ \textsf{\textcolor{red}{\MakeUppercase{\XSIMmixedcase{\GetExerciseName}}}}%
+ \quad
+ }
+ {\par\bigskip}
+
+\begin{document}
+
+\section{My first set of exercises}
+\begin{exercise}
+ Prove that $\frac{1}{2}\Delta(f_{ij}f^{ij})
+ =\nabla^{k}f^{ij}+f^{ij}f^{k}[2\nabla_{i}R_{jk}-\nabla_{k}R_{ij}]$
+\end{exercise}
+\begin{solution}
+ From \dots
+\end{solution}
+
+\begin{exercise}
+ Prove that Paulinho is smart.
+\end{exercise}
+\begin{solution}
+ All ducks are smart. Paulinho is a duck. Therefore, Paulinho is smart.
+\end{solution}
+
+\begin{exercise}
+ Prove that Paulinho is smart.
+\end{exercise}
+\begin{solution}
+ All ducks are smart. Paulinho is a duck. Therefore, Paulinho is smart.
+\end{solution}
+
+\section{My second set of exercises}
+\begin{exercise}
+ Prove that Paulinho is smart.
+\end{exercise}
+\begin{solution}
+ All ducks are smart. Paulinho is a duck. Therefore, Paulinho is smart.
+\end{solution}
+
+\begin{exercise}
+ Prove that Paulinho is smart.
+\end{exercise}
+\begin{solution}
+ All ducks are smart. Paulinho is a duck. Therefore, Paulinho is smart.
+\end{solution}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369636.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369636.pdf
new file mode 100644
index 0000000000..2bc106f303
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369636.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369636.tex b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369636.tex
new file mode 100644
index 0000000000..e13b8653f4
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369636.tex
@@ -0,0 +1,46 @@
+% https://tex.stackexchange.com/q/369686/
+\documentclass[a4paper,11pt]{article}
+\usepackage[top=2cm, bottom=3cm, left=4cm, right=4cm]{geometry}
+
+\usepackage[T1]{fontenc}
+\usepackage{fourier}
+\usepackage{tgpagella}
+\usepackage[utf8]{inputenc}
+
+\usepackage{xsim,needspace,adjustbox,scrextend}
+
+\xsimsetup{
+ exercise/the-counter = \arabic{exercise}. ,
+ exercise/template = square
+}
+
+\DeclareExerciseEnvironmentTemplate{square}
+ {%
+ \Needspace*{2\baselineskip}%
+ \addmargin[0pt]{.15\textwidth}%
+ \par\noindent
+ \adjustbox{
+ fbox = 1pt 0pt,
+ lap = {\textwidth},
+ valign = t,
+ set vsize = {0pt}{0pt}
+ }{\rule{0pt}{20pt}\hspace{20pt}}%
+ \textbf{\GetExerciseProperty{counter}} %
+ }
+ {\endaddmargin\vspace{\baselineskip}}
+
+\usepackage{lipsum}
+
+\begin{document}
+
+\noindent\hrulefill
+
+\begin{exercise}
+ \lipsum[1]
+\end{exercise}
+
+\begin{exercise}
+ \lipsum[2]
+\end{exercise}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369803.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369803.pdf
new file mode 100644
index 0000000000..73eab39f10
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369803.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369803.tex b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369803.tex
new file mode 100644
index 0000000000..58b6800f93
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-369803.tex
@@ -0,0 +1,50 @@
+% https://tex.stackexchange.com/q/369803
+\documentclass[a4paper,parskip=half]{scrartcl}
+\usepackage[utf8]{inputenc}
+\usepackage[ngerman]{babel}
+
+\usepackage{amsmath}
+\usepackage{amsthm}
+\usepackage{amsfonts}
+\usepackage{amssymb}
+
+\usepackage[left=2cm,right=2.5cm,top=2.5cm,bottom=2cm]{geometry}
+
+\usepackage{xsim,siunitx}
+\DeclareExerciseTagging{difficulty}
+\DeclareExerciseEnvironmentTemplate{custom}
+ {%
+ \subsection*
+ {%
+ \XSIMmixedcase{\GetExerciseName}\nobreakspace
+ \GetExerciseProperty{counter}%
+ \IfInsideSolutionF
+ {%
+ \IfExercisePropertySetT{subtitle}
+ { {\normalfont(\GetExerciseProperty{subtitle})}}%
+ }%
+ }%
+ }{}
+
+\xsimsetup{
+ exercise/name = \XSIMtranslate{question} ,
+ exercise/template=custom ,
+ solution/print=true
+}
+
+\begin{document}
+
+\begin{exercise}[ID=wdsw, subtitle = Widerstandswürfel , difficulty = 2]
+ Gegeben ist ein Würfel, wobei jede der Kanten einen Widerstand von $R =
+ \SI{1}{\ohm}$ hat.
+
+ Wie groß ist der Widerstand entlang einer Raumdiagonale?
+\end{exercise}
+\begin{solution}
+ Wir wollen den Widerstand zwischen den Punkten $X$ und $Y$ bestimmen, also
+ entlang der Raumdiagonale (siehe Abb. \ref{fig:wdsws1}). Weil die
+ Raumdiagonale eine Symmetrieachse ist, sollte das Problem symmetrisch sein,
+ und deswegen eine recht einfache Lösung haben.
+\end{solution}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-370642.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-370642.pdf
new file mode 100644
index 0000000000..13933e80c3
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-370642.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-370642.tex b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-370642.tex
new file mode 100644
index 0000000000..99b300c4a0
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-370642.tex
@@ -0,0 +1,25 @@
+% https://tex.stackexchange.com/q/370642/
+\documentclass[a4paper,12pt]{article}
+\usepackage{xsim}
+
+\DeclareExerciseEnvironmentTemplate{simple}
+ {\par\noindent\textbf{\GetExerciseProperty{counter}}. }
+ {\par}
+\xsimsetup{exercise/template=simple}
+
+\begin{document}
+
+\begin{exercise}\label{eq1}
+ Let $X$ be such that\dots
+\end{exercise}
+
+\begin{exercise}
+ In this exercise consider $Y=2$ \dots
+\end{exercise}
+
+\begin{exercise}
+ Consider $X$ as in exercise~\ref{eq1} (I would like to see the issue
+ number~1)
+\end{exercise}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-391530.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-391530.pdf
new file mode 100644
index 0000000000..137c858769
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-391530.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-391530.tex b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-391530.tex
new file mode 100644
index 0000000000..1deafe5fb0
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-391530.tex
@@ -0,0 +1,67 @@
+% https://tex.stackexchange.com/q/391530
+\documentclass{article}
+\usepackage{xsim}
+
+\DeclareExerciseType{subquestion}{
+ exercise-env = question ,
+ solution-env = answer ,
+ exercise-name = Question ,
+ solution-name = Answer ,
+ exercise-template = item ,
+ solution-template = item
+}
+
+\DeclareExerciseProperty{title}
+
+\makeatletter
+\DeclareExerciseEnvironmentTemplate{named}
+ {%
+ \subsection*{%
+ \GetExercisePropertyTF{title}
+ {#1}
+ {??\@latex@warning{Please give an exercise title}}%
+ }%
+ }
+ {}
+\makeatother
+
+\DeclareExerciseEnvironmentTemplate{item}
+ {\item}
+ {}
+
+\DeclareExerciseCollection{exercise-pool}
+
+\xsimsetup{
+ exercise/template = named
+}
+
+\begin{filecontents*}{\jobname-exercises.tex}
+\begin{question}
+ Who is the Defence Minister?
+\end{question}
+\begin{question}
+ Who is the Home Minister?
+\end{question}
+\begin{question}
+ Who is the Finance Minister?
+\end{question}
+\begin{question}
+ Who is the External Affairs Minister?
+\end{question}
+\end{filecontents*}
+
+\begin{document}
+
+\collectexercises{exercise-pool}
+\input{\jobname-exercises.tex}
+\collectexercisesstop{exercise-pool}
+
+\begin{exercise}[title=Answer the following in one sentence:]
+ \begin{enumerate}
+ \item Who is the President?
+ \item Who is the Prime Minister?
+ \printrandomexercises[collection=exercise-pool]{2}
+ \end{enumerate}
+\end{exercise}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-395273.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-395273.pdf
new file mode 100644
index 0000000000..c3796c8ee0
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-395273.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texsx-395273.tex b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-395273.tex
new file mode 100644
index 0000000000..fe6152ed96
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texsx-395273.tex
@@ -0,0 +1,74 @@
+\documentclass{article}
+\usepackage{xsim,tcolorbox,needspace}
+
+% declare a boolean property:
+\DeclareExerciseProperty*{short}
+% declare a tag like property:
+\DeclareExerciseTagging{level}
+
+% declare a template which typesets exercises differently according to given
+% properties:
+\DeclareExerciseEnvironmentTemplate{exercise}
+ {%
+ \renewcommand*\theenumi{\theexercise.\arabic{enumi}}%
+ \par\addvspace{\baselineskip}
+ \Needspace*{2\baselineskip}
+ \noindent
+ \GetExercisePropertyT{level}{\marginpar{\sffamily Level: #1}}%
+ \textbf{\XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}.} %
+ \GetExercisePropertyT{subtitle}{\textit{#1}}%
+ \IfExerciseBooleanPropertyF{short}{\par\noindent}%
+ }
+ {}
+
+% declare a tcolorbox template for the solutions:
+\DeclareExerciseEnvironmentTemplate{solution}
+ {\tcolorbox[colback=yellow,colframe=red]}
+ {\endtcolorbox}
+
+% declare a user command for short answers:
+\NewDocumentCommand\answer{m}{%
+ \IfSolutionPrintT{%
+ \UseExerciseTemplate{begin}{solution}%
+ #1%
+ \UseExerciseTemplate{end}{solution}%
+ }{}%
+}
+
+% setup exercises and solutions:
+\SetExerciseParameters{exercise}{
+ exercise-template = exercise ,
+ solution-template = solution
+}
+
+% remove this option to hide the answers:
+\xsimsetup{solution/print=true}
+
+\usepackage{lipsum}
+
+\begin{document}
+
+\begin{exercise}[level=hard,short]
+ Just a short exercise
+\end{exercise}
+\begin{solution}
+ The somewhat longer solution to the short exercise. \lipsum[1]
+\end{solution}
+
+\begin{exercise}[subtitle=This one has a title,level=easy]
+ Answer the following questions.
+ \begin{enumerate}
+ \item question \answer{answer}
+ \item question \answer{answer}
+ \end{enumerate}
+\end{exercise}
+
+\begin{exercise}
+ A long exercise. \lipsum[4]\answer{The answer}
+\end{exercise}
+
+\begin{exercise}[level=medium,short]
+ Another short exercise.\answer{The answer}
+\end{exercise}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texwelt-15093.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.texwelt-15093.pdf
new file mode 100644
index 0000000000..3dc9fb1649
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texwelt-15093.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texwelt-15093.tex b/macros/latex/contrib/xsim/doc/examples/xsim.texwelt-15093.tex
new file mode 100644
index 0000000000..1f3fcfefcb
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texwelt-15093.tex
@@ -0,0 +1,133 @@
+% http://texwelt.de/wissen/fragen/15093/
+\documentclass[paper=a4]{scrartcl}
+\usepackage[utf8]{inputenc}
+\usepackage[ngerman]{babel}
+
+\usepackage{xsim,needspace}
+
+\DeclareExerciseTagging{AFB}
+\DeclareExerciseEnvironmentTemplate{myexam}
+ {
+ \par\vspace{\baselineskip}
+ \Needspace*{3\baselineskip}
+ \noindent
+ \textbf{\IfInsideSolutionTF{Lösung}{Aufgabe}~\GetExerciseProperty{counter}.}%
+ \GetExercisePropertyT{subtitle}{\quad\textit{#1}}%
+ \hfill
+ \GetExercisePropertyT{AFB}{Schwierigkeit: #1}%
+ \GetExercisePropertyT{points}{%
+ \marginpar{%
+ \PropertyValue
+ \GetExercisePropertyT{bonus-points}{+\PropertyValue}%
+ \,P.%
+ }%
+ }%
+ \par\noindent
+ }
+ {}
+
+\xsimsetup{exercise/template=myexam}
+
+\begin{document}
+
+\begin{exercise}[subtitle=Eine Frage, AFB=1, points=3]
+ Das ist eine sehr tolle Frage.
+\end{exercise}
+
+\begin{exercise}[AFB=2, points=3]
+ Das ist eine sehr tolle Frage.
+\end{exercise}
+
+\begin{exercise}[AFB=3]
+ Das ist eine sehr tolle Frage.
+\end{exercise}
+
+\begin{exercise}[subtitle=Eine andere Frage, AFB=4, points=3]
+ Das ist eine sehr tolle Frage.
+\end{exercise}
+
+\begin{exercise}[subtitle=Eine Frage, AFB=2]
+ Das ist eine sehr tolle Frage.
+\end{exercise}
+
+\end{document}
+
+% andere Idee:
+\documentclass[paper=a4]{scrartcl}
+\usepackage[utf8]{inputenc}
+\usepackage[ngerman]{babel}
+
+\usepackage{xsim}
+
+\DeclareExerciseTagging{AFB}
+
+\DeclareExerciseEnvironmentTemplate{AFB}{%
+ \subsection*{%
+ \XSIMmixedcase{\GetExerciseName}\nobreakspace
+ \GetExerciseProperty{counter}%
+ \IfExercisePropertySetT{subtitle}%
+ { {\normalfont\itshape\GetExerciseProperty{subtitle}}}%
+ }
+ \marginpar{%
+ \GetExercisePropertyT{AFB}{%
+ \leavevmode\llap{Schwierigkeit: \PropertyValue\hspace*{\marginparsep}}%
+ }%
+ \GetExercisePropertyT{points}{%
+ \PropertyValue
+ \nobreakspace\XSIMtranslate{points}%
+ }%
+ }%
+}{}
+
+\DeclareExerciseEnvironmentTemplate{AFBsol}{%
+ \subsection*{%
+ \XSIMmixedcase{\GetExerciseName}\nobreakspace
+ \GetExerciseProperty{counter}%
+ \IfExercisePropertySetT{subtitle}%
+ { {\normalfont\itshape\GetExerciseProperty{subtitle}}}%
+ }
+ \textit{\small
+ \GetExercisePropertyT{AFB}{Schwierigkeit: \PropertyValue}%
+ \GetExercisePropertyT{points}{%
+ \IfExercisePropertySetT{AFB}{ }%
+ (\PropertyValue\nobreakspace\XSIMtranslate{points})%
+ }%
+ }%
+ \par\noindent
+}{}
+
+\DeclareExerciseTranslation{German}{default-heading}{Lösungen}
+
+\xsimsetup{
+ exercise/template=AFB ,
+ solution/template=AFBsol ,
+ exercise/name=Aufgabe
+}
+
+\begin{document}
+
+\begin{exercise}[subtitle=Eine Frage, AFB=1, points=3]
+ Das ist eine sehr tolle Frage.
+\end{exercise}
+\begin{solution}
+ Das ist eine tolle Lösung!
+\end{solution}
+\begin{exercise}[AFB=2, points=3]
+ Das ist eine sehr tolle Frage.
+\end{exercise}
+
+\begin{exercise}[AFB=3]
+ Das ist eine sehr tolle Frage.
+\end{exercise}
+
+\begin{exercise}[subtitle=Eine andere Frage, AFB=4, points=3]
+ Das ist eine sehr tolle Frage.
+\end{exercise}
+
+\begin{exercise}[subtitle=Eine Frage, AFB=2]
+ Das ist eine sehr tolle Frage.
+\end{exercise}
+
+\printsolutions
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texwelt-6698.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.texwelt-6698.pdf
new file mode 100644
index 0000000000..000663bf44
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texwelt-6698.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.texwelt-6698.tex b/macros/latex/contrib/xsim/doc/examples/xsim.texwelt-6698.tex
new file mode 100644
index 0000000000..9e388b9f69
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.texwelt-6698.tex
@@ -0,0 +1,86 @@
+% http://texwelt.de/wissen/fragen/6698/
+\documentclass{article}
+\usepackage[utf8]{inputenc}
+\usepackage[ngerman]{babel}
+
+\usepackage{needspace}
+\usepackage{xsim}
+\xsimsetup{
+ exercise/name = Aufgabe ,
+ solution/name = Lösung ,
+ exercise/within = section ,
+ exercise/the-counter = \thesection.\arabic{exercise} ,
+ exercise/template = mine
+}
+
+\newif\iflist
+
+\DeclareExerciseEnvironmentTemplate{mine}{
+ \par\vspace{\baselineskip}
+ \Needspace*{3\baselineskip}
+ \noindent
+ \textbf{\GetExerciseName~\GetExerciseProperty{counter}}%
+ \GetExercisePropertyT{subtitle}{\quad\textit{#1}}%
+ \iflist
+ \GetExercisePropertyT{page}{ (Seite~#1)}%
+ \fi
+ % not necessary if you don't use points:
+ \GetExercisePropertyT{points}{%
+ \marginpar{%
+ \PropertyValue
+ \GetExercisePropertyT{bonus-points}{+\PropertyValue}%
+ \,\XSIMtranslate{points-abbr}%
+ }%
+ }%
+ \par\noindent
+}
+{}
+
+\usepackage{multicol}
+
+\begin{document}
+
+\section{Erstes Kapitel}
+\begin{exercise}
+ Eine erste Aufgabe
+\end{exercise}
+\begin{exercise}
+ Eine zweite Aufgabe
+\end{exercise}
+
+\subsection{Erstes Unterkapitel}
+\begin{exercise}
+ Eine Aufgabe in einem Unterkapitel
+\end{exercise}
+\begin{exercise}
+ Noch eine Aufgabe in einem Unterkapitel
+\end{exercise}
+
+\subsubsection{Tiefer geschachteltes Unterkapitel}
+\begin{exercise}
+ Noch eine Aufgabe
+\end{exercise}
+
+\subsubsection{Weiter geschachtelt}
+\begin{exercise}
+ Eine weitere Aufgabe
+\end{exercise}
+
+\subsection{Zweites Unterkapitel}
+\begin{exercise}
+ Und eine weitere Aufgabe
+\end{exercise}
+
+\clearpage
+
+\section{Zweites Kapitel}
+\begin{exercise}
+ Eine Aufgabe in einem anderen Kapitel
+\end{exercise}
+
+\begin{multicols}{2}[\section{Aufgabenübersicht}]
+ \listtrue
+ \printcollection{all exercises}
+\end{multicols}
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.various.pdf b/macros/latex/contrib/xsim/doc/examples/xsim.various.pdf
new file mode 100644
index 0000000000..d0406e830c
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.various.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/examples/xsim.various.tex b/macros/latex/contrib/xsim/doc/examples/xsim.various.tex
new file mode 100644
index 0000000000..1b7b13f98b
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/examples/xsim.various.tex
@@ -0,0 +1,237 @@
+\documentclass{article}
+\usepackage{xsim,lipsum,tcolorbox}
+
+\DeclareExerciseType{question}{
+ exercise-env = question ,
+ solution-env = hint ,
+ exercise-name = Question ,
+ solution-name = Hint ,
+ exercise-template = default ,
+ solution-template = default ,
+ counter = exercise % shares a counter with the `exercise' type
+}
+
+\DeclareExerciseType{problem}{
+ exercise-env = problem ,
+ solution-env = answer ,
+ exercise-name = Problem ,
+ solution-name = Answer ,
+ exercise-template = tcolorbox ,
+ solution-template = tcolorbox
+}
+
+\DeclareExerciseProperty{grade}
+\DeclareExerciseProperty{difficulty}
+
+\tcbuselibrary{breakable}
+\DeclareExerciseEnvironmentTemplate{tcolorbox}
+ {%
+ \newcommand*\writehere{%
+ \IfInsideSolutionTF{}{%
+ \tcblower
+ \emph{Your answer:}
+ \vspace*{4cm}
+ }%
+ }
+ \vspace{\baselineskip}
+ \tcolorbox[
+ colback = red!5!white ,
+ colframe = red!75!black ,
+ colbacktitle = yellow!50!red ,
+ coltitle = red!25!black ,
+ fonttitle = \bfseries ,
+ subtitle style = {
+ boxrule = 0.4pt ,
+ colback = yellow!50!red!25!white
+ } ,
+ breakable ,
+ title = \GetExerciseName~\GetExerciseProperty{counter}
+ \IfExercisePropertySetT{points}{%
+ (\GetExerciseProperty{points}
+ \IfExerciseGoalSingularTF{points}
+ {\XSIMtranslate{point}}
+ {\XSIMtranslate{points}})%
+ }]
+ \IfInsideSolutionF{%
+ \IfExercisePropertySetT{tags}{%
+ Tags: \ListExerciseTags{tags}{, } \par
+ }%
+ }%
+ }
+ {%
+ \endtcolorbox
+ \vspace{\baselineskip}
+ }
+
+\xsimsetup{
+ % tags = {geometry} ,
+ % topics = {geometry}
+ % tags/ingore-untagged % if true untagged exercise will be printed regardless
+ % % which tags have been chosen
+}
+
+\begin{document}
+
+\gradingtable \par \bigskip
+
+Total: \printtotalpoints \par
+from questions: \printpoints{question} \par
+from exercises: \printpoints{exercise} \par
+from problems: \printpoints{problem} \par \bigskip
+
+Total bonus: \printtotalbonus \par
+from questions: \printbonus{question} \par
+from exercises: \printbonus{exercise} \par
+from problems: \printbonus{problem} \par
+
+% 1
+\begin{exercise}[points=4,bonus-points=1,topics=geometry,tags={geometry,triangles},grade=7]
+ \lipsum[1]
+\begin{verbatim}
+foo x^2 y^3 \gna
+\end{verbatim}
+\end{exercise}
+\begin{solution}[print]
+ This is the solution to \ExerciseType\ \GetExerciseProperty{counter}.
+\begin{verbatim}
+foo x^2 y^3 \gna
+\end{verbatim}
+\end{solution}
+
+% 2
+\begin{exercise}[subtitle=Foo,points=5,topics=analysis,tags={analysis,functions},grade=11]
+ \lipsum[2]
+\end{exercise}
+\begin{solution}
+ This is the solution to \ExerciseType\ \GetExerciseProperty{counter}.
+\end{solution}
+
+% 3
+\begin{problem}[tags={analysis,functions}]
+ \lipsum[3]
+ \writehere
+\end{problem}
+\begin{answer}
+ This is the solution to \ExerciseType\ \GetExerciseProperty{counter}.
+\end{answer}
+
+% 4
+\begin{question}
+ \lipsum[4]
+
+ \verb+\ExerciseID+: \GetExerciseAliasProperty{ID}
+
+ \verb+\GetExerciseProperty{id}+: \GetExerciseProperty{id}
+
+ \verb+\GetExerciseAliasProperty{ID}+: \GetExerciseAliasProperty{ID}
+
+ \verb+\GetExerciseProperty{ID}+: \GetExerciseProperty{ID}
+\end{question}
+\begin{hint}
+ This is the solution to \ExerciseType\ \GetExerciseProperty{counter}.
+\end{hint}
+
+% 5
+\begin{problem}[points=2]
+ \lipsum[3]
+
+ \verb+\ExerciseID+: \GetExerciseAliasProperty{ID}
+
+ \verb+\GetExerciseProperty{id}+: \GetExerciseProperty{id}
+
+ \verb+\GetExerciseAliasProperty{ID}+: \GetExerciseAliasProperty{ID}
+
+ \verb+\GetExerciseProperty{ID}+: \GetExerciseProperty{ID}
+ \writehere
+\end{problem}
+\begin{answer}
+ This is the solution to \ExerciseType\ \GetExerciseProperty{counter}.
+\end{answer}
+
+% 6
+\begin{problem}[points=1]
+ \lipsum[3]
+
+ \verb+\ExerciseID+: \GetExerciseAliasProperty{ID}
+
+ \verb+\GetExerciseProperty{id}+: \GetExerciseProperty{id}
+
+ \verb+\GetExerciseAliasProperty{ID}+: \GetExerciseAliasProperty{ID}
+
+ \verb+\GetExerciseProperty{ID}+: \GetExerciseProperty{ID}
+\end{problem}
+\begin{answer}
+ This is the solution to \ExerciseType\ \GetExerciseProperty{counter}.
+\end{answer}
+
+% 7
+\begin{exercise}[ID=test]
+ \lipsum[5]
+
+ \verb+\ExerciseID+: \GetExerciseAliasProperty{ID}
+
+ \verb+\GetExerciseProperty{id}+: \GetExerciseProperty{id}
+
+ \verb+\GetExerciseAliasProperty{ID}+: \GetExerciseAliasProperty{ID}
+
+ \verb+\GetExerciseProperty{ID}+: \GetExerciseProperty{ID}
+\end{exercise}
+\begin{solution}
+ This is the solution to \ExerciseType\ \GetExerciseProperty{counter}.
+\end{solution}
+
+% 8
+\begin{exercise}[print=false,use=false]
+ \lipsum[5]
+\end{exercise}
+\begin{solution}
+ This is the solution to \ExerciseType\ \GetExerciseProperty{counter}.
+\end{solution}
+
+% \printsolutionstype{exercise}
+
+\printsolutions*
+
+\section{Statistics}
+
+\ForEachUsedExerciseByType{%
+ \noindent\XSIMmixedcase{\ExerciseParameterGet{#1}{exercise-name}}~#3: \\
+ \hspace*{2em}id: #2, type: #1, subtitle: #4, points: #5, bonus: #6\par \medskip
+}
+
+\bigskip
+
+\ForEachUsedExerciseByID{%
+ \noindent\XSIMmixedcase{\ExerciseParameterGet{#1}{exercise-name}}~#3: \\
+ \hspace*{2em}id: #2, type: #1, subtitle: #4, points: #5, bonus: #6\par \medskip
+}
+
+\bigskip
+
+\ForEachUsedExerciseByType{%
+ \ExercisePropertyIfSetT{#1}{#2}{points}
+ { \XSIMmixedcase{\ExerciseParameterGet{#1}{exercise-name}}~#3: #5~points\par }%
+}
+
+\bigskip
+
+Number of questions: \numberofquestions \par
+Number of exercises: \numberofexercises \par
+Number of problems: \numberofproblems
+
+\section{Grading tables}
+
+\gradingtable[template=default*,type=exercise] \par \bigskip
+
+\gradingtable[template=default*,type=problem] \par \bigskip
+
+\gradingtable[template=default*] \par \bigskip
+
+% vertical
+\gradingtable[type=exercise] \par \bigskip
+
+\gradingtable[type=problem] \par \bigskip
+
+\gradingtable
+
+\end{document}
diff --git a/macros/latex/contrib/xsim/doc/xsim-manual.cls b/macros/latex/contrib/xsim/doc/xsim-manual.cls
new file mode 100644
index 0000000000..1db5337a58
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/xsim-manual.cls
@@ -0,0 +1,822 @@
+% ----------------------------------------------------------------------------
+% the XSIM package
+%
+% eXercise Sheets IMproved
+%
+% ----------------------------------------------------------------------------
+% Clemens Niederberger
+% Web: https://github.com/cgnieder/xsim
+% E-Mail: contact@mychemistry.eu
+% ----------------------------------------------------------------------------
+% Copyright 2017--2018 Clemens Niederberger
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+% http://www.latex-project.org/lppl.txt
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+%
+% The Current Maintainer of this work is Clemens Niederberger.
+% ----------------------------------------------------------------------------
+% If you have any ideas, questions, suggestions or bugs to report, please
+% feel free to contact me.
+% ----------------------------------------------------------------------------
+%
+% please ignore the contents of this file -- it is not a good example for
+% coding...
+%
+\ProvidesClass{xsim-manual}[2017/09/18]
+
+\LoadClass[load-preamble,add-index]{cnltx-doc}
+\RequirePackage{imakeidx}
+\RequirePackage[utf8]{inputenc}
+\RequirePackage{xsim}
+
+\RequirePackage{geometry}
+\geometry{
+ left = 3.8cm ,
+ right = 2.8cm
+}
+
+\setcnltx{
+ package = {xsim},
+ info =
+ \textsc{e\textcolor{cnltx}{X}ercise \textcolor{cnltx}{S}heets
+ \textcolor{cnltx}{IM}proved} \\
+ the official successor of the \cnltxpackagenameformat{exsheets} package ,
+ url = https://github.com/cgnieder/xsim ,
+ authors = Clemens Niederberger ,
+ email = contact@mychemistry.eu ,
+ quote-format = \small\biolinumLF ,
+ add-cmds = {
+ blank ,
+ addbonus ,
+ addpoints ,
+ AddtoExerciseGoal ,
+ AddtoExerciseGoalPrint ,
+ AddtoExerciseTypeGoal ,
+ AddtoExerciseTypeGoalPrint ,
+ blank ,
+ collectexercises ,
+ collectexercisestype ,
+ collectexercisesstop ,
+ DeclareExerciseCollection ,
+ DeclareExerciseEnvironmentTemplate ,
+ DeclareExerciseGoal ,
+ DeclareExerciseHeadingTemplate ,
+ DeclareExerciseProperty ,
+ DeclareExercisePropertyAlias ,
+ DeclareExerciseTableTemplate ,
+ DeclareExerciseTagging ,
+ DeclareExerciseTranslation ,
+ DeclareExerciseTranslations ,
+ DeclareExerciseType ,
+ DeclareGradeDistribution ,
+ ExerciseCollection ,
+ ExerciseGoalValuePrint ,
+ ExerciseID ,
+ ExerciseParameterGet ,
+ ExercisePropertyGet ,
+ ExercisePropertyGetAlias ,
+ ExercisePropertyGlobalSave ,
+ ExercisePropertyIfSetF ,
+ ExercisePropertyIfSetT ,
+ ExercisePropertyIfSetTF ,
+ ExercisePropertySave ,
+ ExerciseTableType ,
+ ExerciseTableCode ,
+ ExerciseType ,
+ ForeachExerciseTag ,
+ ForEachExerciseTranslation ,
+ ForEachPrintedExerciseByType ,
+ ForEachPrintedExerciseByID ,
+ ForEachUsedExerciseByType ,
+ ForEachUsedExerciseByID ,
+ GetExerciseAliasProperty ,
+ GetExerciseName ,
+ GetExerciseParameter ,
+ GetExerciseProperty ,
+ GetExercisePropertyF ,
+ GetExercisePropertyT ,
+ GetExercisePropertyTF ,
+ GlobalSaveExerciseProperty ,
+ gradingtable ,
+ IfExerciseBooleanPropertyF ,
+ IfExerciseBooleanPropertyT ,
+ IfExerciseBooleanPropertyTF ,
+ IfExerciseGoalF ,
+ IfExerciseGoalF ,
+ IfExerciseGoalTF ,
+ IfExerciseGoalSingularF ,
+ IfExerciseGoalSingularT ,
+ IfExerciseGoalSingularTF ,
+ IfExerciseGoalsSumF ,
+ IfExerciseGoalsSumT ,
+ IfExerciseGoalsSumTF ,
+ IfExercisePropertyExistF ,
+ IfExercisePropertyExistT ,
+ IfExercisePropertyExistTF ,
+ IfExercisePropertySetF ,
+ IfExercisePropertySetT ,
+ IfExercisePropertySetTF ,
+ IfExerciseTypeGoalsSumF ,
+ IfExerciseTypeGoalsSumT ,
+ IfExerciseTypeGoalsSumTF ,
+ IfExerciseTagSetF ,
+ IfExerciseTagSetT ,
+ IfExerciseTagSetTF ,
+ IfExerciseTopicSetF ,
+ IfExerciseTopicSetT ,
+ IfExerciseTopicSetTF ,
+ IfInsideSolutionF ,
+ IfInsideSolutionT ,
+ IfInsideSolutionTF ,
+ loadxsimstyle ,
+ numberofexercises ,
+ numberofusedexercises ,
+ points ,
+ printallsolutions ,
+ printcollection ,
+ printexercise ,
+ printgoal ,
+ printpoints ,
+ printrandomexercises ,
+ printsolution ,
+ printsolutions ,
+ printsolutionstype ,
+ PropertyValue ,
+ ProvideExerciseTagging ,
+ SaveExerciseProperty ,
+ SetExerciseParameter ,
+ SetExerciseParameters ,
+ theexercise ,
+ TotalExerciseGoal ,
+ TotalExerciseGoals ,
+ TotalExerciseTypeGoal ,
+ TotalExerciseTypeGoals ,
+ UseExerciseTags ,
+ UseExerciseTagsX ,
+ UseExerciseTemplate ,
+ XSIMexpandcode ,
+ XSIMsetfilebegin ,
+ XSIMfilewritestart ,
+ XSIMfilewritestop ,
+ XSIMgobblechars ,
+ XSIMsetfileend ,
+ XSIMifblankT ,
+ XSIMifblankF ,
+ XSIMifblankTF ,
+ XSIMifchapterF ,
+ XSIMifchapterT ,
+ XSIMifchapterTF ,
+ XSIMifeqF ,
+ XSIMifeqT ,
+ XSIMifeqTF ,
+ XSIMmixedcase ,
+ XSIMputright ,
+ xsimsetup ,
+ xsimstyle ,
+ XSIMtranslate
+ } ,
+ add-envs = { exercise , solution } ,
+ add-silent-cmds = {
+ @percentchar ,
+ bottomrule ,
+ breite ,
+ choice ,
+ cs ,
+ DeclareFloatingEnvironment ,
+ enddescription ,
+ endtcolorbox ,
+ hint ,
+ hoehe ,
+ iflist ,
+ IfNoValueTF ,
+ ifnumless ,
+ lipsum ,
+ lstdefinestyle ,
+ lstset ,
+ midrule ,
+ Needspace ,
+ NewDocumentCommand ,
+ NewDocumentEnvironment ,
+ newlist ,
+ numberofcolumns ,
+ numberofproblems ,
+ pkg ,
+ pointsandbonus ,
+ printA, printC, printE ,
+ printhints ,
+ printcompletepoints ,
+ printsumofpointsandbonus ,
+ setlist ,
+ settasks ,
+ tcbuselibrary ,
+ tcolorbox ,
+ thechapter ,
+ thesection ,
+ toprule ,
+ whileboolexpr ,
+ xsim
+ } ,
+ pre-output = { \let\marginpar\marginnote } ,
+ add-listings-options = {
+ numberstyle = \tiny\noncopy
+ } ,
+ index-setup = { level = \section } ,
+ makeindex-setup = { columns = 2 , columnsep = 1em } ,
+ module-sep = {\texttt{/}}%
+}
+
+
+\RequirePackage[en-US]{datetime2}
+\newrobustcmd*\xsim@add@version[2]{\csdef{xsimversion#1}{\DTMdate{#2}}}
+\renewrobustcmd*\sinceversion[1]{%
+ \cnltx@version@note{\GetTranslation{cnltx-introduced}~#1 (\csuse{xsimversion#1})}%
+}
+\renewrobustcmd*\changedversion[1]{%
+ \cnltx@version@note{\GetTranslation{cnltx-changed}~#1 (\csuse{xsimversion#1})}%
+}
+
+\newnote*\sincechanged[2]{\GetTranslation{cnltx-introduced}~#1
+ (\csuse{xsimversion#1}), changed with version~#2 (\csuse{xsimversion#2})}
+
+\renewcommand*\versionnoteformat{\scriptsize\sffamily\RaggedRight}
+
+\renewcommand*\cnltx@module@text[2]{%
+ \begingroup
+ \reversemarginpar
+ \setlength\marginparsep{1em}%
+ \marginnote{\hfill\llap{\module#1{#2}\cnltx@module@sep}}%
+ \endgroup
+}
+
+\RequirePackage{accsupp}
+\newcommand*\noncopy[1]{%
+ \BeginAccSupp{method=escape,ActualText={}}%
+ #1%
+ \EndAccSupp{}%
+}
+
+\def\libertine@figurestyle{LF}
+\RequirePackage[libertine]{newtxmath}
+\def\libertine@figurestyle{OsF}
+
+\RequirePackage{refcount}
+
+\renewcommand*\footref[1]{%
+ \begingroup
+ \unrestored@protected@xdef\@thefnmark{\getrefnumber{#1}}%
+ \endgroup
+ \@footnotemark
+}
+
+\newcommand*\eTeX{%
+ \texorpdfstring
+ {\mbox{$\epsilon$-\TeX}}
+ {e-TeX}%
+}
+
+\RequirePackage[
+ backend=biber,
+ style=cnltx,
+ sortlocale=en_US,
+ indexing=cite]{biblatex}
+\addbibresource{cnltx.bib}
+
+\RequirePackage[biblatex]{embrac}
+\ChangeEmph{[}[,.02em]{]}[.055em,-.08em]
+\ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em]
+
+\defbibheading{bibliography}{\section{References}}
+
+\colorlet{property}{orange}
+\newidxcmd\property{\code{\textcolor{property}{#1}}}[ (property)]
+\newrobustcmd*\prop{\@ifstar{\cnltx@prop@star}{\cnltx@prop@nostar}}
+
+\RequirePackage{marginnote}
+
+\renewcommand*\module@idx@app{ (option class)}
+
+\newrobustcmd*\cnltx@prop@star{%
+ \cnltx@ifdash
+ {\cnltx@prop@aux*\meta}
+ {\cnltx@prop@aux*\marg}%
+}
+\newrobustcmd*\cnltx@prop@nostar{%
+ \cnltx@ifdash
+ {\cnltx@prop@aux{}\meta}
+ {\cnltx@prop@aux{}\marg}%
+}
+\newcommand*\cnltx@prop@aux[4]{%
+ \code{\property#1{#3}\cnltx@isvalue#2{#4}}%
+}
+
+\newrobustcmd*\propis{%
+ \@ifstar
+ {\cnltx@propis*}
+ {\cnltx@propis{}}%
+}
+\newrobustcmd*\cnltx@propis[1]{%
+ \cnltx@ifdash
+ {\cnltx@prop@aux{#1}\@firstofone}
+ {\cnltx@prop@aux{#1}\Marg}%
+}
+\newrobustcmd*\choiceprop{%
+ \@ifstar
+ {\cnltx@choiceprop@star}
+ {\cnltx@choiceprop@nostar}%
+}
+\def\cnltx@choiceprop@star#1#2{%
+ \code{\property*{#1}\cnltx@isvalue\choices{#2}}}
+\def\cnltx@choiceprop@nostar#1#2{%
+ \code{\property{#1}\cnltx@isvalue\choices{#2}}}
+\newcommand*\boolprop{%
+ \@ifstar
+ {\cnltx@boolprop@star}
+ {\cnltx@boolprop@nostar}%
+}
+\def\cnltx@boolprop@star#1{\choiceprop*{#1}{\default{true},false}}
+\def\cnltx@boolprop@nostar#1{\choiceprop{#1}{\default{true},false}}
+
+\newenvironment{properties}
+ {%
+ \def\propert{\@cnltx@option@item\property}%
+ \def\propval{\@cnltx@option@item\prop}%
+ \def\proplit{\@cnltx@option@item\propis}%
+ \def\propchoice{\@cnltx@option@item\choiceprop}%
+ \def\propbool{\@cnltx@option@item\boolprop}%
+ \cnltxlist
+ }
+ {\endcnltxlist}
+
+\colorlet{parameter}{blue}
+\newidxcmd\parameter{\code{\textcolor{parameter}{#1}}}[ (parameter)]
+\newrobustcmd*\para{\@ifstar{\cnltx@para@star}{\cnltx@para@nostar}}
+
+\newrobustcmd*\cnltx@para@star{%
+ \cnltx@ifdash
+ {\cnltx@para@aux*\meta}
+ {\cnltx@para@aux*\marg}%
+}
+\newrobustcmd*\cnltx@para@nostar{%
+ \cnltx@ifdash
+ {\cnltx@para@aux{}\meta}
+ {\cnltx@para@aux{}\marg}%
+}
+\newcommand*\cnltx@para@aux[4]{%
+ \code{\parameter#1{#3}\cnltx@isvalue#2{#4}}%
+}
+
+\newrobustcmd*\parais{%
+ \@ifstar
+ {\cnltx@parais*}
+ {\cnltx@parais{}}%
+}
+\newrobustcmd*\cnltx@parais[1]{%
+ \cnltx@ifdash
+ {\cnltx@para@aux{#1}\@firstofone}
+ {\cnltx@para@aux{#1}\Marg}%
+}
+\newrobustcmd*\choicepara{%
+ \@ifstar
+ {\cnltx@choicepara@star}
+ {\cnltx@choicepara@nostar}%
+}
+\def\cnltx@choicepara@star#1#2{%
+ \code{\parameter*{#1}\cnltx@isvalue\choices{#2}}}
+\def\cnltx@choicepara@nostar#1#2{%
+ \code{\parameter{#1}\cnltx@isvalue\choices{#2}}}
+\newcommand*\boolpara{%
+ \@ifstar
+ {\cnltx@boolpara@star}
+ {\cnltx@boolpara@nostar}%
+}
+\def\cnltx@boolpara@star#1{\choicepara*{#1}{\default{true},false}}
+\def\cnltx@boolpara@nostar#1{\choicepara{#1}{\default{true},false}}
+
+\newenvironment{parameters}
+ {%
+ \def\param{\@cnltx@option@item\parameter}%
+ \def\paraval{\@cnltx@option@item\para}%
+ \def\paralit{\@cnltx@option@item\parais}%
+ \def\parachoice{\@cnltx@option@item\choicepara}%
+ \def\parabool{\@cnltx@option@item\boolpara}%
+ \cnltxlist
+ }
+ {\endcnltxlist}
+
+\RequirePackage{acro}
+
+\DeclareAcronym{prop}{
+ short = property ,
+ long = \emph{Properties} are options of exercises which are individual for
+ each exercise and can be retrieved and used in exercise templates. ,
+ short-plural-form = properties
+}
+
+\DeclareAcronym{para}{
+ short = parameter ,
+ long = \emph{Parameters} are options of exercise types which are the same
+ for each exercise of a type and can be retrieved and used in exercise
+ templates.
+}
+
+\DeclareAcronym{goal}{
+ short = goal ,
+ long = \emph{Goals} are a certain type of \acsp*{prop} with a numerical
+ value the sum of which is available throughout the document.
+}
+
+\DeclareAcronym{tag}{
+ short = tag ,
+ long = \emph{Tags} are a certain type of \acsp*{prop} with a csv list as
+ value which can be used for selective usage of exercises.
+}
+
+\DeclareAcronym{coll}{
+ short = collection ,
+ long = A \emph{collection} bundles a number of exercises of one type or all
+ types of exercises within certain barriers in the document. Those
+ exercise collections can be printed at any place in the document.
+}
+
+\DeclareAcronym{tmpl}{
+ short = template ,
+ long = {\emph{Templates} are generic code frameworks which are used for
+ typesetting \xsim's objects such as exercises, solutions, or grading
+ tables.}
+}
+
+\ExplSyntaxOn
+\NewAcroCommand \Acs
+ {
+ \acro_first_upper:
+ \acro_short:n {#1}
+ }
+\NewAcroCommand \Acsp
+ {
+ \acro_first_upper:
+ \acro_plural:
+ \acro_short:n {#1}
+ }
+\ExplSyntaxOff
+
+\newcommand*\environ{\@ifstar\environ@star\environ@nostar}
+\newcommand*\environ@star[1]{\beginenv*\Marg{\env*{#1}}}
+\newcommand*\environ@nostar[1]{\beginenv*\Marg{\env{#1}}}
+
+\RequirePackage{tcolorbox}
+\tcbuselibrary{skins,breakable}
+\tcbset{enhanced,enhanced jigsaw}
+
+\newtcolorbox{bewareofthedog}{
+ colback = white ,
+ colframe = red ,
+ underlay={%
+ \path[draw=none]
+ (interior.south west)
+ rectangle node[red]{\Huge\bfseries !}
+ ([xshift=-4mm]interior.north west);
+ }%
+}
+
+\newtcolorbox{cnltxcode}[1][]{
+ boxrule = 1pt ,
+ colback = cnltxbg ,
+ colframe = cnltx ,
+ arc = 5pt ,
+ beforeafter skip = .5\baselineskip ,%
+ #1%
+}
+
+\RenewDocumentEnvironment{sourcecode}{O{}}
+ {%
+ \pgfqkeys{/cnltx}{#1}%
+ \setlength\cnltx@sidebysidewidth
+ {\dimexpr .45\columnwidth -\lst@xleftmargin -\lst@xrightmargin\relax}%
+ \XSIMexpandcode{%
+ \noexpand\lstset{
+ style=cnltx,
+ \ifboolexpe{ bool {cnltx@sidebyside} and not bool {cnltx@codeonly} }
+ {linewidth=\cnltx@sidebysidewidth,}{}%
+ \expandonce\cnltx@local@listings@options
+ }%
+ }%
+ \XSIMgobblechars{2}%
+ \XSIMifblankTF{#1}
+ {\XSIMfilewritestart*{\jobname.tmp}}
+ {\XSIMfilewritestart{\jobname.tmp}}%
+ }
+ {%
+ \XSIMfilewritestop
+ \cnltxcode[breakable]%
+ \lstinputlisting[style=cnltx]{\jobname.tmp}%
+ \endcnltxcode
+ }
+
+\RenewDocumentEnvironment{example} {O{}}
+ {%
+ \pgfqkeys{/cnltx}{#1}%
+ \setlength\cnltx@sidebysidewidth
+ {\dimexpr .45\columnwidth -\lst@xleftmargin -\lst@xrightmargin\relax}%
+ \XSIMexpandcode{%
+ \noexpand\lstset{
+ style=cnltx,
+ \ifboolexpe{ bool {cnltx@sidebyside} and not bool {cnltx@codeonly} }
+ {linewidth=\cnltx@sidebysidewidth,}{}%
+ \expandonce\cnltx@local@listings@options
+ }%
+ }%
+ \XSIMgobblechars{2}%
+ \XSIMifblankTF{#1}
+ {\XSIMfilewritestart*{\jobname.tmp}}
+ {\XSIMfilewritestart{\jobname.tmp}}%
+ }
+ {%
+ \XSIMfilewritestop
+ \ifbool{cnltx@sidebyside}
+ {%
+ \cnltxcode
+ \noindent
+ \minipage[c]{\cnltx@sidebysidewidth}%
+ \cnltx@pre@source@hook
+ \lstinputlisting[style=cnltx] {\jobname.tmp}%
+ \cnltx@after@source@hook
+ \endminipage\hfill
+ \minipage[c]{\cnltx@sidebysidewidth}%
+ \cnltx@pre@example@hook
+ \input {\jobname.tmp}%
+ \cnltx@after@example@hook
+ \endminipage
+ }
+ {%
+ \cnltxcode[breakable]%
+ \cnltx@pre@source@hook
+ \lstinputlisting{\jobname.tmp}%
+ \cnltx@after@source@hook
+ \tcblower
+ \cnltx@pre@example@hook
+ \input {\jobname.tmp}%
+ \cnltx@after@example@hook
+ }%
+ \endcnltxcode
+ }
+
+\renewrobustcmd*\inputsourcecode[2][]{%
+ \begingroup
+ \pgfqkeys{/cnltx}{#1}%
+ \XSIMexpandcode{%
+ \noexpand\lstset{
+ style=cnltx,%
+ \expandonce\cnltx@local@listings@options
+ }%
+ }%
+ \cnltxcode[breakable]%
+ \lstinputlisting{#2}%
+ \endcnltxcode
+ \endgroup
+}
+
+\RequirePackage{longtable,booktabs}
+
+\RequirePackage{lipsum}
+\RequirePackage{varioref}
+\RequirePackage{bookmark}
+
+\xsimsetup{
+ clear-aux ,
+ path = exercises
+}
+
+\DeclareExerciseCollection{foo}
+\DeclareExerciseCollection{layouts}
+
+\newrobustcmd*\TF{%
+ \colorlet{outside}{.}%
+ \textcolor{red}{\underline{\textcolor{outside}{TF}}}%
+}
+
+\newcommand*\narg{\textcolor{argument}{\code{-}}}
+\newcommand*\barg{\textcolor{argument}{\code{\bang}}}
+
+\newrobustcmd\bang{!}
+
+\renewrobustcmd*\code[1]{\begingroup\codefont\let\^\textasciicircum#1\endgroup}
+
+% ----------------------------------------------------------------------------
+\loadxsimstyle{layouts}
+
+\DeclareExerciseEnvironmentTemplate{tcolorbox}
+ {%
+ \tcolorbox[
+ colback = red!5!white ,
+ colframe = red!75!black ,
+ colbacktitle = yellow!50!red ,
+ coltitle = red!25!black ,
+ subtitle style = {
+ boxrule = 0.4pt ,
+ colback = yellow!50!red!25!white
+ } ,
+ breakable ,
+ drop shadow ,
+ beforeafter skip = .5\baselineskip ,
+ title =
+ \textbf{\GetExerciseName~\GetExerciseProperty{counter}}%
+ \GetExercisePropertyT{subtitle}
+ { \textit{\PropertyValue}}%
+ \IfInsideSolutionF{%
+ \GetExercisePropertyT{points}
+ { % notice the space
+ (\printgoal{\PropertyValue}
+ \IfExerciseGoalSingularTF{points}
+ {\XSIMtranslate{point}}
+ {\XSIMtranslate{points}})%
+ }%
+ }%
+ ]%
+ }
+ {\endtcolorbox}
+
+\DeclareExerciseProperty*{bonus}
+\DeclareExerciseEnvironmentTemplate{bonus}
+ {%
+ \subsection*
+ {%
+ \IfExerciseBooleanPropertyT{bonus}{\llap{$\bigstar$ }Bonus }%
+ \XSIMmixedcase{\GetExerciseName}\nobreakspace
+ \GetExerciseProperty{counter}%
+ \IfInsideSolutionF
+ {%
+ \IfExercisePropertySetT{subtitle}
+ { {\normalfont\itshape\GetExerciseProperty{subtitle}}}%
+ }%
+ }
+ \GetExercisePropertyT{points}
+ {%
+ \marginpar
+ {%
+ \IfInsideSolutionF{\rule{1.2cm}{1pt}\slash}%
+ \PropertyValue
+ \GetExercisePropertyT{bonus-points}
+ {\nobreakspace(+\PropertyValue)}%
+ \nobreakspace\XSIMtranslate{point-abbr}%
+ }%
+ }%
+ }
+ {}
+
+% ----------------------------------------------------------------------------
+
+\DeclareExerciseType{problem}{
+ exercise-env = problem ,
+ solution-env = answer ,
+ exercise-name = Problem ,
+ solution-name = Answer ,
+ exercise-template = tcolorbox ,
+ solution-template = tcolorbox
+}
+
+\RequirePackage{hyperref,bookmark}
+
+% ----------------------------------------------------------------------------
+
+\ExplSyntaxOn
+\cs_set:Npn \__xsim_get_texsx_number:w texsx- #1 \q_stop: {#1}
+\cs_set:Npn \__xsim_get_texwelt_number:w texwelt- #1 \q_stop: {#1}
+\cs_set:Npn \__xsim_get_golatex_number:w golatex- #1 \q_stop: {#1}
+
+\newcommand* \xsim@example@links [1] {
+ \href { \xsim@example@texfile@path {#1} } { \color{white} [\TeX] } ~
+ \href { \xsim@example@pdffile@path {#1} } { \color{white} [PDF] }
+ \tl_if_in:nnT {#1} {texsx}
+ {
+ \tl_set:Nx \l_tmpa_tl { \__xsim_get_texsx_number:w #1 \q_stop: }
+ \space \href
+ { https \c_colon_str //tex.stackexchange.com/q/ \l_tmpa_tl / }
+ { \color {white} [forum] }
+ }
+ \tl_if_in:nnT {#1} {texwelt}
+ {
+ \tl_set:Nx \l_tmpa_tl { \__xsim_get_texwelt_number:w #1 \q_stop: }
+ \space \href
+ { http \c_colon_str //texwelt.de/wissen/fragen/ \l_tmpa_tl / }
+ { \color {white} [forum] }
+ }
+ \tl_if_in:nnT {#1} {golatex}
+ {
+ \tl_set:Nx \l_tmpa_tl { \__xsim_get_golatex_number:w #1 \q_stop: }
+ \space \href
+ { http \c_colon_str //golatex.de/viewtopic,p, \l_tmpa_tl .html }
+ { \color {white} [forum] }
+ }
+}
+\ExplSyntaxOff
+
+\newcounter{examplefile}
+\newcounter{examplefiles}
+\newcommand*\xsim@add@example[1]{%
+ \listadd\xsim@examplefiles{#1}%
+ \stepcounter{examplefiles}%
+}
+\newcommand*\listexamplefiles{%
+ \def\xsim@example@texfile@path##1{./examples/xsim.##1.tex}%
+ \def\xsim@example@pdffile@path##1{./examples/{xsim.##1}.pdf}%
+ \def\do##1{%
+ \begin{cnltxcode}[
+ step and label={examplefile}{example:##1} ,
+ sidebyside align=top seam,sidebyside,
+ righthand width=\linewidth/4,
+ sidebyside gap=0pt,
+ lower separated=false,
+ title=Example~\theexamplefile\ \enquote{\texttt{##1}}
+ \xsim@example@links{##1}%
+ ]
+ \bookmark[level=2,dest=examplefile.\arabic{examplefile}]{Example~\theexamplefile\ (##1)}%
+ \lstinputlisting[style=cnltx,lastline=10]{\xsim@example@texfile@path{##1}}
+ \tcblower
+ \fbox{%
+ \href{\xsim@example@pdffile@path{##1}}{%
+ \includegraphics[width=.8\linewidth]{\xsim@example@pdffile@path{##1}}}}%
+ \end{cnltxcode}
+ }%
+ \dolistloop\xsim@examplefiles
+}
+
+\xsim@add@example{blanks}
+\xsim@add@example{boxed-headings}
+\xsim@add@example{code-and-output}
+\xsim@add@example{collections}
+\xsim@add@example{crossref}
+\xsim@add@example{description-list}
+\xsim@add@example{different-point-types}
+\xsim@add@example{difficulties}
+\xsim@add@example{hints}
+\xsim@add@example{floating}
+\xsim@add@example{grade-distribution}
+\xsim@add@example{listings}
+\xsim@add@example{multiplechoice}
+\xsim@add@example{listofexercises}
+\xsim@add@example{pointsums}
+\xsim@add@example{randomexercises}
+\xsim@add@example{various}
+\xsim@add@example{texsx-13635}
+\xsim@add@example{texsx-155630}
+\xsim@add@example{texsx-199360}
+\xsim@add@example{texsx-299534}
+\xsim@add@example{texsx-305110}
+\xsim@add@example{texsx-308883}
+\xsim@add@example{texsx-338165}
+\xsim@add@example{texsx-350028}
+\xsim@add@example{texsx-369065}
+\xsim@add@example{texsx-369636}
+\xsim@add@example{texsx-369803}
+\xsim@add@example{texsx-370642}
+\xsim@add@example{texsx-391530}
+\xsim@add@example{texsx-395273}
+\xsim@add@example{texwelt-6698}
+\xsim@add@example{texwelt-15093}
+\xsim@add@example{golatex-80640}
+\xsim@add@example{golatex-91339}
+
+% ----------------------------------------------------------------------------
+
+\newcommand*\listlayouts{%
+ \def\do##1{%
+ \begin{cnltxcode}[{title=Layout \enquote{\texttt{##1}}}]
+ \ifcsdef{xsim@layout@extra@##1}
+ {\csuse{xsim@layout@extra@##1}}
+ {}%
+ \xsimsetup{exercise/template={##1}}
+ \let\marginpar\marginnote
+ \XSIMexpandcode{%
+ \printexercise{exercise}{\GetExerciseIdForProperty{ID}{showlayout}}
+ }%
+ \end{cnltxcode}
+ }%
+ \dolistloop\xsim@layouts
+}
+
+\NewDocumentCommand\xsim@add@layout{mo}{%
+ \listadd\xsim@layouts{#1}%
+ \IfNoValueF{#2}{\csdef{xsim@layout@extra@#1}{#2}}%
+}
+
+\xsim@add@layout{default}
+\xsim@add@layout{runin}[\renewcommand*\theexercise{\arabic{exercise}.}]
+\xsim@add@layout{margin}[\renewcommand*\theexercise{\arabic{exercise}.}]
+
+\xsim@add@version{0.8} {2017-05-18}
+\xsim@add@version{0.8a} {2017-05-19}
+\xsim@add@version{0.8b} {2017-05-23}
+\xsim@add@version{0.9} {2017-06-20}
+\xsim@add@version{0.10} {2017-09-19}
+\xsim@add@version{0.10a} {2017-10-04}
+\xsim@add@version{0.11} {2018-02-12}
+
+% ----------------------------------------------------------------------------
+\endinput
diff --git a/macros/latex/contrib/xsim/doc/xsim.history b/macros/latex/contrib/xsim/doc/xsim.history
new file mode 100644
index 0000000000..b0a2fe526b
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/xsim.history
@@ -0,0 +1,113 @@
+--------------------------------------------------------------------------
+
+XSIM -- eXercise Sheets IMproved
+
+--------------------------------------------------------------------------
+Clemens Niederberger
+Web: https://github.com/cgnieder/xsim
+E-Mail: contact@mychemistry.eu
+--------------------------------------------------------------------------
+Copyright 2017--2018 Clemens Niederberger
+
+This work may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either version 1.3
+of this license or (at your option) any later version.
+The latest version of this license is in
+ http://www.latex-project.org/lppl.txt
+and version 1.3 or later is part of all distributions of LaTeX
+version 2005/12/01 or later.
+
+This work has the LPPL maintenance status `maintained'.
+
+The Current Maintainer of this work is Clemens Niederberger.
+--------------------------------------------------------------------------
+
+HISTORY:
+
+ v0.0 2017/02/09 - start with coding the first ideas
+ v0.1 2017/03/19 - first draft which actually seems to do everything as
+ planned
+ v0.2 2017/03/21 - bugfix in the verbwrite module
+ - add `use!' and `print!' properties
+ - add the concepts of `noupdate' and `boolean' properties
+ v0.4 2017/03/24 - \IfExerciseBooleanPropertyTF
+ - \GetExercisePropertyTF, \PropertyValue
+ - \printallsolutions
+ - \UseExerciseTemplate
+ - bug fix in solution environments: now get printed again
+ when option `print=true' is used
+ - bug fix to the translations of the solution list headings:
+ exercise name instead of exercise type is now printed
+ - \AddtoExerciseTypeGoal, \AddtoExerciseGoal
+ \AddtoExerciseTypeGoalPrint, \AddtoExerciseGoalPrint,
+ \ExerciseGoalValuePrint
+ - \addpoints, \addbonus, \points, \printgoal
+ v0.5 2017/03/30 - add style file mechanism
+ - make solution print conditions `section' and `chapter'
+ combinable
+ v0.5a 2017/04/15 - fix wrong translation of the `default-heading'
+ v0.5b 2017/04/16 - add \SetExerciseProperty
+ v0.6 2017/04/27 - official interface for grade distributions
+ - refine hook management (environment module)
+ v0.6a 2017/04/28 - refine \blank command, add documentation for said command
+ v0.7 2017/05/09 - \xsim_list_length:n
+ - new boolean property `used'
+ - when an exercise is collected the counter isn't stepped
+ but only when the exercise is inserted for the first
+ time; when this happens the new property `used' is set to
+ `true'
+ - make setting boolean properties case insensitive
+ - add missing pieces to manual (eg `page' property...)
+ - \TotalExerciseGoals and \TotalExerciseTypeGoals
+ - \XSIMifchapterTF
+ - \xsim_if_goal_sum:nnnTF and friends,
+ \IfExerciseTypeGoalsSumTF and \IfExerciseGoalsSumTF
+ - some more hints in the manual regarding collections
+ v0.8 2017/05/18 - bug fix in \xsim_set_property:nnnn
+ - random exercise lists from collections
+ - \xsim_collection_count:n
+ - \GetExerciseIdForProperty and \GetExerciseTypeForProperty
+ for unique properties
+ - set property `print=false' during collection and only to
+ true when the corresponding exercises actually are
+ printed
+ - do not insert \par at the beginning and end of exercises
+ and solutions; this should be left to the templates!
+ - new option `print-collection/print' which allows to
+ choose between exercises, solutions, and both to be
+ printed
+ - new parameter `solution-counter' in order to avoid
+ possible conflicts with existing counters
+ v0.8a 2017/05/19 - \IfPrintSolutionTF
+ v0.8b 2017/05/23 - use \printgoal in default environment template
+ - \xsim_print_goal:nnn now expands input to a number
+ v0.9 2017/06/20 - \xsimstyle's behaviour now matches the description in
+ the manual
+ - add style file `layouts' which at the moment provides the
+ two exercise templates `runin' and `margin'
+ - \printforexercises , \xsim_print_type_code:nnnnn
+ - \IfExerciseParameterSetTF
+ - \GetExerciseParameterTF
+ - change syntax of \SetExerciseProperty
+ - \SetExpandedExerciseProperty
+ - \ExerciseSetProperty, \ExerciseSetExpandedProperty
+ - property `sectioning'
+ - \IfExistSolutionTF
+ v0.10 2017/09/19 - \xsim_input:nnn
+ - \GetExerciseBody
+ - option `blank/fill'
+ - bug fix in \xsim_start_collection:nn
+ - added further examples to package
+ - new option `file-extension'
+ v0.10a 2017/10/01 - bug fix: grading table options can now be set with
+ \xsimsetup (issue 15)
+ v0.11 2018/02/12 - change name requirement for style files in order to
+ prevent possible name clashes with module files
+ - fix bug in \SetExerciseProperty and
+ \SetExpandedExerciseProperty
+ - fix bug when xsimverb is used standalone (issue 21)
+ - add option `split-aux-lists' (issue 18)
+ - \IfExerciseTagSetTF and \IfExerciseTopicSetTF
+ - introduce a \xsim_if_<tagging>_value:nTF for each tag
+ kind
+ - \ProvideExerciseTagging
diff --git a/macros/latex/contrib/xsim/doc/xsim.ideas b/macros/latex/contrib/xsim/doc/xsim.ideas
new file mode 100644
index 0000000000..29fa058fde
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/xsim.ideas
@@ -0,0 +1,31 @@
+--------------------------------------------------------------------------
+
+XSIM -- eXercise Sheets IMproved
+
+--------------------------------------------------------------------------
+Clemens Niederberger
+Web: https://github.com/cgnieder/xsim
+E-Mail: contact@mychemistry.eu
+--------------------------------------------------------------------------
+Copyright 2017--2018 Clemens Niederberger
+
+This work may be distributed and/or modified under the
+conditions of the LaTeX Project Public License, either version 1.3
+of this license or (at your option) any later version.
+The latest version of this license is in
+ http://www.latex-project.org/lppl.txt
+and version 1.3 or later is part of all distributions of LaTeX
+version 2005/12/01 or later.
+
+This work has the LPPL maintenance status `maintained'.
+
+The Current Maintainer of this work is Clemens Niederberger.
+--------------------------------------------------------------------------
+
+IDEAS:
+
+- a document class `xsim-exam' for creating exams
+- a mechanism for providing variants of an exam
+- provide a switch: either write the environments to an external file
+ or save it to an auxiliary file ? (not really sure about this one --
+ probably not)
diff --git a/macros/latex/contrib/xsim/doc/xsim_manual.pdf b/macros/latex/contrib/xsim/doc/xsim_manual.pdf
new file mode 100644
index 0000000000..2cc93eb00b
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/xsim_manual.pdf
Binary files differ
diff --git a/macros/latex/contrib/xsim/doc/xsim_manual.tex b/macros/latex/contrib/xsim/doc/xsim_manual.tex
new file mode 100644
index 0000000000..53c620c1bb
--- /dev/null
+++ b/macros/latex/contrib/xsim/doc/xsim_manual.tex
@@ -0,0 +1,2288 @@
+% !arara: pdflatex: { action: nonstopmode }
+% !arara: biber
+% !arara: pdflatex: { action: nonstopmode }
+% arara: pdflatex: { action: nonstopmode }
+% arara: pdflatex: { action: nonstopmode }
+% ----------------------------------------------------------------------------
+% the XSIM package
+%
+% eXercise Sheets IMproved
+%
+% ----------------------------------------------------------------------------
+% Clemens Niederberger
+% Web: https://github.com/cgnieder/xsim
+% E-Mail: contact@mychemistry.eu
+% ----------------------------------------------------------------------------
+% Copyright 2017--2018 Clemens Niederberger
+%
+% This work may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.3
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+% http://www.latex-project.org/lppl.txt
+% and version 1.3 or later is part of all distributions of LaTeX
+% version 2005/12/01 or later.
+%
+% This work has the LPPL maintenance status `maintained'.
+%
+% The Current Maintainer of this work is Clemens Niederberger.
+% ----------------------------------------------------------------------------
+% If you have any ideas, questions, suggestions or bugs to report, please
+% feel free to contact me.
+% ----------------------------------------------------------------------------
+\documentclass{xsim-manual}
+
+\usepackage{filecontents}
+\begin{filecontents*}{\jobname.bib}
+@online{texsx:romannumeral,
+ author = {Bruno Le Floch} ,
+ title = {Cunning (La)TeX tricks} ,
+ urldate = {2017-03-02} ,
+ url = {http://tex.stackexchange.com/a/19769/}
+}
+@online{texsx:tagged/exsheets,
+ title = {Questions tagged `exsheets'} ,
+ author = {various} ,
+ url = {http://tex.stackexchange.com/questions/tagged/exsheets} ,
+ urldate = {2017-05-15}
+}
+\end{filecontents*}
+\addbibresource{\jobname.bib}
+
+\begin{document}
+
+\section{Licence, Requirements and \texorpdfstring{\textsc{readme}}{README}}
+\license
+
+\xsim\ loads the packages \pkg{expl3}~\cite{bnd:l3kernel},
+\pkg{xparse}~\cite{bnd:l3packages}, \pkg{etoolbox}~\cite{pkg:etoolbox},
+\pkg{array}~\cite{pkg:array} \pkg{booktabs}~\cite{pkg:booktabs} and
+\pkg{translations}~\cite{pkg:translations}. All of these packages are present
+on a modern and up to date \TeX\ distribution such as \TeX~Live or MiK\TeX\ so
+no further action should be needed. When you are using \xsim\ you should be
+using an up to date \TeX\ distribution, anyway.
+
+\begin{bewareofthedog}
+ Newer versions of \xsim\ may depend on newer versions of the support
+ packages. Remember: it is always dangerous to update single packages.
+ Always update your \TeX\ distribution if you want an up to date version of a
+ package. Be careful: if you're in the middle of an important project it
+ might be better to wait with the update until you've finished the project.
+ Every update might be breaking some things.
+\end{bewareofthedog}
+
+\section{Motivation and Background}
+
+It has been quite a while since I first published
+\pkg{exsheets}~\cite{pkg:exsheets} in June 2012. Since then it has gained a
+user base and a little bit of popularity as the number of questions on tex.sx
+shows (119~at the time of writing)~\cite{texsx:tagged/exsheets}. User
+questions, bug reports and feature requests improved it over the time. It
+still has a version number starting with a zero, though, which in my
+versioning system means I still consider it experimental.
+
+This is due to several facts. It lacks a few features which I consider
+essential for a full version~1. For one thing it is not possible to have
+several kinds of exercises numbered independently. Using verbatim material
+such as listings inside exercises and solutions is not possible and the
+current workaround isn't that ideal either. One request which dates back
+quite a while now was to have different types of points to exercises\ldots
+
+All of those aren't easy to add due to the way \pkg{exsheets} is implemented
+right now. As a consequence I wanted to re-implement \pkg{exsheets} for a long
+time. This is what lead to \xsim. Internally the package works completely
+different.
+
+\begin{bewareofthedog}
+ \xsim\ will be the official successor of \pkg{exsheets} which is now
+ considered obsolete but will stay alive and will still receive bugfix
+ releases. However, new features will not be added to \pkg{exsheets} any
+ more.
+\end{bewareofthedog}
+
+\section{How to Read the Manual}\label{sec:how-read-manual}
+
+\subsection{Nomenclature}
+
+Throughout this manual certain terms are used. This section explains their
+meaning in this manual.
+
+\acuseall
+\printacronyms[heading=none]
+
+\subsection{Package Options}\label{sec:package-options}
+\xsim\ has these package options:
+\begin{options}
+ \opt{verbose}
+ Writes extensive information about what \xsim\ is doing into the log
+ file.
+ \opt{final}
+ If used the exercise and solution environments will not rewrite the
+ environment body files.
+ \opt{clear-aux}
+ If used every time the total number of exercise changes \xsim\ will write
+ \emph{less} information to the auxfile on the next run and only if the
+ number of exercises stays stable between compilations the needed
+ information will be written to the auxfile. \emph{This needs more
+ compilations until everything stabilizes but should reduce the
+ probability of possibly faulty exercises after changes to the document.}
+ The \option{final} option automatically disables this option. See also
+ sections~\vref{sec:how-exerc-envir} and~\vref{sec:resolve-getting}.
+\end{options}
+
+Those options are used the usual way as package option
+\begin{sourcecode}
+ \usepackage[verbose]{xsim}
+\end{sourcecode}
+or as global option
+\begin{sourcecode}
+ \documentclass[verbose]{article}
+\end{sourcecode}
+or via the setup command:
+\begin{commands}
+ \command{xsimsetup}[\marg{options}]
+ Set up \xsim's package options and all other options described at
+ other places in the manual.
+\end{commands}
+
+\subsection{Setting Options}
+Apart from the package options already described in
+section~\vref{sec:package-options} \xsim\ has further options. Those can be
+\enquote{toplevel} options or options belonging to a module.
+\begin{options}
+ \keyval*{toplevel}{value}
+ A toplevel option.
+ \keyval*{sublevel}{value}\Module*{module}
+ A sublevel option belonging to the module \module*{module}
+\end{options}
+Both kinds of options are set with \cs{xsimsetup}:
+\begin{sourcecode}
+ \xsimsetup{
+ toplevel = {value} ,
+ module/sublevel = {value}
+ }
+\end{sourcecode}
+
+\subsection{Command descriptions}
+
+Some commands do have a \expandablesymbol\ symbol printed next to their
+names. This indicates that the command is expandable, \ie, it is usable in an
+\cs*{edef} or \cs*{write} context and will expand according to its
+description. All other commands are engine protected, \ie, in the sense of
+\eTeX's \cs*{protected}.
+
+Some command name descriptions end with \code{\TF}.
+\begin{commands}
+ \command*{SomeCommand\TF}[\meta{arguments}\marg{true}\marg{false}]
+ A command with maybe some arguments and ending with the two arguments
+ \meta{true} and \meta{false}.
+\end{commands}
+This means two things: the command is a conditional which tests something and
+depending on the outcome of the test leaves either the \meta{true} argument
+(\code{T}) or the \meta{false} argument (\code{F}) in the input stream. It
+also means two additional commands exist:
+\begin{commands}
+ \command*{SomeCommandT}[\meta{arguments}\marg{true}]
+ The same as \cs*{SomeCommandTF} but only with the \meta{true} argument and
+ no \meta{false} argument.
+ \command*{SomeCommandF}[\meta{arguments}\marg{false}]
+ The same as \cs*{SomeCommandTF} but only with the \meta{false} argument and
+ no \meta{true} argument.
+\end{commands}
+
+
+\section{Exercises and Solutions}
+
+The two predefined environments for exercises and solutions are the following
+ones:
+\begin{environments}
+ \environment{exercise}[\oarg{\acsp*{prop}}]
+ Input and typeset an exercise. See section~\vref{sec:exercise-properties}
+ for details on exercise \acsp*{prop}.
+ \environment{solution}[\oarg{options}]
+ Input and typeset the solution to the exercise of the previous
+ \env{exercise} environment. See section~\vref{sec:printing-solutions} for
+ details on options of solutions.
+\end{environments}
+
+\begin{example}
+ \begin{exercise}
+ A first example for an exercise.
+ \end{exercise}
+ \begin{solution}
+ A first example for a solution.
+ \end{solution}
+\end{example}
+
+As can be seen in the example a solution is not printed with the default
+setup. This can be changed using the following option.
+\begin{options}
+ \keybool{print}\Module{solution}\Default{false}
+ Set if solutions are printed or or not.
+\end{options}
+
+The option (belonging to the module \module*{solution}) can either be set
+locally as option to the \env{solution} environment
+\begin{sourcecode}
+ \begin{solution}[print=true]
+ A first example for a solution.
+ \end{solution}
+\end{sourcecode}
+or with the setup command for all following solutions:
+\begin{sourcecode}
+ \xsimsetup{
+ solution/print = true
+ }
+\end{sourcecode}
+
+There is an completely analoguous option for the \env{exercise} environment:
+\begin{options}
+ \keybool{print}\Module{exercise}\Default{true}
+ Set if exercises are printed or or not.
+\end{options}
+More details on those two environments can be found in
+section~\vref{sec:using-printing}.
+
+\section{How the Exercise Environments Work}\label{sec:how-exerc-envir}
+Both the exercise and the solution enviroments write the contents of their
+bodies verbatim to external files following a certain naming structure:
+\begin{itemize}
+ \item
+ \code{\meta{jobname}-\meta{type}-\meta{id}-exercise|solution-body.tex}
+\end{itemize}
+The name starts with the name of the job (which is the name of the document
+itself) followed by type and id of the corresponding exercise and then
+followed by the environment type. For example both enviroments from the first
+example have been written to files named
+\begin{itemize}
+ \item \verbcode+xsim_manual-exercise-1-exercise-body.tex+ and
+ \item \verbcode+xsim_manual-exercise-1-solution-body.tex+, respectively.
+\end{itemize}
+These external files are input when the respective exercise or solution is
+printed. An advantage of using external files is that \emph{verbatim material
+ is allowed} inside the environments. Details on the \meta{type} of an
+exercise will be given in section~\vref{sec:new-exercise-types}. \emph{The
+ \meta{id} of an exercise is a positive integer unique to each exercise
+ environment regardless if the exercise is being printed or used at all.}
+
+Each of those files contains some information about itself and where and why
+it was generated\footnote{In this example the sourcecode line number is
+ misleading as the example where the file was generated itself was an
+ external file where the \env{exercise} environment indeed \emph{was} on
+ line~1.}:
+
+\inputsourcecode{exercises/xsim_manual-exercise-1-exercise-body.tex}
+
+Arguably one downside of the approach using external files for each exercise
+and its solution is that your project folder will be cluttered with files. In
+order to deal with this somehow \xsim\ offers the following option:
+\begin{options}
+ \keyval{path}{path name}\Default
+ With this option a subfolder or path within the main project folder can be
+ given. Exercises will be written to and included from this path.
+ \emph{The path must exist on your system before you can use it!} This
+ document uses \keyis{path}{exercises}.
+ \keyval{file-extension}{string}\Default{\code{tex}}
+ \sinceversion{0.10}This option let's you choose the extension of the
+ auxiliary files.
+\end{options}
+
+Another thing to keep in mind: the environment in many ways works the same way
+as the \env{filecontents} environment. \emph{This also means that you
+ \emph{cannot} have comments on the first line of the environments:}
+\begin{sourcecode}
+ \begin{exercise}[points=2] % this comment will cause trouble
+ Lorem ipsum
+ \end{exercise}
+\end{sourcecode}
+
+\begin{bewareofthedog}
+ \xsim\ writes a lot of stuff to the auxfile for re-using information on
+ subsequent compilations. If you add exercises, change properties \etc\ it
+ might happen that wrong information is staying in the auxfile and is wrongly
+ used by \xsim. In such cases deleting the auxfile and doing a few fresh
+ compilations may resolve your problems.
+
+ Sometimes the \emph{existence of exercise or solution files from earlier
+ compilations} may lead to wrong lists of exercises or solutions. In such
+ cases it can be useful to delete all those files and doing a fresh
+ compilation. It may be helpful to use a subfolder for those exernal files
+ which will make deleting them a little bit easier. (Don't forget to both
+ create the subfolder and set \option{path} accordingly then.)
+
+ Using the \option{clear-aux} option might help to reduce erroneous exercises.
+\end{bewareofthedog}
+
+\begin{bewareofthedog}
+ A lot of the lines \xsim\ writes to the auxfile and reads in a subsequent
+ run look like this:
+\begin{sourcecode}
+ \XSIM {points}{exercise-2=={4}|exercise-10=={2.5}|problem-11=={5}}
+\end{sourcecode}
+ As you can see different entries of the various properties of exercises are
+ separated with a \code{|}. This means that you cannot use this symbol
+ inside properties. This is why \xsim\ provides an option to change this
+ marker.
+\end{bewareofthedog}
+\begin{options}
+ \keyval{split-aux-lists}{string}\Default{\code{|}}
+ Set\sinceversion{0.11} the string that is used to separate the property
+ entries in the auxfile.
+\end{options}
+
+\section{New Exercise Types}\label{sec:new-exercise-types}
+
+It is easy to define new exercise environments together with a corresponding
+solution environment using the following command:
+\begin{commands}
+ \command{DeclareExerciseType}[\marg{type}\marg{parameters}]
+ Declare a new exercise type analoguous to the \env{exercise} and
+ \env{solution} environments.
+\end{commands}
+Declaring a new exercise type will also define a new command:
+\begin{commands}
+ \command{numberof\meta{exercise-env}s}
+ These commands hold the absolut number of used exercises of type
+ \meta{type}. The meaning of \meta{exercise-env} will become clear below
+ when the exercise parameters are explained. It is always the same as the
+ exercise environment name.
+\end{commands}
+\begin{example}
+ There are \numberofexercises~exercises and \numberofproblems~problem in this
+ manual.
+\end{example}
+\xsim's pre-defined environment pair has been defined as follows:
+\begin{sourcecode}
+ \DeclareExerciseType{exercise}{
+ exercise-env = exercise ,
+ solution-env = solution ,
+ exercise-name = \XSIMtranslate{exercise} ,
+ solution-name = \XSIMtranslate{solution} ,
+ exercise-template = default ,
+ solution-template = default
+ }
+\end{sourcecode}
+
+The above already is an example for almost all parameters that can (and often
+must) be set. Here is the complete list:
+\begin{parameters}
+ \paraval{exercise-env}{exercise environment name}
+ The name for the environment used for the exercises of type \meta{type}.
+ \emph{This parameter is mandatory.} It can't be changed afterwards.
+ \paraval{solution-env}{solution environment name}
+ The name for the environment used for the solutions of type \meta{type}.
+ \emph{This parameter is mandatory.} It can't be changed afterwards.
+ \paraval{exercise-name}{exercise name}
+ The name of the exercises of type \meta{type} -- used for typesetting.
+ \emph{This parameter is mandatory.}
+ \paraval{solution-name}{solution name}
+ The name of the solutions of type \meta{type} -- used for typesetting.
+ \emph{This parameter is mandatory.}
+ \paraval{exercise-template}{exercise template}
+ The template used for typesetting the exercises of type \meta{type}.
+ \emph{This parameter is mandatory.} See
+ section~\vref{sec:styl-exerc-templ} for details on templates.
+ \paraval{solution-template}{solution template}
+ The template used for typesetting the exercises of type \meta{type}.
+ \emph{This parameter is mandatory.} See
+ section~\vref{sec:styl-exerc-templ} for details on templates.
+ \paraval{counter}{counter name}
+ The counter used for the exercises of type \meta{type}. If not explicitly
+ set the counter with the same name as \parameter{exercise-env} is used.
+ Otherwise the specified counter is used. This enables to have different
+ types of exercises sharing a common counter. \emph{This parameter can't
+ be changed afterwards.} If the explicit or implicit counter does not
+ exist, yet, it will be defined.
+ \paraval{solution-counter}{counter name}
+ The counter used for the solutions of type \meta{type}. If not explicitly
+ set the counter with the same name as \parameter{solution-env} is used.
+ Otherwise the specified counter is used. This enables to have different
+ types of solutions sharing a common counter although this doesn't actually
+ make much sense. But it can be useful to avoid using an already existing
+ counter. \emph{This parameter can't be changed afterwards.} If the
+ explicit or implicit counter does not exist, yet, it will be defined. The
+ sole purpose of this counter is to be able to label solutions so they can
+ be \cs*{pageref}ed.
+ \paraval{number}{integer}
+ An internal parameter that is used to keep track of the number of
+ exercises of a type. This parameter cannot be set or changed by the
+ user.
+\end{parameters}
+
+It is possible to change some of the parameters after an exercise type has
+been defined. Those include \parameter{exercise-name},
+\parameter{solution-name}, \parameter{exercise-template}, and
+\parameter{solution-template}:
+\begin{commands}
+ \command{SetExerciseParameter}[\marg{type}\marg{parameter}\marg{value}]
+ Usable to set a single parameter to a new value.
+ \command{SetExerciseParameters}[\marg{type}\marg{parameters}]
+ Set several parameters at once. \meta{parameters} is a csv list of
+ key/value pairs.
+\end{commands}
+If you try to set an already set but fixed parameter like
+\parameter{exercise-env} a warning will be written to the log file. For all
+parameters that can be changed also options exist wich can be set via
+\cs{xsimsetup}. They are explained in
+section~\vref{sec:environment-options-hooks}.
+
+\begin{bewareofthedog}
+ All exercises of a type use the parameters
+ (\eg, \parameter{exercise-template}) that are \emph{currently active}. If
+ you want exercises with a different look or different names in the same
+ document you should use different exercises types.
+\end{bewareofthedog}
+
+\section{Exercise Properties}\label{sec:exercise-properties}
+
+\subsection{Predefined Properties}
+
+Exercise like the \env{exercise} environment and possibly others defined with
+\cs{DeclareExerciseType} have a number of predefined \acsp*{prop}:
+\begin{properties}
+ \propval{id}{integer}
+ Holds the internal id of an exercise. \emph{Cannot be set by the user}.
+ \propval{ID}{text}
+ Holds the user id of an exercise if defined. Otherwise it is equal to
+ \property{id}.
+ \propval{counter}{text}
+ Holds the counter value represenation of an exercise (\ie, what you
+ usually know as \cs*{the\meta{counter}}). \emph{Cannot be set by the
+ user}.
+ \propval{counter-value}{integer}
+ Holds the counter value of an exercise (\ie, what you usually know as
+ \cs*{arabic}\marg{counter}). \emph{Cannot be set by the user}.
+ \propval{subtitle}{text}
+ Holds the subtitle of an exercise.
+ \propval{points}{number}
+ Holds the reachable points of an exercise.
+ \propval{bonus-points}{number}
+ Holds the reachable bonus-points of an exercise.
+ \propbool{print}
+ Holds the print boolean of an exercise.
+ \propbool{print\bang}
+ Holds a special print boolean of an exercise, see
+ page~\pageref{property:print!}.
+ \propbool{use}
+ Holds the usage boolean of an exercise.
+ \propbool{use\bang}
+ Holds a special usage boolean of an exercise, see
+ page~\pageref{property:print!}.
+ \propbool{used}
+ True if an exercise has been used at least once. For an existing exercise
+ this is only false for exercises that have been collected
+ (\cf~section~\vref{sec:collecting-exercises}).
+ \propval{tags}{csv list of tags}
+ Holds the list of tags the exercise should be associated with.
+ \propval{topics}{csv list of topics}
+ Holds the list of topics the exercise should be associated with.
+ \propval{page}{text}
+ Holds the page counter value represenation of an exercise (\ie, what you
+ usually know as \cs*{thepage}).
+ \propval{page-value}{integer}
+ Holds the page counter value of an exercise (\ie, what you usually know as
+ \cs*{arabic}\Marg{page}).
+ \propval{section}{text}
+ Holds the section counter value represenation of an exercise (\ie, what
+ you usually know as \cs*{thesection}).
+ \propval{section-value}{integer}
+ Holds the section counter value of an exercise (\ie, what you usually know
+ as \cs*{arabic}\Marg{section}).
+ \propval{chapter}{text}
+ Holds the chapter counter value represenation of an exercise (\ie, what
+ you usually know as \cs*{thechapter}). \emph{Only if a command
+ \cs*{chapter} \emph{and} a counter \code{chapter} exist.}
+ \propval{chapter-value}{integer}
+ Holds the chapter counter value of an exercise (\ie, what you usually know
+ as \cs*{arabic}\Marg{chapter}). \emph{Only if a command \cs*{chapter}
+ \emph{and} a counter \code{chapter} exist.}
+ \propval{sectioning}{section numbers}
+ Holds five brace groups which in turn hold the section numbers (integers)
+ of the exercise in the order
+ \marg{chapter}\marg{section}\marg{subsection}\marg{subsubsection}\marg{paragraph}.
+\end{properties}
+
+Some of these \acsp*{prop} are fixed and cannot be set by the user. Those
+include \property{id}, \property{counter}, and \property{counter-value}. The
+others can be set using the optional argument of the exercise environment.
+
+\begin{example}
+ \begin{exercise}[subtitle={This is a subtitle},points=4,bonus-points=1]
+ An exercise where some properties have been set.
+ \end{exercise}
+\end{example}
+
+\subsection{Declaring Own Properties}
+
+\xsim\ offers the possibility to declare additional exercise properties:
+\begin{commands}
+ \command{DeclareExerciseProperty}[\barg\sarg\narg\marg{property}]
+ Declares the property \meta{property}.
+
+ If used with the optional \barg\ a \textbf{unique property} is defined
+ which means that each exercise must have a property value distinct from
+ all other exercises (all means all -- \emph{independent from the exercise
+ type}).
+
+ If used with the optional \sarg\ a \textbf{boolean property} is defined
+ which means that it only should get the values \code{true} or \code{false}
+ and if used without value it gets the value \code{true} instead of an
+ empty value. If any other value is used the property is set to
+ \code{false}. A boolean property obviously cannot be unique. The
+ optional \sarg\ takes precedence over the optional \barg, \ie, if both are
+ present the property is boolean \emph{but not} unique.
+
+ If used with the optional \narg\ a property is defined which won't get
+ updated through subsequent compilation runs but is only set when the
+ exercise is used.
+ \command{DeclareExercisePropertyAlias}[\marg{property 1}\marg{property 2}]
+ Declares \meta{property 1} to be an alias of \meta{property 2}. This
+ means that each time \meta{property 2} is set \meta{property 1} will be
+ set to the same value \emph{unless} it has been set already. As an
+ example: property \property{ID} is an alias of property \property{id}.
+\end{commands}
+
+This is better demonstrated with an example:
+\begin{example}
+ \begin{exercise}
+ \lipsum[4] % from package `lipsum'
+ \verb+\GetExerciseProperty{id}+: \GetExerciseProperty{id} \par
+ \verb+\GetExerciseAliasProperty{ID}+: \GetExerciseAliasProperty{ID} \par
+ \verb+\GetExerciseProperty{ID}+: \GetExerciseProperty{ID}
+ \end{exercise}
+ \begin{exercise}[ID=foo-bar]
+ \lipsum[4]
+ \verb+\GetExerciseProperty{id}+: \GetExerciseProperty{id} \par
+ \verb+\GetExerciseAliasProperty{ID}+: \GetExerciseAliasProperty{ID} \par
+ \verb+\GetExerciseProperty{ID}+: \GetExerciseProperty{ID}
+ \end{exercise}
+\end{example}
+
+The power of properties will get more clear when reading
+section~\vref{sec:styl-exerc-templ} about templates.
+
+\subsection[Exercise Goals]{A Special Kind of Property: Exercise Goals}\label{sec:goals}
+
+Exercise goals are a generic concept in \xsim\ for exercise properties like
+\property{points} or \property{bonus-points}. Those are properties which can
+(only) get a decimal number as value the sum of which is calculated and
+available (after a compilation) throughout the document.
+\begin{commands}
+ \command{DeclareExerciseGoal}[\marg{goal}]
+ Declare a new exercise goal named \meta{goal} and also a property called
+ \meta{goal}.
+ \command{TotalExerciseTypeGoal}[\marg{type}\marg{goal}\marg{singular}\marg{plural}]
+ Get the sum of goal \meta{goal} for all exercises of type \meta{type}.
+ \meta{singular} and \meta{plural} are placed after the sum in the input
+ stream depending on whether the sum equals~$1$ or not.
+ \command{TotalExerciseTypeGoals}[\marg{type}\marg{list of
+ goals}\marg{singular}\marg{plural}]
+ Get the sum of goal all goals in \meta{list of goals} for all exercises of
+ type \meta{type}. The goal names in \meta{list of goals} must be
+ separated with \code{+}. \meta{singular} and \meta{plural} are placed
+ after the sum in the input stream depending on whether the sum equals~$1$
+ or not.
+ \command{TotalExerciseGoal}[\marg{goal}\marg{singular}\marg{plural}]
+ Get the sum of goal \meta{goal} for all exercises. \meta{singular} and
+ \meta{plural} are placed after the sum in the input stream depending on
+ whether the sum equals~$1$ or not.
+ \command{TotalExerciseGoals}[\marg{list of
+ goals}\marg{singular}\marg{plural}]
+ Get the sum of goal all goals in \meta{list of goals} for all exercises.
+ The goal names in \meta{list of goals} must be separated with
+ \code{+}. \meta{singular} and \meta{plural} are placed after the sum in
+ the input stream depending on whether the sum equals~$1$ or not.
+ \command{AddtoExerciseTypeGoal}[\marg{type}\marg{goal}\marg{value}]
+ Adds \meta{value} to the goal \meta{goal} of exercise type \meta{type}.
+ \command{AddtoExerciseTypeGoalPrint}[\marg{type}\marg{goal}\marg{value}%
+ \marg{singular}\marg{plural}]
+ Adds \meta{value} to the goal \meta{goal} of exercise type \meta{type}.
+ The value and -- depending on wether the value equals $1$ or not --
+ \meta{singular} or \meta{plural} are left in the input stream.
+ \command{AddtoExerciseGoal}[\marg{goal}\marg{value}]
+ Adds \meta{value} to the goal \meta{goal} of the current exercise
+ type. (To be used within exercises.)
+ \command{AddtoExerciseTypeGoalPrint}[\marg{goal}\marg{value}%
+ \marg{singular}\marg{plural}]
+ Adds \meta{value} to the goal \meta{goal} of the current exercise type.
+ The value and -- depending on wether the value equals $1$ or not --
+ \meta{singular} or \meta{plural} are left in the input stream. (To be used
+ within exercises.)
+ \command{ExerciseGoalValuePrint}[\marg{value}\marg{singular}\marg{plural}]
+ Print \meta{value} and -- depending on wether the value equals $1$ or not --
+ \meta{singular} or \meta{plural}.
+ \command{printgoal}[\marg{value}]
+ Print \meta{value} according to option \option{goal-print}. Defined in
+ terms of \cs{ExerciseGoalValuePrint}.
+ \command{printpoints}[\marg{type}]
+ Print the sum of points for all exercises of type \meta{type} followed by
+ an appropriate translation of the words \enquote{point} or
+ \enquote{points}, respectively\footnote{See section~\vref{sec:exerc-transl}
+ for details on the definition and usage of language dependent words.}.
+ Defined in terms of \cs{TotalExerciseTypeGoal}.
+ \command{printtotalpoints}
+ Print the sum of points for all exercises followed by an appropriate
+ translation of the words \enquote{point} or \enquote{points},
+ respectively. Defined in terms of \cs{TotalExerciseGoal}.
+ \command{addpoints}[\sarg\marg{value}]
+ Adds \meta{value} to the points of the current exercise type. (To be used
+ within exercises.) Prints the value followed by an appropriate
+ translation of the words \enquote{point} or \enquote{points},
+ respectively. The starred version prints nothing. Defined in terms of
+ \cs{AddtoExerciseGoal} and \cs{AddtoExerciseGoalPrint}.
+ \command{points}[\marg{value}]
+ Print \meta{value}followed by an appropriate translation of the words
+ \enquote{point} or \enquote{points}, respectively. Defined in terms of
+ \cs{ExerciseGoalValuePrint}.
+ \command{printbonus}[\marg{type}]
+ Print the sum of bonus points for all exercises of type \meta{type}
+ followed by an appropriate translation of the words \enquote{point} or
+ \enquote{points}, respectively. Defined in terms of
+ \cs{TotalExerciseTypeGoal}.
+ \command{printtotalbonus}
+ Print the sum of bonus points for all exercises followed by an appropriate
+ translation of the words \enquote{point} or \enquote{points},
+ respectively. Defined in terms of \cs{TotalExerciseGoal}.
+ \command{addbonus}[\sarg\marg{value}]
+ Adds \meta{value} to the bonus points of the current exercise type. (To be
+ used within exercises.) Prints the value followed by an appropriate
+ translation of the words \enquote{point} or \enquote{points},
+ respectively. The starred version prints nothing. Defined in terms of
+ \cs{AddtoExerciseGoal} and \cs{AddtoExerciseGoalPrint}.
+\end{commands}
+
+The two existing goals are defined with
+\begin{sourcecode}
+ \DeclareExerciseGoal{points}
+ \DeclareExerciseGoal{bonus-points}
+\end{sourcecode}
+
+When goal values are printed the decimal number is fed to a function which can
+be changed using the following option:
+\begin{options}
+ \keyval{goal-print}{code}\Default{\#1}
+ How to format goal values. Use \code{\#1} to refer to the actual number.
+\end{options}
+
+At last some examples for a custom command: let's say you want a command which
+prints the complete sum for all exercises of all exercise types of both
+\property{points} \emph{and} \property{bonus-points} added up:
+\begin{sourcecode}
+ \NewDocumentCommand\printsumofpointsandbonus{}{%
+ \TotalExerciseGoals{points+bonus-points}
+ {\,\XSIMtranslate{point}}
+ {\,\XSIMtranslate{points}}%
+ }
+\end{sourcecode}
+Here is how you could mimick the command \cs*{totalpoints} from
+\pkg{exsheets}:
+\begin{sourcecode}
+ \NewDocumentCommand\pointsandbonus{}{%
+ \TotalExerciseGoal{points}{}{}%
+ \IfExerciseGoalsSumF{bonus-points}{=0}
+ {\,(+\,\TotalExerciseGoal{bonus-points}{}{})}%
+ \,\XSIMtranslate{points}%
+ }
+\end{sourcecode}
+
+
+\subsection[Exercise Tags]{A Special Kind of Property: Exercise Tags}\label{sec:tags}
+
+Exercise tags are a generic concept in \xsim\ for exercise properties like
+\property{tags} or \property{topics}. Those are properties which can (only)
+get a csv list of strings as value. Those strings can be used to selectively
+use exercises. See section~\vref{sec:using-printing} for details on
+\emph{usage} of exercises and the difference to \emph{printing} an exercise
+and how to use exercise tags for selection.
+\begin{commands}
+ \command{DeclareExerciseTagging}[\marg{tag}]
+ This defines an exercise tagging group named \meta{tag}. It also defines a
+ property named \meta{tag}. In addition two options are defined: an option
+ named \code{\meta{tag}} which can be used for selection and an boolean
+ option \code{\meta{tag}/ignore-untagged}.
+ \command{ProvideExerciseTagging}[\marg{tag}]
+ The\sinceversion{0.11} same as \cs{DeclareExerciseTagging} but does
+ nothing when \meta{tag} already exists.
+\end{commands}
+The two existing tagging groups have been defined and preset with the
+following code:
+\begin{sourcecode}
+ \DeclareExerciseTagging{tags}
+ \DeclareExerciseTagging{topics}
+ \xsimsetup{tags/ingore-untagged=false}
+\end{sourcecode}
+This means that these options are available:
+\begin{options}
+ \keyval{tags}{csv list of tags}
+ Choose the set of tags whose associated exercises should be printed.
+ \keyval{topics}{csv list of topics}
+ Choose the set of topics whose associated exercises should be printed.
+ \keybool{ignore-untagged}\Module{tags}\Default{false}
+ If set to true exercises with no tags will be printed even if tags have
+ been chosen with the option \option{tags}.
+ \keybool{ignore-untagged}\Module{topics}\Default{true}
+ If set to true exercises with no topics will be printed even if topics
+ have been chosen with the option \option{topics}.
+\end{options}
+
+It may happen that you choose certain tags for printing and want one or two
+exercises to be printed or used even if they don't match the tagging
+criteria. For this reason two additional properties exist which can be set to
+an exercise:\label{property:print!}
+\begin{properties}
+ \propbool{print\bang}
+ If set to true the exercise will be printed (and thus used) regardless of
+ other conditions.
+ \propbool{use\bang}
+ If set to true the exercise will be used regardless of other conditions.
+\end{properties}
+
+\section{Using and Printing an Exercise}\label{sec:using-printing}
+\subsection{What the Environments do}
+
+When an exercise is started with \environ{exercise} (or other environments
+defined through \cs{DeclareExerciseType}) then different things happen
+depending on different settings:
+\begin{itemize}
+ \item If the \emph{insert mode} is active nothing happens, see
+ section~\vref{sec:collecting-exercises} for details on this.
+ \item Else the id integer is incremented.
+ \item If the exercise is \emph{used} the corresponding counter is stepped
+ and the exercise is added to the \enquote{use list}. The properties
+ \property{counter} and \property{use} are updated accordingly.
+ \item If an exercise is \emph{printed} then it is also \emph{used}. An
+ exercise that isn't used cannot be printed. Being printed means two
+ things: being added to the \enquote{print list} and being typeset at the
+ position where the exercise is placed in the source file. If an exercise
+ is \emph{not printed but used} it means that the counter will be stepped.
+ This can be useful for creating an exercise sheet only containing the
+ solutions for some exercises.
+ \item If an exercise is printed certain hooks and template code is inserted
+ around the environment body.
+\end{itemize}
+
+\begin{example}
+ \begin{exercise}[print=false]
+ This exercise will not be printed but the exercise counter will be
+ incremented nonetheless. Its solution will be printed in the list of
+ solutions.
+ \end{exercise}
+ \begin{solution}
+ The solution of the exercise that has not been printed.
+ \end{solution}
+\end{example}
+
+The schematic structure of an exercise is shown in
+figure~\vref{fig:schematic-structure}.
+
+\begin{figure}
+ \centering
+ \begin{tikzpicture}
+ \node[draw,minimum width=.7\linewidth] at (0,0) {pre hook};
+ \node[draw,minimum width=.7\linewidth] at (0,-1) {begin template code};
+ \node[draw,minimum width=.7\linewidth] at (0,-2) {begin hook};
+ \node[draw,minimum width=.7\linewidth] at (0,-3) {environment body};
+ \node[draw,minimum width=.7\linewidth] at (0,-4) {end hook};
+ \node[draw,minimum width=.7\linewidth] at (0,-5) {end template code};
+ \node[draw,minimum width=.7\linewidth] at (0,-6) {post hook};
+ \end{tikzpicture}
+ \caption{Schematic structure of an exercise or solution.}\label{fig:schematic-structure}
+\end{figure}
+
+\subsection{Environment Options \& Hooks}\label{sec:environment-options-hooks}
+
+For each exercise type there are the following options for both environments,
+the environments' names are the module names for the options (here using the
+\enquote{exercise} type):
+\begin{options}
+ \keybool{print}\Module{exercise}\Default{true}
+ Determines if exercises of type \enquote{exercise} are printed.
+ \keybool{use}\Module{exercise}\Default{true}
+ Determines if exercises of type \enquote{exercise} are used.
+ \keyval{within}{counter}\Module{exercise}\Default
+ Adds the exercise counter to the reset list of the counter
+ \meta{counter}. \emph{Beware that if the counter is a shared counter
+ this will affect \emph{all objects} using this counter!}
+ \keyval{the-counter}{code}\Module{exercise}
+ An interface for redefining the counter representation command
+ \cs*{the\meta{counter}}.
+ \keyval{template}{template}\Module{exercise}
+ An interface for \cs{SetExerciseParameter}\Marg{exercise}%
+ \Marg{exercise-template}\marg{template}.
+ \keyval{template}{template}\Module{solution}
+ An interface for \cs{SetExerciseParameter}\Marg{exercise}%
+ \Marg{solution-template}\marg{template}.
+ \keyval{name}{name}\Module{exercise}
+ An interface for \cs{SetExerciseParameter}\Marg{exercise}%
+ \Marg{exercise-name}\marg{name}.
+ \keyval{name}{name}\Module{solution}
+ An interface for \cs{SetExerciseParameter}\Marg{exercise}%
+ \Marg{solution-name}\marg{name}.
+ \keyval{pre-hook}{code}\Module{exercise}\Default
+ The code for the \emph{pre exercise hook} for exercises of the type
+ \enquote{exercise}.
+ \keyval{begin-hook}{code}\Module{exercise}\Default
+ The code for the \emph{begin exercise hook} for exercises of the type
+ \enquote{exercise}.
+ \keyval{end-hook}{code}\Module{exercise}\Default
+ The code for the \emph{end exercise hook} for exercises of the type
+ \enquote{exercise}.
+ \keyval{post-hook}{code}\Module{exercise}\Default
+ The code for the \emph{post exercise hook} for exercises of the type
+ \enquote{exercise}.
+ \keybool{print}\Module{solution}\Default{false}
+ Determines if solutions of type \enquote{exercise} are printed.
+ \keyval{pre-hook}{code}\Module{solution}\Default
+ The code for the \emph{pre solution hook} for solutions of the type
+ \enquote{exercise}.
+ \keyval{begin-hook}{code}\Module{solution}\Default
+ The code for the \emph{begin solution hook} for solutions of the type
+ \enquote{exercise}.
+ \keyval{end-hook}{code}\Module{solution}\Default
+ The code for the \emph{end solution hook} for solutions of the type
+ \enquote{exercise}.
+ \keyval{post-hook}{code}\Module{solution}\Default
+ The code for the \emph{post solution hook} for solutions of the type
+ \enquote{exercise}.
+ % TODO
+\end{options}
+
+\subsection{(Re-) Inserting a Certain Exercise}
+If you know type and \property{id} of an exercise you can (re-)insert every
+existing exercise, \ie, every exercise whose external file exists.
+\begin{commands}
+ \command{printexercise}[\marg{type}\marg{id}]
+ Inserts the exercise of type \meta{type} with the \property{id}
+ \meta{id}.
+\end{commands}
+\begin{example}
+ \printexercise{exercise}{5}
+\end{example}
+
+\section{Collecting Exercises}\label{sec:collecting-exercises}
+
+\subsection{Background}
+\xsim\ knows the concept of \enquote{exercise collections}. A collection of
+exercises can be useful when you want to print a certain group of exercises
+several times. Each collection must have a unique name with which you can
+refer to the corresponding collection. A collection is realized by declaring
+the collection and by surrounding the exercises belonging to the collection
+with a certain pair of commands (this is explained in the next section).
+
+Let's say you have several files of math exercises where one only contains
+geometry exercises and another only calculus exercises and so on. Surrounding
+the \cs*{input} of each file with said pair of commands for a certain
+collection all exercises of the corresponding file now are a collection which
+then can be printed at once whereever you want the collection of exercises to
+be printed. By choosing certain tags (see section~\vref{sec:tags}) inside
+each collection you could even cherry-pick exercises from the external file.
+
+\subsection{Usage}
+\emph{A collection must be declared in the preamble.} Using a pair of
+commands explained below exercises between those commands are added to the
+corresponding collection but not printed. After a collection is completed the
+collection can be printed as often as needed.
+\begin{commands}
+ \command{DeclareExerciseCollection}[\marg{collection name}]
+ Define a new collection \meta{collection name} in the document preamble.
+ \command{collectexercisestype}[\marg{collection name}\marg{exercise type}]
+ Opens the collection \meta{collection name} which now collects all
+ exercises of type \meta{exercise type} until the collection is closed with
+ \cs{collectexercisesstop}. Collections of other types are not
+ collected\footnote{This command starts a group with
+ \cs*{begingroup}!}.
+ \command{collectexercises}[\marg{collection name}]
+ Opens the collection \meta{collection name} which now collects all
+ exercises until the collection is closed with
+ \cs{collectexercisesstop}\footnote{This command starts a group with
+ \cs*{begingroup}!}.
+ \command{collectexercisesstop}[\marg{collection name}]
+ Closes the collection \meta{collection name}\footnote{This command ends
+ a group with \cs*{endgroup}!}.
+ \command{printcollection}[\oarg{options}\marg{collection name}]
+ Prints the collection \meta{collection name}, \ie, all exercises collected
+ earlier. This command cannot be used before the corresponding collection
+ has been closed correctly.
+\end{commands}
+
+Valid options are the following:
+\begin{options}
+ \keybool{headings}\Module{print-collection}\Default{false}
+ If true a heading for each exercise type is inserted.
+ \keyval{headings-template}{template}\Module{print-collection}\Default{collection}
+ The heading template used when \keyis{headings}{true}.
+ \keychoice{print}{exercises,solutions,both}\Module{print-collection}\Default{exercises}
+ Determines wether \cs{printcollection} prints the exercises or the
+ solutions of the collection. When you choose \code{both} exercises and
+ solutions are printed alternately.
+\end{options}
+
+Those options can also be set via \cs{xsimsetup} using the module
+\module{print-collection}.
+
+\begin{bewareofthedog}
+ Please be aware that exercises are not used or printed while they are
+ collected. Nonetheless the property \property{use} is set to \code{true}
+ (so that solutions can be printed even if the exercises are not) and the
+ property \property{print} is set to \code{false}. Also their counters are
+ \emph{not stepped} during the process. This only happens when they are
+ printed the first time, \cf~the \property{used} property. At that time
+ also the properties \property{page}, \property{section} and
+ \property{chapter} are set and the property \property{print} is set to
+ \code{true}.
+\end{bewareofthedog}
+
+The usage should be clear:
+\begin{example}
+ \collectexercises{foo}
+ \begin{exercise}
+ This exercise is added to the collection `foo'.
+ \end{exercise}
+ \begin{exercise}
+ This exercise is also added to the collection `foo'.
+ \end{exercise}
+ \begin{exercise}
+ So is this.
+ \end{exercise}
+ \begin{exercise}
+ As well as this one.
+ \end{exercise}
+ \collectexercisesstop{foo}
+\end{example}
+Once the collection is closed it can be printed:
+\begin{example}
+ \printcollection{foo}
+\end{example}
+
+You can open several collections at the same time:
+\begin{sourcecode}
+ \collectexercises{foo}
+ ...
+ \collectexercisestype{bar}{exercises}
+ ...
+ \collectexercisesstop{bar}
+ ...
+ \collectexercisesstop{foo}
+\end{sourcecode}
+Exercises will be added to each open collection.
+
+There is one generic collection called \enquote{\code{all exercises}}. As the
+name already suggests it will hold all exercises. So if you say
+\begin{sourcecode}
+ \printcollection{all exercises}
+\end{sourcecode}
+all exercises will be printed.
+
+\begin{bewareofthedog}
+ If you use \cs*{label}s inside of exercises and you print exercises more
+ than once in your document (by reusing a collection for example) you will
+ get
+\begin{sourcecode}
+ LaTeX Warning: There were multiply-defined labels.
+\end{sourcecode}
+ Equally if you have environments like \environ{equation} which step a
+ counter inside an exercise or solution the counter will be stepped each time
+ the exercise is used.
+\end{bewareofthedog}
+
+At last now an example using external files, collections and tags:
+\begin{sourcecode}
+ % preamble:
+ % \DeclareExerciseCollection{foo-easy}
+ % \DeclareExerciseCollection{foo-medium}
+ % \DeclareExerciseTagging{difficulty}
+
+ % document:
+ \collectexercises{foo-easy}
+ \xsimsetup{difficulty=easy}
+ \input{foo.tex}
+ \collectexercisesstop{foo-easy}
+ % collection `foo-easy' now contains all exercises of file `foo.tex' tagged
+ % with `difficulty=easy'
+
+ \collectexercises{foo-medium}
+ \xsimsetup{difficulty=medium}
+ \input{foo.tex}
+ \collectexercisesstop{foo-medium}
+ % collection `foo-medium' now contains all exercises of file `foo.tex'
+ % tagged with `difficulty=medium'
+\end{sourcecode}
+
+\begin{bewareofthedog}
+ The recommended usage is similar to the last example. Actually a collection
+ can be printed \emph{before} it is opened, too. (This needs \emph{at least}
+ two compilations, though.) However, it is safer printing a collection only
+ once and only \emph{after it has been collected}. No guaranties are given
+ that properties are set correctly if you use the collection before. You
+ usually also will make sure that the exercises in a collection are unique,
+ \ie, that an exercise is not part of several collections -- at least not if
+ both collections are printed in the same document.
+\end{bewareofthedog}
+
+\section{Printing Random Exercises From a Collection}
+\xsim\ provides the possibility of selecting random exercises from a
+collection (\cf~section~\vref{sec:collecting-exercises}).
+\begin{bewareofthedog}
+ Please be aware that this feature is \emph{not} available in \XeLaTeX!
+\end{bewareofthedog}
+\begin{commands}
+ \command{printrandomexercises}[\oarg{options}\marg{number}]
+ This command prints \meta{number} random exercises from the collection
+ chosen with option \option{collection}, see below. When this command is
+ used it generates a random list of integers which is written to the
+ \code{aux} file. On the subsequent compilations the according exercises
+ are printed. \emph{If you want to regenerate the random list you have to
+ delete the \code{aux} file before compiling.}
+\end{commands}
+Valid options for this command are:
+\begin{options}
+ \keybool{sort}\Module{random}\Default{true}
+ Determines wether the random chosen exercises should be sorted according
+ to their order of definition in the collection or not.
+ \keyval{collection}{collection}\Module{random}\Default{all exercises}
+ The collection from which the exercises are to be chosen from.
+ \keyval{exclude}{csv list of ids}\Module{random}
+ A list of \property{id}s or \property{ID}s of exercises \emph{not} to be
+ chosen.
+ \keychoice{print}{exercises,solutions,both}\Module{random}\Default{exercises}
+ Determines wether \cs{printrandomexercises} prints the exercises or the
+ solutions. When you choose \code{both} exercises and solutions are
+ printed alternately.
+\end{options}
+
+\begin{example}
+ \printrandomexercises[collection=foo]{2}
+\end{example}
+
+The example above of course doesn't make much sense but if you have a
+collection which collects exercises from an external file and the exercises
+haven't been printed in the document before then you will get a list of
+subsequently numbered exercises.
+
+\section{Printing Solutions}\label{sec:printing-solutions}
+
+There are different commands for printing the solutions to exercises:
+\begin{commands}
+ \command{printsolutionstype}[\sarg\oarg{options}\marg{exercise type}]
+ Prints the solutions of all used exercises of type \meta{exercise type}.
+ The starred version only prints the solutions of all printed exercises of
+ type \meta{exercise type}.
+ \command{printsolutions}[\sarg\oarg{options}]
+ Prints the solutions of all used exercises of all types ordered by type.
+ The starred version only prints the solutions of all printed exercises of
+ all types.
+ \command{printallsolutions}[\sarg\oarg{options}]
+ Prints the solutions of all used exercises of all types ordered by
+ appearance in the document. The starred version only prints the solutions
+ of all printed exercises of all types.
+ \command{printsolution}[\oarg{options}\marg{type}\marg{id}]
+ Prints the solution of the exercise of type \meta{type} with the
+ \property{id} \meta{id}.
+\end{commands}
+
+\begin{example}
+ \printsolutionstype{exercise}
+\end{example}
+
+The options can be divided into two groups. The ones in the first group
+modify the layout.
+\begin{options}
+ \keybool{headings}\Module{print-solutions}\Default{true}
+ If true a heading for each exercise type is inserted.
+ \keyval{headings-template}{template}\Module{print-solutions}\Default{default}
+ The heading template used when \keyis{headings}{true}.
+\end{options}
+
+The ones in the second group set conditions selecting which solutions are
+printed. If you combine those conditions a solution is printed if it meets
+either of the conditions.
+\begin{options}
+ \keychoice{section}{\default{true},false,\meta{integer}}\Module{print-solutions}%
+ \Default{false}
+ If you set \keyis{section}{true} only solutions of exercises of the
+ current section are printed. If you set \keyis{section}{4} only solutions
+ of exercises in a section with number~$4$ are printed.
+ \keychoice{chapter}{\default{true},false,\meta{integer}}\Module{print-solutions}%
+ \Default{false}
+ If you set \keyis{chapter}{true} only solutions of exercises of the
+ current chapter are printed. If you set \keyis{chapter}{4} only solutions
+ of exercises in a chapter with number~$4$ are printed.
+ \keychoice{collection}{false,\meta{collection name}}\Module{print-solutions}%
+ \Default{false}
+ If used only solutions of exercises belonging to collection
+ \meta{collection name} are printed.
+\end{options}
+
+The conditions can be combined. The following call will only print solutions
+from exercises in section~3 of chapter~2:
+\begin{sourcecode}
+ \printsolutions[chapter=2,section=3]
+\end{sourcecode}
+
+\begin{bewareofthedog}
+ The selection per section or per chapter relies on the \emph{counter
+ numbers} of the sections or chapters, respectively. This means if section
+ numbers are reset (\eg\ by \cs*{chapter} or \cs*{appendix}) and you have
+ exercises from \emph{different} sections with \emph{the same section number}
+ the solutions of \emph{all those exercises} will be printed. This means you
+ only should use the \option{section} selection when section are the top
+ document level headings (apart from parts) and you have no exercises in the
+ appendix. Similar considerations are valid for the \option{chapter}
+ selection.
+\end{bewareofthedog}
+
+All options can also be set via \cs{xsimsetup} using the module
+\module{print-solutions}.
+
+\begin{example}
+ \printsolutions[section=4,headings-template=per-section]
+\end{example}
+
+\begin{example}
+ \printsolution{exercise}{5}
+\end{example}
+
+\section{Grading Tables}\label{sec:grading-tables}
+When you create exercises it may not only be desirable to be able to add
+points and bonus-points to a question (see section~\vref{sec:goals} about
+exercise goals) but also to be able to output a grading table. \xsim\ has
+built-in means for this.
+\begin{commands}
+ \command{gradingtable}[\oarg{options}]
+ Print a grading table.
+\end{commands}
+Valid options for this command are
+\begin{options}
+ \keyval{template}{template}\Default{default}
+ Choose the template used for the grading table.
+ \keyval{type}{exercise type}\Default
+ Choose the exercise type for which the table is printed.
+\end{options}
+Both option defaults can be changed with \cs{xsimsetup} setting the options
+using \module{grading-table}:
+\begin{sourcecode}
+ \xsimsetup{
+ grading-table/template = default*
+ }
+\end{sourcecode}
+
+An example:
+\begin{example}
+ \gradingtable[type=exercise]
+\end{example}
+
+Or using the \enquote{\code{default*}} template:
+\begin{example}
+ \gradingtable[template=default*,type=exercise]
+\end{example}
+
+Available templates and how to define new ones are explained in
+sections~\vref{sec:grad-table-templ} and~\vref{sec:template-examples}. \xsim\
+per default provides two templates \enquote{\code{default}} and
+\enquote{\code{default*}}, the first one has a vertical layout, the second a
+horizontal layout. Both templates can be used per type like in the examples
+above or for all types at once by leaving the specification \option{type}
+away:
+\begin{example}
+ \gradingtable
+\end{example}
+
+\section{Styling the Exercises -- Templates}\label{sec:styl-exerc-templ}
+
+\subsection{Background}
+Whenever \xsim\ outputs something to be typeset it uses so-called templates
+for the task. \xsim\ knows of three different kinds of templates:
+\begin{itemize}
+ \item environment templates (see section~\vref{sec:envir-templ}),
+ \item heading templates (see section~\vref{sec:heading-templates}) and
+ \item grading table templates (see section~\vref{sec:grad-table-templ})
+\end{itemize}
+
+The most important one for the styling of the exercises are the environment
+templates. Those templates give you complete control over the look and
+arrangement of an exercise. To be able to do this \xsim\ provides a large
+number of commands which can be used only inside template
+definitions\footnote{The last sentence is wrong: those commands can be used
+ anywhere but most of them only give useful results inside of templates.}.
+Those commands are explained in the next section. Their usage will hopefully
+become clear in the examples in section~\vref{sec:template-examples}. Having
+full control over the layout comes at a price: you need to be able to program
+yourself in order to achieve certain layouts\footnote{I plan to incorporate
+ the most common layouts -- and maybe some fancy ones, too -- in the examples
+ section~\vref{sec:template-examples} but at the time of writing this is still
+ up in the air.}.
+
+\subsection{Templates Provided by the Package}
+\xsim\ comes with a few predefined layouts:
+\begin{description}
+ \item[\code{default}] The template activated per default and the only one
+ available without further action.
+ \item[\code{runin}] A layout rather similar to the one by package
+ \pkg{exsheets}, see section~\vref{sec:runin-template}. Available through
+ the style file \code{layouts} (see section~\vref{sec:style-files} for more
+ information on style files\index{style file}).
+ \item[\code{margin}] A layout rather similar to the one by package
+ \pkg{exsheets}, see section~\ref{sec:margin-template}. Available through
+ the style file \code{layouts} (see section~\vref{sec:style-files} for more
+ information on style files\index{style file}).
+\end{description}
+
+\collectexercises{layouts}
+\begin{exercise}[subtitle=The Subtitle,points=2.5,ID=showlayout]
+ Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Ut purus elit,
+ vestibulum ut, placerat ac, adipiscing vitae, felis. Curabitur dictum
+ gravida mauris. Nam arcu libero, nonummy eget, consectetuer id, vulputate a,
+ magna. Donec vehicula augue eu neque. Pellentesque habitant morbi tristique
+ senectus et netus et malesuada fames ac turpis egestas. Mauris ut leo. Cras
+ viverra metus rhoncus sem.
+\end{exercise}
+\collectexercisesstop{layouts}
+
+\listlayouts
+
+\subsection{Commands for Usage in Template Definitions}
+\subsubsection{Goals}
+\begin{commands}
+ \command{IfExerciseGoal\TF}[\marg{goal}\marg{relation and
+ value}\marg{true}\marg{false}]
+ Checks the sum of goal \meta{goal} against \meta{relation and value}.
+ \command{IfExerciseGoalSingular\TF}[\marg{goal}\marg{true}\marg{false}]
+ Checks if the value of the goal \meta{goal} of the current exercise
+ equals~$1$. This is the same as \\
+ \cs{IfExerciseGoalTF}\marg{goal}\Marg{=1}\marg{true}\marg{false}.
+ \command{IfExerciseTypeGoalsSum\TF}[\marg{type}\marg{list of
+ goals}\marg{relation and value}\marg{true}\marg{false}]
+ Ckecks the sum of all goals in \meta{list of goals} for the exercises of
+ type \meta{type} against \meta{relation and value}.
+ \command{IfExerciseGoalsSum\TF}[\marg{type}\marg{list of
+ goals}\marg{relation and value}\marg{true}\marg{false}]
+ Ckecks the sum of all goals in \meta{list of goals} for all exercises of
+ all types against \meta{relation and value}.
+ \command{TotalExerciseTypeGoal}[\marg{goal}\marg{type}\marg{singular}\marg{plural}]
+ Print the sum of goal \meta{goal} for the exercises of type \meta{type}
+ and append \meta{singular} or \meta{plural} depending on wether the sum
+ equals~$1$ or not.
+ \command{TotalExerciseGoal}[\marg{goal}\marg{singular}\marg{plural}]
+ Print the sum of goal \meta{goal} for all exercises of all types
+ and append \meta{singular} or \meta{plural} depending on wether the sum
+ equals~$1$ or not.
+\end{commands}
+
+\subsubsection{Properties}
+\begin{commands}
+ \expandable\command{IfExercisePropertyExist\TF}[\marg{property}\marg{true}%
+ \marg{false}]
+ Tests wether an exercise property with the name \meta{property} is defined.
+ \command{IfExercisePropertySet\TF}[\marg{property}\marg{true}\marg{false}]
+ Tests wether the exercise property \meta{property} has been set for the
+ current exercise.
+ \expandable\command{GetExerciseProperty}[\marg{property}]
+ Retrieves the value of the property \meta{property} for the current
+ exercise.
+ \command{GetExerciseProperty\TF}[\marg{property}\marg{true}\marg{false}]
+ Tests wether the exercise property \meta{property} has been set for the
+ current exercise. Inside the \meta{true} branch you can refer to the
+ retrieved value either with \code{\#1} or with \cs{PropertyValue}.
+ \emph{This command expands its contents inside a group.}
+ \command{GetExerciseBody}[\Marg{exercise\textnormal{|}solution}]
+ \sinceversion{0.10}Retrieves the environment body of either the
+ \code{exercise} or the corresponding \code{solution} of the current
+ exercise.
+ \expandable\command{GetExerciseIdForProperty}[\marg{property}\marg{value}]
+ Retrieves the property \property{id} of the exercise where the property
+ \meta{property} has the value \meta{value}. \emph{This only works for
+ \emph{unique} properties!}
+ \command{GetExerciseTypeForProperty}[\marg{property}\marg{value}]
+ Retrieves the property \property{type} of the exercise where the
+ property \meta{property} has the value \meta{value}. \emph{This only
+ works for \emph{unique} properties!}
+ \command{SetExerciseProperty}[\marg{property}\marg{value}]
+ \changedversion{0.9}Set the property \meta{property} of the current
+ exercise to \meta{value}.
+ \command{SetExpandedExerciseProperty}[\marg{property}\marg{value}]
+ \sinceversion{0.9}Expand \meta{value} \cs*{edef}-like and set the property
+ \meta{property} of the current exercise to the result of the expansion.
+ \command{ExerciseSetProperty}[\marg{type}\marg{id}\marg{property}\marg{value}]
+ \sinceversion{0.9}Set the property \meta{property} of the exercise of type
+ \meta{type} and id \meta{id} to \meta{value}.
+ \command{ExerciseSetExpandedProperty}[\marg{type}\marg{id}\marg{property}\marg{value}]
+ \sinceversion{0.9}Expand \meta{value} \cs*{edef}-like and set the property
+ \meta{property} of the exercise of type \meta{type} and id \meta{id} to
+ the result of the expansion.
+ \expandable\command{IfExerciseBooleanProperty\TF}[\marg{property}%
+ \marg{true}\marg{false}]
+ Checks wether the boolean property \meta{property} has value \code{true}
+ or \meta{false} and leaves the corresponding argument in the input
+ stream. Gives an error if \meta{property} is not a boolean property.
+ \expandable\command{GetExerciseAliasProperty}[\marg{property}]
+ Retrieves the value of the property of which \meta{property} is an alias
+ of for the current exercise.
+ \command{SaveExerciseProperty}[\marg{property}\meta{macro}]
+ Saves the value of the property \meta{property} for the current
+ exercise in macro \meta{macro}.
+ \command{GlobalSaveExerciseProperty}
+ Globally saves the value of the property \meta{property} for the current
+ exercise in macro \meta{macro}.
+ \command{ExercisePropertyIfSet\TF}[\marg{type}\marg{id}\marg{property}%
+ \marg{true}\marg{false}]
+ Test if the property \meta{property} has been set for the exercise of type
+ \meta{type} with id \meta{id}.
+ \expandable\command{ExercisePropertyGet}[\marg{type}\marg{id}\marg{property}]
+ Retrieves the value of the property \meta{property} for the exercise of type
+ \meta{type} with id \meta{id}.
+ \expandable\command{ExercisePropertyGetAlias}[\marg{type}\marg{id}\marg{property}]
+ Retrieves the value of the property of which \meta{property} is an alias
+ of for the exercise of type \meta{type} with id \meta{id}.
+ \command{ExercisePropertySave}[\marg{type}\marg{id}\marg{property}\meta{macro}]
+ Saves the value of the property \meta{property} for the exercise of type
+ \meta{type} with id \meta{id} in macro \meta{macro}.
+ \command{ExercisePropertyGlobalSave}[\marg{type}\marg{id}\marg{property}\meta{macro}]
+ Globally saves the value of the property \meta{property} for the exercise
+ of type \meta{type} with id \meta{id} in macro \meta{macro}.
+\end{commands}
+
+\subsubsection{Parameters}
+\begin{commands}
+ \expandable\command{GetExerciseParameter}[\marg{parameter}]
+ Retrieves the value of the parameter \meta{paramater} for the current
+ exercise type.
+ \command{GetExerciseParameter\TF}[\marg{parameter}\marg{true}\marg{false}]
+ \sinceversion{0.9}Retrieves the value of the parameter \meta{paramater}
+ for the current exercise type. Inside the \meta{true} branch you can refer
+ to the retrieved value either with \code{\#1} or with \cs{ParameterValue}.
+ \emph{This command expands its contents inside a group.}
+ \expandable\command{GetExerciseName}
+ Retrieves the value of the parameter \parameter{exercise-name} for the
+ current exercise or of the parameter \parameter{solution-name} for the
+ current solution.
+ \expandable\command{ExerciseParameterGet}[\marg{type}\marg{parameter}]
+ Retrieves the value of the parameter \meta{parameter} for the exercise of type
+ \meta{type} with id \meta{id}.
+ \expandable\command{IfExerciseParameterSet\TF}[\marg{parameter}%
+ \marg{true}\marg{false}]
+ \sinceversion{0.9}Test if the parameter \meta{parameter} has been set for
+ the current exercise type.
+ \expandable\command{ExerciseParameterIfSet\TF}[\marg{type}\marg{parameter}%
+ \marg{true}\marg{false}]
+ \sinceversion{0.9}Test if the parameter \meta{parameter} has been set for
+ the exercise type \meta{type}.
+\end{commands}
+
+\subsubsection{Tags}
+\begin{commands}
+ \command{ForEachExerciseTag}[\marg{type}\marg{code}]
+ Loops over all tags of tag type \meta{type} for the current exercise
+ applying \meta{code} each time. Inside \meta{code} you can refer to the
+ corresponding tag with \code{\#1}.
+ \command{ListExerciseTags}[\marg{type}\marg{between}]
+ Lists all tags of tag type \meta{type} for the current exercise using
+ \meta{between} as a separator.
+ \command{UseExerciseTags}[\marg{type}\marg{between
+ two}\marg{between}\marg{between last two}]
+ Lists all tags of tag type \meta{type} for the current exercise using
+ \meta{between} as a separator and \meta{between last two} as separator
+ between the last two tags of the list. If the list only consists of two
+ tags \meta{between two} is used as separator.
+ \command{IfExerciseTagSet\TF}[\marg{value}\marg{true}\marg{false}]
+ In\sinceversion{0.11} order to insert text (also \emph{outside} of
+ exercises) depending on the chosen tags this command lets you check if
+ value \meta{value} has been set for \property{tags}.
+ \command{IfExerciseTopicSet\TF}[\marg{value}\marg{true}\marg{false}]
+ In\sinceversion{0.11} order to insert text (also \emph{outside} of
+ exercises) depending on the chosen tags this command lets you check if
+ value \meta{value} has been set for \property{topics}.
+\end{commands}
+
+\subsubsection{Further Commands for Usage in Template Definitions}
+\begin{commands}
+ \command{UseExerciseTemplate}[\marg{type}\marg{name}]
+ Retrieve template \meta{name} of type \meta{type}. This can be useful if
+ you want to define a template which just adds some code to an existing
+ template (an automated \cs*{label}, say).
+ \expandable\command{ExerciseType}
+ Can be used to refer to the current exercise type.
+ \expandable\command{ExerciseID}
+ Can be used to refer to the current exercise id.
+ \expandable\command{ExerciseCollection}
+ Can be used in certain templates to refer to the collection that is
+ currently inserted.
+ \expandable\command{numberofusedexercises}
+ Holds the total number of used exercises. Useful in table template
+ definitions.
+ \expandable\command{ExerciseTableType}[\marg{code}]
+ In table template definitions this macro either expands to the given
+ exercise type or -- if no type has been given -- to \meta{code}.
+ \expandable\command{IfInsideSolution\TF}[\marg{true}\marg{false}]
+ Tests if the template is used inside a solution environment or not.
+ \expandable\command{IfSolutionPrint\TF}[\marg{true}\marg{false}]
+ Tests if the option \option{print} for the solutions of the current
+ \cs{ExerciseType} is set to \code{true} or \code{false}.
+ \command{IfExistSolution\TF}[\marg{true}\marg{false}]
+ \sinceversion{0.9}Tests if a solution for the current exercise exists.
+ \command{ForEachPrintedExerciseByType}[\marg{code}]
+ Loops over each \emph{printed} exercise ordered by the exercise types and
+ within each type by id. Inside \meta{code} you can refer to several
+ properties of the corresponding exercise:
+ \begin{itemize}
+ \item \code{\#1}: the type of the exercise
+ \item \code{\#2}: the id of the exercise
+ \item \code{\#3}: the \property{counter} property of the exercise
+ \item \code{\#4}: the \property{subtitle} property of the exercise
+ \item \code{\#5}: the \property{points} property of the exercise
+ \item \code{\#6}: the \property{bonus-points} property of the exercise
+ \end{itemize}
+ \command{ForEachUsedExerciseByType}[\marg{code}]
+ Loops over each \emph{used} exercise ordered by the exercise types and
+ within each type by id. Inside \meta{code} you can refer to several
+ properties of the corresponding exercise:
+ \begin{itemize}
+ \item \code{\#1}: the type of the exercise
+ \item \code{\#2}: the id of the exercise
+ \item \code{\#3}: the \property{counter} property of the exercise
+ \item \code{\#4}: the \property{subtitle} property of the exercise
+ \item \code{\#5}: the \property{points} property of the exercise
+ \item \code{\#6}: the \property{bonus-points} property of the exercise
+ \end{itemize}
+ \command{ForEachPrintedExerciseByID}
+ Loops over each \emph{printed} exercise order by the exercise id. Inside
+ \meta{code} you can refer to several properties of the corresponding
+ exercise:
+ \begin{itemize}
+ \item \code{\#1}: the type of the exercise
+ \item \code{\#2}: the id of the exercise
+ \item \code{\#3}: the \property{counter} property of the exercise
+ \item \code{\#4}: the \property{subtitle} property of the exercise
+ \item \code{\#5}: the \property{points} property of the exercise
+ \item \code{\#6}: the \property{bonus-points} property of the exercise
+ \end{itemize}
+ \command{ForEachUsedExerciseByID}
+ Loops over each \emph{used} exercise order by the exercise id. Inside
+ \meta{code} you can refer to several properties of the corresponding
+ exercise:
+ \begin{itemize}
+ \item \code{\#1}: the type of the exercise
+ \item \code{\#2}: the id of the exercise
+ \item \code{\#3}: the \property{counter} property of the exercise
+ \item \code{\#4}: the \property{subtitle} property of the exercise
+ \item \code{\#5}: the \property{points} property of the exercise
+ \item \code{\#6}: the \property{bonus-points} property of the exercise
+ \end{itemize}
+ \expandable\command{XSIMtranslate}[\marg{keyword}]
+ Delivers the translation of \meta{keyword} according to the current
+ document language (in the meaning of a \pkg{babel}~\cite{pkg:babel} or
+ \pkg{polyglossia}~\cite{pkg:polyglossia} language). Existing keywords and
+ keyword translations (and how to add new ones) are explained in
+ section~\vref{sec:exerc-transl}.
+ \command{XSIMexpandcode}[\marg{code}]
+ Expands \meta{code} like \cs*{edef} does and leaves the result in the
+ input stream.
+ \expandable\command{XSIMifchapter\TF}[\marg{true}\marg{false}]
+ Returns \meta{true} if both a macro \cs*{chapter} and a counter
+ \code{chapter} are defined and \meta{false} otherwise.
+ \command{XSIMmixedcase}[\marg{code}]
+ Converts the full expansion\footnote{This is a \cs*{romannumeral}
+ expansion~\cite{texsx:romannumeral}.\label{fn:romannumeral}} of
+ \meta{code} to mixed case: \\
+ \verbcode+\XSIMmixedcase{this is some text}+ \XSIMmixedcase{this is some
+ text} \\
+ \emph{This command expands \meta{code} before converting it}.
+ \command{XSIMputright}[\meta{macro}\marg{code}]
+ Extends the macro definition of \meta{macro} with \meta{code} putting it
+ to the right. This is more or less a local version of the LaTeX kernel
+ macro \cs*{g@addto@macro}.
+ \expandable\command{XSIMifeq\TF}[\marg{code 1}\marg{code
+ 2}\marg{true}\marg{false}]
+ Checks if the full expansion\footref{fn:romannumeral} of \meta{code 1} and
+ \meta{code 2} is the same tokenlist.
+ \expandable\command{XSIMifblank\TF}[\marg{code}\marg{true}\marg{false}]
+ Checks if the full expansion\footref{fn:romannumeral} of \meta{code} is
+ blank (\ie, if it is empty or only consists of spaces).
+\end{commands}
+
+\subsection{Declaring Templates}
+\subsubsection{Environment Templates}\label{sec:envir-templ}
+\begin{commands}
+ \command{DeclareExerciseEnvironmentTemplate}[\marg{name}\marg{begin
+ code}\marg{end code}]
+ Declare the environment template \meta{name}.
+\end{commands}
+Environment templates are used by the exercise and solution environments.
+Those are the templates set with the parameters \parameter{exercise-template}
+and \parameter{solution-template}.
+
+The predefined template is called \enquote{\code{default}}, see
+section~\vref{sec:exercise-templ-default}.
+
+\subsubsection{Heading Templates}\label{sec:heading-templates}
+\begin{commands}
+ \command{DeclareExerciseHeadingTemplate}[\marg{name}\marg{code}]
+ Declare the heading template \meta{name}.
+\end{commands}
+Heading templates are used by \cs{printsolutions}, \cs{printsolutionstype} and
+\cs{printcollection}. Those are the templates set with the option
+\option{headings-template} of the modules \module{print-solutions} and
+\module{print-collection}.
+
+The predefined templates are \enquote{\code{default}},
+\enquote{\code{collection}}, \enquote{\code{per-section}} and
+\enquote{\code{per-chapter}} see section~\vref{sec:headings-templates}.
+
+\subsubsection{Grading Table Templates}\label{sec:grad-table-templ}
+\begin{commands}
+ \command{DeclareExerciseTableTemplate}[\marg{name}\marg{code}]
+ Declare the grading table template \meta{name}.
+\end{commands}
+Table templates are used by \cs{gradingtable}. Those are the templates set
+with the option \option{template} of module \module{grading-table}
+
+The predefined templates are \enquote{\code{default}} and
+\enquote{\code{default}}, see sections~\vref{sec:table-templ-default}
+and~\vref{sec:table-templ-default*}.
+
+\subsection{Examples}\label{sec:template-examples}
+
+The repository of this package\footnote{GitHub:
+ \url{https://github.com/cgnieder/xsim/}, CTAN:
+ \url{http://www.ctan.org/pkg/xsim/}} currently includes
+\theexamplefiles~example documents demonstrating how different aspects of this
+package work or how different kinds of problems can be solved or how different
+kinds of layouts can be achieved as well as how solve concrete problems that
+have come up in different \LaTeX\ forums, see
+section~\vref{sec:example-files}.
+
+\subsubsection{The \code{default} Exercise Template}\label{sec:exercise-templ-default}
+
+Below the definition of the \code{default} exercise template provided by
+\xsim\ is shown:
+
+\begin{sourcecode}
+ \DeclareExerciseEnvironmentTemplate{default}{%
+ \subsection*
+ {%
+ \XSIMmixedcase{\GetExerciseName}\nobreakspace
+ \GetExerciseProperty{counter}%
+ \IfInsideSolutionF
+ {%
+ \GetExercisePropertyT{subtitle}
+ { {\normalfont\itshape\PropertyValue}}%
+ }%
+ }
+ \GetExercisePropertyT{points}
+ {%
+ \marginpar
+ {%
+ \IfInsideSolutionF{\rule{1.2cm}{1pt}\slash}%
+ \printgoal{\PropertyValue}
+ \GetExercisePropertyT{bonus-points}{~(+\printgoal{\PropertyValue})}%
+ ~\XSIMtranslate {point-abbr}%
+ }%
+ }%
+ }
+ {}
+\end{sourcecode}
+
+\subsubsection{A New Exercise Type Using \pkg*{tcolorbox}}
+Let's say we want exercises to be put in a \env*{tcolorbox}. We want a bold
+title and. if given, an italic subtitle. Exercises should also have the
+points after the subtitle in parentheses if given. Let's also say we want
+those to be an additional exercise type in addition to the ones \xsim\ already
+provides. This is shown with the following code which is also how the
+problems in this manual have been defined:
+
+\begin{sourcecode}
+ \DeclareExerciseEnvironmentTemplate{tcolorbox}
+ {%
+ \tcolorbox[
+ colback = red!5!white ,
+ colframe = red!75!black ,
+ colbacktitle = yellow!50!red ,
+ coltitle = red!25!black ,
+ breakable ,
+ drop shadow ,
+ beforeafter skip = .5\baselineskip ,
+ title =
+ \textbf{\GetExerciseName~\GetExerciseProperty{counter}}%
+ \GetExercisePropertyT{subtitle}{ \textit{\PropertyValue}}%
+ \IfInsideSolutionF{%
+ \GetExercisePropertyT{points}{ % notice the space
+ (%
+ \printgoal{\PropertyValue}
+ \IfExerciseGoalSingularTF{points}
+ {\XSIMtranslate{point}}
+ {\XSIMtranslate{points}}%
+ )%
+ }%
+ }%
+ ]%
+ }
+ {\endtcolorbox}
+
+ \DeclareExerciseType{problem}{
+ exercise-env = problem ,
+ solution-env = answer ,
+ exercise-name = Problem ,
+ solution-name = Answer ,
+ exercise-template = tcolorbox ,
+ solution-template = tcolorbox
+ }
+\end{sourcecode}
+
+See it in action:
+\begin{example}
+ \begin{problem}[subtitle=My subtitle,points=5]
+ This is a problem using a subtitle and points.
+ \end{problem}
+ \begin{answer}
+ This is the answer to problem~\GetExerciseProperty{counter}.
+ \end{answer}
+\end{example}
+
+\subsubsection{Mimicking \pkg*{exsheets}' \code{runin} Template}
+\label{sec:runin-template}
+
+The following example shows how you could mimick \pkg*{exsheets}' \code{runin}
+template. The outcome isn't exactly the same since \pkg{exsheets} doesn't use
+\cs*{marginpar} but the result should look very similar. A safer definition
+would use a real sectioning command for the title.
+
+\begin{sourcecode}
+ \usepackage{needspace}
+ \DeclareExerciseEnvironmentTemplate{runin}
+ {%
+ \par\vspace{\baselineskip}
+ \Needspace*{2\baselineskip}
+ \noindent
+ \textbf{\XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}}%
+ \GetExercisePropertyT{subtitle}{ \textit{#1}} % <<< notice the space
+ \IfInsideSolutionF{%
+ \GetExercisePropertyT{points}{%
+ \marginpar{%
+ \printgoal{\PropertyValue}%
+ \GetExercisePropertyT{bonus-points}{+\printgoal{\PropertyValue}}%
+ \,\IfExerciseGoalSingularTF{points}
+ {\XSIMtranslate{point}}
+ {\XSIMtranslate{points}}%
+ }%
+ }%
+ }%
+ }
+ {}
+\end{sourcecode}
+
+\subsubsection{Mimicking \pkg*{exsheets}' \code{margin} Template}
+\label{sec:margin-template}
+
+The following example shows how you could mimick \pkg*{exsheets}'
+\code{margin} template.
+
+\begin{sourcecode}
+ \DeclareExerciseEnvironmentTemplate{margin}
+ {%
+ \trivlist
+ \item[\llap{%
+ \smash{%
+ \tabular[t]{@{}r@{}}
+ \textbf{\XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}}
+ \IfExercisePropertySetT{points}{%
+ \tabularnewline
+ (%
+ \printgoal{\GetExerciseProperty{points}}%
+ \GetExercisePropertyT{bonus-points}{+\printgoal{#1}}%
+ \,\XSIMtranslate{point-abbr}%
+ )%
+ }%
+ \endtabular
+ }%
+ }]\relax
+ }
+ {\endtrivlist}
+\end{sourcecode}
+
+\subsubsection{The Headings Templates}\label{sec:headings-templates}
+\xsim\ defines four heading templates which only differ by which text they
+output:
+\begin{sourcecode}
+ \DeclareExerciseHeadingTemplate{default}
+ {\section*{\XSIMtranslate{default-heading}}}
+ \DeclareExerciseHeadingTemplate{collection}
+ {\section*{\XSIMtranslate{collection-heading}}}
+ \DeclareExerciseHeadingTemplate{per-section}
+ {\section*{\XSIMtranslate{per-section-heading}}}
+ \DeclareExerciseHeadingTemplate{per-chapter}
+ {\section*{\XSIMtranslate{per-chapter-heading}}}
+\end{sourcecode}
+Section~\vref{sec:exerc-transl} shows how the translations are defined.
+
+\subsubsection{The \code{default} Table Template}\label{sec:table-templ-default}
+This template is the one used for grading tables per default. It has a
+vertical layout.
+
+\begin{sourcecode}
+ \DeclareExerciseTableTemplate{default}{%
+ \XSIMputright\ExerciseTableCode{%
+ \toprule
+ \XSIMifblankTF{\ExerciseType}
+ {}
+ {\XSIMmixedcase{\GetExerciseParameter{exercise-name}}}
+ &
+ \XSIMmixedcase{\XSIMtranslate{points}} &
+ \XSIMtranslate{reached} \\
+ \midrule
+ }%
+ \ForEachUsedExerciseByType{%
+ \XSIMifeqTF{#1}{\ExerciseTableType{#1}}
+ {%
+ \XSIMifblankTF{\ExerciseType}
+ {%
+ \XSIMputright\ExerciseTableCode{%
+ \XSIMmixedcase{\ExerciseParameterGet{#1}{exercise-name} }%
+ }%
+ }
+ {}%
+ \XSIMputright\ExerciseTableCode
+ {#3 & \XSIMifblankTF{#5}{\printgoal{0}}{\printgoal{#5}} & \\ }%
+ }
+ {}%
+ }
+ \XSIMputright\ExerciseTableCode{%
+ \midrule
+ \XSIMtranslate{total} &
+ \XSIMifblankTF{\ExerciseType}
+ {\TotalExerciseGoal{points}{}{}}
+ {\TotalExerciseTypeGoal{\ExerciseType}{points}{}{}} &
+ \\ \bottomrule
+ }%
+ \XSIMexpandcode{%
+ \noexpand\begin{tabular}{\XSIMifblankTF{\ExerciseType}{l}{c}cc}
+ \noexpand\ExerciseTableCode
+ \noexpand\end{tabular}%
+ }%
+ }
+\end{sourcecode}
+
+The part
+\begin{sourcecode}
+ \XSIMifblankTF{\ExerciseType}{ ... }{ ... }
+\end{sourcecode}
+repeatedly checks if an exercise type has been given for the table. This
+makes it possible to design the table differently if it is for one exercise
+type only (the \code{true} case) or for all exercise types (the \code{false}
+case). \cs*{ExerciseTableType}\marg{code} either expands to the given
+exercise type or to \meta{code}.
+
+\subsubsection{The \code{default*} Table Template}\label{sec:table-templ-default*}
+The second of the predefined grading table templates. It has a horizontal
+layout.
+\begin{bewareofthedog}
+ If you have a lot of exercises the width of a table with this layout may
+ exceed the text width of the document!
+\end{bewareofthedog}
+
+\begin{sourcecode}
+ \DeclareExerciseTableTemplate{default*}{%
+ \XSIMputright\ExerciseTableCode{%
+ \toprule
+ \XSIMifblankTF{\ExerciseType}
+ {}
+ {\XSIMmixedcase{\GetExerciseParameter{exercise-name}}}
+ &%
+ }%
+ \ForEachUsedExerciseByType{%
+ \XSIMifeqTF {#1} { \ExerciseTableType {#1} }
+ {
+ \XSIMifblankTF{\ExerciseType}
+ {%
+ \XSIMputright\ExerciseTableCode{%
+ \XSIMmixedcase{\ExerciseParameterGet{#1}{exercise-name} }%
+ }%
+ }
+ {}%
+ \XSIMputright\ExerciseTableCode{#3 &}
+ }
+ {}%
+ }%
+ \XSIMputright\ExerciseTableCode{%
+ \XSIMtranslate{total} \\
+ \midrule
+ \XSIMmixedcase{\XSIMtranslate{points}} &
+ }%
+ \ForEachUsedExerciseByType{%
+ \XSIMifeqTF{#1}{\ExerciseTableType{#1}}
+ {%
+ \XSIMputright\ExerciseTableCode{%
+ \XSIMifblankTF{#5}{\printgoal{0}}{\printgoal{#5}} &}%
+ }
+ {}%
+ }%
+ \XSIMputright\ExerciseTableCode{%
+ \XSIMifblankTF{\ExerciseType}
+ {\TotalExerciseGoal{points}{}{}}
+ {\TotalExerciseTypeGoal{\ExerciseType}{points}{}{}}%
+ \\ \midrule
+ \XSIMtranslate{reached} &%
+ }%
+ \ForEachUsedExerciseByType{%
+ \XSIMifeqTF{#1}{\ExerciseTableType{#1}}
+ {\XSIMputright\ExerciseTableCode{&}}
+ {}%
+ }%
+ \XSIMputright\ExerciseTableCode{ \\ \bottomrule }%
+ \def\numberofcolumns{%
+ \XSIMifblankTF{\ExerciseType}
+ {\numberofusedexercises}
+ {\csname numberof \ExerciseType s\endcsname}%
+ }%
+ \XSIMifeqF{\numberofcolumns}{0}
+ {%
+ \begin{tabular}{l*{\numberofcolumns}{c}c}
+ \ExerciseTableCode
+ \end {tabular}%
+ }%
+ }
+\end{sourcecode}
+
+The part
+\begin{sourcecode}
+ \XSIMifblankTF{\ExerciseType}{ ... }{ ... }
+\end{sourcecode}
+repeatedly checks if an exercise type has been given for the table. This
+makes it possible to design the table differently if it is for one exercise
+type only (the \code{true} case) or for all exercise types (the \code{false}
+case). \cs*{ExerciseTableType}\marg{code} either expands to the given
+exercise type or to \meta{code}.
+
+\section{Exercise Translations}\label{sec:exerc-transl}
+
+\begin{commands}
+ \command{DeclareExerciseTranslation}[\marg{language}\marg{keyword}\marg{translation}]
+ Declare the translation of \meta{keyword} for language \meta{language}.
+ \command{DeclareExerciseTranslations}[\marg{keyword}\marg{translations}]
+ Declare the translations of \meta{keyword} for several languages at once.
+ See an example of the usage below.
+ \expandable\command{XSIMtranslate}[\marg{keyword}]
+ Delivers the translation of \meta{keyword} according to the current
+ document language (in the meaning of a \pkg{babel}~\cite{pkg:babel} or
+ \pkg{polyglossia}~\cite{pkg:polyglossia} language).
+ \command{ForEachExerciseTranslation}[\marg{code}]
+ Loops over all translations of all keywords known to \xsim. Inside
+ \meta{code} you can refer to the keyword with \code{\#1}, to the language
+ with \code{\#2}, and to the translation with \code{\#3}.
+\end{commands}
+
+As an example how to use \cs{DeclareExerciseTranslations} here is how the
+translations for \code{exercise} have been defined:
+
+\begin{sourcecode}
+ \DeclareExerciseTranslations{exercise}{
+ Fallback = exercise ,
+ English = exercise ,
+ French = exercice ,
+ German = \"Ubung
+ }
+\end{sourcecode}
+
+Table~\vref{tab:translation-keys} shows all existing keywords with all
+predefined translations.
+
+\ForEachExerciseTranslation{
+ \appto\translationtable{\texttt{#1} & #2 & \texttt{\detokenize{#3}} \\}
+}
+
+\begin{longtable}{llp{.55\linewidth}}
+ \caption{Translation keywords predefined by \xsim.}
+ \label{tab:translation-keys} \\
+ \toprule
+ \bfseries keyword & \bfseries language & \bfseries translation \\
+ \midrule
+ \endfirsthead
+ \toprule
+ \bfseries keyword & \bfseries language & \bfseries translation \\
+ \midrule
+ \endhead
+ \bottomrule
+ \endlastfoot
+ \midrule
+ & & \hfill\emph{continues} \\
+ \endfoot
+ \translationtable
+\end{longtable}
+
+\section{Cloze Tests and Blank Lines}
+
+Similar to \pkg{exsheets} \xsim\ provides a command \cs{blank}:
+\begin{commands}
+ \command{blank}[\sarg\oarg{options}\marg{text to be filled in}]
+ Creates a blank in normal text or in an exercise but fills the text of its
+ argument if inside a solution. If used at the \emph{begin of a paragraph}
+ \cs{blank} will do two things: it will set the linespread according to an
+ option explained below and will insert \cs*{par} after the lines. The
+ starred version doesn't do these things.
+\end{commands}
+
+Those are the options for customization:
+\begin{options}
+ \keyval{blank-style}{code}\Module{blank}\Default{\cs*{underline}\Marg{\#1}}
+ Instructions for typesetting the blank cloze. Refer to the filled in
+ space with \code{\#1}.
+ \keyval{filled-style}{code}\Module{blank}\Default{\cs*{underline}\Marg{\#1}}
+ Instructions for typesetting the filled cloze. Refer to the filled in text
+ with \code{\#1}
+ \keyval{style}{code}
+ Shortcut for setting both \option{blank-style} and \option{filled-style}
+ at once.
+ \keyval{scale}{decimal number}\Module{blank}\Default{\code{1}}
+\textsc{} Scales the blank to \meta{decimal number} times its natural width.
+ \keyval{width}{dim}\Module{blank}\Default
+ Sets the blank to a width of \meta{dim}. This takes precendence over
+ \option{scale}.
+ \keyval{linespread}{decimal number}\Module{blank}\Default{\code{1}}
+ Set the linespread for the blank lines. This only has an effect if
+ \cs{blank} is used at the begin of a paragraph.
+ \keyval{line-increment}{dim}\Module{blank}\Default{\code{1pt}}
+ The blank line is built in multiples of this value. If the value is too
+ large you may end up with uneven lines. If the value is too small you may
+ end up with a non-ending compilation. Experiment with values to find the
+ suiting one for your use case.
+ \keyval{line-minimum-length}{dim}\Module{blank}\Default{\code{2em}}
+ The minimal length a line must have before it is built step by step.
+\end{options}
+
+\begin{example}
+ This is a \blank{blank} outside in normal text.
+ \begin{exercise}
+ Try to fill in \blank[width=4cm]{these} blanks. All of them
+ \blank{are created} by using the \cs{blank} \blank{command}.
+ \end{exercise}
+ \xsimsetup{blank/filled-style=\textcolor{red}{#1}}
+ \begin{solution}[print]
+ Try to fill in \blank[width=4cm]{these} blanks. All of them
+ \blank{are created} by using the \cs{blank} \blank{command}.
+ \end{solution}
+\end{example}
+A number of empty lines are easily created by setting the \option{width}
+option:
+\begin{example}
+ Write up the pros and cons of \xsim\ over \pkg{exsheets}:
+
+ \blank[width=4.8\linewidth,linespread=1.5]{}
+\end{example}
+
+\edef\lastsection{\arabic{section}}
+
+\appendix
+
+\section{Future Plans}
+
+\xsim\ is complete in so far as it is perfectly usable to create exams or
+exercise and solution sections in books with the most freedom in layout
+already. But still there are features which would be useful additions. Below
+I list all ideas that I currently plan to add to \xsim:
+\begin{itemize}
+ \item a document class \code{xsim-exam} for creating exams; this class
+ should itself feature the possibility of creating different versions of an
+ exam, maybe already provide multiple choice questions and so on; one could
+ also think about automatic creation of running headers and footers, \ie,
+ means for changing the layout of the exam; following the spirit of \xsim\
+ this should probably be done using templates as well.
+\end{itemize}
+I am very open to suggestions regarding features, both in general and
+specifically regarding the document class.
+
+\section{FAQ \& How to\dots}
+This section serves as a kind of gallery showing solutions to common
+problems. I expect this section to grow over the years. Some examples
+especially regarding other layouts are also shown in example files added to
+this package.
+
+\subsection{\dots Know if \xsim\ Needs Another Compilation?}
+If \xsim\ wants you to recompile your document it writes the following to the
+logfile:
+\begin{sourcecode}
+ *************************************************
+ * xsim warning: "rerun"
+ *
+ * Exercise properties may have changed. Rerun to get them synchronized.
+ *************************************************
+\end{sourcecode}
+So just check the logfile regularly (which you should be doing anyway) and
+keep your eyes open.
+
+\subsection{\dots Resolve Getting Repeatedly Wrong Exercise Properties or
+ Wrong Exercise Lists?}\label{sec:resolve-getting}
+\xsim\ writes a lot of stuff to the auxfile for re-using information on
+subsequent compilations. If you add exercises, change properties \etc\ it
+might happen that wrong information is staying in the auxfile and is wrongly
+used by \xsim. In such cases deleting the auxfile and doing a few fresh
+compilations may resolve your problems.
+
+Sometimes the \emph{existence of exercise or solution files from earlier
+ compilations} may lead to wrong lists of exercises or solutions. In such
+cases it can be useful to delete all those files and doing a fresh
+compilation. It may be helpful to use a subfolder for those exernal files
+which will make deleting them a little bit easier. (Don't forget to both
+create the subfolder and set \option{path} accordingly then.)
+
+Using the \option{clear-aux} option might help to reduce erroneous exercises.
+
+\subsection{\dots Resolve Strange Errors After Updating?}
+\xsim\ writes a lot of stuff to the auxfile. An update may well change how
+this is done so deleting the auxfile and doing a few fresh compilations may
+resolve your problems.
+
+\subsection{\code{! TeX capacity exceeded, sorry [text input levels=15].}
+ Why?}
+Did you try to use an exercise or solution in a macro of some sort? This
+generally will fail\footnote{The reasons are similar to the ones given here:
+ \url{https://tex.stackexchange.com/a/295422/}.}. But there should never be
+the need to hide the environments inside of a macro, anyway.
+
+\subsection{\code{Runaway argument? !File ended while scanning use of \^{}\^{}M.} Why?}
+Did you try to use an exercise or solution in a macro of some sort? This
+generally will fail. But there should never be the need to hide the
+environments inside of a macro, anyway.
+
+\subsection{\dots Put a Star (or Another Symbol) in Headings of Exercises That
+ Are Special?}
+
+The code below shows one possible modification of an exercise template which
+allows to easily create bonus exercises:
+\begin{sourcecode}
+ % preamble:
+ \usepackage{amsymb}
+ % declare boolean property:
+ \DeclareExerciseProperty*{bonus}
+ \DeclareExerciseEnvironmentTemplate{bonus}
+ {%
+ \subsection*
+ {%
+ % test for boolean property and insert star symbol if true:
+ \IfExerciseBooleanPropertyT{bonus}{\llap{$\bigstar$ }Bonus }%
+ \XSIMmixedcase{\GetExerciseName}\nobreakspace
+ \GetExerciseProperty{counter}%
+ \IfInsideSolutionF
+ {%
+ \IfExercisePropertySetT{subtitle}
+ { {\normalfont\itshape\GetExerciseProperty{subtitle}}}%
+ }%
+ }
+ \GetExercisePropertyT{points}
+ {%
+ \marginpar
+ {%
+ \IfInsideSolutionF{\rule{1.2cm}{1pt}\slash}%
+ \PropertyValue
+ \GetExercisePropertyT{bonus-points}
+ {\nobreakspace(+\PropertyValue)}%
+ \nobreakspace\XSIMtranslate{point-abbr}%
+ }%
+ }%
+ }
+ {}
+\end{sourcecode}
+
+The usage is now as follows:
+\begin{example}
+ \xsimsetup{exercise/template = bonus}
+ % set the boolean property to true
+ \begin{exercise}[bonus]
+ A bonus question.
+ \end{exercise}
+\end{example}
+
+\subsection{\dots Create and Use \xsim\ Style Files?}\label{sec:style-files}
+\index{style file|(}
+
+\xsim\changedversion{0.11} offers you the possibility to create own
+\emph{style files}. Let's say you want to have a style called
+\code{math-exam}. Then you need to save all necessary definitions in a file
+called:
+\begin{center}
+ \code{xsim.style.math-exam.code.tex}
+\end{center}
+The first command in the file should be \cs{xsimstyle}\Marg{math-exam}. This
+file can now be loaded into your document using
+\cs{loadxsimstyle}\Marg{math-exam}:
+\begin{sourcecode}
+ \documentclass[DIV=18,parskip=half]{scrartcl}
+ \usepackage[T1]{fontenc}
+ \usepackage[utf8]{inputenc}
+
+ \usepackage[clear-aux]{xsim}
+ \loadxsimstyle{math-exam}
+
+ \title{Math Exam \#3}
+ \date{2017-03-28}
+\end{sourcecode}
+
+In this style file stuff like template and property definitions should
+happen. This is more or less a convenient way to
+\begin{itemize}
+ \item keep the preamble \enquote{clean} and
+ \item define re-usable styles without the need of copying the document
+ preamble to another document.
+\end{itemize}
+A style file is like a package or class file, \ie, \code{@} has category
+code~11 (letter).
+
+The formal description of the commands:
+\begin{commands}
+ \command{xsimstyle}[\sarg\marg{style name}]
+ The\changedversion{0.11} first command in a \xsim\ style file called
+ \code{xsim.style.\meta{style name}.code.tex} which defines the \xsim\
+ style \meta{style name}. The starred version activates expl3
+ syntax\footnote{Those users who want this will know what it means. If you
+ don't know what it means you will not need it.}.
+ \command{loadxsimstyle}[\marg{csv list of style names}]
+ Load one or more styles into the document.
+\end{commands}
+
+\begin{bewareofthedog}
+ At the moment this mechanism offers no advantages over creating a custom
+ package or simply \cs*{input}ing a file. Future versions might provide
+ additional features.
+\end{bewareofthedog}
+
+\index{style file|)}
+
+\subsection{\dots Print All Solutions Grouped by Section?}
+Here is an idea how to get a list of all solutions grouped by the section the
+corresponding exercises are appearing in.
+\begin{sourcecode}
+ % preamble:
+ % \usepackage{etoolbox}
+ % \newcounter{sections}
+
+ % document:
+ \setcounter{sections}{1}
+ \whileboolexpr
+ { test {\ifnumless{\value{sections}}{\value{section}+1}} }
+ {
+ \printsolutions[section=\value{sections},headings-template=per-section]
+ \stepcounter{sections}
+ }
+\end{sourcecode}
+For this manual we then get the following list\footnote{Taking care of the
+ fact that we're in the appendix now which means we can't use
+ \cs*{value}\Marg{section}. Therefore this manual does
+ \cs*{edef}\cs*{lastsection}\Marg{\cs*{arabic}\Marg{section}} right before
+ \cs*{appendix}}.
+
+\newcounter{sections}
+\setcounter{sections}{1}
+\whileboolexpr
+ { test {\ifnumless{\value{sections}}{\lastsection+1}} }
+ {
+ \printsolutions[section=\value{sections},headings-template=per-section]
+ \stepcounter{sections}
+ }
+
+\section{The \pkg*{xsimverb} package}\label{sec:xsimverb-package}
+\xsim\ comes bundled with another package called \pkg{xsimverb}. This package
+loads a very small subset of \xsim\ which allows to create environments which
+write their contents verbatim to external files. It provides the following
+commands (which of course are also available in \xsim, too):
+
+\begin{commands}
+ \command{XSIMfilewritestart}[\sarg\marg{file name}]
+ Start writing to the file named \meta{file name}. This should be the
+ \emph{last} command in the \emph{begin} definition of an environment. If
+ is is used in an environment with arguments where the \emph{last} argument
+ is optional you should check if the optional argument is given and use
+ the starred version if the test is negative. This is demonstrated in an
+ example below using \pkg{xparse}'s \cs{NewDocumentEnvironment}. \emph{If
+ you want an environment with only an optional argument you \emph{should}
+ use \pkg{xparse}'s commands to define it. Due to the way how
+ \cs*{newenvironment} scans for optional arguments you'll otherwise may
+ end up with leading spaces gobbled from the first line in your
+ environment.}
+ \command{XSIMfilewritestop}
+ Stop writing to the file. This should be the \emph{first} command in the
+ \emph{end} definition of an environment.
+ \command{XSIMsetfilebegin}[\marg{code}]
+ This command can be used to write something to the external file
+ \emph{before} the environment contents. Must be set before
+ \cs{XSIMfilewritestart} in the \emph{begin} definition.
+ \command{XSIMsetfileend}[\marg{code}]
+ This command can be used to write something to the external file
+ \emph{after} the environment contents. Must be set before
+ \cs{XSIMfilewritestart} in the \emph{begin} definition.
+ \command{XSIMgobblechars}[\marg{integer}]
+ Determines how many characters are cut off of the beginning of each line
+ of the environment body before it is written to the file. The default
+ value is~$0$.
+\end{commands}
+
+An example of how to use those commands:
+\begin{sourcecode}
+ \documentclass{article}
+ \usepackage{xsimverb,listings}
+
+ \makeatletter
+ \NewDocumentEnvironment{example}{o}
+ {%
+ \XSIMsetfilebegin{\@percentchar\space file `\jobname.tmp'}%
+ \XSIMsetfileend{\@percentchar\space bye bye}%
+ \IfNoValueTF{#1}
+ {\XSIMfilewritestart*{\jobname.tmp}}
+ {\XSIMfilewritestart{\jobname.tmp}}%
+ }
+ {%
+ \XSIMfilewritestop
+ \lstinputlisting[language={[LaTeX]TeX}]{\jobname.tmp}%
+ \input{\jobname.tmp}
+ }
+ \makeatother
+
+ \begin{document}
+
+ \begin{example}
+ bla bla \LaTeX
+ \end{example}
+
+ \end{document}
+\end{sourcecode}
+
+The \code{tmp} file produced by the above example will contain the following
+three lines (if the file itself was called \code{test.tex}):
+\begin{sourcecode}
+ % file `test.tmp'
+ bla bla \LaTeX
+ % bye bye
+\end{sourcecode}
+
+\section{All Exercise Examples}
+
+\begin{bewareofthedog}
+ You will notice that some exercises from
+ section~\vref{sec:template-examples} look differently in this section. That
+ is because all exercises of a type use the template that's \emph{currently
+ active}. If you want exercises with a different look you should use
+ different exercises types.
+\end{bewareofthedog}
+
+The following list is created with this code:
+\begin{sourcecode}
+ \xsimsetup{exercise/template = bonus}
+ \printcollection[headings]{all exercises}
+\end{sourcecode}
+
+\xsimsetup{exercise/template = bonus}
+\printcollection[headings]{all exercises}
+
+\section{All Solution Examples}
+\printsolutions
+
+\section{Example Documents Coming With This Package}\label{sec:example-files}
+The repository of this package\footnote{GitHub:
+ \url{https://github.com/cgnieder/xsim/}, CTAN:
+ \url{http://www.ctan.org/pkg/xsim/}} currently includes
+\theexamplefiles~example documents demonstrating how different aspects of this
+package work or how different kinds of problems can be solved or how different
+kinds of layouts can be achieved as well as how to solve concrete problems
+that have come up in different \LaTeX\ forums.
+
+\listexamplefiles
+
+\printbibliography
+
+\end{document}