From 478b4d04587698beca915fbed7329dbb77f6fde1 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 25 Oct 2013 21:58:37 +0000 Subject: exsheets (25oct13) git-svn-id: svn://tug.org/texlive/trunk@31997 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/exsheets/README | 12 +- .../doc/latex/exsheets/cntformats_en.pdf | Bin 423275 -> 416464 bytes .../doc/latex/exsheets/cntformats_en.tex | 555 ++--- .../texmf-dist/doc/latex/exsheets/exsheets_en.pdf | Bin 638882 -> 690202 bytes .../texmf-dist/doc/latex/exsheets/exsheets_en.tex | 2592 ++++++++++---------- Master/texmf-dist/doc/latex/exsheets/tasks_en.pdf | Bin 430673 -> 443041 bytes Master/texmf-dist/doc/latex/exsheets/tasks_en.tex | 783 +++--- .../texmf-dist/tex/latex/exsheets/cntformats.sty | 241 +- .../tex/latex/exsheets/exsheets-listings.sty | 146 ++ Master/texmf-dist/tex/latex/exsheets/exsheets.sty | 230 +- .../tex/latex/exsheets/exsheets_headings.cfg | 66 +- .../tex/latex/exsheets/exsheets_headings.def | 145 +- 12 files changed, 2407 insertions(+), 2363 deletions(-) create mode 100644 Master/texmf-dist/tex/latex/exsheets/exsheets-listings.sty (limited to 'Master/texmf-dist') diff --git a/Master/texmf-dist/doc/latex/exsheets/README b/Master/texmf-dist/doc/latex/exsheets/README index c679481cec6..8869c5c2001 100644 --- a/Master/texmf-dist/doc/latex/exsheets/README +++ b/Master/texmf-dist/doc/latex/exsheets/README @@ -1,14 +1,15 @@ -------------------------------------------------------------------------- -EXSHEETS 2013/06/28 +EXSHEETS 2013/10/24 bundled packages: -the EXSHEETS package v0.9h +the EXSHEETS package v0.10 Yet another package for the creation of exercise sheets -the CNTFORMATS package v0.5 +the EXSHEETS-LISTINGS package v0.2 + Using listings in exsheets +the CNTFORMATS package v0.6 A different way to read counters. the TASKS package v0.9d Horizontal columned lists. -All mentioned packages are described in exsheets_en.pdf -------------------------------------------------------------------------- Clemens Niederberger Web: https://bitbucket.org/cgnieder/exsheets/ @@ -29,7 +30,8 @@ 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.sty, exsheets-listings.sty, + exsheets_headings.def, exsheets_headings.cfg, exsheets_configurations.cfg, exsheets_en.tex, exsheets_en.pdf diff --git a/Master/texmf-dist/doc/latex/exsheets/cntformats_en.pdf b/Master/texmf-dist/doc/latex/exsheets/cntformats_en.pdf index 8af9557974d..bcb1bc621b0 100644 Binary files a/Master/texmf-dist/doc/latex/exsheets/cntformats_en.pdf and b/Master/texmf-dist/doc/latex/exsheets/cntformats_en.pdf differ diff --git a/Master/texmf-dist/doc/latex/exsheets/cntformats_en.tex b/Master/texmf-dist/doc/latex/exsheets/cntformats_en.tex index 98a1605aa48..8fa6ed82b38 100644 --- a/Master/texmf-dist/doc/latex/exsheets/cntformats_en.tex +++ b/Master/texmf-dist/doc/latex/exsheets/cntformats_en.tex @@ -1,11 +1,11 @@ % arara: pdflatex -% arara: biber -% arara: pdflatex +% !arara: biber +% !arara: pdflatex % arara: pdflatex % -------------------------------------------------------------------------- -% the TRANSLATIONS package +% the CNTFORMATS package % -% +% A different way to read counters % % -------------------------------------------------------------------------- % Clemens Niederberger @@ -31,94 +31,50 @@ % 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[toc=index,toc=bib,numbers=noendperiod]{cnpkgdoc} -% ---------------------------------------------------------------------------- -% document layout and typographic features -\docsetup{ - pkg = {cntformats} , +\documentclass[load-preamble+]{cnltx-doc} +\usepackage{cntformats} + +\setcnltx{ + package = {cntformats} , + authors = Clemens Niederberger , + email = {contact@mychemistry.eu} , url = {https://bitbucket.org/cgnieder/exsheets/} , - subtitle = {{\small part of the \href{exsheets_en.pdf}{\ExSheets} bundle}\\[\baselineskip]a different way to read counters} , - language = en , - modules = true , - code-box = { - backgroundcolor = gray!7!white , - skipbelow = .6\baselineskip plus .5ex minus .5ex , - skipabove = .6\baselineskip plus .5ex minus .5ex + info = {% + {\small part of the \href{exsheets_en.pdf}{\ExSheets} + bundle}\\[\baselineskip] + a different way to read counters% } , - gobble = 1 + add-cmds = { + @cntfmts@parsed@pattern, AddCounterPattern, + eSaveCounterPattern, + NewCounterPattern, NewPatternFormat, + ReadCounterFrom, ReadCounterPattern, ReadCounterPatternFrom, + SaveCounterPattern + } , + add-silent-cmds = { + alphalph, + cs, + ExplSyntaxOff, ExplSyntaxOn, + int, + myoddnumber, + numexpr, ordinalnum, + relax, + somesetupcommand, + tmpa, tmpb, the + } } -\usepackage{libertinehologopatch} -\cnpkgusecolorscheme{friendly} + +\defbibheading{bibliography}[\bibname]{\addsec{#1}} + +\newpackagename\ExSheets{ExSheets} +\def\at{\cnltxat} \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 -\addcmds{ - @cntfmts@parsed@pattern, AddCounterPattern, alphalph, - cs, eSaveCounterPattern, ExplSyntaxOff, ExplSyntaxOn, int, - myoddnumber, NewCounterPattern, NewPatternFormat, numexpr, ordinalnum, - ReadCounterFrom, ReadCounterPattern, ReadCounterPatternFrom, relax, - SaveCounterPattern, somesetupcommand, - tmpa, tmpb, the -} - -% ---------------------------------------------------------------------------- -% 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,columnsep=1em] - -\usepackage{csquotes} -\usepackage[backend=biber,style=alphabetic]{biblatex} - +\usepackage{subcaption} % ---------------------------------------------------------------------------- % example definitions that have to be done in the preamble: @@ -130,278 +86,225 @@ \NewPatternFormat{x}{\myoddnumber} \NewCounterPattern{testa}{ta} -% ---------------------------------------------------------------------------- -% custom commands -\newcommand*\ExSheets{{\scshape\textcolor{main}{ExSheets}}\xspace} - -\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}{% -% }% -% } - \begin{document} -\section{Motivation}\secidx{Motivation} -\cntformats provides a way to format counters with what I will call patterns. -This does not in any way effect the usual \LaTeXe\ way of treating counters and -does not use \cmd*{the} nor is it affected by the redefinition of them. +\section{Motivation} +\cntformats\ provides a way to format counters with what I will call patterns. +This does not in any way effect the usual \LaTeXe\ way of treating counters +and does not use \cs*{the\meta{counter}} nor is it affected by the redefinition of +them. This package is aimed at package or class authors and probably not very useful for document authors. When I first had the idea for this package the idea of what it does already -existed as part of the \ExSheets package. I can't recall why I came up with +existed as part of the \ExSheets\ package. I can't recall why I came up with the idea in the first place or why I originally wanted a new syntax for -formatting the \code{question} counter. Anyway, here we are. -\secidx*{Motivation} +formatting the \code{question} counter. I am also not convinced any more that +it is a good idea. Anyway, here we are. -\section{License and Requirements}\label{sec:license}\secidx{Requirements} -\cntformats 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.'' +\section{License and Requirements}\label{sec:license} +\license -\cntformats requires the \paket{etoolbox} package. -\secidx*{Requirements} +\cntformats\ requires the \needpackage{etoolbox} package~\cite{pkg:etoolbox} +and the \pkg*{cnltx-base}\footnote{\CTANurl{cnltx}} package~\cite{bnd:cnltx}. -\section{Example}\secidx{Example} +\section{Example} A use case typically looks as follows: -\begin{beispiel} - \ReadCounterPattern{se.sse} -\end{beispiel} -where the key \code{se} stands for the current value of the \code{section} counter -and \code{sse} for \code{subsection}, respectively. \code{se.sse} is an example -for what will be called \emph{pattern}. The keys for the counters can have optional -arguments that specify the format: -\begin{beispiel} - \stepcounter{subsection} - \ReadCounterPattern{se[A](sse[r])} -\end{beispiel} -\code{A} stands for \cmd{Alph} and \code{r} for \cmd{roman}. A complete list can -be found in table~\ref{tab:predefined:formats} on page~\pageref{tab:predefined:formats}. -As you can see you can insert arbitrary other tokens in a pattern that won't be -changed. It is important to notice, though, that the patterns are only replaced -if they're \emph{not} placed in a braced group! - -\begin{beispiel} - \ReadCounterPattern{{se[A](sse[r])}} -\end{beispiel} - -I would imagine that the argument to \cmd{ReadCounterPattern} is usually +\begin{example}[side-by-side] + \ReadCounterPattern{se.sse} +\end{example} +where the key \code{se} stands for the current value of the \code{section} +counter and \code{sse} for \code{subsection}, respectively. \code{se.sse} is +an example for what will be called \emph{pattern}. The keys for the counters +can have optional arguments that specify the format: +\begin{example}[side-by-side] + \stepcounter{subsection} + \ReadCounterPattern{se[A](sse[r])} +\end{example} +\code{A} stands for \cs*{Alph} and \code{r} for \cs*{roman}. A complete list +can be found in table~\ref{tab:predefined:formats} on +page~\pageref{tab:predefined:formats}. As you can see you can insert +arbitrary other tokens in a pattern that won't be changed. It is important to +notice, though, that the patterns are only replaced if they're \emph{not} +placed in a braced group! + +\begin{example}[side-by-side] + \ReadCounterPattern{{se[A](sse[r])}} +\end{example} + +I would imagine that the argument to \cs{ReadCounterPattern} is usually supplied by a user setting an option \ldots -\begin{beispiel}[code only] - \somesetupcommand{ - counter-format = se[A](sse[r]) - } -\end{beispiel} +\begin{sourcecode} + \somesetupcommand{ + counter-format = se[A](sse[r]) + } +\end{sourcecode} \ldots{} and then internally used by the corresponding package or class. -\secidx*{Example} -\section{Usage}\secidx{Usage} -In the following description of the available commands the symbol \expsign{} -means that the command is expandable, \unexpsign{} means that it isn't. -In order to make counters known to \cntformats the following commands are used: -\begin{beschreibung} - \Befehl{AddCounterPattern}*[]{}\ma{}\newline - This command will make the (existing) counter \code{} known to - \cntformats and assign the pattern \code{} to it. - \Befehl{NewCounterPattern}*[]{}\ma{}\newline - This command will create a new counter \code{}, make it known to - \cntformats and assign the pattern \code{} to it. - \Befehl{ReadCounterFrom}[]{}\ma{}\newline - If you use one of the commands above with the starred version the number for - the pattern is not automatically fetched from the internal \cmd*{c@}. - This can now be assigned with \cmd{ReadCounterFrom} where \code{} - is the macro that holds the number. -\end{beschreibung} +\section{Usage} +In the following description of the available commands the symbol +\textcolor{expandable}{\expandablesign} means that the command is expandable. + +In order to make counters known to \cntformats\ the following commands are used: +\begin{commands} + \command{AddCounterPattern}[\sarg\oarg{module}\marg{counter}\marg{pattern}] + This command will make the (existing) counter \meta{counter} known to + \cntformats\ and assign the pattern \meta{pattern} to it. + \command{NewCounterPattern}[\sarg\oarg{module}\marg{counter}\marg{pattern}] + This command will create a new counter \meta{counter}, make it known to + \cntformats\ and assign the pattern \meta{pattern} to it. + \command{ReadCounterFrom}[\oarg{module}\marg{counter}\marg{internal cmd}] + If you use one of the commands above with the starred version the number + for the pattern is not automatically fetched from the internal + \cs*{c@\meta{counter}}. This can now be assigned with + \cs{ReadCounterFrom} where \meta{internal cmd} is the macro that holds + the number. +\end{commands} The commands above can only be used in the document preamble. After the creation of these pattern markers one wants to be able to use them. There are a number of macros that allow different aspects of usage. -\begin{beschreibung} - \Befehl{ReadCounterPattern}[]{}\newline - Reads, interprets and prints a pattern. - \expandable\Befehl{@cntfmts@parsed@pattern}\newline - After \cmd{ReadCounterPattern} has been used the current pattern interpretation - is stored in this macro. The \emph{interpretation} is \emph{not} what is printed. - See the examples below for details. - \Befehl{ReadCounterPatternFrom}[]{}\newline - Reads, interprets and prints a pattern that's stored in a macro.\\ - Otherwise the same as \cmd{ReadCounterPattern}. - \Befehl{SaveCounterPattern}{}\ma{}\ma{}\newline - Saves the \code{} in \code{} and the interpreted pattern in - \code{}. - \Befehl{eSaveCounterPattern}[]{}\ma{}\ma{}\newline - Saves the \code{} in \code{} and the expanded pattern in - \code{}. - \Befehl{SaveCounterPatternFrom}[]{}\ma{}\ma{}\newline - Like \cmd{SaveCounterPattern} but reads the pattern from a macro. - \Befehl{eSaveCounterPatternFrom}[]{}\ma{}\ma{}\newline - Like \cmd{eSaveCounterPattern} but reads the pattern from a macro. -\end{beschreibung} - -The optional argument \code{} should be specific for a package, say, so +\begin{commands} + \command{ReadCounterPattern}[\oarg{module}\marg{pattern}] + Reads, interprets and prints a pattern. + \expandable\command{\at cntfmts\at parsed\at pattern} + After \cs{ReadCounterPattern} has been used the current pattern + interpretation is stored in this macro. The \emph{interpretation} is + \emph{not} what is printed. See the examples below for details. + \command{ReadCounterPatternFrom}[\oarg{module}\marg{macro that holds + pattern}] + Reads, interprets and prints a pattern that's stored in a macro.\\ + Otherwise the same as \cs{ReadCounterPattern}. + \command{SaveCounterPattern}[\marg{cmd a}\marg{cmd b}\marg{pattern}] + Saves the \meta{pattern} in \meta{cmd a} and the interpreted pattern in + \meta{cmd b}. + \command{eSaveCounterPattern}[\oarg{module}\marg{cmd a}\marg{cmd + b}\marg{pattern}] + Saves the \meta{pattern} in \meta{cmd a} and the expanded pattern in + \meta{cmd b}. + \command{SaveCounterPatternFrom}[\oarg{module}\marg{cmd a}\marg{cmd + b}\marg{macro that holds pattern}] + Like \cs{SaveCounterPattern} but reads the pattern from a macro. + \command{eSaveCounterPatternFrom}[\oarg{module}\marg{cmd a}\marg{cmd + b}\marg{macro that holds pattern}] + Like \cs{eSaveCounterPattern} but reads the pattern from a macro. +\end{commands} + +The optional argument \meta{module} should be specific for a package, say, so that different patterns for the \code{section} for example don't interfer with -each other. If you leave the argument the default module \code{cntfmts} is used. +each other. If you leave the argument the default module \code{cntfmts} is +used. -The \ExSheets packages uses the commands with the module \code{exsheets}. +The \ExSheets\ packages uses the commands with the module \code{exsheets}. You can find the following lines in \ExSheets' code: -\begin{beispiel}[code only] - \AddCounterPattern*[exsheets]{section}{se} - \ReadCounterFrom[exsheets]{section} \l__exsheets_counter_sec_int - \NewCounterPattern*[exsheets]{question}{qu} - \ReadCounterFrom[exsheets]{question} \l__exsheets_counter_qu_int -\end{beispiel} +\begin{sourcecode} + \AddCounterPattern*[exsheets]{section}{se} + \ReadCounterFrom[exsheets]{section} \l__exsheets_counter_sec_int + \NewCounterPattern*[exsheets]{question}{qu} + \ReadCounterFrom[exsheets]{question} \l__exsheets_counter_qu_int +\end{sourcecode} Now let's see a short example that hopefully explains what the macros do: -\begin{beispiel} - % preamble - % \NewCounterPattern{testa}{ta} - \setcounter{testa}{11} - \ReadCounterPattern{ta} - \ReadCounterPattern{ta[a]} \\ - \ttfamily\makeatletter - \meaning\@cntfmts@parsed@pattern - - \bigskip - \SaveCounterPattern\tmpa\tmpb{ta[a]} - \meaning\tmpa \\ - \meaning\tmpb - - \bigskip - \eSaveCounterPattern\tmpa\tmpb{ta[a]} - \meaning\tmpa \\ - \meaning\tmpb -\end{beispiel} -You can see that somehow additional (empty) groups and a \cmd*{relax} found their -way into the interpreted and thus the expanded pattern. This is due to the fact -that reading optional arguments expandably isn't easy and must have some safety -net. -\secidx*{Usage} - -\section{Predefined and New Patterns and Format Keys}\secidx{Predefined Patterns} +\begin{example} + % preamble + % \NewCounterPattern{testa}{ta} + \setcounter{testa}{11} + \ReadCounterPattern{ta} + \ReadCounterPattern{ta[a]} \\ + \ttfamily\makeatletter + \meaning\@cntfmts@parsed@pattern + + \bigskip + \SaveCounterPattern\tmpa\tmpb{ta[a]} + \meaning\tmpa \\ + \meaning\tmpb + + \bigskip + \eSaveCounterPattern\tmpa\tmpb{ta[a]} + \meaning\tmpa \\ + \meaning\tmpb +\end{example} +You can see that somehow an additional \cs*{@empty} found its way into the +interpreted pattern. This is due to the fact that reading optional arguments +expandably isn't easy and must have some safety net. + +\section{Predefined and New Patterns and Format Keys} \subsection{Predefined Patterns and Format Keys} -\cntformats predefines a number of pattern keys. These are listed in +\cntformats\ predefines a number of pattern keys. These are listed in table~\ref{tab:predefined:patterns}. -\begin{multicols}{2} -\begin{center} - \centering - \captionof{table}{Predefined Patterns for the module \code{cntfmts}.}\label{tab:predefined:patterns} - \begin{tabular}{>{\ttfamily}l>{\ttfamily}l} - \toprule - \normalfont\bfseries counter & \normalfont\bfseries pattern \\ - \midrule - chapter & ch \\ - section & se \\ - subsection & sse \\ - subsubsection & ssse \\ - paragraph & pg \\ - \bottomrule - \end{tabular} - - \captionof{table}{Predefined Format Keys}\label{tab:predefined:formats} - \begin{tabular}{>{\ttfamily}ll} - \toprule - \normalfont\bfseries key & \normalfont\bfseries format \\ - \midrule - 1 & \cmd{arabic} \\ - a & \cmd{alph} \\ - A & \cmd{Alph} \\ - r & \cmd{roman} \\ - R & \cmd{Roman} \\ - \bottomrule - \end{tabular} -\end{center} -\end{multicols} - \subsection{New Patterns and Format Keys} -Table~\ref{tab:predefined:formats} lists the predefined formats. If you want you -can add own formats. -\begin{beschreibung} - \Befehl{NewPatternFormat}{}\ma{}\newline - \code{} is a number presentation command like \cmd{@alph}, \textit{i.e.}, - it needs a mandatory argument that takes a number. It is used in \code{} - \emph{without} its argument. This command can only be used in the preamble. -\end{beschreibung} +Table~\ref{tab:predefined:formats} lists the predefined formats. If you want +you can add own formats. +\begin{commands} + \command{NewPatternFormat}[\marg{pattern}\marg{format}] + \meta{format} is a number presentation command like \cs*{@alph}, \ie, + it needs a mandatory argument that takes a number. It is used in + \meta{format} \emph{without} its argument. This command can only be used + in the preamble. +\end{commands} + +\begin{table} + \centering + \caption{Predefined Patterns and Format Keys.} + \addtocounter{table}{-1}% necessary fix for subcaption and KOMA + \begin{minipage}{.48\linewidth} + \centering + \subcaption{Predefined Patterns for the module \code{cntfmts}.} + \label{tab:predefined:patterns} + \begin{tabular}{>{\ttfamily}l>{\ttfamily}l} + \toprule + \normalfont\bfseries counter & \normalfont\bfseries pattern \\ + \midrule + chapter & ch \\ + section & se \\ + subsection & sse \\ + subsubsection & ssse \\ + paragraph & pg \\ + \bottomrule + \end{tabular} + \end{minipage} + \begin{minipage}{.48\linewidth} + \centering + \subcaption{Predefined Format Keys} + \label{tab:predefined:formats} + \begin{tabular}{>{\ttfamily}ll} + \toprule + \normalfont\bfseries key & \normalfont\bfseries format \\ + \midrule + 1 & \cs*{arabic} \\ + a & \cs*{alph} \\ + A & \cs*{Alph} \\ + r & \cs*{roman} \\ + R & \cs*{Roman} \\ + \bottomrule + \end{tabular} + \end{minipage} +\end{table} Here are now a few examples of possible new patterns. Suppose the following code in the preamble: -\begin{beispiel}[code only] - \usepackage{alphalph,fmtcount} - \newcommand*\myoddnumber[1]{\the\numexpr2*(#1)-1\relax} - - \NewPatternFormat{aa}{\alphalph} - \NewPatternFormat{o}{\ordinalnum} - \NewPatternFormat{x}{\myoddnumber} - - \newcounter{testa} - \NewCounterPattern{testa}{ta} - \setcounter{testa}{4} -\end{beispiel} - -Then we can use the new pattern and the new formats as follows:\setcounter{testa}{4} -\begin{beispiel} - \ReadCounterPattern{ta[aa]} - \ReadCounterPattern{ta[o]} - \ReadCounterPattern{ta[x]} -\end{beispiel} -\secidx*{Predefined Patterns} - -\section{Implementation} -In the following code the lines 1--30 have been omitted. They only repeat the -license statement which has already been mentioned in section~\ref{sec:license}. - -\implementation[linerange={31-1000},firstnumber=31] - -\indexprologue{\noindent Section titles are indicated \textbf{bold}, packages -\textsf{sans serif}, commands \code{\textbackslash\textcolor{code}{brown}} - and options \textcolor{key}{\code{yellow}}.\par\bigskip} - -\printindex - -\end{document} \ No newline at end of file +\begin{sourcecode} + \usepackage{alphalph,fmtcount} + \newcommand*\myoddnumber[1]{\the\numexpr2*(#1)-1\relax} + + \NewPatternFormat{aa}{\alphalph} + \NewPatternFormat{o}{\ordinalnum} + \NewPatternFormat{x}{\myoddnumber} + + \newcounter{testa} + \NewCounterPattern{testa}{ta} + \setcounter{testa}{4} +\end{sourcecode} + +Then we can use the new pattern and the new formats as +follows:\setcounter{testa}{4} +\begin{example} + \ReadCounterPattern{ta[aa]} + \ReadCounterPattern{ta[o]} + \ReadCounterPattern{ta[x]} +\end{example} + +\end{document} diff --git a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf index 43e3d50d569..ac91edfbcfc 100644 Binary files a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf 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 index 338a78b0912..547d7257865 100644 --- a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex +++ b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex @@ -1,6 +1,7 @@ % arara: pdflatex % !arara: biber % !arara: pdflatex +% !arara: pdflatex % arara: pdflatex % -------------------------------------------------------------------------- % the EXSHEETS package @@ -26,119 +27,137 @@ % % 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 -% -% - 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} , +\documentclass[load-preamble+,scrartcl={DIV10}]{cnltx-doc} +\usepackage[load-headings,load-tasks]{exsheets} +\setcnltx{ + package = {exsheets} , + authors = Clemens Niederberger , + email = contact@mychemistry.eu , url = {https://bitbucket.org/cgnieder/exsheets/} , - title = the ExSheets bundle , - subtitle = {% - the packages \ExSheets, \href{tasks_en.pdf}{\Tasks} and + title = the \ExSheets\ bundle , + info = {% + the packages \ExSheets, \ExSheetslistings, \href{tasks_en.pdf}{\Tasks} 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 + 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, + DebugExSheets, + DeclareQuestionClass,DeclareQuestionProperty, + examspace, + exlabel, + ForEachQuestion, + GetQuestionProperty, + grade, + includequestions,iflastquestion, + lastvariant, + NewQuSolPair,NewLstQuSolPair, + numberofquestions, + points,pointssum, + PrintIfIncludeActiveF,PrintIfIncludeActiveT,PrintIfIncludeActiveTF, + 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 } , - gobble = 1 + add-envs = { + question, + solution, + tasks + } , + add-silent-cmds = { + acs, + bigstar,bottomrule, + citetitle,cs,color, + DeclareInstance,DeclareTemplateInterface, + endspacing, + keyis, + leftthumbsup, + midrule, + rightarrow,rlap, + s,sample,setlength, + spacing,square, + tabcolsep, + textcite, + textcolor, + tmpa,tmpb, + toprule + } } -\makeatletter -\edef\cntfmtsversion{\@cntfmts@version} -\edef\tasksversion{v\@tasks@version} -\makeatother +\usepackage{exsheets-listings} + +\edef\exsheetslistingsverion{v\csname exsheets@listings@version\endcsname} +\edef\cntfmtsversion{\csname @cntfmts@version\endcsname} +\edef\tasksversion{v\csname @tasks@version\endcsname} -\usepackage{libertinehologopatch} +\microtypesetup{tracking=scshape} -\cnpkgusecolorscheme{friendly} +\defbibheading{bibliography}[\bibname]{\section{#1}} \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 -} - -% cntformats: -\newcommand*\cntformats{{\scshape\textcolor{main}{cntformats}}\xspace} -\addcmds{ - @cntfmts@parsed@pattern, AddCounterPattern, eSaveCounterPattern, - NewCounterPattern, ReadCounterFrom, ReadCounterPattern, - ReadCounterPatternFrom, SaveCounterPattern, tmpa, tmpb -} +\newpackagename\ExSheets{ExSheets} +\newpackagename\ExSheetslistings{ExSheets-listings} +\newpackagename\cntformats{cntformats} +\newpackagename\Tasks{tasks} -% tasks: -\newcommand*\Tasks{{\scshape\textcolor{main}{tasks}}\xspace} -\addcmds{ - leftthumbsup, NewTasks, settasks, task -} % ---------------------------------------------------------------------------- % other packages, bibliography, index -\usepackage{xcoffins,wasysym,enumitem,booktabs,siunitx} +\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 , @@ -155,98 +174,28 @@ } \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 Messineo and Salvatore Vassallo}, - 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/} +@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} } -@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/} +@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} @@ -271,75 +220,48 @@ \let\checkmark\relax \usepackage{dingbat} +\DeclareRobustCommand*\questionstar{\texorpdfstring{\bonusquestionsign}{* }} +\DeclareRobustCommand*\bonusquestionsign{\llap{$\bigstar$\space}} + \NewQuSolPair - {question*}[name=\protect\llap{$\bigstar$\space}Bonus Question] - {solution*}[name=\protect\llap{$\bigstar$\space}Solution] + {question*}[name=\questionstar Bonus Question] + {solution*}[name=\questionstar Solution] -\NewTasks[style=multiplechoice]{choices}[\choice](3) +\NewTasks[style=multiplechoice]{multiplechoice}[\choice](3) \newcommand*\correct{\PrintSolutionsTF{\checkedchoicebox}{\choicebox}} \usepackage{alphalph} \NewPatternFormat{aa}{\alphalph} \NewCounterPattern{testa}{ta} -\usepackage{etoolbox} -\robustify\code - -% ---------------------------------------------------------------------------- -\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}}} - -\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.}} +% \AfterPackage!{hyperref}{% +% \pdfstringdefDisableCommands{\def\questionstar{* }}% +% } \begin{document} -\part{Preliminary}\secidx{Preliminary} +\part{Preliminaries} \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} +\license + +\ExSheets\ loads and needs the following packages: +\needpackage{l3kernel}~\cite{pkg:l3kernel}, \pkg{xparse}, \pkg{xtemplate}, +\pkg{l3keys2e}\footnote{all three \CTANurl{l3packages}}~\cite{pkg:l3packages}, +\pkg{l3sort}\footnote{\CTANurl{l3experimental}}~\cite{pkg: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: -\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/}}). +\pkg{eqexam}~\cite{pkg:eqexam}, \pkg{exam}~\cite{pkg: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 @@ -356,51 +278,55 @@ 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}). +down. \ExSheets\ provides a possibility for that (see the \Tasks\ package). 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}.}. + at the \pkg{multienum} package~\cite{pkg:multienum}.}. -On the other hand \ExSheets doesn't --~and probably won't~-- offer a real +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. +\pkg{examdesign}~\cite{pkg:examdesign}, for example. Or exploit the +possibilities \pkg{enumitem}~\cite{pkg: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 +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 three packages: \ExSheets, \Tasks\ and \cntformats. -\Tasks is described in part~\ref{part:tasks} and \cntformats in -part~\ref{part:cntformats}. These packages provide functionality that is used -by \ExSheets. They can, however, be used independently from \ExSheets. +\ExSheets\ actually bundles four packages: \ExSheets, \ExSheetslistings\ +\Tasks\ and \cntformats. \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}. + +The \Tasks\ package and the \cntformats\ package have their own +documentation. These packages provide functionality that is used by +\ExSheets. They can, however, be used independently from \ExSheets. The package \cntformats\ is probably not really useful on a user-level but maybe for package writers. -\changedversion{0.9i}\ExSheets\ used to bundle the \paket*{translations} -package, too, but doesn't any more. You can find the \paket*{translations} +\changedversion{0.9i}\ExSheets\ used to bundle the \pkg{translations} +package, too, but doesn't any more. You can find the \pkg{translations} package as a package of it's own on the \ac{ctan}. -\section{Installation and Documentation}\secidx[Installation]{Preliminary} -If you install \ExSheets manually beware to put the files +\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}. You -\emph{can} install the other packages, \Tasks and \cntformats, in different -locations but since they belong to \ExSheets they probably should be placed in -the same directory. +\emph{can} install the other packages, \Tasks\ 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. @@ -409,13 +335,29 @@ 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 \Tasks\ Package} +\noindent\sinceversion{0.9a}The \Tasks\ package has got its own documentation -- +\url{tasks_en.pdf}. Please read that file for details on the package. + +\subsection{The \cntformats\ Package} +\noindent\sinceversion{0.5}The \cntformats\ package has got its own +documentation -- \url{cntformats_en.pdf}. Please read that file for details +on the package. + +\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} +\subsection{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 +\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 +\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}. @@ -423,12 +365,12 @@ 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. +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 -\cmd{settasks}{label-offset=0pt} which should cure things again. +\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 @@ -437,333 +379,346 @@ 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. -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. +This manual contains links to the respective manuals. + +\subsection{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. + +\subsection{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}. \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 +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 +\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{beispiel}[code only] - \usepackage[]{exsheets} -\end{beispiel} +\begin{sourcecode} + \usepackage[]{exsheets} +\end{sourcecode} 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} +\begin{sourcecode} + \begin{env}[] + ... + \end{env} +\end{sourcecode} 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. +\begin{commands} + \command{SetupExSheets}[\oarg{module}\marg{options}] +\end{commands} +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 -\paket{xtemplate} package you are able to define your own instances of some of +\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 \paket{xtemplate} package is in +however, brings in a possible instability: the \pkg{xtemplate} package is in an experimental and developping 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. -\secidx*{Setup} -\section{Package Options}\label{sec:options}\secidx{Package Options} -The package \ExSheets has some options, namely the following ones: -\begin{beschreibung} +\section{Package Options}\label{sec:options} +The package \ExSheets\ has some options, namely the following ones: +\begin{options} %% color - \Option{color}{}\Default{exsheetsblue} + \keyval{color}{colour}\Default{exsheetsblue} A custom colour that is used in certain but very rare circumstances. %% counter-format - \Option{counter-format}{}\Default{qu.} + \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}. - \Option{counter-within}{}\Default{} + \keyval{counter-within}{counter}\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. + \keybool{auto-label}\Default{false} + If set to \code{true} \ExSheets\ will automatically place a + \cs*{label}\Marg{qu:\meta{id}} 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} + \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 - \Option{headings-format}{}\Default{\cmd{normalsize}\cmd{bfseries}} + \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*{bfseries}\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}. %% load-headings - \Option{load-headings}{\default{true}|false}\Default{false} + \keybool{load-headings}\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}. + \keybool{load-tasks}\Default{false} + Loads additional styles for the \env{tasks} environment. See + the \href{tasks_en.pdf}{documentation of the \Tasks\ package}. %% totoc - \Option{totoc}{\default{true}|false}\Default{false} + \keybool{totoc}\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} + \keybool{questions-totoc}\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} + \keybool{solutions-totoc}\Default{false} This option adds the solutions with their names and numbers to the table of contents. %% toc-level - \Option{toc-level}{}\Default{subsection} + \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 - \Option{questions-toc-level}{}\Default{subsection} + \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 - \Option{solutions-toc-level}{}\Default{subsection} + \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 - \Option{use-ref}{\default{true}|false}\Default{false} + \keybool{use-ref}\Default{false} enable referencing to sections and chapters in a way that the references - can be used with \cmd{printsolutions}, see + can be used with \cs{printsolutions}, see section~\ref{sssec:print_specific_section} for details. -\end{beschreibung} +\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. -\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} +\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 + optionial! +\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 \code{question} environment takes an optional argument \ma{} that +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{beispiel} - \begin{question}{3} - This is our first difficult question that is worth 3 points! - \end{question} -\end{beispiel} +\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{+} 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} +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} \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 +\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} +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. - - 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}{