path: root/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex

% !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}