From 864a1bbab21506fbb07551883dfca2ad457f2514 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Fri, 28 Jun 2013 21:55:58 +0000 Subject: exsheets (28jun13) git-svn-id: svn://tug.org/texlive/trunk@31008 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/exsheets/README | 7 +- .../texmf-dist/doc/latex/exsheets/exsheets_en.pdf | Bin 693353 -> 639328 bytes .../texmf-dist/doc/latex/exsheets/exsheets_en.tex | 1769 +++++++------------- .../doc/latex/exsheets/translations_en.pdf | Bin 408785 -> 425157 bytes .../doc/latex/exsheets/translations_en.tex | 99 +- 5 files changed, 678 insertions(+), 1197 deletions(-) (limited to 'Master/texmf-dist/doc') diff --git a/Master/texmf-dist/doc/latex/exsheets/README b/Master/texmf-dist/doc/latex/exsheets/README index c0684082854..ccb7a57df5a 100644 --- a/Master/texmf-dist/doc/latex/exsheets/README +++ b/Master/texmf-dist/doc/latex/exsheets/README @@ -1,10 +1,9 @@ -------------------------------------------------------------------------- -EXSHEETS 2013/05/26 - +EXSHEETS 2013/06/28 bundled packages: -the EXSHEETS package v0.9f +the EXSHEETS package v0.9h Yet another package for the creation of exercise sheets -the TRANSLATIONS package v0.9d +the TRANSLATIONS package v0.10 a simple translator the CNTFORMATS package v0.5 A different way to read counters. diff --git a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.pdf index b70f61851f6..5805105ab7f 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 7b61f2870aa..deb80de722d 100644 --- a/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex +++ b/Master/texmf-dist/doc/latex/exsheets/exsheets_en.tex @@ -86,7 +86,11 @@ \edef\cntfmtsversion{\@cntfmts@version} \edef\tasksversion{v\@tasks@version} \makeatother -\usepackage{libertinehologopatch} + +% this messes with the solutions headings in the appendix: +% \usepackage{libertinehologopatch} +% => figure out why + \cnpkgusecolorscheme{friendly} \usepackage[biblatex]{embrac}[2012/06/29] @@ -215,7 +219,7 @@ } @package{esami, title = {esami}, - author = {Grazia Messi­neo and Sal­va­tore Vas­sallo}, + author = {Grazia Messineo and Salvatore Vassallo}, date = {2013-03-08}, version = {1.0}, url = {http://mirror.ctan.org/macros/latex/contrib/esami/} @@ -303,6 +307,9 @@ \NewPatternFormat{aa}{\alphalph} \NewCounterPattern{testa}{ta} +\usepackage{etoolbox} +\robustify\code + % ---------------------------------------------------------------------------- % custom commands \newcommand*\Default[1]{% @@ -350,12 +357,13 @@ \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. + 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 + 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.}} @@ -365,127 +373,135 @@ \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.'' +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). +\paket{pgfcore}. \ExSheets calls \cmd{normalem} (from the \paket{ulem} +package). \section{Motivation}\secidx[Motivation]{Preliminary} -There are already quite a number of packages that allow the creation of exercise -sheets or written exams. Just to name the most common ones: +There are already quite a number of packages that allow the creation of +exercise sheets or written exams. Just to name the most common ones: \paket*{eqexam}~\cite{eqexam}, \paket*{exam}~\cite{exam}, \paket*{examdesign}~\cite{examdesign}, \paket*{exercise}~\cite{exercise}, \paket*{probsoln}~\cite{probsoln}, \paket*{answers}~\cite{answers}, -\paket*{esami}~\cite{esami}, \paket*{exsol}~\cite{exsol} (and many more% -\footnote{see \url{http://www.ctan.org/characterization/primary/document-types/exams-exercise-sets-and-answers/}}). - -One thing I missed in all packages that I've tried out\footnote{Well, probably I -didn't try hard enough\ldots} was a high flexibility in choosing which questions -and solutions should be printed, where which solutions should be printed and so -on, combined with the possibility to assign questions to different classes so one -could for example create two versions of an exam out of the box. And --~I can't -get enough~-- I also want to be able to use/design different layouts for questions -additional to a standard section-like format. All these points are realized in -\ExSheets. +\paket*{esami}~\cite{esami}, \paket*{exsol}~\cite{exsol} (and many +more\footnote{see + \url{http://www.ctan.org/characterization/primary/document-types/exams-exercise-sets-and-answers/}}). + +One thing I missed in all packages that I've tried out\footnote{Well, probably + I didn't try hard enough\ldots} was a high flexibility in choosing which +questions and solutions should be printed, where which solutions should be +printed and so on, combined with the possibility to assign questions to +different classes so one could for example create two versions of an exam out +of the box. And --~I can't get enough~-- I also want to be able to use/design +different layouts for questions additional to a standard section-like format. +All these points are realized in \ExSheets. Additionally one should be able to assign some sort of meta-data to questions -that of course should be easily reusable. How this can be done is explained +that of course should be easily reusable. How this can be done is explained in section~\ref{sec:additional_info}. Then there is --~at least in Germany~-- the habit of having lists of exercises aligned in columns but counting from the left to the right instead from up to -down. \ExSheets provides a possibility for that (see part~\ref{part:tasks}). -I am not quite content with it as it works now, though\footnote{There are still -other possibilities, for example take a look here: -\url{http://tex.stackexchange.com/questions/67966/enumerate-in-multicols} or at -the \paket*{multienum} package~\cite{multienum}.}. +down. \ExSheets provides a possibility for that (see part~\ref{part:tasks}). +I am not quite content with it as it works now, though\footnote{There are + still other possibilities, for example take a look here: + \url{http://tex.stackexchange.com/questions/67966/enumerate-in-multicols} or + at the \paket*{multienum} package~\cite{multienum}.}. On the other hand \ExSheets doesn't --~and probably won't~-- offer a real -possibility for creating multiple choice questions. As a fact it doesn't provide -many (if any) means to specify the \emph{type} of question or the structure. If -these are your needs take a look at \paket{examdesign}~\cite{examdesign}, for -example. Or exploit the possibilities \paket{enumitem}~\cite{enumitem} gives you. - -I had the idea for this package in 2008. Back then my \TeX{} skills were by far -not good enough to write it. Actually, even today I wouldn't have been able to -realize it without all the l3 packages like \paket*{l3kernel} and \paket*{l3packages}. -I actively began to develop \ExSheets in spring~2011 but it wasn't until now -(September~2012) that I consider it stable enough for wider usage. At the time -of writing (\today) there still are probably lots of rough edges let alone bugs -so I am very interested in all kinds of feedback. +possibility for creating multiple choice questions. As a fact it doesn't +provide many (if any) means to specify the \emph{type} of question or the +structure. If these are your needs take a look at +\paket{examdesign}~\cite{examdesign}, for example. Or exploit the +possibilities \paket{enumitem}~\cite{enumitem} gives you. + +I had the idea for this package in 2008. Back then my \TeX{} skills were by +far not good enough to write it. Actually, even today I wouldn't have been +able to realize it without all the l3 packages like \paket*{l3kernel} and +\paket*{l3packages}. I actively began to develop \ExSheets in spring~2011 but +it wasn't until now (September~2012) that I consider it stable enough for +wider usage. At the time of writing (\today) there still are probably lots of +rough edges let alone bugs so I am very interested in all kinds of feedback. \section{Additional Packages} \ExSheets actually bundles four packages: \ExSheets, \Tasks, \translations and -\cntformats. \Tasks is described in part~\ref{part:tasks}, \translations is -described in part~\ref{part:translations} and \cntformats in part~\ref{part:cntformats}. -These packages provide functionality that is used by \ExSheets. They can, however, -be used independently from \ExSheets. +\cntformats. \Tasks is described in part~\ref{part:tasks}, \translations is +described in part~\ref{part:translations} and \cntformats in +part~\ref{part:cntformats}. These packages provide functionality that is used +by \ExSheets. They can, however, be used independently from \ExSheets. The packages \translations and \cntformats both aren't really useful on a user-level but maybe for package writers. -\section{Installation}\secidx[Installation]{Preliminary} +\section{Installation and Documentation}\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_headings.def+ + \item[]\verb+exsheets_headings.cfg+ \end{itemize} -in the same directory as the \code{exsheets.sty} file\footnote{That is, a directory -like \code{texmf-local/tex/latex/exsheets}, probably}. You \emph{can} install the -other packages, \Tasks, \translations and \cntformats, in different locations but -since they belong to \ExSheets they probably should be placed in the same directory. +in the same directory as the \code{exsheets.sty} file\footnote{That is, a + directory like \code{texmf-local/tex/latex/exsheets}, probably}. You +\emph{can} install the other packages, \Tasks, \translations and \cntformats, +in different locations but since they belong to \ExSheets they probably should +be placed in the same directory. -You should put the file \code{tasks.cfg} in the same directory as the \code{tasks.sty} -file. +You should put the file \code{tasks.cfg} in the same directory as the +\code{tasks.sty} file. -As with every manual package installation you need to make sure to put the files -in a directory where \TeX\ can find them and afterwards update the database. +As with every manual package installation you need to make sure to put the +files in a directory where \TeX\ can find them and afterwards update the +database. \section{News} -With version~0.7 there has been a potentially breaking change: the \code{tasks} -environment previously provided by \ExSheets has been extracted into a package -of its own. This does not change any syntax \emph{per se}. However, if you used -custom settings then you'll probably run into some problems. The options for the -environment are no longer set with \cmd{SetupExSheets} but with \cmd{settasks}. -Also the object that is used for the list template and its instances has been -renamed from \code{exsheets-tasks} into \code{tasks}. +With version~0.7 there has been a potentially breaking change: the +\code{tasks} environment previously provided by \ExSheets has been extracted +into a package of its own. This does not change any syntax \emph{per + se}. However, if you used custom settings then you'll probably run into some +problems. The options for the environment are no longer set with +\cmd{SetupExSheets} but with \cmd{settasks}. Also the object that is used for +the list template and its instances has been renamed from +\code{exsheets-tasks} into \code{tasks}. What's probably even more of a breaking change is a syntax difference of the \code{tasks} environment: the optional argument for the number of columns is -\emph{no longer set in braces but parentheses}. This is deliberate as it +\emph{no longer set in braces but parentheses}. This is deliberate as it reflects the optional nature of the argument better and is consistent with the syntax of \cmd{NewTasks}, too. -Additionally the labels of the list got an additional offset of \code{1ex} from -the items which will lead to slightly different output. In some cases this might -actually lead to the most annoying changes. In this case say +Additionally the labels of the list got an additional offset of \code{1ex} +from the items which will lead to slightly different output. In some cases +this might actually lead to the most annoying changes. In this case say \cmd{settasks}{label-offset=0pt} which should cure things again. -I am very sorry for any inconvenience! I am trying to keep such changes as minimal -and rare as possibly. However, it is not always avoidable when a package is new -and still a child. It will grow up eventually. +I am very sorry for any inconvenience! I am trying to keep such changes as +minimal and rare as possibly. However, it is not always avoidable when a +package is new and still a child. It will grow up eventually. \ExSheets' other packages -- \href{tasks_en.pdf}{\Tasks}, -\href{translations_en.pdf}{\translations} and \href{cntformats_en.pdf}{\cntformats} --- have gotten their own documentation which are essentially extracted from this -very document you're reading now. They still will be documented in the main -documentation (this document), though. Right now (April~25th~2013) the separate -documentations do not contain much more information than is written here but they -might, in time, get more details about the corresponding package. +\href{translations_en.pdf}{\translations} and +\href{cntformats_en.pdf}{\cntformats} -- have gotten their own documentation +which are essentially extracted from this very document you're reading now. +They still will be documented in the main documentation (this document), +though. Right now (April~25th~2013) the separate documentations do not +contain much more information than is written here but they might, in time, +get more details about the corresponding package. \section{Thanks} -I need to thank the many users who gave me feedback so far! For one thing this -shows me that \ExSheets is useful to people. It also led to many improvements -like new features and countless bug fixes. +I need to thank the many users who gave me feedback so far! For one thing +this shows me that \ExSheets is useful to people. It also led to many +improvements like new features and countless bug fixes. \secidx*{Preliminary} \part{The \ExSheets package}\label{part:exsheets}\secidx{\ExSheets}[ExSheets] \section{Setup}\secidx{Setup} -The \ExSheets package has three different types of options, kind of. The first -type are the classic package options which are used when you load \ExSheets: +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} @@ -502,115 +518,123 @@ 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: +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 \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 +The third type aren't options at all, actually. However, thanks to the great \paket{xtemplate} package you are able to define your own instances of some of -the objects used by \ExSheets. This is explained in a little more detail in -part~\ref{part:style} on page~\pageref{part:style}\,ff. +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 +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} - %% color - \Option{color}{}\Default{exsheetsblue} - A custom colour that is used in certain but very rare circumstances. - %% counter-format - \Option{counter-format}{}\Default{qu.} - Formatting of the counter of the questions. This option takes a special kind - of string that is described in section~\ref{ssec:counter}. - \Option{counter-within}{}\Default{} - Resets the \code{question} counter with every step of \code{}. - %% auto-label - \Option{auto-label}{\default{true}|false}\Default{false} - If set to true \ExSheets will automatically place a \cmd*{label}{qu:} - for each question. It will also create the question properties \code{ref} - and \code{pageref}, see section~\ref{sec:additional_info} for more on this. - %% headings - \Option{headings}{}\Default{block} - Choose the style of the questions' and solutions' headings. There are two - predefined styles: \code{block} and \code{runin}. - %% headings-format - \Option{headings-format}{}\Default{\cmd{normalsize}\cmd{bfseries}} - This code is placed immediately before the headings of the questions and - solutions. - %% load-headings - \Option{load-headings}{\default{true}|false}\Default{false} - Loads additional styles for the headings. More on this is described in - section~\ref{sec:exsheets-headings}. - %% load-tasks - \Option{load-tasks}{\default{true}|false}\Default{false} - Loads additional styles for the \code{tasks} environment. See part~\ref{part:tasks}. - %% totoc - \Option{totoc}{\default{true}|false}\Default{false} - This option adds the questions and solutions with their names and numbers to - the table of contents. - %% questions-totoc - \Option{questions-totoc}{\default{true}|false}\Default{false} - This option adds the questions with their names and numbers to the table of - contents. - %% solutions-totoc - \Option{solutions-totoc}{\default{true}|false}\Default{false} - This option adds the solutions with their names and numbers to the table of - contents. - %% toc-level - \Option{toc-level}{}\Default{subsection} - This option sets the level in which questions and solutions should appear in - the table of contents. - %% questions-toc-level - \Option{questions-toc-level}{}\Default{subsection} - This option sets the level in which questions should appear in the table of - contents. - %% solutions-toc-level - \Option{solutions-toc-level}{}\Default{subsection} - This option sets the level in which solutions should appear in the table of - contents. - %% use-ref - \Option{use-ref}{\default{true}|false}\Default{false} - enable referencing to sections and chapters in a way that the references can - be used with \cmd{printsolutions}, see section~\ref{sssec:print_specific_section} - for details. + %% color + \Option{color}{}\Default{exsheetsblue} + A custom colour that is used in certain but very rare circumstances. + %% counter-format + \Option{counter-format}{}\Default{qu.} + Formatting of the counter of the questions. This option takes a special + kind of string that is described in section~\ref{ssec:counter}. + \Option{counter-within}{}\Default{} + Resets the \code{question} counter with every step of \code{}. + %% auto-label + \Option{auto-label}{\default{true}|false}\Default{false} + If set to true \ExSheets will automatically place a \cmd*{label}{qu:} + for each question. It will also create the question properties \code{ref} + and \code{pageref}, see section~\ref{sec:additional_info} for more on + this. + %% headings + \Option{headings}{}\Default{block} + Choose the style of the questions' and solutions' headings. There are two + predefined styles: \code{block} and \code{runin}. + %% headings-format + \Option{headings-format}{}\Default{\cmd{normalsize}\cmd{bfseries}} + This code is placed immediately before the headings of the questions and + solutions. + %% load-headings + \Option{load-headings}{\default{true}|false}\Default{false} + Loads additional styles for the headings. More on this is described in + section~\ref{sec:exsheets-headings}. + %% load-tasks + \Option{load-tasks}{\default{true}|false}\Default{false} + Loads additional styles for the \code{tasks} environment. See + part~\ref{part:tasks}. + %% totoc + \Option{totoc}{\default{true}|false}\Default{false} + This option adds the questions and solutions with their names and numbers + to the table of contents. + %% questions-totoc + \Option{questions-totoc}{\default{true}|false}\Default{false} + This option adds the questions with their names and numbers to the table + of contents. + %% solutions-totoc + \Option{solutions-totoc}{\default{true}|false}\Default{false} + This option adds the solutions with their names and numbers to the table + of contents. + %% toc-level + \Option{toc-level}{}\Default{subsection} + This option sets the level in which questions and solutions should appear + in the table of contents. + %% questions-toc-level + \Option{questions-toc-level}{}\Default{subsection} + This option sets the level in which questions should appear in the table + of contents. + %% solutions-toc-level + \Option{solutions-toc-level}{}\Default{subsection} + This option sets the level in which solutions should appear in the table + of contents. + %% use-ref + \Option{use-ref}{\default{true}|false}\Default{false} + enable referencing to sections and chapters in a way that the references + can be used with \cmd{printsolutions}, see + section~\ref{sssec:print_specific_section} for details. \end{beschreibung} -The \code{toc} options are demonstrated with section~\ref{sec:solutions:list} and -the solutions printed there being listed in the table of contents. +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. +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{} ... } + \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. +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): +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. +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. @@ -625,39 +649,41 @@ argument. \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: +\code{question} environment. In this case you can use these commands: \begin{beschreibung} - \expandable\Befehl{IfInsideQuestionTF}{}\ma{} - \expandable\Befehl{IfInsideQuestionT}{} - \expandable\Befehl{IfInsideQuestionF}{} + \expandable\Befehl{IfInsideQuestionTF}{}\ma{} + \expandable\Befehl{IfInsideQuestionT}{} + \expandable\Befehl{IfInsideQuestionF}{} \end{beschreibung} \subsection{Options to the \code{question} Environment}\secidx[options]{questions} The \code{question} environment takes one or more of the following options: \begin{beschreibung} - \Option[question]{type}{exam|exercise}\Default{exercise} - determines the type of question and changes the default name of a question - from ``Exercise'' to ``Question''. These default names are language dependent.\\ - If you use \cmd*{usepackage}[ngerman]{babel}, for example, then the names - are ``\"Ubung and ``Aufgabe''. - \Option[question]{name}{}\Default{} - sets a custom name. All predefined names are discarded. - \Option[question]{print}{\default{true}|false}\Default{true} - prints or hides the question. - \Option[question]{ID}{}\Default{} - assigns a custom \acs{id} to the question. See section~\ref{ssec:ids} for further - information. - \Option[question]{label}{