% arara: pdflatex % arara: biber % arara: pdflatex % arara: pdflatex % -------------------------------------------------------------------------- % the EXSHEETS package % % Yet another package for the creation of exercise sheets % % -------------------------------------------------------------------------- % Clemens Niederberger % Web: https://bitbucket.org/cgnieder/exsheets/ % E-Mail: contact@mychemistry.eu % -------------------------------------------------------------------------- % Copyright 2011-2013 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. % -------------------------------------------------------------------------- % The exsheets bundle consists of the files % - exsheets.sty, exsheets_headings.def, exsheets_headings.cfg, % exsheets_configurations.cfg, % exsheets_en.tex, exsheets_en.pdf % % - tasks.sty, tasks.cfg, tasks_en.tex, task_en.pdf % % - translations.sty, translations_en.tex, translations_en.pdf, % translations-basic-dictionary-english.trsl, % translations-basic-dictionary-french.trsl, % translations-basic-dictionary-german.trsl, % translations-basic-dictionary-spanish.trsl % % - cntformats.sty, cntformats_en.tex, cntformats_en.pdf % % - README % -------------------------------------------------------------------------- % If you have any ideas, questions, suggestions or bugs to report, please % feel free to contact me. % -------------------------------------------------------------------------- % % if you want to compile this documentation you'll need the document class % `cnpkgdoc' which you can get here: % https://bitbucket.org/cgnieder/cnpkgdoc/ % the class is licensed LPPL 1.3 or later % % use `pdflatex' and `biber' for compilation % \PassOptionsToPackage{supstfm=libertinesups}{superiors} \documentclass[DIV10,toc=index,toc=bib,numbers=noendperiod]{cnpkgdoc} % ---------------------------------------------------------------------------- % document layout and typographic features \docsetup{ pkg = {[load-headings,load-tasks]exsheets} , url = {https://bitbucket.org/cgnieder/exsheets/} , title = the ExSheets bundle , subtitle = {% the packages \ExSheets, \href{tasks_en.pdf}{\Tasks}, \href{translations_en.pdf}{\translations} and \href{cntformats_en.pdf}{\cntformats}\\ \emph{or}\\ Yet another package for the creation of exercise sheets and exams.% } , name = ExSheets , language = en , modules = true , code-box = { backgroundcolor = gray!7!white , skipbelow = .6\baselineskip plus .5ex minus .5ex , skipabove = .6\baselineskip plus .5ex minus .5ex , innerleftmargin = 1.5em , innerrightmargin = 2.5em } , gobble = 1 } \makeatletter \edef\trnsltversion{\@trnslt@version} \edef\cntfmtsversion{\@cntfmts@version} \edef\tasksversion{v\@tasks@version} \makeatother \usepackage{libertinehologopatch} \cnpkgusecolorscheme{friendly} \usepackage[biblatex]{embrac}[2012/06/29] \ChangeEmph{[}[,.02em]{]}[.055em,-.08em] \ChangeEmph{(}[-.01em,.04em]{)}[.04em,-.05em] \usepackage{microtype} \usepackage[multiple]{fnpct} \renewcommand*\othersectionlevelsformat[3]{\textcolor{main}{#3\autodot}\enskip} \renewcommand*\partformat{\textcolor{main}{\partname~\thepart\autodot}} \pagestyle{headings} \setcapindent{1.5em} \setkomafont{caption}{\normalfont\footnotesize\sffamily} \setkomafont{captionlabel}{\normalfont\footnotesize\sffamily\scshape} \usepackage{booktabs,array,ragged2e} % ---------------------------------------------------------------------------- % code examples % ExSheets: \addcmds{ acs, addpoints, blank, bigstar, bottomrule, checkedchoicebox, choice, choicebox, citetitle, cmd, color, correct, DebugExSheets, DeclareInstance, DeclareQuestionClass, DeclareQuestionProperty, DeclareTemplateInterface, endspacing, examspace, ForEachQuestion, GetQuestionProperty, grade, includequestions, iflastquestion, lastvariant, midrule, NewQuSolPair, numberofquestions, points, PrintIfIncludeActiveF, PrintIfIncludeActiveT, PrintIfIncludeActiveTF, printsolutions, PrintSolutionsF, PrintSolutionsTF, PrintSolutionsT, questionsincludedlast, QuestionNumber, RenewQuSolPair, rightarrow, rlap, s, sample, setlength, SetQuestionProperties, SetupExSheets, SetVariations, spacing, square, startnewitemline, sumpoints, tabcolsep, textcite, textcolor, toprule, totalpoints, variant, vary } % translations: \newcommand*\translations{{\scshape\textcolor{main}{translations}}\xspace} \addcmds{ cuisine, DeclareDictTranslation, DeclareLanguage, DeclareLanguageAlias, DeclareLanguageDialect, DeclareTranslation, GetTranslation, GetTranslationFor, kitchen, LoadDictionary, LoadDictionaryFor, NewTranslation, ProvideDictionaryFor, RenewTranslation, SaveTranslation, SaveTranslationFor, selectlanguage } % cntformats: \newcommand*\cntformats{{\scshape\textcolor{main}{cntformats}}\xspace} \addcmds{ @cntfmts@parsed@pattern, AddCounterPattern, eSaveCounterPattern, NewCounterPattern, ReadCounterFrom, ReadCounterPattern, ReadCounterPatternFrom, SaveCounterPattern, tmpa, tmpb } % tasks: \newcommand*\Tasks{{\scshape\textcolor{main}{tasks}}\xspace} \addcmds{ leftthumbsup, NewTasks, settasks, task } % ---------------------------------------------------------------------------- % other packages, bibliography, index \usepackage{xcoffins,wasysym,enumitem,booktabs,siunitx} \usepackage[accsupp]{acro} \DeclareAcronym{id}{ short = id , long = Identifier , format = \scshape , pdfstring = ID , accsupp = ID } \usepackage{filecontents} \usepackage{imakeidx} \begin{filecontents*}{\jobname.ist} heading_prefix "{\\bfseries " heading_suffix "\\hfil}\\nopagebreak\n" headings_flag 1 delim_0 "\\dotfill\\hyperpage{" delim_1 "\\dotfill\\hyperpage{" delim_2 "\\dotfill\\hyperpage{" delim_r "}\\textendash\\hyperpage{" delim_t "}" suffix_2p "\\nohyperpage{\\,f.}" suffix_3p "\\nohyperpage{\\,ff.}" \end{filecontents*} \indexsetup{othercode=\footnotesize} \makeindex[options={-s \jobname.ist},intoc,columns=3] \usepackage{csquotes} \usepackage[backend=biber,style=alphabetic]{biblatex} \addbibresource{biblatex-examples.bib} \addbibresource{\jobname.bib} \begin{filecontents}{\jobname.bib} @package{answers, title = {answers}, author = {Mike Piff}, maintainer = {Joseph Wright}, date = {2010-10-11}, version = {2.13}, url = {http://mirror.ctan.org/macros/latex/contrib/answers/} } @package{enumitem, title = {enumitem}, author = {Javier Bezos}, date = {2011-09-28}, version = {3.5.2}, url = {http://mirror.ctan.org/macros/latex/contrib/enumitem/} } @package{eqexam, title = {eqexam}, author = {D. P. Story}, date = {2011-09-01}, version = {3.0k}, url = {http://mirror.ctan.org/macros/latex/contrib/eqexam/} } @package{esami, title = {esami}, author = {Grazia Messi­neo and Sal­va­tore Vas­sallo}, date = {2013-03-08}, version = {1.0}, url = {http://mirror.ctan.org/macros/latex/contrib/esami/} } @package{exam, title = {exam}, author = {Philip Hirschhorn}, date = {2011-05-22}, version = {2.4}, url = {http://mirror.ctan.org/macros/latex/contrib/exam/} } @package{examdesign, title = {examdesign}, author = {Jason Alexander}, date = {2001-03-26}, version = {1.1}, url = {http://mirror.ctan.org/macros/latex/contrib/examdesign/} } @package{exercise, title = {exercise}, author = {Paul Pichaureau}, date = {2012-05-08}, version = {1.58}, url = {http://mirror.ctan.org/macros/latex/contrib/exercise/} } @package{exsol, title = {exsol}, author = {Walter Daems}, date = {2013-05-12}, version = {0.6}, url = {http://mirror.ctan.org/macros/latex/contrib/exsol/} } @package{multienum, title = {multienum}, author = {Dennis Kletzing}, date = {2005-05-19}, version = {n.n.}, url = {http://mirror.ctan.org/macros/latex/contrib/multienum/} } @package{probsoln, title = {probsoln}, author = {Nicola L. C. Talbot}, date = {2012-08-23}, version = {3.04}, url = {http://mirror.ctan.org/macros/latex/contrib/probsoln/} } \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} \NewQuSolPair {question*}[name=\protect\llap{$\bigstar$\space}Bonus Question] {solution*}[name=\protect\llap{$\bigstar$\space}Solution] \NewTasks[style=multiplechoice]{choices}[\choice](3) \newcommand*\correct{\PrintSolutionsTF{\checkedchoicebox}{\choicebox}} \DeclareTranslation{English}{Kueche}{kitchen} \DeclareTranslation{German}{Kueche}{K\"uche} \DeclareTranslation{Spanish}{Kueche}{cocina} \DeclareTranslation{French}{Kueche}{cuisine} \DeclareTranslation{English}{foo}{foo} \DeclareTranslation{British}{foo}{bar} \usepackage{alphalph} \NewPatternFormat{aa}{\alphalph} \NewCounterPattern{testa}{ta} % ---------------------------------------------------------------------------- % custom commands \newcommand*\Default[1]{% \hfill\llap {% \ifblank{#1}% {(initially~empty)}% {Default:~\code{#1}}% }% \newline } \newcommand*\required{\hfill\llap{required}\newline} \newcommand*\optional{\hfill\llap{optional}\newline} \newcommand*\nooption[2]{\item[\code{\textcolor{key}{#1} = #2}] \cnpkgdocarrow\ } \newcommand*\unexpsign{$\RHD$} \newcommand*\expsign{\textcolor{red}{$\rhd$}} \renewcommand*\cnpkgdoctriangle{\unexpsign} \newcommand*\expandable{% \def\cnpkgdoctriangle{% \expsign \gdef\cnpkgdoctriangle{\unexpsign}}} \usepackage{marginnote} \makeatletter \newcommand*\sinceversion[1]{% \@bsphack \marginnote{% \footnotesize\sffamily\RaggedRight \textcolor{black!75}{Introduced in version~#1}}% \@esphack} \newcommand*\changedversion[1]{% \@bsphack \marginnote{% \footnotesize\sffamily\RaggedRight \textcolor{black!75}{Changed in version~#1}}% \@esphack} \makeatother \pdfstringdefDisableCommands{\def\llap#1{#1\space}\def\bigstar{*}} % ---------------------------------------------------------------------------- % title page \TitlePicture{% \parbox{.8\linewidth}{% \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.}} \begin{document} \part{Preliminary}\secidx{Preliminary} \section{Licence and Requirements} \secidx[Licence]{Preliminary}\secidx[Requirements]{Preliminary} \ExSheets is placed under the terms of the \LaTeX{} Project Public License, version 1.3 or later (\url{http://www.latex-project.org/lppl.txt}). It has the status ``maintained.'' \ExSheets loads and needs the following packages: \paket*{l3kernel}, \paket{xparse}, \paket{xtemplate}, \paket{l3sort}, \paket{l3keys2e}, \paket{xcolor}, \paket{ulem}, \paket{etoolbox}, \paket{environ}, and \paket{pgfcore}. \ExSheets calls \cmd{normalem} (from the \paket{ulem} package). \section{Motivation}\secidx[Motivation]{Preliminary} 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: \paket*{eqexam}~\cite{eqexam}, \paket*{exam}~\cite{exam}, \paket*{examdesign}~\cite{examdesign}, \paket*{exercise}~\cite{exercise}, \paket*{probsoln}~\cite{probsoln}, \paket*{answers}~\cite{answers}, \paket*{esami}~\cite{esami}, \paket*{exsol}~\cite{exsol} (and many more% \footnote{see \url{http://www.ctan.org/characterization/primary/document-types/exams-exercise-sets-and-answers/}}). 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. \ExSheets provides a possibility for that (see part~\ref{part:tasks}). I am not quite content with it as it works now, though\footnote{There are still other possibilities, for example take a look here: \url{http://tex.stackexchange.com/questions/67966/enumerate-in-multicols} or at the \paket*{multienum} package~\cite{multienum}.}. On the other hand \ExSheets doesn't --~and probably won't~-- offer a real possibility for creating multiple choice questions. As a fact it doesn't provide many (if any) means to specify the \emph{type} of question or the structure. If these are your needs take a look at \paket{examdesign}~\cite{examdesign}, for example. Or exploit the possibilities \paket{enumitem}~\cite{enumitem} gives you. 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 \paket*{l3kernel} and \paket*{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 four packages: \ExSheets, \Tasks, \translations and \cntformats. \Tasks is described in part~\ref{part:tasks}, \translations is described in part~\ref{part:translations} and \cntformats in part~\ref{part:cntformats}. These packages provide functionality that is used by \ExSheets. They can, however, be used independently from \ExSheets. The packages \translations and \cntformats both aren't really useful on a user-level but maybe for package writers. \section{Installation}\secidx[Installation]{Preliminary} 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}. You \emph{can} install the other packages, \Tasks, \translations and \cntformats, in different locations but since they belong to \ExSheets they probably should be placed in the same directory. You should put the file \code{tasks.cfg} in the same directory as the \code{tasks.sty} file. 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. \section{News} 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 \cmd{SetupExSheets} but with \cmd{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 \cmd{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 \cmd{settasks}{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}, \href{translations_en.pdf}{\translations} and \href{cntformats_en.pdf}{\cntformats} -- have gotten their own documentation which are essentially extracted from this very document you're reading now. They still will be documented in the main documentation (this document), though. Right now (April~25th~2013) the separate documentations do not contain much more information than is written here but they might, in time, get more details about the corresponding package. \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. \secidx*{Preliminary} \part{The \ExSheets package}\label{part:exsheets}\secidx{\ExSheets}[ExSheets] \section{Setup}\secidx{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{beispiel}[code only] \usepackage[]{exsheets} \end{beispiel} These options are described in section~\ref{sec:options}. The second type are options that belong to a specific environment or command. These options are either used directly with the environment/command \begin{beispiel}[code only] \begin{env}[] ... \end{env} \end{beispiel} or can be set with the setup command: \begin{beschreibung} \Befehl{SetupExSheets}[]{} \end{beschreibung} The options of the second type all belong to \textcolor{module}{\code{modules}}. Let's say you want to specify some options of the \code{question} environment. You can then say the following: \begin{beispiel}[code only] \SetupExSheets[question]{option1,option2=value2} % or: \SetupExSheets{question/option1,question/option2=value2} \end{beispiel} The \textcolor{module}{\code{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 \paket{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. \secidx*{Setup} \section{Package Options}\label{sec:options}\secidx{Package Options} The package \ExSheets has some options, namely the following ones: \begin{beschreibung} %% color \Option{color}{}\Default{exsheetsblue} A custom colour that is used in certain but very rare circumstances. %% counter-format \Option{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}. \Option{counter-within}{}\Default{} Resets the \code{question} counter with every step of \code{}. %% auto-label \Option{auto-label}{\default{true}|false}\Default{false} If set to true \ExSheets will automatically place a \cmd*{label}{qu:} for each question. It will also create the question properties \code{ref} and \code{pageref}, see section~\ref{sec:additional_info} for more on this. %% headings \Option{headings}{}\Default{block} Choose the style of the questions' and solutions' headings. There are two predefined styles: \code{block} and \code{runin}. %% headings-format \Option{headings-format}{}\Default{\cmd{normalsize}\cmd{bfseries}} This code is placed immediately before the headings of the questions and solutions. %% load-headings \Option{load-headings}{\default{true}|false}\Default{false} Loads additional styles for the headings. More on this is described in section~\ref{sec:exsheets-headings}. %% load-tasks \Option{load-tasks}{\default{true}|false}\Default{false} Loads additional styles for the \code{tasks} environment. See part~\ref{part:tasks}. %% totoc \Option{totoc}{\default{true}|false}\Default{false} This option adds the questions and solutions with their names and numbers to the table of contents. %% questions-totoc \Option{questions-totoc}{\default{true}|false}\Default{false} This option adds the questions with their names and numbers to the table of contents. %% solutions-totoc \Option{solutions-totoc}{\default{true}|false}\Default{false} This option adds the solutions with their names and numbers to the table of contents. %% toc-level \Option{toc-level}{}\Default{subsection} This option sets the level in which questions and solutions should appear in the table of contents. %% questions-toc-level \Option{questions-toc-level}{}\Default{subsection} This option sets the level in which questions should appear in the table of contents. %% solutions-toc-level \Option{solutions-toc-level}{}\Default{subsection} This option sets the level in which solutions should appear in the table of contents. %% use-ref \Option{use-ref}{\default{true}|false}\Default{false} enable referencing to sections and chapters in a way that the references can be used with \cmd{printsolutions}, see section~\ref{sssec:print_specific_section} for details. \end{beschreibung} The \code{toc} options are demonstrated with section~\ref{sec:solutions:list} and the solutions printed there being listed in the table of contents. \secidx*{Package Options} \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 \code{question} Environment}\label{ssec:questions} Questions are written inside the \code{question} environment: \begin{beschreibung} \Umg{question}[]{\unskip\ma{} ... } \end{beschreibung} \begin{beispiel} \begin{question} This is our very first very difficult to solve question! \end{question} \end{beispiel} 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 \code{question} environment takes an optional argument \ma{} that can be used to assign points to the question (as is common in written exams): \begin{beispiel} \begin{question}{3} This is our first difficult question that is worth 3 points! \end{question} \end{beispiel} 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{+} as argument. \begin{beispiel} \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{beispiel} \sinceversion{0.3}On additional thing: you might want to define custom commands that should behave differently if they're inside or outside of the \code{question} environment. In this case you can use these commands: \begin{beschreibung} \expandable\Befehl{IfInsideQuestionTF}{}\ma{} \expandable\Befehl{IfInsideQuestionT}{} \expandable\Befehl{IfInsideQuestionF}{} \end{beschreibung} \subsection{Options to the \code{question} Environment}\secidx[options]{questions} The \code{question} environment takes one or more of the following options: \begin{beschreibung} \Option[question]{type}{exam|exercise}\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.\\ If you use \cmd*{usepackage}[ngerman]{babel}, for example, then the names are ``\"Ubung and ``Aufgabe''. \Option[question]{name}{}\Default{} sets a custom name. All predefined names are discarded. \Option[question]{print}{\default{true}|false}\Default{true} prints or hides the question. \Option[question]{ID}{}\Default{} assigns a custom \acs{id} to the question. See section~\ref{ssec:ids} for further information. \Option[question]{label}{