From d2e50e76ef7e64efa460c918c4c751262c063476 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Sat, 13 Oct 2012 09:39:42 +0000 Subject: new latex packages exsheets (12Oct) git-svn-id: svn://tug.org/texlive/trunk@27953 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/exsheets/README | 46 + .../texmf-dist/doc/latex/exsheets/exsheets_en.pdf | Bin 0 -> 681099 bytes .../texmf-dist/doc/latex/exsheets/exsheets_en.tex | 2118 ++++++++++++++++++++ .../texmf-dist/tex/latex/exsheets/cntformats.sty | 324 +++ Master/texmf-dist/tex/latex/exsheets/exsheets.sty | 2045 +++++++++++++++++++ .../tex/latex/exsheets/exsheets_configurations.cfg | 5 + .../tex/latex/exsheets/exsheets_headings.cfg | 302 +++ .../tex/latex/exsheets/exsheets_headings.def | 371 ++++ .../tex/latex/exsheets/exsheets_tasks.cfg | 56 + .../tex/latex/exsheets/exsheets_tasks.def | 334 +++ .../texmf-dist/tex/latex/exsheets/translations.sty | 311 +++ Master/tlpkg/tlpsrc/collection-latexextra.tlpsrc | 1 + Master/tlpkg/tlpsrc/exsheets.tlpsrc | 0 13 files changed, 5913 insertions(+) create mode 100644 Master/texmf-dist/doc/latex/exsheets/README create mode 100644 Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf create mode 100644 Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex create mode 100644 Master/texmf-dist/tex/latex/exsheets/cntformats.sty create mode 100644 Master/texmf-dist/tex/latex/exsheets/exsheets.sty create mode 100644 Master/texmf-dist/tex/latex/exsheets/exsheets_configurations.cfg create mode 100644 Master/texmf-dist/tex/latex/exsheets/exsheets_headings.cfg create mode 100644 Master/texmf-dist/tex/latex/exsheets/exsheets_headings.def create mode 100644 Master/texmf-dist/tex/latex/exsheets/exsheets_tasks.cfg create mode 100644 Master/texmf-dist/tex/latex/exsheets/exsheets_tasks.def create mode 100644 Master/texmf-dist/tex/latex/exsheets/translations.sty create mode 100644 Master/tlpkg/tlpsrc/exsheets.tlpsrc diff --git a/Master/texmf-dist/doc/latex/exsheets/README b/Master/texmf-dist/doc/latex/exsheets/README new file mode 100644 index 00000000000..4ac38eeb800 --- /dev/null +++ b/Master/texmf-dist/doc/latex/exsheets/README @@ -0,0 +1,46 @@ +-------------------------------------------------------------------------- +EXSHEETS v0.2b - 2012/10/08 + +bundled packages: +the EXSHEETS package + Yet another package for the creation of exercise sheets +the TRANSLATIONS package + a simple translator +the CNTFORMATS package + A different way to read counters. + +All mentioned packages are described in exsheets_en.pdf +-------------------------------------------------------------------------- +Clemens Niederberger +Web: https://bitbucket.org/cgnieder/exsheets/ +E-Mail: contact@mychemistry.eu +-------------------------------------------------------------------------- +Copyright 2011-2012 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 package consists of the files + - exsheets.sty, exsheets_headings.def, exsheets_headings.cfg, + exsheets_tasks.def, exsheets_tasks.cfg, exsheets_configurations.cfg, + - exsheets_en.tex, exsheets_en.pdf, + - README +-------------------------------------------------------------------------- +The translations package consists of the files + - translations.sty +-------------------------------------------------------------------------- +The cntformats package consists of the files + - cntformats.sty +-------------------------------------------------------------------------- +If you have any ideas, questions, suggestions or bugs to report, please +feel free to contact me. +-------------------------------------------------------------------------- \ No newline at end of file diff --git a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf new file mode 100644 index 00000000000..8125d021770 Binary files /dev/null and b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf differ diff --git a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex new file mode 100644 index 00000000000..f8e2eefd934 --- /dev/null +++ b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex @@ -0,0 +1,2118 @@ +% 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-2012 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 package consists of the files +% - exsheets.sty, exsheets_headings.def, exsheets_headings.cfg, +% exsheets_tasks.def, exsheets_tasks.cfg, exsheets_configurations.cfg, +% - exsheets_en.tex, exsheets_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 `xelatex' and `biber' for compilation +% +\RequirePackage{setspace} +\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 = ExSheets , + 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 +} +\cnpkgusecolorscheme{friendly} + +\usepackage{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, citetitle, cmd, color, + DeclareInstance, DeclareTemplateInterface, DeclareQuestionProperty, + DebugExSheets, endspacing, GetQuestionProperty, grade, includequestions, + midrule, points, PrintIfIncludeActiveF, PrintIfIncludeActiveT, + PrintIfIncludeActiveTF, printsolutions, PrintSolutionsTF, + QuestionNumber, s, sample, setlength, SetQuestionProperties, SetupExSheets, + spacing, square, sumpoints, tabcolsep, task, textcite, textcolor, toprule, + totalpoints +} + +% translations: +\newcommand*\translations{{\scshape\textcolor{main}{translations}}\xspace} +\addcmds{ + cuisine, DeclareLanguage, DeclareLanguageAlias, 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 +} + +% ---------------------------------------------------------------------------- +% other packages, bibliography, index +\usepackage{xcoffins,wasysym,enumitem,acro,booktabs,siunitx} +\DeclareAcronym{id}{id}{Identifier} +\DeclareAcronymFormat{id}{\scshape} + +\usepackage{filecontents} +\begin{filecontents}{\jobname.ist} + heading_prefix "{\\bfseries " + heading_suffix "\\hfil}\\nopagebreak\n" + headings_flag 1 + delim_0 "\\dotfill " + delim_1 "\\dotfill " + delim_2 "\\dotfill " + delim_r "\\textendash" + suffix_2p "\\nohyperpage{\\,f.}" + suffix_3p "\\nohyperpage{\\,ff.}" +\end{filecontents} + +\usepackage{imakeidx} +% \indexsetup{level=\section*} +\makeindex[intoc,options={-sl \jobname.ist}] + +\usepackage{csquotes} +\usepackage[backend=biber]{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://www.ctan.org/pkg/answers/} +} +@package{enumitem, + title = {enumitem}, + author = {Javier Bezos}, + date = {2011-09-28}, + version = {3.5.2}, + url = {http://www.ctan.org/pkg/enumitem/} +} +@package{exam, + title = {exam}, + author = {Philip Hirschhorn}, + date = {2011-05-22}, + version = {2.4}, + url = {http://www.ctan.org/pkg/exam/} +} +@package{examdesign, + title = {examdesign}, + author = {Jason Alexander}, + date = {2001-03-26}, + version = {1.1}, + url = {http://www.ctan.org/pkg/examdesign/} +} +@package{exercise, + title = {exercise}, + author = {Paul Pichaureau}, + date = {2012-05-08}, + version = {1.58}, + url = {http://www.ctan.org/pkg/answers/} +} +@package{multienum, + title = {multienum}, + author = {Dennis Kletzing}, + date = {2005-05-19}, + version = {n.n.}, + url = {http://www.ctan.org/pkg/multienum/} +} +@package{probsoln, + title = {probsoln}, + author = {Nicola L. C. Talbot}, + date = {2011-12-10}, + version = {3.02}, + url = {http://www.ctan.org/pkg/probsolns/} +} +\end{filecontents} + +% ---------------------------------------------------------------------------- +% example definitions that have to be done in the preamble: +\DeclareQuestionProperty{points} +\DeclareQuestionProperty{notes} +\DeclareQuestionProperty{reference} +\DeclareQuestionProperty{topic} + +\DeclareRelGrades{ + 1 = 1 , + {1,5} = .9167 , + 2 = .8333 , + {2,5} = .75 , + 3 = .6667 , + {3,5} = .5833 , + 4 = .5 +} + +\DeclareTranslation{English}{Kueche}{kitchen} +\DeclareTranslation{German}{Kueche}{K\"uche} +\DeclareTranslation{Spanish}{Kueche}{cocina} +\DeclareTranslation{French}{Kueche}{cuisine} + +\usepackage{alphalph} +\makeatletter +\NewPatternFormat{aa}{\alphalph@alph} +\makeatother +\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}}} + +% ---------------------------------------------------------------------------- +% 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/or + topics 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}, \paket{lcg} +and \paket{silence}. \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{exam}~\cite{exam}, +\paket{examdesign}~\cite{examdesign}, \paket{exercise}~\cite{exercise}, +\paket{probsoln}~\cite{probsoln}, \paket{answers}~\cite{answers} (and +\href{http://www.ctan.org/characterization/primary/document-types/exams-exercise-sets-and-answers/}{many more}). + +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 section~\ref{sec: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}, 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 three packages: \ExSheets, \translations and \cntformats. +\translations is described in part~\ref{part:translations} and \cntformats in +part~\ref{part:cntformats}. These two packages provide functionality that is used +by \ExSheets. They can, however, be used independently from \ExSheets. + +\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+ + \item[]\verb+exsheets_tasks.def+ + \item[]\verb+exsheets_tasks.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 two packages, \translations and \cntformats, in different locations but since +they belong to \ExSheets they probably should be placed in the same directory. + +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. +\secidx*{Preliminary} + +\part{The \ExSheets package}\label{part:exsheets}\secidx{\ExSheets}[ExSheets] +\section{Package Usage} +\subsection{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 be \ExSheets. This is explained in a little more detail in +part~\ref{part:style} on page~\pageref{part:style}\,ff. +\secidx*{Setup} + +\subsection{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{}. + %% 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 section~\ref{sec: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} + +\subsection{Create Questions/Exercises and their Solutions} +Now, let's start with the most important part: the questions and (possibly) their +respective solutions. +\subsubsection{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} + +\subsubsection{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]{class}{}\Default{} + assigns a class to the question. See section~\ref{sec:classes} for further + information. + \Option[question]{topic}{}\Default{} + assigns a topic to the question. See section~\ref{sec:topics} for further + information. + \Option[question]{use}{\default{true}|false}\Default{true} + discards the question. Or not. +\end{beschreibung} +\begin{beispiel} + \begin{question}[type=exam] + This question has the type \texttt{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{beispiel} + +The difference between \key{print} and \key{use} lies behind the scenes: with +\key{print}{false} the question is not printed, but it still gets an individual +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 \key{use}{false} it +is fully discarded which means it is not accessible through an \acs{id} and a possible +solution will not be saved. +\secidx*{questions} + +\subsubsection{The \code{solution} Environment}\secidx{solutions} +If you want to save/print (more on the exact usage in section~\ref{sec:solutions}) +a solution you have to use the \code{solution} environment \emph{after} the +question it belongs to and \emph{before} the next question. +\begin{beschreibung} + \Umg{solution}[]{...} +\end{beschreibung} +\begin{beispiel} + \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{beispiel} +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! + +\subsubsection{Options to the \code{solution} Environment}\secidx[options]{solutions} +The \code{solutions} environment also has options, namely these: +\begin{beschreibung} + \Option[solution]{name}{}\Default{} + sets a custom name. + \Option[solution]{print}{\default{true}|false}\Default{false} + prints or hides the solution. +\end{beschreibung} +Their meaning is the same as those for the \code{question} environment. +\begin{beispiel} + \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{beispiel} +\secidx*{solutions} + +\subsubsection{Setting the Counter}\label{ssec:counter}\secidx{Setting the Counter} +The package option \key{counter-format} allows you to specify how +the question counter 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 section~\ref{sec:tasks}), 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}: \cmd{arabic}, \code{a}: \cmd{alph}, \code{A}: +\cmd{Alph}, \code{r}: \cmd{roman} and \code{R}: \cmd{Roman}. +\begin{beispiel} + \SetupExSheets{counter-format=Nr~se~(qu[a])} + \begin{question} + A question with a differently formatted number. + \end{question} +\end{beispiel} +\secidx*{Setting the Counter} + +\subsubsection{Language Settings}\secidx{Language Settings} +The names of the questions and solutions are language dependent. If you use +\paket{babel} or \paket{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 \paket{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{beispiel}[code only] + \DeclareTranslation{Danish}{exsheets-exercise-name} + {\O{}velse} + \DeclareTranslation{Danish}{exsheets-question-name} + {Opgave} + \DeclareTranslation{Danish}{exsheets-solution-name} + {Opl\o{}sning} +\end{beispiel} +If this isn't working it means that the language you're using is unknown to +the \translations package (see part~\ref{part:translations}). In this case please +notify me, too. You then can still use the \key{name} options. +\secidx*{Language Settings} + +\subsection{Counting Points}\label{sec:points}\secidx{Counting Points} +\subsubsection{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{beschreibung} + \Befehl{addpoints}*{}\newline + This command can be used to add points assigned to subquestions. + \cmd{addpoints} will print the points (with ``unit'') \emph{and} add them to + the sum of all points, \cmd{addpoints}* will only add them but print nothing. + \Befehl{points}*{}\newline + This command will only print the points (with ``unit'') but won't add them + to the sum of points. + \Befehl{addbonus}*{}\newline + This command can be used to add bonus points assigned to subquestions. + \cmd{addbonus} will print the points (with ``unit'') \emph{and} add them to + the sum of all bonus points, \cmd{addbonus}* will only add them but print nothing. + \Befehl{bonus}*{}\newline + This command will only print the bonus points (with ``unit'') but won't add them + to the sum of bonus points. + \Befehl{pointssum}*\newline + Prints the sum of all points with or without (starred version) ``unit'': + \pointssum + \Befehl{currentpointssum}*\newline + Prints the current sum of points with or without (starred version) ``unit'': + \currentpointssum + \Befehl{bonussum}*\newline + Prints the sum of all bonus points with or without (starred version) ``unit'': + \bonussum + \Befehl{currentbonussum}*\newline + Prints the current sum of bonus points with or without (starred version) ``unit'': + \currentbonussum + \Befehl{totalpoints}*\newline + prints the sum of the points \emph{and} the sum of the bonus points with ``unit'': + \totalpoints + The starred version prints the sum of the points without ``unit'': \totalpoints*. +\end{beschreibung} +The last three commands 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 \code{enumerate} environment that are all worth \points{1} each. +You have two possibilities to display and count them: +\begin{beispiel} + % 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{beispiel} + +\subsubsection{Options}\secidx[options]{Counting Points} +\begin{beschreibung} + \Option[points]{name}{}\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 seperated + with a slash: \key{name}{point/s}. This sets also the name of the bonus points. + \Option[points]{name-plural}{}\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. + \Option[points]{bonus-name}{}\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 seperated + with a slash: \key{bonus-name}{point/s}. + \Option[points]{bonus-plural}{}\Default{} + Instead of forming the plural form with an ending to the singular form this + option allows to set an extra word for it. + \Option[points]{use-name}{\default{true}|false}\Default{true} + Don't display the name at all. Or do. + \Option[points]{number-format}{}\Default{} + This option allows formatting of the number, \eg italics: + \key{number-format}{\cmd{textit}}. + \Option[points]{bonus-format}{}\Default{} + This option allows formatting of the number of the bonus points, \eg italics: + \key{bonus-format}{\cmd{textit}}. + \Option[points]{parse}{\default{true}|false}\Default{true} + If set to \code{false} the points are not counted and the \cmd{totalpoints}, + \cmd{pointssum} and \cmd{bonussum} commands won't know their value. + \Option[points]{separate-bonus}{\default{true}|false}\Default{false} + This option determines whether points and bonus points each get their own + unit when they appear together (in the margin or with \cmd{totalpoints}). + \Option[points]{pre-bonus}{}\Default{(+} + Code to be inserted before the bonus points when they follow normal points. + \Option[points]{post-bonus}{}\Default{)} + Code to be inserted after the bonus points when they follow normal points. +\end{beschreibung} +\begin{beispiel} + \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{beispiel} +\secidx*{Counting Points} + +\subsection{A Grade Distribution}\secidx{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{beispiel} + % 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{beispiel} + +These are the available commands and options: +\begin{beschreibung} + \Befehl{DeclareRelGrades}{=,...}\newline + This command is used to define grades and assign the percentage of total + points to them. + \Befehl{grade}*{}\newline + Gives the number of points corresponding to a grade depending on the value + of \cmd{pointssum} with or without (starred version) ``unit''. + \Option[grades]{round}{}\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. + \Option[grades]{half}{\default{true}|false}\Default{false} + If set to \code{true} points are rounded either to full or to half points. +\end{beschreibung} +\secidx*{Grade Distribution} + +\subsection{Printing Solutions}\label{sec:solutions}\secidx[print]{solutions} +You have already seen that you can print solutions where they are using the +\key[solution]{print} option. But \ExSheets offers you quite more possibilities. + +In the next subsections the usage of the command +\begin{beschreibung} + \Befehl{printsolutions}[] +\end{beschreibung} +is discussed. + +Before we do that a hint: remember that you can set the option \key{print} globally: +\begin{beispiel}[code only] + % in the preamble + \SetupExSheets{solution/print=true} +\end{beispiel} + +Now if you want to typeset some text depending on the option being true or not +you can use the following commands: +\begin{beschreibung} + \expandable\Befehl{PrintSolutionsTF}{}\ma{} + \expandable\Befehl{PrintSolutionsT}{} + \expandable\Befehl{PrintSolutionsF}{} +\end{beschreibung} +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. + +\subsubsection{Print all}\secidx[print!all]{solutions} +The first and easiest usage of \cmd{printsolutions} is the following: +\begin{beispiel}[code only] + \printsolutions +\end{beispiel} +There is nothing more to say, really. It prints all solutions you have specified +except those belonging to a question with option \key{use}{false}. Yes, there's +one more point: \cmd{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{beispiel}[below] + \printsolutions +\end{beispiel} + +\subsubsection{Print per chapter/section}\secidx[print!per section/chapter]{solutions} +\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{beispiel}[code only] + \printsolutions[section] + % or + \printsolutions[chapter] +\end{beispiel} +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{beispiel} + \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 + \cmd{printsolutions}. + \end{solution} + And now: + \printsolutions[section] +\end{beispiel} + +\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{beispiel}[below] + \printsolutions[section={1-7,10}] + % the same for chapters: + % \printsolutions[chapter={1-7,10}] +\end{beispiel} +Don't forget that \cmd{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{beispiel}[code only] + \printsolutions[section={-4,10-}] +\end{beispiel} +This would print the solutions from sections~1--4 and from all sections with +number 10\footnote{Or rather where \cmd{value}{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 \key{use-ref}{true}. Then you can do something +like +\begin{beispiel}[code only] + % 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{beispiel} +With the package option \key{use-ref}{true} each usage of \cmd{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 \cmd{S} and \cmd{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} \cmd{printsolutions}. + +Since some packages like the well known \paket{hyperref} for example redefine +\cmd{label} \key{use-ref} won't work in together with it. In this case don't +use \key{use-ref} and set \cmd{exlabel}{