summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/exsheets/exsheets_en.tex
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/exsheets/exsheets_en.tex
Initial commit
Diffstat (limited to 'macros/latex/contrib/exsheets/exsheets_en.tex')
-rw-r--r--macros/latex/contrib/exsheets/exsheets_en.tex2650
1 files changed, 2650 insertions, 0 deletions
diff --git a/macros/latex/contrib/exsheets/exsheets_en.tex b/macros/latex/contrib/exsheets/exsheets_en.tex
new file mode 100644
index 0000000000..d79c5de063
--- /dev/null
+++ b/macros/latex/contrib/exsheets/exsheets_en.tex
@@ -0,0 +1,2650 @@
+% !arara: pdflatex
+% !arara: biber
+% arara: pdflatex
+% arara: pdflatex
+% arara: pdflatex
+% --------------------------------------------------------------------------
+% the EXSHEETS package
+%
+% Yet another package for the creation of exercise sheets
+%
+% --------------------------------------------------------------------------
+% Clemens Niederberger
+% Web: http://www.mychemistry.eu/forums/forum/exsheets/
+% E-Mail: contact@mychemistry.eu
+% --------------------------------------------------------------------------
+% Copyright 2011-2017 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[load-preamble+]{cnltx-doc}
+
+\usepackage{exsheets}
+\usepackage{bookmark}
+
+\setcnltx{
+ package = {exsheets} ,
+ authors = Clemens Niederberger ,
+ email = contact@mychemistry.eu ,
+ url = {http://www.mychemistry.eu/forums/forum/exsheets/} ,
+ title = the \ExSheets\ bundle ,
+ info = {%
+ the packages \ExSheets{} and \ExSheetslistings \\
+ \emph{or}\\
+ Yet another package for the creation of exercise sheets and exams.%
+ } ,
+ module-sep = {\,>>\,} ,
+ index-setup = { othercode=\footnotesize,level=\section} ,
+ abstract = {%
+ \ExSheets\ provides means to create exercises or questions and their
+ corresponding solutions. The questions can be divided into classes and
+ can be printed selectively. Meta-data to questions can be added and
+ recovered.
+ \par
+ The solutions may be printed where they are, can be collected and printed
+ at a later point in the document alltogether or section-wise or
+ selectively by \acs{id}.\par
+ \ExSheets\ provides a comprehensive interface for styling the headings of
+ questions and solutions.%
+ } ,
+ add-cmds = {
+ % exsheets:
+ addpoints,
+ blank,
+ C,
+ checkedchoicebox,choice,choicebox,
+ correct,
+ CurrentQuestionID,
+ DebugExSheets,
+ DeclareExSheetsHeadingContainer,
+ DeclareQuestionClass,DeclareQuestionProperty,
+ examspace,
+ exlabel,
+ ForEachQuestion,
+ GetQuestionClass,
+ GetQuestionProperty,
+ grade,
+ includequestions,iflastquestion,
+ IfQuestionPropertyF,IfQuestionPropertyT,IfQuestionPropertyTF,
+ IfQuestionSubtitleF,IfQuestionSubtitleT,IfQuestionSubtitleTF,
+ lastvariant,
+ NewQuSolPair,NewLstQuSolPair,
+ numberofquestions,
+ points,pointssum,
+ PrintIfIncludeActiveF,PrintIfIncludeActiveT,PrintIfIncludeActiveTF,
+ PrintQuestionClassF,PrintQuestionClassT,PrintQuestionClassTF,
+ printsolutions,
+ PrintSolutionsF,PrintSolutionsTF,PrintSolutionsT,
+ questionsincludedlast,QuestionNumber,RenewQuSolPair,
+ S,
+ SetQuestionProperties,
+ SetupExSheets,
+ SetVariations,
+ startnewitemline,
+ sumpoints,
+ totalpoints,
+ variant,vary,
+ % cntformats:
+ @cntfmts@parsed@pattern,
+ AddCounterPattern,
+ eSaveCounterPattern,
+ NewCounterPattern,
+ ReadCounterFrom,
+ ReadCounterPattern,ReadCounterPatternFrom,
+ SaveCounterPattern,
+ % tasks:
+ NewTasks,
+ settasks,
+ task
+ } ,
+ add-envs = {
+ question,
+ solution,
+ tasks
+ } ,
+ add-silent-cmds = {
+ acs,
+ bigstar,bottomrule,
+ citetitle,cs,color,
+ DeclareInstance,DeclareTemplateInterface,
+ endmdframed,endspacing,
+ keyis,
+ leftthumbsup,
+ mdframed,midrule,
+ rightarrow,rlap,
+ s,sample,setlength,
+ spacing,square,
+ tabcolsep,
+ textcite,
+ textcolor,
+ tmpa,tmpb,
+ toprule
+ }
+}
+\usepackage{exsheets-listings}
+
+\microtypesetup{tracking=scshape}
+
+\defbibheading{bibliography}[\bibname]{\section{#1}}
+
+\usepackage[biblatex]{embrac}[2012/06/29]
+ \ChangeEmph{[}[,.02em]{]}[.055em,-.08em]
+ \ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em]
+\usepackage{booktabs,array,ragged2e}
+
+\newpackagename\ExSheets{ExSheets}
+\newpackagename\ExSheetslistings{ExSheets-listings}
+\newpackagename\cntformats{cntformats}
+\newpackagename\Tasks{tasks}
+
+% ----------------------------------------------------------------------------
+% other packages, bibliography, index
+\usepackage{xcoffins,wasysym,enumitem,siunitx}
+
+\usepackage[accsupp]{acro}
+\DeclareAcronym{faq}{
+ short = faq ,
+ long = Frequently Asked Questions ,
+ format = \scshape ,
+ pdfstring = FAQ ,
+ accsupp = FAQ
+}
+\DeclareAcronym{id}{
+ short = id ,
+ long = Identifier ,
+ format = \scshape ,
+ pdfstring = ID ,
+ accsupp = ID
+}
+\DeclareAcronym{ctan}{
+ short = ctan ,
+ long = Comprehensive \TeX\ Archive Network ,
+ format = \scshape ,
+ pdfstring = CTAN ,
+ accsupp = CTAN
+}
+
+\usepackage{filecontents}
+
+\usepackage{csquotes}
+
+\addbibresource{biblatex-examples.bib}
+\addbibresource{\jobname.bib}
+
+\begin{filecontents*}{\jobname.bib}
+@online{tex.sx:131546,
+ title = {Fixing lstlisting inside \ExSheets\ \code{question} and
+ \code{solution} environments} ,
+ author = {Stefano Bragaglia} ,
+ url = {http://tex.stackexchange.com/q/131546/5049} ,
+ date = {2013-09-04} ,
+ urldate = {2013-09-22}
+}
+@online{tex.sx:133907,
+ title = {How do I extract repeated functionality (\ExSheets\ workaround) to
+ make it reusable?} ,
+ author = {Forkrul Assail} ,
+ url = {http://tex.stackexchange.com/q/133907/5049} ,
+ date = {2013-09-18} ,
+ urldate = {2013-09-22}
+}
+\end{filecontents*}
+
+% ----------------------------------------------------------------------------
+% example definitions that have to be done in the preamble:
+\DeclareQuestionClass{difficulty}{difficulties}
+\DeclareQuestionProperty{notes}
+\DeclareQuestionProperty{reference}
+\DeclareQuestionProperty{topic}
+
+\DeclareRelGrades{
+ 1 = 1 ,
+ {1,5} = .9167 ,
+ 2 = .8333 ,
+ {2,5} = .75 ,
+ 3 = .6667 ,
+ {3,5} = .5833 ,
+ 4 = .5
+}
+
+\usepackage{amssymb}
+\let\checkmark\relax
+\usepackage{dingbat}
+
+\DeclareRobustCommand*\questionstar{\texorpdfstring{\bonusquestionsign}{* }}
+\DeclareRobustCommand*\bonusquestionsign{\llap{$\bigstar$\space}}
+
+\NewQuSolPair
+ {question*}[name=\questionstar Bonus Question]
+ {solution*}[name=\questionstar Solution]
+
+\NewTasks[style=multiplechoice]{multiplechoice}[\choice](3)
+\newcommand*\correct{\PrintSolutionsTF{\checkedchoicebox}{\choicebox}}
+
+\usepackage{alphalph}
+\NewPatternFormat{aa}{\alphalph}
+\NewCounterPattern{testa}{ta}
+
+% \AfterPackage!{hyperref}{%
+% \pdfstringdefDisableCommands{\def\questionstar{* }}%
+% }
+
+\begin{document}
+
+\part{Preliminaries}
+\section{Licence and Requirements}
+\license
+
+\ExSheets\ loads and needs the following packages:
+\needpackage{l3kernel}~\cite{bnd:l3kernel}, \pkg{xparse}, \pkg{xtemplate},
+\pkg{l3keys2e}\footnote{all three \CTANurl{l3packages}}~\cite{bnd:l3packages},
+\pkg{l3sort}\footnote{\CTANurl{l3experimental}}~\cite{bnd:l3experimental},
+\needpackage{xcolor}~\cite{pkg:xcolor}, \needpackage{ulem}~\cite{pkg:ulem},
+\needpackage{etoolbox}~\cite{pkg:etoolbox},
+\needpackage{environ}~\cite{pkg:environ}, and
+\pkg{pgfcore}\footnote{\CTANurl[graphics]{pgf}}~\cite{pkg:pgf}. \ExSheets\
+calls \cs*{normalem} (from the \pkg{ulem} package).
+
+\section{Motivation}
+There are already quite a number of packages that allow the creation of
+exercise sheets or written exams. Just to name the most common ones:
+\pkg{eqexam}~\cite{pkg:eqexam}, \pkg{exam}~\cite{cls:exam},
+\pkg{examdesign}~\cite{pkg:examdesign}, \pkg{exercise}~\cite{pkg:exercise},
+\pkg{probsoln}~\cite{pkg:probsoln}, \pkg{answers}~\cite{pkg:answers},
+\pkg{esami}~\cite{pkg:esami}, \pkg{exsol}~\cite{pkg:exsol} (and many
+more \ldots).
+
+One thing I missed in all packages that I've tried out\footnote{Well, probably
+ I didn't try hard enough\ldots} was a high flexibility in choosing which
+questions and solutions should be printed, where which solutions should be
+printed and so on, combined with the possibility to assign questions to
+different classes so one could for example create two versions of an exam out
+of the box. And --~I can't get enough~-- I also want to be able to use/design
+different layouts for questions additional to a standard section-like format.
+All these points are realized in \ExSheets.
+
+Additionally one should be able to assign some sort of meta-data to questions
+that of course should be easily reusable. How this can be done is explained
+in section~\ref{sec:additional_info}.
+
+Then there is --~at least in Germany~-- the habit of having lists of exercises
+aligned in columns but counting from the left to the right instead from up to
+down. That's why the \pkg{tasks} package was developed as part of \ExSheets{}
+and was distributed as part of the bundle\changedversion{0.15}. Now it is a
+package of its own but is loaded by \ExSheets{} automatically with the
+necessary setup to make them work together nicely.
+
+\ExSheets{} has no native support for multiple choice tests but that doesn't
+mean that you can't create them with \ExSheets. It just means that they may
+be a bit more work with \ExSheets{} than with other packages.
+
+I had the idea for this package in 2008. Back then my \TeX{} skills were by
+far not good enough to write it. Actually, even today I wouldn't have been
+able to realize it without all the l3 packages like \pkg{l3kernel} and
+\pkg{l3packages}. I actively began to develop \ExSheets\ in spring~2011 but
+it wasn't until now (September~2012) that I consider it stable enough for
+wider usage. At the time of writing (\today) there still are probably lots of
+rough edges let alone bugs so I am very interested in all kinds of feedback.
+
+\section{Additional Packages}
+\ExSheets\ actually bundles two packages: \ExSheets, \ExSheetslistings.
+\ExSheetslistings\ is an add-on to \ExSheets\ that offers some functionality
+to use \pkg{listings} with \ExSheets. It is presented in
+part~\ref{part:listings}.
+
+\ExSheets\ used to bundle the \pkg{translations} package,
+too\changedversion{0.9i}, but doesn't any more. You can find the
+\pkg{translations} package as a package of it's own on the \ac{ctan}. It also
+used to bundle the packages \pkg{tasks} and
+\pkg{cntformats}\changedversion{0.15}. They're available now as packages of
+their own as well.
+
+% \section{Installation and Documentation}
+% If you install \ExSheets\ manually beware to put the files
+% \begin{itemize}
+% \item[]\verb+exsheets_headings.def+
+% \item[]\verb+exsheets_headings.cfg+
+% \end{itemize}
+% in the same directory as the \code{exsheets.sty} file\footnote{That is, a
+% directory like \code{texmf-local/tex/latex/exsheets}, probably}.
+
+% As with every manual package installation you need to make sure to put the
+% files in a directory where \TeX\ can find them and afterwards update the
+% database.
+
+% \subsection{The \pkg*{tasks} Package}
+% The \pkg{tasks} package~\cite{pkg:tasks} used to be part of the \ExSheets\
+% bundle but is a package of its own now\changedversion{0.15} and released
+% independently. You can find it as every other package on \ctan\ and in a full
+% \TeX~Live or \hologo{MiKTeX} installation.
+
+% \subsection{The \pkg*{cntformats} Package}
+% The \pkg{cntformats} package~\cite{pkg:cntformats} used to be part of the
+% \ExSheets\ bundle but is a package of its own now\changedversion{0.15} and
+% released independently. You can find it as every other package on \ctan\ and
+% in a full \TeX~Live or \hologo{MiKTeX} installation.
+
+% \subsection{The \pkg*{translations} Package}
+% The \pkg{translations} package~\cite{pkg:translations} used to be part of the
+% \ExSheets\ bundle but is a package of its own now\changedversion{0.9i} and
+% released independently. You can find it as every other package on \ctan\ and
+% in a full \TeX~Live or \hologo{MiKTeX} installation.
+
+% \section{News}
+% \begin{description}
+% \item[Version 0.7]
+% With version~0.7 there has been a potentially breaking change: the
+% \code{tasks} environment previously provided by \ExSheets\ has been
+% extracted into a package of its own. This does not change any syntax
+% \emph{per se}. However, if you used custom settings then you'll probably run
+% into some problems. The options for the environment are no longer set with
+% \cs{SetupExSheets} but with \cs{settasks}. Also the object that is used for
+% the list template and its instances has been renamed from
+% \code{exsheets-tasks} into \code{tasks}.
+
+% What's probably even more of a breaking change is a syntax difference of the
+% \code{tasks} environment: the optional argument for the number of columns is
+% \emph{no longer set in braces but parentheses}. This is deliberate as it
+% reflects the optional nature of the argument better and is consistent with
+% the syntax of \cs{NewTasks}, too.
+
+% Additionally the labels of the list got an additional offset of \code{1ex}
+% from the items which will lead to slightly different output. In some cases
+% this might actually lead to the most annoying changes. In this case say
+% \cs{settasks}\Marg{label-offset=0pt} which should cure things again.
+
+% I am very sorry for any inconvenience! I am trying to keep such changes as
+% minimal and rare as possibly. However, it is not always avoidable when a
+% package is new and still a child. It will grow up eventually.
+
+% \ExSheets' other packages -- \href{tasks_en.pdf}{\Tasks} and
+% \href{cntformats_en.pdf}{\cntformats} -- have gotten their own documentation
+% which are essentially extracted from this very document you're reading now.
+% This manual contains links to the respective manuals.
+
+% \item[Version v0.9i]
+% The \pkg{translations} package~\cite{pkg:translations} is no longer part of
+% the \ExSheets\ bundle. From now on (July~17.\@ 2013) it is provided as a
+% package of its own.
+
+% \item[Version 0.10]
+% The \ExSheets\ family has got a new member: \ExSheetslistings. This package
+% proposes a solution for the problem of using verbatim material in \ExSheets'
+% \env{question} and \env{solution} environments. It is presented in
+% part~\ref{part:listings}.
+
+% Question now can get subtitles that are printed if the heading instance
+% supports it, see section~\ref{sec:subtitles-questions}.
+
+% \item[Version 0.11]
+% The commands \cs{GetQuestionClass} and \cs{PrintQuestionClassTF} have been
+% added. They're explained in section~\ref{sec:retr-class-value}.
+
+% \item[Version 0.12]
+% The \option{auto-label} is now more flexible to allow the use together with
+% packages \pkg{cleveref}.
+
+% Question properties can now be retrieved before the question is printed (by
+% writing the properties to the \code{aux} file).
+
+% \item[Version 0.13]
+% New options:
+% \begin{itemize}
+% \item \option{chapter-hook} allows to add code to the list of solutions
+% when the solutions of a new chapter are printed, see
+% section~\ref{sec:solutions-print-all}.
+% \item \option{section-hook} allows to add code to the list of solutions
+% when the solutions of a new section are printed, see
+% section~\ref{sec:solutions-print-all}.
+% \end{itemize}
+
+% \item[Version 0.14]
+% New options:
+% \begin{itemize}
+% \item New option \option{pre-hook} to the \env{question} environment that
+% allows to add code directly before the question body, see
+% section~\ref{sec:opti-ques-envir}.
+% \item New option \option{post-hook} to the \env{question} environment that
+% allows to add code directly after the question body, see
+% section~\ref{sec:opti-ques-envir}.
+% \item New command \cs{ExSheetsHeading}, see
+% section~\ref{sec:using-an-exsheets}.
+% \item New pre-defined question properties \code{question-body},
+% \code{bonus-points} and \code{counter}, see
+% section~\ref{sec:additional_info}.
+% \item New option \option{save-to-aux}, see
+% section~\ref{sec:additional_info}.
+% \end{itemize}
+
+% \item[Version 0.15]
+% \begin{itemize}
+% \item The packages \pkg{tasks} and \pkg{cntformats} have been removed from
+% the bundle and are now distributed as packages of their own.
+% \item The options \option*{load-headings} and \option*{load-tasks} have
+% been dropped. The optional functionality they provided is now provided
+% all the time.
+% \item New command \cs{IfQuestionPropertyTF}, see
+% section~\ref{sec:additional_info}.
+% \end{itemize}
+
+% \item[Version 0.16]
+% New options/changes:
+% \begin{itemize}
+% \item The option \option{pre-hook} to the \env{question} environment now
+% places its contents before the question heading, see
+% section~\ref{sec:opti-ques-envir}.
+% \item New option \option{pre-body-hook} to the \env{question} environment
+% which adds its contents before the question body, see
+% section~\ref{sec:opti-ques-envir}.
+% \item New option \option{post-body-hook} to the \env{question} environment
+% which adds its contents after the question body, see
+% section~\ref{sec:opti-ques-envir}.
+% \item New option \option{pre-hook} to the \env{solution} environment which
+% adds code before a solution, see section~\ref{sec:opti-soli-envir}.
+% \item New option \option{post-hook} to the \env{solution} environment which
+% adds code after a solution, see section~\ref{sec:opti-soli-envir}.
+% \item New option \option{pre-body-hook} to the \env{solution} environment
+% which adds its contents before the solution body, see
+% section~\ref{sec:opti-soli-envir}.
+% \item New option \option{post-body-hook} to the \env{solution} environment
+% which adds its contents after the solution body, see
+% section~\ref{sec:opti-soli-envir}.
+% \end{itemize}
+
+% \item[Version 0.17]
+% New option:
+% \begin{itemize}
+% \item The option \option{use-saved-counter-format} has been introduced. It
+% is described in section~\ref{sec:solutions} on
+% page~\pageref{option:use-saved-counter-format}.
+% \end{itemize}
+
+% \item[Version 0.18]
+% The package now provides the correct Danish translations, thanks to Jonas
+% Nyrup.
+
+% The macro \cs{exsheetsprintsolution} is introduced, see
+% page~\pageref{exsheetsprintsolution} for a little bit of an explanation.
+
+% The option \option{no-skip-below} is introduced which disables the insertion
+% of vertical space after the question and solution environments.
+
+% \item[Version 0.20]
+% New command \cs{DeclareExSheetsHeadingContainer}.
+
+% \item[Version 0.21] Changes:
+% \begin{itemize}
+% \item \cs{includequestions} issues an error if it can't find the file to
+% include.
+% \item question properties are now also accessable when the corresponding
+% question isn't printed.
+% \item The variables \verbcode+\l_exsheets_counter_qu_int+ and \\
+% \verbcode+\g_exsheets_question_identification_prop+ are now public.
+% \end{itemize}
+% \end{description}
+
+\section{Thanks}
+I need to thank the many users who gave me feedback so far! For one thing
+this shows me that \ExSheets\ is useful to people. It also led to many
+improvements like new features and countless bug fixes.
+
+\part{The \ExSheets\ package}\label{part:exsheets}
+\section{Setup}
+The \ExSheets\ package has three different types of options, kind of. The
+first type are the classic package options which are used when you load
+\ExSheets:
+\begin{sourcecode}
+ \usepackage[<options>]{exsheets}
+\end{sourcecode}
+All general options can be used this way and most of them are described in
+section~\ref{sec:options}. All of those options also can be set via the setup
+command:
+\begin{commands}
+ \command{SetupExSheets}[\oarg{module}\marg{options}]
+\end{commands}
+
+The second type are options that belong to a specific environment or command.
+These options are either used directly with the environment/command
+\begin{sourcecode}
+ \begin{env}[<options>]
+ ...
+ \end{env}
+\end{sourcecode}
+or can also be set with the setup command. In the first case they only act
+upon the environment or command where they're used. In the second case they
+are set for all following uses of the corresponding environment or command.
+
+The options of the second type all belong to \module*{modules}. Let's say you
+want to specify some options of the \env{question} environment. You can then
+say the following:
+\begin{sourcecode}
+ \SetupExSheets[question]{option1,option2=value2}
+ % or:
+ \SetupExSheets{question/option1,question/option2=value2}
+\end{sourcecode}
+The \module*{module} an option belongs to is written in the left margin next
+to the when the option is described.
+
+The third type aren't options at all, actually. However, thanks to the great
+\pkg{xtemplate} package you are able to define your own instances of some of
+the objects used by \ExSheets. This is explained in a little more detail in
+part~\ref{part:style} on page~\pageref{part:style}\,ff. This third type,
+however, brings in a possible instability: the \pkg{xtemplate} package is in
+an experimental and developing state. This means that the sytax of the
+package may and possibly will change sometime in the future. I cannot foresee
+what any consequences of that will be for \ExSheets.
+
+\section{General Options}\label{sec:options}
+The package \ExSheets\ has some options, namely the following ones:
+\begin{options}
+ %% counter-format
+ \keyval{counter-format}{counter-format}\Default{qu.}
+ Formatting of the counter of the questions. This option takes a special
+ kind of string that is described in section~\ref{ssec:counter}.
+ \keyval{counter-within}{counter}\Default
+ Resets the \code{question} counter with every step of \meta{counter}.
+ %% auto-label
+ \keybool{auto-label}\Default{false}
+ If set to \code{true} \ExSheets\ will automatically place a
+ \cs*{label}\Marg{qu:\meta{id}} for each question. See
+ section~\ref{sec:auto-label-opti} for ways to customize this. It will
+ also create the question properties \code{ref} and \code{pageref}, see
+ section~\ref{sec:additional_info} for more on this.
+ %% headings
+ \keyval{headings}{instance}\Default{block}
+ Choose the style of the questions' and solutions' headings. There are two
+ predefined styles: \code{block} and \code{runin}.
+ %% headings-format
+ \keyval{headings-format}{code}\Default{\cs*{normalsize}\cs*{bfseries}}
+ This code is placed immediately before the headings of the questions and
+ solutions.
+ \keyval{subtitle-format}{code}\Default{\cs*{normalsize}\cs*{itshape}}
+ This code is placed immediately before the subtitle of the questions and
+ solutions. It only has an effect with a title instance that uses the
+ subtitle coffin, see section~\ref{sec:exsheets-headings}.
+ % skip-below
+ \keyval{skip-below}{dim}\Default{.5\cs*{baselineskip}}
+ \sinceversion{0.18}Sets the vertical space that is inserted after the
+ question and solution environments.
+ % no-skip-below
+ \keybool{no-skip-below}\Default{false}
+ \sinceversion{0.18}Disables the insertion of vertical space after the
+ question and solution environments.
+ %% totoc
+ \keybool{totoc}\Default{false}
+ This option adds the questions and solutions with their names and numbers
+ to the table of contents.
+ %% questions-totoc
+ \keybool{questions-totoc}\Default{false}
+ This option adds the questions with their names and numbers to the table
+ of contents.
+ %% solutions-totoc
+ \keybool{solutions-totoc}\Default{false}
+ This option adds the solutions with their names and numbers to the table
+ of contents.
+ %% toc-level
+ \keyval{toc-level}{toc level}\Default{subsection}
+ This option sets the level in which questions and solutions should appear
+ in the table of contents.
+ %% questions-toc-level
+ \keyval{questions-toc-level}{toc level}\Default{subsection}
+ This option sets the level in which questions should appear in the table
+ of contents.
+ %% solutions-toc-level
+ \keyval{solutions-toc-level}{toc level}\Default{subsection}
+ This option sets the level in which solutions should appear in the table
+ of contents.
+ %% use-ref
+ \keybool{use-ref}\Default{false}
+ enable referencing to sections and chapters in a way that the references
+ can be used with \cs{printsolutions}, see
+ section~\ref{sssec:print_specific_section} for details.
+\end{options}
+The \code{toc} options are demonstrated with section~\ref{sec:solutions:list}
+and the solutions printed there being listed in the table of contents.
+
+
+\section{Create Questions/Exercises and their Solutions}
+Now, let's start with the most important part: the questions and (possibly)
+their respective solutions.
+\subsection{The \env*{question} Environment}\label{ssec:questions}
+Questions are written inside the \env{question} environment:
+\begin{environments}
+ \environment{question}[\oarg{options}\marg{points}]
+ The main environment: creates a new exercise/question. Both arguments are
+ optional!
+\end{environments}
+\begin{example}
+ \begin{question}
+ This is our very first very difficult to solve question!
+ \end{question}
+\end{example}
+As you can see a heading is automatically created and the question is
+numbered. You can of course change both the numbering and the naming, but
+more on that later.
+
+The \env{question} environment takes an optional argument \marg{points} that
+can be used to assign points to the question (as is common in written exams):
+\begin{example}
+ \begin{question}{3}
+ This is our first difficult question that is worth 3 points!
+ \end{question}
+\end{example}
+These points are saved internally (see section~\ref{sec:points} for reasons
+why) and are written to the right margin next to the question heading in the
+default setting.
+
+You can also assign bonus points by inserting \code{\meta{point}+\meta{bonus
+ points}} as argument.
+\begin{example}
+ \begin{question}{1+1}
+ This question is worth 1 point and 1 bonus point.
+ \end{question}
+ \begin{question}{+3}
+ This question is a bonus question. It is worth 3 bonus points.
+ \end{question}
+\end{example}
+
+The points are counted and added to the total sum of points, see
+section~\ref{sec:points} for details on this. \sinceversion{0.12}Should you
+want that the points of a specific question \emph{should not be added} to the
+total sum then precede it with a bang \code{!}:
+\begin{example}
+ \begin{question}{!3}
+ This question's points won't be added to the total sum.
+ \end{question}
+\end{example}
+Beware that this also prevents bonus points. The points simply will be
+written where the heading instance puts them.
+
+\sinceversion{0.3}One additional thing: you might want to define custom
+commands that should behave differently if they're inside or outside of the
+\env{question} environment. In this case you can use these commands:
+\begin{commands}
+ \expandable\command{IfInsideQuestionTF}[\marg{true code}\marg{false code}]
+ Check if inside of a question and either leave \meta{true code} or
+ \meta{false code} in the input stream.
+ \expandable\command{IfInsideQuestionT}[\marg{true code}]
+ Check if inside of a question and either leave \meta{true code} in the
+ input stream if true.
+ \expandable\command{IfInsideQuestionF}[\marg{false code}]
+ Check if inside of a question and either leave \meta{false code} in the
+ input stream if not.
+\end{commands}
+
+\subsection{Options to the \env*{question} Environment}\label{sec:opti-ques-envir}
+The \env{question} environment takes one or more of the following options:
+\begin{options}
+ \keychoice{type}{exam,exercise}\Module{question}\Default{exercise}
+ Determines the type of question and changes the default name of a question
+ from ``Exercise'' to ``Question''. These default names are language
+ dependent.\par
+ If you use \cs*{usepackage}\oarg{ngerman}\marg{babel}, for example, then
+ the names are ``Übung'' and ``Aufgabe''.
+ \keyval{name}{name}\Module{question}\Default
+ Sets a custom name. All predefined names are discarded.
+ \keyval{subtitle}{subtitle}\Module{question}\Default
+ Adds a subtitle \meta{subtitle} for the question that is used by headings
+ instances that make use of the subtitle coffin, see
+ section~\ref{sec:exsheets-headings}.
+ \keyval{skip-below}{dim}\Module{question}\Default{.5\cs*{baselineskip}}
+ \sinceversion{0.18}Sets the vertical space that is inserted after the
+ question environment.
+ \keybool{no-skip-below}\Module{question}\Default{false}
+ \sinceversion{0.18}Disables the insertion of vertical space after the
+ question environment.
+ \keybool{print}\Module{question}\Default{true}
+ Prints or hides the question.
+ \keyval{ID}{id}\Module{question}\Default
+ Assigns a custom \acs{id} to the question. See section~\ref{ssec:ids} for
+ further information.
+ \keyval{label}{label}\Module{question}\Default
+ Places a \cs*{label}\marg{label} for the question. This will overwrite
+ any label that is placed by the \option{auto-label} option.
+ \keyval{class}{class}\Module{question}\Default
+ Assigns a class \meta{class} to the question. See
+ section~\ref{sec:classes} for further information.
+ \keyval{topic}{topic}\Module{question}\Default
+ Assigns a topic \meta{topic} to the question. See
+ section~\ref{sec:topics} for further information.
+ \keybool{use}\Module{question}\Default{true}
+ Discards the question. Or not.
+ \keyval{pre-hook}{code}\Module{question}\Default
+ \changedversion{0.16}Adds \meta{code} directly before the question title.
+ \keyval{post-hook}{code}\Module{question}\Default
+ \changedversion{0.16}Adds \meta{code} directly after the question.
+ \keyval{pre-body-hook}{code}\Module{question}\Default
+ \sinceversion{0.16}Adds \meta{code} directly before the question body.
+ \keyval{post-body-hook}{code}\Module{question}\Default
+ \sinceversion{0.16}Adds \meta{code} directly after the question body.
+\end{options}
+
+\begin{example}
+ \begin{question}[type=exam]
+ This question has the type \keyis{type}{exam}. The default name has changed
+ from ``Exercise'' to ``Question''.
+ \end{question}
+ \begin{question}[name=Fancy name]
+ This question has a custom name.
+ \end{question}
+ \begin{question}[print=false]
+ This question is not printed.
+ \end{question}
+\end{example}
+
+The difference between \option{print} and \option{use} lies behind the scenes:
+with \keyis{print}{false} the question is not printed, but it still gets an
+individual \ac{id}, is numbered, and a possible solution is saved. This is
+for example useful when you want to print a sample solution for an exam. With
+\keyis{use}{false} it is fully discarded which means it is not accessible
+through an \acs{id} and a possible solution will not be saved.
+
+\subsection{Subtitles to Questions}\label{sec:subtitles-questions}
+The \option{subtitle} option mentioned in section~\ref{sec:opti-ques-envir}
+can be used to add a subtitle to a question. However, unless you choose a
+suitable heading (see section~\ref{sec:exsheets-headings}) it won't be
+printed. Currently there is \emph{one} heading instance that uses the
+subtitles but it should be easy to create a custom heading using one of the
+existing ones as a starter example. When creating such a heading you may want
+to distinguish between the cases when a subtitle has been given and when no
+subtitle is present. This can be done with the following commands:
+\begin{commands}
+ \expandable\command{IfQuestionSubtitleTF}[\marg{true code}\marg{false code}]
+ Tests if the current question has a subtitle. Leaves either \meta{true
+ code} or \meta{false code} in the input stream.
+ \expandable\command{IfQuestionSubtitleT}[\marg{true code}]
+ Tests if the current question has a subtitle. Leaves \meta{true code} in
+ the input stream if it has.
+ \expandable\command{IfQuestionSubtitleF}[\marg{false code}]
+ Tests if the current question has a subtitle. Leaves \meta{false code} in
+ the input stream if it hasn't.
+\end{commands}
+
+A subtitle is also a property of a question in the sense of
+section~\ref{sec:additional_info}. That means if a subtitle is given it can
+be retrieved with \cs{GetQuestionProperty}.
+
+As an example you could define your own heading instance that prints the
+\acs{id} of a question and (if given) the subtitle:
+
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{QE}{default}{
+ join = {
+ title[r,B]number[l,B](.333em,0pt) ;
+ title[r,B]subtitle[l,B](1em,0pt)
+ } ,
+ attach = {
+ main[l,vc]title[l,vc](0pt,0pt) ;
+ main[r,vc]points[l,vc](\marginparsep,0pt)
+ } ,
+ subtitle-post-code = {ID: \CurrentQuestionID} ,
+ number-post-code = {\IfQuestionSubtitleF{ID: \CurrentQuestionID}}
+ }
+\end{sourcecode}
+
+Please see section~\ref{sec:exsheets-headings} for more details on heading
+instances.
+
+\subsection{The \env*{solution} Environment}
+If you want to save/print (more on the exact usage in
+section~\ref{sec:solutions}) a solution you have to use the \env{solution}
+environment \emph{after} the question it belongs to and \emph{before} the next
+question.
+\begin{environments}
+ \environment{solution}[\oarg{options}]
+ The main environment for adding solutions to exercises/questions.
+\end{environments}
+\begin{example}
+ \begin{question}[ID=first]\label{qu:question_with_solution}
+ This is our first question that gets a solution!
+ \end{question}
+ \begin{solution}
+ This is the solution to exercise~\ref{qu:question_with_solution}!
+ \end{solution}
+\end{example}
+You can see that in the default settings the solution is \emph{not} written to
+the document. It has been saved, though, for possible later usage. We will
+see the solution later!
+
+\subsection{Options to the \env*{solution} Environment}\label{sec:opti-soli-envir}
+The \env{solutions} environment also has options, namely these:
+\begin{options}
+ \keyval{name}{name}\Module{solution}\Default
+ Sets a custom name.
+ \keybool{print}\Module{solution}\Default{false}
+ Prints or hides the solution.
+ \keyval{skip-below}{dim}\Module{solution}\Default{.5\cs*{baselineskip}}
+ \sinceversion{0.18}Sets the vertical space that is inserted after the
+ solution environment.
+ \keybool{no-skip-below}\Module{solution}\Default{false}
+ \sinceversion{0.18}Disables the insertion of vertical space after the
+ solution environment.
+ \keyval{pre-hook}{code}\Module{solution}\Default
+ \sinceversion{0.16}Adds \meta{code} directly before the solution title.
+ \keyval{post-hook}{code}\Module{solution}\Default
+ \sinceversion{0.16}Adds \meta{code} directly after the solution.
+ \keyval{pre-body-hook}{code}\Module{solution}\Default
+ \sinceversion{0.16}Adds \meta{code} directly before the solution body.
+ \keyval{post-body-hook}{code}\Module{solution}\Default
+ \sinceversion{0.16}Adds \meta{code} directly after the solution body.
+\end{options}
+Their meaning is the same as those for the \code{question} environment.
+\begin{example}
+ \begin{question}{5}
+ The solution to this questions gets printed where it is.
+ \end{question}
+ \begin{solution}[print]
+ See? This solution gets printed where you have put it in the code of
+ your document.
+ \end{solution}
+ \begin{question}{2.5}
+ The solution to this questions gets printed where it is \emph{and}
+ has a fancy name. Have you noticed that you can assign partial
+ points?
+ \end{question}
+ \begin{solution}[print,name=Fancy name]
+ See? This solution gets printed where you have put it and has a fancy
+ name!
+ \end{solution}
+\end{example}
+
+\subsection{Setting the Counter}\label{ssec:counter}
+The package option \option{counter-format} allows you to specify how the question
+counter (a counter unsurprisingly name \code{question}) is formatted.
+
+The input is an arbitrary string which means you can have anything as counter
+number. However, the letter combinations \code{ch}, \code{se}, \code{qu} and
+\code{tsk} are replaced with the counters for the chapter, section, question
+or tasks (see the \Tasks\ package), respectively. While the last one is not
+really useful in this case the others allow for a combined numbering. Each of
+these letter combinations can have an optional argument that specifies the
+format of the respective counter. \code{1}: \cs*{arabic}, \code{a}:
+\cs*{alph}, \code{A}: \cs*{Alph}, \code{r}: \cs*{roman} and \code{R}:
+\cs*{Roman}.
+\begin{example}
+ \SetupExSheets{counter-format=Nr~se~(qu[a])}
+ \begin{question}
+ A question with a differently formatted number.
+ \end{question}
+\end{example}
+Since the strings associated with the counters are replaced one has to hide
+them if they are actually wanted in the counter format. The easiest way would
+to hide them in braces.
+\begin{example}
+ \SetupExSheets{counter-format={section}\,se~{question}\,(qu[a])}
+ \begin{question}
+ A question with a yet differently formatted number.
+ \end{question}
+\end{example}
+
+\subsection{Language Settings}
+The names of the questions and solutions are language dependent. If you use
+\pkg{babel} or \pkg{polyglossia} \ExSheets\ will adapt to the document language.
+\ExSheets\ has a number of translations but surely not all! If you miss a
+language please drop me a line in an
+email\footnote{\href{mailto:contact@mychemistry.eu}{contact@mychemistry.eu}}
+containing the \pkg{babel} language name and the correct translations for
+questions (possibly distinguishing between exercises and exam questions) and
+solutions.
+
+Until I implement it you can add something like this to your preamble (example
+for Danish) and try if it works:
+\begin{sourcecode}
+ \DeclareTranslation{Danish}{exsheets-exercise-name}{\O{}velse}
+ \DeclareTranslation{Danish}{exsheets-question-name}{Opgave}
+ \DeclareTranslation{Danish}{exsheets-solution-name}{Opl\o{}sning}
+\end{sourcecode}
+If this isn't working it means that the language you're using is unknown to
+the \pkg{translations} package. In this case please notify me, too. You then
+can still use the \option{name} options.
+
+\section{Counting Points}\label{sec:points}
+\subsection{The Commands}
+You have seen in section~\ref{ssec:questions} that you can assign points to a
+question. If you do so these points are printed into the
+margin\footnote{Well, not necessarily. It depends on the heading style you
+ have chosen.} and are counted internally. But there are additional commands
+to assign points or bonus points and a number of commands to retrieve the sum
+of points and/or bonus points.
+\begin{commands}
+ \command{addpoints}[\sarg\marg{num}]
+ This command can be used to add points assigned to subquestions.
+ \cs{addpoints} will print the points (with ``unit'') \emph{and} add them
+ to the sum of all points, \cs{addpoints}\sarg\ will only add them but print
+ nothing.
+ \command{points}[\sarg\marg{num}]
+ This command will only print the points (with ``unit'') but won't add them
+ to the sum of points.
+ \command{addbonus}[\sarg\marg{num}]
+ This command can be used to add bonus points assigned to subquestions.
+ \cs{addbonus} will print the points (with ``unit'') \emph{and} add them
+ to the sum of all bonus points, \cs{addbonus}\sarg\ will only add them but
+ print nothing.
+ \command{bonus}[\sarg\marg{num}]
+ This command will only print the bonus points (with ``unit'') but won't
+ add them to the sum of bonus points.
+ \command{pointssum}[\sarg]
+ Prints the sum of all points with or without (starred version) ``unit'':
+ \pointssum
+ \command{currentpointssum}[\sarg]
+ Prints the current sum of points with or without (starred version)
+ ``unit'': \currentpointssum
+ \command{bonussum}[\sarg]
+ Prints the sum of all bonus points with or without (starred version)
+ ``unit'': \bonussum
+ \command{currentbonussum}[\sarg]
+ Prints the current sum of bonus points with or without (starred version)
+ ``unit'': \currentbonussum
+ \command{totalpoints}[\sarg]
+ prints the sum of the points \emph{and} the sum of the bonus points with
+ ``unit'': \totalpoints\space The starred version prints the sum of the
+ points without ``unit'': \totalpoints*.
+\end{commands}
+The commands \cs{pointssum}, \cs{bonussum} and \cs{totalpoints} need at
+least \emph{two} \LaTeX\ runs to get the sum right.
+
+Suppose you have an exercise worth \points{4} which consists of four questions
+listed with an \env{enumerate} environment that are all worth \points{1}
+each. You have two possibilities to display and count them:
+\begin{example}
+ % uses package `enumitem'
+ \begin{question}{4}
+ \begin{enumerate}[label=\alph*)]
+ \item blah (\points{1})
+ \item blah (\points{1})
+ \item blah (\points{1})
+ \item blah (\points{1})
+ \end{enumerate}
+ \end{question}
+ \begin{question}
+ \begin{enumerate}[label=\alph*)]
+ \item blah (\addpoints{1})
+ \item blah (\addpoints{1})
+ \item blah (\addpoints{1})
+ \item blah (\addpoints{1})
+ \end{enumerate}
+ \end{question}
+\end{example}
+
+\subsection{Options}
+\begin{options}
+ \keyval{name}{name}\Module{points}\Default{P.}
+ Choose the ``unit'' for the points. If you like to differentiate between
+ a single point and more than one point you can give a plural ending
+ separated with a slash: \keyis{name}{point/s}. This sets also the name of
+ the bonus points.
+ \keyval{name-plural}{plural form of name}\Module{points}\Default
+ Instead of forming the plural form with an ending to the singular form
+ this option allows to set an extra word for it. This sets also the plural
+ form for the bonus points.
+ \keyval{bonus-name}{name}\Module{points}\Default{P.}
+ Choose the ``unit'' for the bonus points. If you like to differentiate
+ between a single point and more than one point you can give a plural
+ ending separated with a slash: \key{bonus-name}{point/s}.
+ \keyval{bonus-plural}{plural form of name}\Module{points}\Default
+ Instead of forming the plural form with an ending to the singular form
+ this option allows to set an extra word for it.
+ \keybool{use-name}\Module{points}\Default{true}
+ Don't display the name at all. Or do.
+ \keyval{format}{code}\Module{points}\Default{\cs*{@firtsofone}}
+ \sinceversion{0.9d}Format number plus name as a whole. Ideally
+ \meta{code} would end with a command that takes an argument. Else
+ number plus name will be braced.
+ \keyval{number-format}{any code}\Module{points}\Default
+ This option allows formatting of the number, \eg, italics:
+ \keyis{number-format}{\cs*{textit}}.
+ \keyval{bonus-format}{any code}\Module{points}\Default
+ This option allows formatting of the number of the bonus points, \eg,
+ italics: \keyis{bonus-format}{\cs*{textit}}.
+ \keybool{parse}\Module{points}\Default{true}
+ If set to \code{false} the points are not counted and the
+ \cs{totalpoints}, \cs{pointssum} and \cs{bonussum} commands won't know
+ their value.
+ \keybool{separate-bonus}\Module{points}\Default{false}
+ This option determines whether points and bonus points each get their own
+ unit when they appear together (in the margin or with \cs{totalpoints}).
+ \keyval{pre-bonus}{tokens}\Module{points}\Default{\cs*{space}(+}
+ Code to be inserted before the bonus points when they follow normal
+ points.
+ \keyval{post-bonus}{tokens}\Module{points}\Default{)}
+ Code to be inserted after the bonus points when they follow normal
+ points.
+\end{options}
+
+\begin{example}[add-sourcecode-options={literate=}]
+ \SetupExSheets[points]{name=point/s,number-format=\color{red}}
+ \begin{question}{1}
+ This one's easy so only 1 point can be earned.
+ \end{question}
+ \begin{question}{7.5}
+ But this one's hard! 7.5 points are in there for you!
+ \end{question}
+\end{example}
+
+\section{Printing Solutions}\label{sec:solutions}
+You have already seen that you can print solutions where they are using the
+\option{print} option. But \ExSheets\ offers you quite more
+possibilities.
+
+In the next subsections the usage of the following command is discussed.
+\begin{commands}
+ \command{printsolutions}[\oarg{setting}]
+ Print solutions of questions/exercises.
+\end{commands}
+
+Before we do that a hint: remember that you can set the option \option{print}
+globally:
+\begin{sourcecode}
+ % in the preamble
+ \SetupExSheets{solution/print=true}
+\end{sourcecode}
+
+Now if you want to typeset some text depending on the option being true or not
+you can use the following commands:
+\begin{commands}
+ \expandable\command{PrintSolutionsTF}[\marg{true code}\marg{false code}]
+ Either leaves \meta{true code} or \meta{false code} in the input stream
+ depending on wether solutions are printed or not, \ie, on the value of the
+ solution's option \option{print}. Inside a \env{solution} environment
+ this always prints \meta{true code}.
+ \expandable\command{PrintSolutionsT}[\marg{true code}]
+ Either leaves \meta{true code} or nothing in the input stream depending on
+ wether solutions are printed or not, \ie, on the value of the solution's
+ option \option{print}. Inside a \env{solution} environment this always
+ prints \meta{true code}.
+ \expandable\command{PrintSolutionsF}[\marg{false code}]
+ Either leaves nothing or \meta{false code} in the input stream depending
+ on wether solutions are printed or not, \ie, on the value of the
+ solution's option \option{print}. Inside a \env{solution}environment this
+ always prints nothing.
+\end{commands}
+They might come in handy if you want two versions of an exercise sheet, one
+with the exercises and one with the solutions, and you want to add different
+titles to these versions, for instance.
+
+% When solutions are saved a lot of information is saved. One of them is the
+% current counter format. The following option determines wether the saved
+% counter format or the currently active one is used when \cs{printsolutions} is
+% called:
+% \begin{options}
+% \keybool{use-saved-counter-format}\Default{true}
+% \changedversion{0.21}When set to true the counter format of solutions
+% printed by \cs{printsolutions}\label{option:use-saved-counter-format} are
+% independent from the setting of \option{counter-format}. The saved format
+% is used instead.
+% \end{options}
+
+\subsection{Print all}\label{sec:solutions-print-all}
+The first and easiest usage of \cs{printsolutions} is the following:
+\begin{sourcecode}
+ \printsolutions
+\end{sourcecode}
+There is nothing more to say, really. It prints all solutions you have
+specified except those belonging to a question with option \keyis{use}{false}.
+Yes, there's one more point: \cs{printsolutions} only knows the solutions
+that have been set \emph{before} its usage! This is also true for every usage
+explained in the next sections.
+
+\begin{example}
+ \printsolutions
+\end{example}
+
+Two options allow to add code to the list of solutions when used with
+\cs{printsolutions}\Oarg{all} (which is the same as using it without option):
+
+\begin{options}
+ \keyval{chapter-hook}{code}
+ \sinceversion{0.13}Adds \meta{code} to the list of solutions every time
+ solutions from a new chapter are printed (before the solutions of the
+ corresponding chapter are printed).
+ \keyval{section-hook}{code}
+ \sinceversion{0.13}Adds \meta{code} to the list of solutions every time
+ solutions from a new section are printed (before the solutions of the
+ corresponding section are printed).
+\end{options}
+
+\subsection{Print per chapter/section}
+\minisec{Current chapter/section}
+If you are not creating an exercise sheet or an exam but are writing a
+textbook you maybe want a section at the end of each chapter showing the
+solution to the exercises presented in that chapter. In this case use the
+command as follows:
+\begin{sourcecode}
+ \printsolutions[section]
+ % or
+ \printsolutions[chapter]
+\end{sourcecode}
+Again, this is pretty much self-explaining. The solutions to the questions of
+the current chapter\footnote{Only if the document class you're using
+ \emph{has} chapters, of course!} or section are printed.
+\begin{example}
+ \begin{question}
+ This is the first and only question in this section.
+ \end{question}
+ \begin{solution}
+ This will be one of a few solutions printed by the following call of
+ \cs{printsolutions}.
+ \end{solution}
+ And now:
+ \printsolutions[section]
+\end{example}
+
+\minisec{Specific chapter/section}\label{sssec:print_specific_section}
+You can also print only the solutions from chapters or sections other than the
+current ones. The syntax is fairly easy:
+\begin{example}
+ \printsolutions[section={1-7,10}]
+ % the same for chapters:
+ % \printsolutions[chapter={1-7,10}]
+\end{example}
+Don't forget that \cs{printsolutions} cannot know the solutions from
+section~10 yet. It is just used to demonstrate the syntax. You can also use
+an open range, \eg, something like
+\begin{sourcecode}
+ \printsolutions[section={-4,10-}]
+\end{sourcecode}
+This would print the solutions from sections~1--4 and from all sections with
+number 10\footnote{Or rather where \cs*{value}\Marg{section} is 10 or greater --
+ the actual counter formatting is irrelevant.} and greater.
+
+There is an obvious disadvantage: you have to know the section numbers! But
+there is a solution: use the package option \keyis{use-ref}{true}. Then you
+can do something like
+\begin{sourcecode}
+ % in the preamble:
+ \usepackage[use-ref]{exsheets}
+ % somewhere in your code after \section{A really cool section title}:
+ \label{sec:ReallyCool}
+ % somewhere later in your code:
+ \printsolutions[section={-\S{sec:ReallyCool}}]
+ % which will print all solutions from questions up to and
+ % including the really cool section
+\end{sourcecode}
+With the package option \keyis{use-ref}{true} each usage of \cs*{label} will
+create additional labels (one preceded with \code{exse:} and another one with
+\code{exch:}) which store the section number and the chapter number,
+respectively. These are used internally by two commands \cs{S} and \cs{C}
+which refer to the section number and the chapter number the label was created
+in. \emph{These commands are only available as arguments of}
+\cs{printsolutions}.
+
+Since some packages like the well known \pkg{hyperref} for example redefine
+\cs*{label} \option{use-ref} won't work in together with it. In this case
+don't use \option{use-ref} and set \cs{exlabel}\marg{label} instead to
+remember the section/the chapter number. Its usage is just like \cs*{label}.
+So the safest way is as follows:
+\begin{sourcecode}
+ % in the preamble:
+ \usepackage{exsheets}
+ % somewhere in your code after \section{A really cool section title}:
+ \exlabel{sec:ReallyCool}
+ % somewhere later in your code:
+ \printsolutions[section={-\S{sec:ReallyCool}}]
+ % which will print all solutions from questions up to and
+ % including the really cool section
+\end{sourcecode}
+Please be aware that the labels must be processed in a previous \LaTeX\ run
+before \cs{S} and \cs{C} can pass them on to \cs{printsolutions}.
+
+\subsection{Print by \acs{id}}\label{ssec:ids}
+Now comes the best part: you can also print selected solutions! Every
+question has an \acs{id}. To see which \acs{id} a question has you can call
+the following command:
+\begin{commands}
+ % \command{DebugExSheets}[\Marg{\choices{true,false}}]
+ % Enable or disable visual \ExSheets' debugging.
+ \expandable\command{CurrentQuestionID}
+ \sinceversion{0.4a}Expands to the current question \acs{id}.
+\end{commands}
+\begin{options}
+ \keybool{debug}
+ Enable or disable visual \ExSheets' debugging.
+\end{options}
+Let's create some more questions and take a look what this command does:
+\begin{example}
+ \SetupExSheets{debug=true}
+ \begin{question}[ID=nice!]
+ A question with a nice \acs{id}!
+ \end{question}
+ \begin{solution}
+ The solution to the question with the nice \acs{id}.
+ \end{solution}
+ \begin{question}{3.75}
+ Yet another question. But this time with quarter points!
+ \end{question}
+ \begin{solution}
+ Yet another solution.
+ \end{solution}
+\end{example}
+
+So now we can call some specific solutions:
+\begin{example}
+ \printsolutions[byID={first,nice!,10,14}]
+\end{example}
+This makes use of the \pkg{l3sort} package which at the time of writing is
+still considered experimental. In case you wonder where solution~14 is:
+question~14 has no solution given.
+
+If you don't want that the solutions are sorted automatically but appear in
+the order given you can use the option
+\begin{options}
+ \keybool{sorted}\Module{solution}\Default{true}
+ Sort solutions given by \acs{id} or don't.
+\end{options}
+
+\section{Conditional Printing of Questions}\label{sec:cond-print-quest}
+\subsection{Using Classes}\label{sec:classes}
+For creating different variants of a written exam or different difficulty
+levels of an exercise sheet it comes in handy if one can assign certain
+classes to questions and then tell \ExSheets\ only to use one ore more
+specific classes.
+\begin{options}
+ \keyval{use-classes}{list of classes}\Default
+ When this option is used only the questions belonging to the specified
+ classes are printed and have their solutions saved.
+\end{options}
+\begin{example}
+ \SetupExSheets{use-classes={A,C}}
+ \begin{question}[class=A]
+ Belonging to class A.
+ \end{question}
+ \begin{question}[class=B]
+ Belonging to class B.
+ \end{question}
+ \begin{question}[class=C]
+ Belonging to class C!
+ \end{question}
+\end{example}
+Questions of classes that are not used are fully discarded. \emph{This also
+ means that questions that don't have a class assigned are discarded.}
+
+\ExplSyntaxOn
+ \bool_set_false:N \g__exsheets_use_classes_bool
+\ExplSyntaxOff
+
+\subsection{Using Topics}\label{sec:topics}
+Similarly to classes one can assign topics to questions. The usage is
+practically identical, the semantic meaning is different.
+\begin{options}
+ \keyval{use-topics}{list of topics}\Default
+ When this option is used only the questions belonging to the specified
+ topics are printed and have their solutions saved.
+\end{options}
+\begin{example}
+ \SetupExSheets{use-topics={trigonometry}}
+ \begin{question}[topic=trigonometry]
+ A trigonometry question.
+ \end{question}
+ \begin{question}[topic=arithmetics]
+ A arithmetics question
+ \end{question}
+\end{example}
+Questions of topics that are not used are fully discarded. \emph{This also
+ means that questions that don't have a topic assigned are discarded.}
+
+If you set both \option{use-classes} and \option{use-topics} then only
+questions will be used that \emph{match both categories}.
+
+Ideally one could assign more than one topic to a question but this is
+\emph{not} supported yet.
+
+\ExplSyntaxOn
+ \bool_set_false:N \g__exsheets_use_topics_bool
+\ExplSyntaxOff
+
+\subsection{Own Dividing Concepts}
+Actually\sinceversion{0.8} both classes and topics are introduced into
+\ExSheets\ internally this way:
+\begin{sourcecode}
+ \DeclareQuestionClass{class}{classes}
+ \DeclareQuestionClass{topic}{topics}
+\end{sourcecode}
+which means you can do the same introducing your own dividing concepts.
+\begin{commands}
+ \command{DeclareQuestionClass}[\marg{singular name}\marg{plural name}]
+ Introduces a new dividing concept and defines both new options for the
+ \env{question} environment and new global options.
+\end{commands}
+
+For example you could decide you want to group your questions according to
+their difficulty. You could place the following line in your preamble:
+\begin{sourcecode}
+ \DeclareQuestionClass{difficulty}{difficulties}
+\end{sourcecode}
+This would define an option \option*{use-difficulties} analogous to
+\option{use-classes} and \option{use-topics}. It would also define an option
+\option{difficulty} for the \env{question} environment. This means you could
+now do something like the following:
+\begin{example}
+ \SetupExSheets{use-difficulties={easy,hard}}
+ \begin{question}[difficulty=easy]
+ An easy question.
+ \end{question}
+ \begin{question}[difficulty=medium]
+ This one's a bit harder.
+ \end{question}
+ \begin{question}[difficulty=hard]
+ Now let's see if you can solve this one.
+ \end{question}
+\end{example}
+
+\subsection{Retrieving the Class Value in a Question}\label{sec:retr-class-value}
+Sometimes it may be desirable to retrieve the value of a class defined by
+\cs{DeclareQuestionClass} that a question has in order to be able to print,
+say. This is possible with the following commands:
+\begin{commands}
+ \expandable\command{GetQuestionClass}[\marg{class}]
+ Prints the value of \meta{class} a question has. The command is
+ expandable. If the class does not exist or the value is empty the command
+ expands to nothing.
+ \command{PrintQuestionClassTF}[\marg{class}\marg{true}\marg{false}]
+ Test if a question has a non-empty value for class \meta{class} and either
+ leaves \meta{true} or \meta{false} in the input stream. In the
+ \meta{true} argument you can refer to the value with \code{\#1} where you
+ want it printed.
+ \command{PrintQuestionClassT}[\marg{class}\marg{true}]
+ Like \cs{PrintQuestionClassTF} but only has the \meta{true} branch.
+ \command{PrintQuestionClassF}[\marg{class}\marg{false}]
+ Like \cs{PrintQuestionClassTF} but only has the \meta{false} branch.
+\end{commands}
+
+\begin{example}
+ \begin{question}[difficulty=hard]
+ This question has the difficulty level
+ ``\PrintQuestionClassTF{difficulty}{#1}{??}''.
+ \end{question}
+\end{example}
+
+\ExplSyntaxOn
+ \bool_set_false:N \g__exsheets_use_difficulties_bool
+\ExplSyntaxOff
+
+\subsection{Tagging Questions}
+There\sinceversion{0.20} is another way of dividing questions: you can assign
+tags to questions:
+\begin{sourcecode}
+ \begin{question}[tags={foo,bar,baz}]
+ ...
+ \end{question}
+\end{sourcecode}
+You can then decide to print only questions with certain tags by using the
+following option:
+\begin{options}
+ \keyval{use-tags}{csv list of tags to include}
+ Select tags. When used only questions being tagged with at least one of
+ the tags in \meta{csv list of tags to include} are printed.
+\end{options}
+
+\section{Adding and Using Additional Information to
+ Questions}\label{sec:additional_info}
+\subsection{Question Properties -- the Basics}
+
+For managing lots of questions and corresponding solutions it can be very
+useful to be able to save and recover additional information to the questions.
+This is possible with the following commands. First the ones for saving:
+\begin{commands}
+ \command{DeclareQuestionProperty}[\marg{name}]
+ This command defines a question property \meta{name}. It can only be
+ used in the document preamble.
+ \command{SetQuestionProperties}[\Marg{\meta{name}=\meta{value},...}]
+ Set the properties for a specific question. this command can only be used
+ inside the \env{question} environment.
+\end{commands}
+Now the commands for recovering the properties:
+\begin{commands}
+ \command{QuestionNumber}[\marg{id}]
+ Recover the number of the question with the \acs{id} \meta{id}. The
+ number is displayed according to the format set with
+ \option{counter-format}.
+ \expandable\command{GetQuestionProperty}[\marg{name}\marg{id}]
+ Recover the property \meta{name} of the question with the \acs{id}
+ \meta{id}. Of course the property must have been declared before. The
+ command is expandable. Since\changedversion{0.12} the properties of a
+ question are written to the \code{aux} file it is possible to retrieve
+ them before the corresponding \env{question} environment has been used.
+ \expandable\command{IfQuestionPropertyTF}[\marg{name}\marg{id}\marg{true}\marg{false}]
+ A command\sinceversion{0.15} that returns \meta{true} if the question with
+ the \acs{id} \meta{id} has the property \meta{name} and \meta{false}
+ otherwise. The variants \cs{IfQuestionPropertyT} and
+ \cs{IfQuestionPropertyF} also exist which only have the \meta{true} or the
+ \meta{false} branch.
+\end{commands}
+
+Let's say we have declared the properties \code{notes}, \code{reference} and
+\code{topic}. By default the property \code{points} is available and gets the
+value of the optional argument of the \code{question} environment.
+
+We can now do the following:
+\begin{example}
+ % uses `biblatex'
+ \begin{question}[ID=center,topic=LaTeX]{3}
+ Explain how you could center text in a \LaTeX\ document.
+ \SetQuestionProperties{
+ topic = \TeX/\LaTeX ,
+ notes = {How to center text.},
+ reference = {\textcite{companion}}}
+ \end{question}
+ \begin{solution}
+ To center a short part of the text body one can use the \env*{center}
+ environment (\points{1}). Inside an environment like \env*{table} one
+ should use \cs*{centering} (\points{1}). For single lines there is also
+ the \cs*{centerline} command (\points{1}).
+ \end{solution}
+ \begin{question}[ID=knuthbooks,topic=LaTeX]{2}
+ Name two books by D.\,E.\,Knuth.
+ \SetQuestionProperties{
+ topic = \TeX/\LaTeX ,
+ notes = {Books by Knuth.},
+ reference = {\textcite{knuth:ct:a,knuth:ct:b,knuth:ct:c,knuth:ct:d,knuth:ct:e}}}
+ \end{question}
+ \begin{solution}
+ For example two volumes from \citetitle{knuth:ct}:
+ \citetitle{knuth:ct:a,knuth:ct:b,knuth:ct:c,knuth:ct:d,knuth:ct:e}. Each
+ valid answer is worth \points{1}
+ \end{solution}
+\end{example}
+
+It is now possible to recover these values later:
+\begin{example}
+ % uses `booktabs'
+ \begin{center}
+ \begin{tabular}{lll}
+ \toprule
+ Question & Property & \\
+ \midrule
+ \QuestionNumber{center}
+ & Points & \GetQuestionProperty{points}{center} \\
+ & Topic & \GetQuestionProperty{topic}{center} \\
+ & References & \GetQuestionProperty{reference}{center} \\
+ & Note & \GetQuestionProperty{notes}{center} \\
+ \midrule
+ \QuestionNumber{knuthbooks}
+ & Points & \GetQuestionProperty{points}{knuthbooks} \\
+ & Topic & \GetQuestionProperty{topic}{knuthbooks} \\
+ & References & \GetQuestionProperty{reference}{knuthbooks} \\
+ & Note & \GetQuestionProperty{notes}{knuthbooks} \\
+ \bottomrule
+ \end{tabular}
+ \end{center}
+\end{example}
+
+Please note that properties \emph{are not the same} as the dividing concepts
+explained in section~\ref{sec:cond-print-quest} although they may seem
+similar in meaning or even have the same name.
+
+When properties are set they are also written to the \code{aux} file which
+means they can be retrieved \emph{before} the corresponding question. Of
+course this means that two compilation runs are necessary.
+
+\subsection{Pre-defined Properties}
+
+A few properties are already defined by \ExSheets:
+\begin{itemize}
+ \item \code{counter}:\sinceversion{0.14} this property holds the actual
+ question number formatted according to the formatting set with option
+ \option{counter-format}.
+ \item \code{subtitle}:\sinceversion{0.12} this property holds the subtitle
+ of the question if given.
+ \item \code{question-body}:\sinceversion{0.14} this property holds the body
+ of the corresponding \env{question} environment. Unlike the other
+ properties it is per default \emph{not} written to the \code{aux} file.
+ \item \code{points}: this property holds the sum of points given to a
+ question.
+ \item \code{bonus-points}:\sinceversion{0.14} this property holds the sum of
+ bonus points given to a question.
+ \item \code{ref}:\sinceversion{0.7f} when the option \option{auto-label} is
+ used this property is defined and expands to the corresponding \cs*{ref}.
+ Also see section~\ref{sec:auto-label-opti}.
+ \item \code{page-ref}:\sinceversion{0.7f} when the option
+ \option{auto-label} is used this property is defined and expands to the
+ corresponding \cs*{pageref}. Also see section~\ref{sec:auto-label-opti}.
+\end{itemize}
+
+There is one option affecting the property \code{question-body}:
+\begin{options}
+ \keybool{save-to-aux}\Module{question}\Default{false}
+ When set to \code{true} the property \code{question-body} is also written
+ to the \code{aux} file.
+\end{options}
+
+\subsection{Advanced Usage}
+
+There are additional commands\sinceversion{0.3} that might prove useful. They
+allow advanced usage of defined properties. Below an example is shown how
+they can be used to generate a grading table.
+\begin{commands}
+ \command{ForEachQuestion}[\marg{code to be executed for each used question}]
+ \changedversion{0.14}Inside the argument one can refer to the \ac{id} of a
+ question with \code{\#1}. You can also refer to the number of the
+ question with \code{\#2}. \emph{Number} means that if you \emph{use}
+ seven questions then those questions have numbers~1 to~7.
+ \expandable\command{numberofquestions}
+ \changedversion{0.14} returns the complete number of used questions.
+ \expandable\command{iflastquestion}[\marg{true code}\marg{false code}]
+ Although this command is available in the whole document it is only useful
+ inside \cs{ForEachQuestion}. It tells you if the end of the loop is
+ reached or not.
+\end{commands}
+
+One could use these commands to create a grading table, for instance:
+\begin{sourcecode}
+ \begin{tabular}{|l|*{\numberofquestions}{c|}c|}\hline
+ Question &
+ \ForEachQuestion{\QuestionNumber{#1}\iflastquestion{}{&}} &
+ Total \\ \hline
+ Points &
+ \ForEachQuestion{\GetQuestionProperty{points}{#1}\iflastquestion{}{&}} &
+ \pointssum* \\ \hline
+ Reached &
+ \ForEachQuestion{\iflastquestion{}{&}} & \\ \hline
+ \end{tabular}
+\end{sourcecode}
+For four questions the table now would look similar to
+figure~\ref{fig:grading-table}.
+
+\begin{figure}[ht]
+ \centering
+ \begin{tabular}{|l|*{4}{c|}c|}\hline
+ Question & 1. & 2. & 3. & 4. & Total \\ \hline
+ Points & 3 & 5 & 10 & 8 & 26 \\ \hline
+ Reached & & & & & \\ \hline
+ \end{tabular}
+ \caption{An example for a grading table. (Actually this is a fake. See the
+ \code{grading-table.tex} file shipped with exsheets for the real use case.)}
+ \label{fig:grading-table}
+\end{figure}
+
+
+\section{Variations of an Exam}
+
+It is a quite common task\sinceversion{0.6} to design an exam in two different
+variants. This is of course possible with \ExSheets' classes (see
+section~\ref{sec:classes}). However, often not the whole question is to be
+different but only small details, the numbers in a maths exam, say. For this
+purpose \ExSheets\ provides the following commands:
+\begin{commands}
+ \command{SetVariations}[\marg{num}]
+ Set the number of different variants. This will determine how many
+ arguments the command \cs{vary} will get. \meta{num} must at least be
+ \code{2} and is initially set to \code{2}.
+ \command{variant}[\marg{num}]
+ Choose the active variant. The argument must be a number between \code{1}
+ and the number set with \cs{SetVariations}. Initially set to \code{1}.
+ \command{vary}[\marg{variant 1}\marg{variant 2}]
+ This command is the one actually used in the document. It has a number of
+ required arguments equal to the number set with \cs{SetVariations}. All
+ of its arguments are discarded except the one specified with
+ \cs{variant}.
+ \command{lastvariant}
+ \sinceversion{0.7b}Each time \cs{vary} is called it stores the value it
+ chose in \cs{lastversion}. This might be convenient to use if one
+ otherwise would have to repeatedly write the same \cs{vary}.
+\end{commands}
+
+\begin{example}
+ \SetVariations{6}%
+ \variant{6}\vary{A}{B}{C}{D}{E}{F}
+ (last variant: \lastvariant)
+ \variant{1}\vary{A}{B}{C}{D}{E}{F}
+ (last variant: \lastvariant)
+ \variant{5}\vary{A}{B}{C}{D}{E}{F}
+ (last variant: \lastvariant)
+ \variant{2}\vary{A}{B}{C}{D}{E}{F}
+ (last variant: \lastvariant)
+ \variant{4}\vary{A}{B}{C}{D}{E}{F}
+ (last variant: \lastvariant)
+ \variant{3}\vary{A}{B}{C}{D}{E}{F}
+ (last variant: \lastvariant)
+\end{example}
+
+\section{A Grade Distribution}
+Probably this is a rather esoteric feature but it could proof useful in some
+cases. Suppose you are a German math teacher and want to grade exactly
+corresponding to the number of points relative to the sum of total points,
+regardless of how big that might be. You could do something like this to
+present your grading decisions for the exam:
+\begin{example}
+ % preamble:
+ % \DeclareRelGrades{
+ % 1 = 1 ,
+ % {1,5} = .9167 ,
+ % 2 = .8333 ,
+ % {2,5} = .75 ,
+ % 3 = .6667 ,
+ % {3,5} = .5833 ,
+ % 4 = .5
+ % }
+ \small\setlength\tabcolsep{2pt}
+ \begin{tabular}{r|*8c}
+ Punkte
+ & $\grade*{1}$ & $\le\grade*{1}$ & $\le\grade*{1,5}$ & $\le\grade*{2}$
+ & $\le\grade*{2,5}$ & $\le\grade*{3}$ & $\le\grade*{3,5}$ & $<\grade*{4}$ \\
+ Note
+ & 1 & 1--2 & 2 & 2--3 & 3 & 3--4 & 4 & 5
+ \end{tabular}
+\end{example}
+
+These are the available commands and options:
+\begin{commands}
+ \command{DeclareRelGrades}[\Marg{\meta{grade}=\meta{num},...}]
+ This command is used to define grades and assign the percentage of total
+ points to them.
+ \command{grade}[\sarg\marg{grade}]
+ Gives the number of points corresponding to a grade depending on the value
+ of \cs{pointssum} with or without (starred version) ``unit''.
+\end{commands}
+\begin{options}
+ \keyval{round}{num}\Module{grades}\Default{0}
+ The number of decimals the points of a grade are rounded to. This doesn't
+ apply to the maximum number of points if the rounded number would be
+ bigger than the actual sum.
+ \keybool{half}\Module{grades}\Default{false}
+ If set to \code{true} points are rounded either to full or to half
+ points.
+\end{options}
+
+\section{Selectively Include Questions from External Files}\label{sec:include}
+\subsection{Caveat}
+I need to say some words of caution: the \cs{includequestions} that will be
+presented shortly is probably \ExSheets' most experimental one at the time of
+writing (\today). Thanks to feedback of users it is constantly improved and
+bugs are fixed. It is not a very efficient way to insert question regarding
+performance and you shouldn't wonder if compilation slows down when you use
+it. It probably needs to be re-written all over but on the one hand that
+would introduce new bugs and on the other hand for the time being I don't have
+the capacities, anyway, so you'll have to live it, I'm afraid.
+
+\subsection{How it works}
+Suppose you have one or more files with questions prepared to use them as a
+kind of database. One for class A, say, one for class B, one for class C and
+so one, something like this:
+\begin{sourcecode}
+ % this is file classA.tex
+ \begin{question}[class=A,ID=A1,topic=X]
+ First question of class A, topic X.
+ \end{question}
+ \begin{solution}
+ First solution of class A.
+ \end{solution}
+ \begin{question}[class=A,ID=A2,topic=Y]
+ Second question of class A, topic Y.
+ \end{question}
+ \begin{solution}
+ Second solution of class A.
+ \end{solution}
+ ...
+ % end of file classA.tex
+ \endinput
+\end{sourcecode}
+You can of course just \cs*{input} or \cs*{include} it but that would of
+course include the whole file into your document. But would't it be nice to
+just include selected questions? Or maybe a five random questions from the
+file? That is possible with the following command:
+\begin{commands}
+ \command{includequestions}[\oarg{options}\marg{list of filenames}]
+ Include questions from external files.
+\end{commands}
+If you use it without options it will have the same effect as \cs*{input}.
+There are however the following options:
+\begin{options}
+ \keybool{all}\Module{include}
+ \keyval{IDs}{list of IDs}\Module{include}\Default
+ Includes only the specified questions.
+ \keyval{random}{num}\Module{include}\Default
+ Includes \meta{num} randomly selected questions. This option uses the
+ \pkg{pgfcore} package to create the pseudo-random numbers.
+ \keyval{exclude}{list of IDs}\Module{include}\Default
+ Questions who's \acp{id} are specified here are \emph{not} included. This
+ option can be combined with the \option{random} option.
+\end{options}
+
+The usage should be self-explainable:
+\begin{sourcecode}
+ % include questions A1, A3 and A4:
+ \includequestions[IDs={A1,A3,A4}]{classA.tex}
+ % or include 3 random questions:
+ \includequestions[random=3]{classA}
+\end{sourcecode}
+In order to be able to select the questions \ExSheets\ needs to \cs*{input}
+the file twice. The first time the available questions are determined, the
+second time the selected questions are used. This unfortunately means that
+anything that is \emph{not} part of a question or solution is also input
+twice. Either don't put anything else into the file or use one of the
+following commands for control:
+\begin{commands}
+ \command{PrintIfIncludeActiveTF}[\marg{true code}\marg{false code}]
+ Checks if the questions are actively included or not and puts \meta{true
+ code} or \meta{false code} in the input stream depending on the answer.
+ \command{PrintIfIncludeActiveT}[\marg{true code}]
+ Checks if the questions are actively included or not and puts \meta{true
+ code} in the input stream if the answer is yes.
+ \command{PrintIfIncludeActiveF}[\marg{false code}]
+ Checks if the questions are actively included or not and puts \meta{false
+ code} in the input stream if the answer is no.
+\end{commands}
+
+The selection can be refined further by selecting questions belonging to a
+specific class of questions (see section~\ref{sec:cond-print-quest}) before
+using \cs{includequestions}.
+
+\sinceversion{0.8}After you've used \cs{includequestions} the \acp{id} of the
+included questions is available as an unordered comma separated list in the
+following macro:
+\begin{commands}
+ \command{questionsincludedlast}
+ Unordered comma separated list of question \acp{id} included with the last
+ usage of \cs{includequestions}.
+\end{commands}
+
+\section{The \option*{auto-label} Option}\label{sec:auto-label-opti}
+The\sinceversion{0.12} package option \option{auto-label} sets a
+\cs*{label}\Marg{qu:\meta{id}} every time the question environment is used.
+Both the used command and the automated label can be customized using the
+following options:
+
+\begin{options}
+ \keyval{label-format}{code}\Default{qu:\#1}
+ The pattern for generating the automatic label. \code{\#1} gets replaced
+ by the \ac{id} of the corresponding question.
+ \keyval{label-cmd}{macro}\Default{\cs*{label}}
+ The command used for generating the label. A command that should take one
+ mandatory argument.
+ \keyval{ref-cmd}{macro}\Default{\cs*{ref}}
+ The command used in the \code{ref} property created by the
+ \option{auto-label} option, also see section \ref{sec:additional_info}.
+ The command should take one mandatory argument.
+ \keyval{pageref-cmd}{macro}\Default{\cs*{pageref}}
+ The command used in the \code{pageref} property created by the
+ \option{auto-label} option, also see section \ref{sec:additional_info}.
+ The command should take one mandatory argument.
+\end{options}
+
+\section{Own Question/Solution Pairs}
+\ExSheets\changedversion{0.9} provides the possibility to create new
+environments that behave like the \env{question} and \env{solution}
+environments. This would allow, for example, to define a
+\env*{question*}/\env*{solution*} environment pair for bonus questions. The
+following commands may be used in the document preamble:
+\begin{commands}
+ \command{NewQuSolPair}[\marg{question}\oarg{question options}\oarg{general
+ options}\marg{solution}\oarg{solution options}\oarg{general options}]
+ Define a new pair of question and solution environments.
+ \command{RenewQuSolPair}[\marg{question}\oarg{question options}\oarg{general
+ options}\marg{solution}\oarg{solution options}\oarg{general options}]
+ Redefine an existing pair of question and solution environments.
+\end{commands}
+The standard environments are defined as follows:
+\begin{sourcecode}
+ \NewQuSolPair{question}{solution}
+\end{sourcecode}
+
+Let's say we want the possibility to add bonus questions. A simple way would
+be to define starred variants that add a star in the margin left to the title:
+\begin{example}
+ % preamble:
+ % - \texorpdfstring is provided by `hyperref'
+ % - \bigstar is provided by `amssymb'
+ % \DeclareRobustCommand*\questionstar{\texorpdfstring{\bonusquestionsign}{* }}
+ % \DeclareRobustCommand*\bonusquestionsign{\llap{$\bigstar$\space}}
+ %
+ % \NewQuSolPair
+ % {question*}[name=\questionstar Bonus Question]
+ % {solution*}[name=\questionstar Solution]
+ \begin{question*}
+ This is a bonus question.
+ \end{question*}
+ \begin{solution*}[print]
+ This is what the solution looks like.
+ \end{solution*}
+\end{example}
+As you can see the environments take the same options as are described for the
+standard \env{question} and \env{solution} environments.
+
+\section{Filling in the Blanks}
+\subsection{Cloze}
+Both\changedversion{0.4} in exercise sheets and in exams it is sometimes
+desirable to be able to create \blank{blanks} that have to be filled in. Or
+maybe some more lines: \blank[width=5\linewidth]{}
+
+\begin{commands}
+ \command{blank}[\sarg\oarg{options}\marg{text to be filled in}]
+ creates a blank in normal text or in a question 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. If you
+ don't want that use the starred version.
+\end{commands}
+
+The options are these:
+\begin{options}
+ \keychoice{style}{line,wave,dline,dotted,dashed}\Module{blank}\Default{line}
+ The style of the line. This uses the corresponding command from the
+ \pkg{ulem} package and is the whole reason why \ExSheets\ loads it in the
+ first place.
+ \keyval{scale}{num}\Module{blank}\Default{1}
+ Scales the width of the blank by factor \meta{num} unless the width is
+ explicitly set.
+ \keyval{width}{dim}\Module{blank}\Default
+ The width of the line. If it is not used the width of the filled in text
+ is used.
+ \keyval{linespread}{num}\Module{blank}\Default{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{1pt}
+ \sinceversion{0.21h}When the blank line ist built it 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.
+ \keyval{line-minimum-length}{dim}\Module{blank}\Default{2em}
+ \sinceversion{0.21h}The minimal length a line must have before it is built
+ step by step.
+\end{options}
+\begin{example}
+ \begin{question}
+ Try to fill in \blank[width=4cm]{these} blanks. All of them
+ \blank[style=dotted]{are created} by using the \cs{blank}
+ \blank[style=dashed]{command}.
+ \end{question}
+ \begin{solution}[print]
+ Try to fill in \blank[width=4cm]{these} blanks. All of them
+ \blank[style=dotted]{are created} by using the \cs{blank}
+ \blank[style=dashed]{command}.
+ \end{solution}
+\end{example}
+A number of empty lines are easily created by setting the width option:
+\begin{example}
+ \blank[width=4.8\linewidth,linespread=1.5]{}
+\end{example}
+
+\subsection{Vertical Space for answers}
+When\sinceversion{0.3} you're creating an exam you might want to add some
+vertical space where the students can write down their answers. While you can
+always use \cs*{vspace} this is not always handy when the space left on the
+page is less than you want. In this case it would be nice if a) there would
+be no warning and b) the rest of the space would be added at the top of the
+next page. This is what the following command is for:
+\begin{commands}
+ \command{examspace}[\sarg\marg{dim}]
+ Add space as specified in \meta{dim}. If the space available on the
+ current page is not enough the rest of the space will be added at the top
+ of the next page. The starred version will silently drop any leftover
+ space instead of adding it to the next page.
+\end{commands}
+\begin{example}[side-by-side]
+ \begin{question}
+ What do you think of this feature?
+ \examspace{3cm}
+ \end{question}
+ This line comes after the space.
+\end{example}
+
+\section{Styling your Exercise/Exam Sheets}\label{part:style}
+\subsection{Background}
+The \ExSheets\ package makes extensive use of \LaTeX3's coffins\footnote{See
+ the documentation to the \pkg{xcoffins} package for more information on
+ that.} as well as its templates concept\footnote{Have a look into the
+ documentation to the \pkg{xtemplate} package.}. The latter allows a
+rather easy extension and customization of some of \ExSheets' environments.
+To be more precise: you can define your own instances for the headings used
+for questions and solutions.
+
+What this package doesn't provide is changing the background of questions or
+framing them. But this is easily possible using the \pkg{mdframed} package
+and its \cs*{surroundwithmdframed} command.
+
+\ExSheets{} also provides the options \option{pre-hook}, \option{post-hook},
+\option{pre-body-hook} and \option{post-body-hook} to both the question and
+the solution environment. With them it is rather straightforward to add a
+\pkg{mdframed} frame for instance:
+\begin{sourcecode}
+ \SetupExSheets{
+ solution/pre-hook = \mdframed ,
+ solution/post-hook = \endmdframed
+ }
+\end{sourcecode}
+
+Then\sinceversion{0.18} there is the macro
+\cs{exsheetsprintsolution}\marg{heading}\marg{body}\label{exsheetsprintsolution}
+which may be redefined to suit your needs. The default definition is
+equivalent to
+\begin{sourcecode}
+ \newcommand\exsheetsprintsolution[2]{#1#2}
+\end{sourcecode}
+
+\subsection{The \code{exsheets-headings} Object}\label{sec:exsheets-headings}
+\ExSheets\ defines the object \code{exsheets-headings} and one template for it,
+the `default' template. The package also defines two instances of this
+template, the `block' instance and the `runin' instance.
+
+\begin{example}
+ \SetupExSheets{headings=block}
+ \begin{question}{1}
+ a `block' heading
+ \end{question}
+ \SetupExSheets{headings=runin}
+ \begin{question}{1}
+ a `runin' heading
+ \end{question}
+\end{example}
+
+\subsubsection{Available Options}
+This section only lists the options that can be used when defining an instance
+of the `default' template. The following subsections will give loads of
+examples of their usage. The options are listed in the definition for the
+template interface:
+
+\begin{sourcecode}
+ \DeclareTemplateInterface{exsheets-heading}{default}{3}{
+ % option : type = default
+ inline : boolean = false ,
+ runin : boolean = false ,
+ indent-first : boolean = false ,
+ toc-reversed : boolean = false ,
+ vscale : real = 1 ,
+ above : length = 2pt ,
+ below : length = 2pt ,
+ main : tokenlist = ,
+ pre-code : tokenlist = ,
+ post-code : tokenlist = ,
+ title-format : tokenlist = ,
+ title-pre-code : tokenlist = ,
+ title-post-code : tokenlist = ,
+ number-format : tokenlist = ,
+ number-pre-code : tokenlist = ,
+ number-post-code : tokenlist = ,
+ subtitle-format : tokenlist = ,
+ subtitle-pre-code : tokenlist = ,
+ subtitle-post-code : tokenlist = ,
+ points-format : tokenlist = ,
+ points-pre-code : tokenlist = ,
+ points-post-code : tokenlist = ,
+ join : tokenlist = ,
+ attach : tokenlist =
+ }
+\end{sourcecode}
+
+Each heading is built with at most five coffins available with the names
+`main', `title', `subtitle', `number' and `points'. Those coffins place
+possibly the whole heading, the title, the subtitle, the question number and
+the assigned points. The only coffin that's always typeset is the `main'
+coffin, which is empty per default.
+
+Coffins can be joined (two become one, the first extends its bounding box to
+contain the second) using the following syntax:
+\begin{sourcecode}
+ join = coffin1[handle11,handle12]coffin2[handle21,handle22](x-offset,y-offset)
+\end{sourcecode}
+The syntax for attaching (two become one, the first does \emph{not} extend its
+bounding box around the second) is the same.
+
+More on coffin handles is described in the documentation for the
+\pkg{xcoffins}. Figure~\ref{fig:handles} briefly demonstrates the available
+handle pairs.
+
+\begin{figure}[ht]
+ \centering
+ \parbox{4.5cm}{%
+ \NewCoffin\ExampleCoffin
+ \SetHorizontalCoffin\ExampleCoffin{\color{gray!30}\rule{4cm}{4cm}}%
+ \DisplayCoffinHandles\ExampleCoffin{blue}%
+ }
+ \caption{Available handles for a horizontal coffin.}\label{fig:handles}
+\end{figure}
+
+It is possible\sinceversion{0.20} to add own static coffins:
+\begin{commands}
+ \command{DeclareExSheetsHeadingContainer}[\marg{name}\marg{code}]
+ Defines a new coffin \meta{name} containing \meta{code}. You can refer to
+ the current question's \ac{id} with \cs{CurrentQuestionID}.
+\end{commands}
+
+The following subsections will show all definitions of the instances available
+and how they look. This will hopefully give you enough ideas to create your
+own instance if you want to have another heading style than the ones
+available. Each of the following instances is available through the option
+\key{headings}{instance}.
+
+The following examples use a sample text defined as follows:
+\begin{sourcecode}
+ \def\s{This is some sample text we will use to create a somewhat
+ longer text spanning a few lines.}
+ \def\sample{\s\ \s\par\s}
+\end{sourcecode}
+\def\s{This is some sample text we will use to create a somewhat longer text
+ spanning a few lines.}
+\def\sample{\s\ \s\par\s}
+
+All of the following examples use the same question call:
+\begin{sourcecode}
+ \SetupExSheets{headings=<name>}
+ \begin{question}[subtitle=The subtitle of the question]{1}
+ A `<name>' heading. \sample
+ \end{question}
+\end{sourcecode}
+
+\subsubsection{The `block' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{block}{default}{
+ join = { title[r,B]number[l,B](.333em,0pt) } ,
+ attach =
+ {
+ main[l,vc]title[l,vc](0pt,0pt) ;
+ main[r,vc]points[l,vc](\marginparsep,0pt)
+ }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=block}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `block' heading. \sample
+\end{question}
+
+\subsubsection{The `runin' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{runin}{default}{
+ runin = true ,
+ number-post-code = \space ,
+ attach =
+ { main[l,vc]points[l,vc](\linewidth+\marginparsep,0pt) } ,
+ join =
+ {
+ main[r,vc]title[r,vc](0pt,0pt) ;
+ main[r,vc]number[l,vc](.333em,0pt)
+ }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=runin}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `runin' heading. \sample
+\end{question}
+
+\subsubsection{The `simple' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{simple}{default}{
+ title-format = \normalsize ,
+ points-pre-code = ( ,
+ points-post-code = ) ,
+ attach = { main[l,t]number[l,t](0pt,0pt) } ,
+ join =
+ {
+ number[r,b]title[l,b](.333em,0pt) ;
+ main[l,b]points[l,t](1em,0pt)
+ }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=simple}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `simple' heading. \sample
+\end{question}
+
+\subsubsection{The `empty' Instance}
+\sinceversion{0.9a}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{empty}{default}{
+ runin = true ,
+ above = \parskip ,
+ below = \parskip ,
+ attach = { main[l,vc]points[l,vc](\linewidth+\marginparsep,0pt) }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=empty}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ An `empty' heading. \sample
+\end{question}
+
+\subsubsection{The `block-rev' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{block-rev}{default}{
+ toc-reversed = true ,
+ join = { number[r,B]title[l,B](.333em,0pt) } ,
+ attach =
+ {
+ main[l,vc]number[l,vc](0pt,0pt) ;
+ main[r,vc]points[l,vc](\marginparsep,0pt)
+ }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=block-rev}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `block-rev' heading. \sample
+\end{question}
+
+\subsubsection{The `block-subtitle' Instance}
+\sinceversion{0.10}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{block-subtitle}{default}{
+ join = {
+ title[r,B]number[l,B](.333em,0pt) ;
+ title[r,B]subtitle[l,B](1em,0pt)
+ } ,
+ attach = {
+ main[l,vc]title[l,vc](0pt,0pt) ;
+ main[r,vc]points[l,vc](\marginparsep,0pt)
+ }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=block-subtitle}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `block-subtitle' heading. \sample
+\end{question}
+\subsubsection{The `block-wp' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{block-wp}{default}{
+ points-pre-code = ( ,
+ points-post-code = ) ,
+ join =
+ {
+ title[r,B]number[l,B](.333em,0pt) ;
+ title[r,B]points[l,B](.333em,0pt)
+ } ,
+ attach = { main[l,vc]title[l,vc](0pt,0pt) }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=block-wp}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `block-wp' heading. \sample
+\end{question}
+
+\subsubsection{The `block-wp-rev' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{block-wp-rev}{default}{
+ toc-reversed = true ,
+ points-pre-code = ( ,
+ points-post-code = ) ,
+ join =
+ {
+ number[r,B]title[l,B](.333em,0pt) ;
+ number[r,B]points[l,B](.333em,0pt)
+ } ,
+ attach = { main[l,vc]number[l,vc](0pt,0pt) }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=block-wp-rev}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `block-wp-rev' heading. \sample
+\end{question}
+
+\subsubsection{The `block-nr' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{block-nr}{default}{
+ attach =
+ {
+ main[l,vc]number[l,vc](0pt,0pt) ;
+ main[r,vc]points[l,vc](\marginparsep,0pt)
+ }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=block-nr}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `block-nr' heading. \sample
+\end{question}
+
+\subsubsection{The `block-nr-wp' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{block-nr-wp}{default}{
+ points-pre-code = ( ,
+ points-post-code = ) ,
+ join = { number[r,vc]points[l,vc](.333em,0pt) } ,
+ attach = { main[l,vc]number[l,vc](0pt,0pt) }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=block-nr-wp}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `block-nr-wp' heading. \sample
+\end{question}
+
+\subsubsection{The `runin-rev' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{runin-rev}{default}{
+ toc-reversed = true ,
+ runin = true ,
+ title-post-code = \space ,
+ attach =
+ { main[l,vc]points[l,vc](\linewidth+\marginparsep,0pt) } ,
+ join =
+ {
+ main[r,vc]number[r,vc](0pt,0pt) ;
+ main[r,vc]title[l,vc](.333em,0pt)
+ }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=runin-rev}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `runin-rev' heading. \sample
+\end{question}
+
+\subsubsection{The `runin-wp' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{runin-wp}{default}{
+ runin = true ,
+ points-pre-code = ( ,
+ points-post-code = )\space ,
+ join =
+ {
+ main[r,vc]title[r,vc](0pt,0pt) ;
+ main[r,vc]number[l,vc](.333em,0pt) ;
+ main[r,vc]points[l,vc](.333em,0pt)
+ }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=runin-wp}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `runin-wp' heading. \sample
+\end{question}
+
+\subsubsection{The `runin-wp-rev' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{runin-wp-rev}{default}{
+ toc-reversed = true ,
+ runin = true ,
+ points-pre-code = ( ,
+ points-post-code = )\space ,
+ join =
+ {
+ main[r,vc]number[r,vc](0pt,0pt) ;
+ main[r,vc]title[l,vc](.333em,0pt) ;
+ main[r,vc]points[l,vc](.333em,0pt)
+ }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=runin-wp-rev}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `runin-wp-rev' heading. \sample
+\end{question}
+
+\subsubsection{The `runin-nr' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{runin-nr}{default}{
+ runin = true ,
+ number-post-code = \space ,
+ attach =
+ { main[l,vc]points[l,vc](\linewidth+\marginparsep,0pt) } ,
+ join = { main[r,vc]number[l,vc](0pt,0pt) }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=runin-nr}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `runin-nr' heading. \sample
+\end{question}
+
+\subsubsection{The `runin-fixed-nr' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{runin-fixed-nr}{default}{
+ runin = true ,
+ number-pre-code = \hbox to 2em \bgroup ,
+ number-post-code = \hfil\egroup ,
+ attach =
+ { main[l,vc]points[l,vc](\linewidth+\marginparsep,0pt) } ,
+ join = { main[r,vc]number[l,vc](0pt,0pt) }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=runin-fixed-nr}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `runin-fixed-nr' heading. \sample
+\end{question}
+
+\subsubsection{The `runin-nr-wp' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{runin-nr-wp}{default}{
+ runin = true ,
+ points-pre-code = ( ,
+ points-post-code = )\space ,
+ join =
+ {
+ main[r,vc]number[l,vc](0pt,0pt) ;
+ main[r,vc]points[l,vc](.333em,0pt)
+ }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=runin-nr-wp}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `runin-nr-wp' heading. \sample
+\end{question}
+
+\subsubsection{The `inline' Instance}
+\sinceversion{0.5}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{inline}{default}{
+ inline = true ,
+ number-pre-code = \space ,
+ number-post-code = \space ,
+ join =
+ {
+ main[r,vc]title[r,vc](0pt,0pt) ;
+ main[r,vc]number[l,vc](0pt,0pt)
+ }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=inline}
+Text before
+\begin{question}[subtitle=The subtitle of the question]{1}
+ An `inline' heading. \sample
+\end{question}
+ Text after
+
+\subsubsection{The `inline-wp' Instance}
+\sinceversion{0.5}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{inline-wp}{default}{
+ inline = true ,
+ number-pre-code = \space ,
+ number-post-code = \space ,
+ points-pre-code = ( ,
+ points-post-code = )\space ,
+ join =
+ {
+ main[r,vc]title[r,vc](0pt,0pt) ;
+ main[r,vc]number[l,vc](0pt,0pt) ;
+ main[r,vc]points[l,vc](0pt,0pt)
+ }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=inline-wp}
+Text before
+\begin{question}[subtitle=The subtitle of the question]{1}
+ An `inline-wp' heading. \sample
+\end{question}
+ Text after
+
+\subsubsection{The `inline-nr' Instance}
+\sinceversion{0.5}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{inline-nr}{default}{
+ inline = true ,
+ number-post-code = \space ,
+ join = { main[r,vc]number[l,vc](0pt,0pt) }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=inline-nr}
+Text before
+\begin{question}[subtitle=The subtitle of the question]{1}
+ An `inline-nr' heading. \sample
+\end{question}
+ Text after
+
+\subsubsection{The `centered' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{centered}{default}{
+ join = { title[r,B]number[l,B](.333em,0pt) } ,
+ attach =
+ {
+ main[hc,vc]title[hc,vc](0pt,0pt) ;
+ main[r,vc]points[l,vc](\marginparsep,0pt)
+ }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=centered}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `centered' heading. \sample
+\end{question}
+
+\subsubsection{The `centered-wp' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{centered-wp}{default}{
+ points-pre-code = ( ,
+ points-post-code = ) ,
+ join =
+ {
+ title[r,B]number[l,B](.333em,0pt) ;
+ title[r,B]points[l,B](.333em,0pt)
+ } ,
+ attach = { main[hc,vc]title[hc,vc](0pt,0pt) }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=centered-wp}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `centered-wp' heading. \sample
+\end{question}
+
+\subsubsection{The `margin' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{margin}{default}{
+ runin = true ,
+ number-post-code = \space ,
+ points-pre-code = ( ,
+ points-post-code = )\space ,
+ join = { title[r,b]number[l,b](.333em,0pt) } ,
+ attach =
+ {
+ main[l,vc]title[r,vc](0pt,0pt) ;
+ main[l,b]points[r,t](0pt,0pt)
+ }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=margin}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `margin' heading. \sample
+\end{question}
+
+\subsubsection{The `margin-nr' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{margin-nr}{default}{
+ runin = true ,
+ attach =
+ {
+ main[l,vc]number[r,vc](-.333em,0pt) ;
+ main[r,vc]points[l,vc](\linewidth+\marginparsep,0pt)
+ }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=margin-nr}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `margin-nr' heading. \sample
+\end{question}
+
+\subsubsection{The `raggedleft' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{raggedleft}{default}{
+ join = { title[r,B]number[l,B](.333em,0pt) } ,
+ attach =
+ {
+ main[r,vc]title[r,vc](0pt,0pt) ;
+ main[r,vc]points[l,vc](\marginparsep,0pt)
+ }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=raggedleft}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `raggedleft' heading. \sample
+\end{question}
+
+\subsubsection{The `fancy' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{fancy}{default}{
+ toc-reversed = true ,
+ indent-first = true ,
+ vscale = 2 ,
+ pre-code = \rule{\linewidth}{1pt} ,
+ post-code = \rule{\linewidth}{1pt} ,
+ title-format = \large\scshape\color{rgb:red,0.65;green,0.04;blue,0.07} ,
+ number-format = \large\bfseries\color{rgb:red,0.02;green,0.04;blue,0.48} ,
+ points-format = \itshape ,
+ join = { number[r,B]title[l,B](.333em,0pt) } ,
+ attach =
+ {
+ main[hc,vc]number[hc,vc](0pt,0pt) ;
+ main[l,vc]points[r,vc](-\marginparsep,0pt)
+ }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=fancy}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `fancy' heading. \sample
+\end{question}
+
+\subsubsection{The `fancy-wp' Instance}
+\begin{sourcecode}
+ \DeclareInstance{exsheets-heading}{fancy-wp}{default}{
+ toc-reversed = true ,
+ indent-first = true ,
+ vscale = 2 ,
+ pre-code = \rule{\linewidth}{1pt} ,
+ post-code = \rule{\linewidth}{1pt} ,
+ title-format = \large\scshape\color{rgb:red,0.65;green,0.04;blue,0.07} ,
+ number-format = \large\bfseries\color{rgb:red,0.02;green,0.04;blue,0.48} ,
+ points-format = \itshape ,
+ points-pre-code = ( ,
+ points-post-code = ) ,
+ join =
+ {
+ number[r,B]title[l,B](.333em,0pt) ;
+ number[r,B]points[l,B](.333em,0pt)
+ } ,
+ attach = { main[hc,vc]number[hc,vc](0pt,0pt) }
+ }
+\end{sourcecode}
+\SetupExSheets{headings=fancy-wp}
+\begin{question}[subtitle=The subtitle of the question]{1}
+ A `fancy-wp' heading. \sample
+\end{question}
+
+\subsection{Using an \ExSheets{} Heading in Custom Code}\label{sec:using-an-exsheets}
+
+It can be useful to have access to \ExSheets{} headings in custom code. This
+is possible with the following command\sinceversion{0.14}:
+
+\begin{commands}
+ \command{ExSheetsHeading}[\marg{instance}\marg{title}\marg{number}%
+ \marg{points}\marg{bonus}\marg{id}]
+ The meaning of the arguments is as follows:
+ \begin{itemize}
+ \item \meta{instance}: the name of the headings instance to be used.
+ \item \meta{title}: the contents of the \code{title} coffin.
+ \item \meta{number}: the contents of the \code{number} coffin.
+ \item \meta{points}: The number of points given to the question. If
+ non-zero this will cause the points to be printed in the \code{points}
+ coffin.
+ \item \meta{bonus}: the same as \meta{points} but for bonus points.
+ \item \meta{id}: the \acs{id} of the question this heading belongs to.
+ \end{itemize}
+\end{commands}
+
+In combination with \cs{ForEachQuestion} the command can be used to build a
+custom list of questions. An example of its usage can be seen at the German
+Q\&A~site \TeX welt: \url{http://texwelt.de/wissen/fragen/6698#6738}.
+
+\subsection{Load Custom Configurations}
+If you have custom configurations you want to be loaded automatically then save
+them in a file \code{exsheets\_configurations.cfg}. If this file is present it
+will be loaded \cs*{AtBeginDocument}.
+
+\SetupExSheets{headings=block}
+
+\part{The \ExSheetslistings\ Package}\label{part:listings}
+\section{The Problem}
+I knew the day would come when people would ask how to include verbatim
+material in the \env{question} and \env{solution} environments. Since they're
+defined with the \pkg{environ} package they're reading their environment
+bodies like macros read their arguments. This makes it impossible to use
+verbatim material inside them\footnote{See the \TeX\ \acs{faq}
+ \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=verbwithin} for reasons
+ why.}. Now the day has come~\cite{tex.sx:131546}. Soon after the first
+question appeared I wrote the first draft for \ExSheetslistings\ for a question
+on \TeX.sx~\cite{tex.sx:133907}.
+
+\section{The Proposed Solution}
+
+The \ExSheetslistings\ package defines \pkg{listings} environments that place
+their contents inside \env{question} and \env{solution} environments. They do
+this by writing the listing to a unique auxiliary file --
+questions to \code{\cs*{jobname}-ex\meta{num}.lst} and solutions to
+\code{\cs*{jobname}-sol\meta{num}.lst} where \meta{num} is an increasing
+integer that ensures that each listing gets a unique file name. Those files
+are then included with \cs{lstinputlisting} if and when the question or
+solution is printed.
+
+\begin{environments}
+ \environment{lstquestion}[\oarg{options}]
+ A \pkg{listings} environment placed in a \env{question}.
+ \environment{lstsolution}[\oarg{options}]
+ A \pkg{listings} environment placed in a \env{solution}.
+\end{environments}
+
+All you have to do to use the package is loading it the usual way:
+\begin{sourcecode}
+ \usepackage{exsheets-listings}
+\end{sourcecode}
+This will also load the packages \ExSheets\ and \pkg{listings} if they're not
+loaded already.
+
+\begin{example}
+ % this uses my listings style used in this documentation for all pieces of
+ % code:
+ \begin{lstquestion}[%
+ pre=Explain what this piece of \TeX\ code does:,
+ listings={style=cnltx}]
+ \begingroup\expandafter\expandafter\expandafter\endgroup
+ \expandafter\ifx\csname foo\endcsname\relax
+ ...
+ \else
+ ...
+ \fi
+ \end{lstquestion}
+\end{example}
+
+The example already shows two options of these environments. Here is the
+complete list:
+\begin{options}
+ \keyval{pre}{text}
+ \meta{text} is placed before the code in the \env{question} or
+ \env{solution} environment.
+ \keyval{post}{text}
+ \meta{text} is placed after the code in the \env{question} or
+ \env{solution} environment.
+ \keyval{options}{options}
+ Options passed to underlying the \env{question} or \env{solution}
+ environment.
+ \keyval{points}{points}
+ The points assigned to the underlying \env{question} environment.
+ \keyval{listings}{options}
+ Options passed to the underlying \pkg{listings} environment.
+\end{options}
+
+There are also two new options for \ExSheets\ that can be set with
+\cs{SetupExSheets}:
+\begin{options}
+ \keyval{listings}{options}\Module{question}
+ Options passed to the underlying \pkg{listings} environment of
+ \env{lstquestion}.
+ \keyval{listings}{options}\Module{solution}
+ Options passed to the underlying \pkg{listings} environment of
+ \env{lstsolution}.
+\end{options}
+
+\section{Own Environments}
+
+\begin{commands}
+ \command{NewLstQuSolPair}[\oarg{options for both environments}\marg{lst question
+ env}\marg{question env}\oarg{options for lst question env}\marg{lst
+ solution env}\marg{solution env}\oarg{options for lst solution env}]
+ Defines two new \pkg{listings} environments that place the listing in a
+ question environment \meta{question env} or a solution environment
+ \meta{solution env}. Those underlying environments should be
+ environments as defined by \cs{NewQuSolPair}. The different options
+ allow to preset options for the newly defined environments.
+\end{commands}
+
+The existing environments have been defined like this:
+\begin{sourcecode}
+ \NewLstQuSolPair{lstquestion}{question}{lstsolution}{solution}
+\end{sourcecode}
+
+\appendix
+\part{Appendix}
+\section{A List of all Solutions used in this Manual}\label{sec:solutions:list}
+\SetupExSheets{headings=block-wp,solutions-totoc}
+\printsolutions
+
+\end{document}