diff options
Diffstat (limited to 'macros/latex/contrib/exesheet/exesheet.dtx')
| -rw-r--r-- | macros/latex/contrib/exesheet/exesheet.dtx | 1537 |
1 files changed, 810 insertions, 727 deletions
diff --git a/macros/latex/contrib/exesheet/exesheet.dtx b/macros/latex/contrib/exesheet/exesheet.dtx index 04cdd77b5b..1e5355ba3a 100644 --- a/macros/latex/contrib/exesheet/exesheet.dtx +++ b/macros/latex/contrib/exesheet/exesheet.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright (C) 2020-2021 by Antoine Missier <antoine.missier@ac-toulouse.fr> +% Copyright (C) 2020-2023 by Antoine Missier <antoine.missier@ac-toulouse.fr> % ---------------------------------------------------------------------- % % This file may be distributed and/or modified under the @@ -23,7 +23,7 @@ %<class>\ProvidesClass{exesheet} %<package>\ProvidesPackage{exesheet} %<*class|package> -[2023/01/16 v2.0 .dtx exesheet file] +[2023/08/25 v2.1 .dtx exesheet file] %</class|package> %<*driver> \documentclass{ltxdoc} @@ -45,7 +45,6 @@ \usepackage{pstricks} \usepackage{array} \usepackage{spacingtricks} -\usepackage{centeredline} % \psset{unit=1cm} \geometry{textwidth=355pt,vmarginratio=1:1,hmarginratio=3:2} @@ -84,7 +83,7 @@ %</driver> % \fi % -% \CheckSum{1118} +% \CheckSum{1132} % % \CharacterTable % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z @@ -137,6 +136,11 @@ % code revision and simplification, % documentation update} % +% \changes{v2.1}{2023/07/30}{ +% new environments tablenuma* and tablitem*} +% \changes{v2.1}{2023/08/24}{ +% English correction in the documentation} +% % \GetFileInfo{exesheet.dtx} % % \maketitle @@ -145,120 +149,123 @@ % % \section{Introduction} % -% The \textsf{exesheet} \emph{package} is used for typesetting exercise or exam sheets. -% In addition, the \textsf{exesheet} \emph{class} loads the \textsf{schooldocs} package. -% This one makes adjustments for margins and title and defines various layout styles -% with particular header and footer, appropriate for exercise sheets (among others). -% See the \textsf{schooldocs} documentation for more details. -% The \textsf{exesheet} \emph{class} is based on \textsf{article} -% and passes to it its unknown options. -% -% Many other packages are dedicated to exercise sheets. -% Most propose to encapsulate each exercise in an environment -% whereas \textsf{exesheet} begins each exercise with |\exercise|, -% which works like a subsection (with the same features) -% and is suitable for documents consisting exclusively of exercises. -% The package provides also alternative formatting, -% more relevant for short exercises. -% -% Another specificity of the \textsf{exesheet} package is the particular settings -% for enumeration lists, -% useful for the numbering of questions or answers inside an exercise. -% -% Other packages provide often more or less elaborate mechanisms -% to manage the placement of answers. -% \textsf{exesheet} has no such ambitions, however, -% for all exercises of the sheet, you can display questions only, -% answers only or both, but always at the place they are inserted -% in the source file. On the other hand this choice may be very flexible: -% you can do a correct version for all exercises together, or a correction per exercise, +% The \textsf{exesheet} \emph{package} is designed for typesetting exercise or exam sheets. +% Additionally, the \textsf{exesheet} \emph{class} loads the \textsf{schooldocs} package. +% The latter makes adjustments to margins and titles, and defines various layout styles +% with specific headers and footers suitable for exercise sheets, among other uses. +% Refer to the documentation of the \textsf{schooldocs} package for more details. +% The \textsf{exesheet} \emph{class} is build upon the \textsf{article} class +% and forwards any unknown options to it. +% +% There are many other packages dedicated to exercise sheets. +% Most of them suggest encapsulating each exercise within an environment. +% In contrast, \textsf{exesheet} starts each exercise with |\exercise|, +% which functions similarly to a subsection (with the same features) +% and is suitable for documents that primarily consist of exercises. +% The package also offers alternative formatting, +% which is more suitable for shorter exercises. +% +% Another distinctive feature of the \textsf{exesheet} package is its specific settings +% for enumeration lists, which are +% useful for numbering questions or answers within an exercise. +% +% While other packages often offer more or less complex mechanisms +% for managing the placement of answers, +% \textsf{exesheet} doesn't aspire to such complexity. However, +% for all exercises within the sheet, you have the capability to display only questions, +% only answers, or both, all while preserving their placement as they appear +% in the source file. This choice allows for great flexibility: +% you can create a correct version for all exercises collectively, +% or individual corrections per exercise, % per part (subpart of exercise), per question, per sub-question. % -% Finally this package enables to display -% a detailed marking scheme in the margin, +% Finally this package enables to display a detailed marking scheme in the margin, % with optional explanations or remarks, -% and with consistency control. +% and offering consistency control. % -% Many settings can be changed and several options manage the output document. -% These options are based on the keyval mechanism: \texttt{key=value} -% (thanks to Maxime Chupin and Denis Bitouzé for their wise ideas to improve this package). -% The options can be passed to class or package, \eg +% Many settings can be customized, and various options are available +% to manage the output document. +% These options rely on the key-val mechanism: \texttt{key=value} +% (thanks to Maxime Chupin and Denis Bitouzé for suggesting this idea to improve this package). +% These options can be applied to the class or the package, \eg % \begin{center} % |\documentclass[a4paper,11pt,output=answers,display=pts]{exesheet}| % \end{center} -% or later with the |\exesheetset|\marg{options} command. +% or later using the command |\exesheetset|\marg{options}. % In the example above, \texttt{a4paper,11pt} are options -% passed to the underlying class \textsf{article}. +% that are passed to the underlying \textsf{article} class. % %\medskip -% \emph{In the current document, a frame is used to highlight -% examples output.} +% \emph{In the current document, a frame is utilized to emphasize output +% examples.} % % \section{Titles} % % \subsection{The \texttt{\bs exercise} command} % % \DescribeMacro{\exercise} -% Each exercise begins with the |\exercise|\oarg{opt} command. +% Each exercise starts with the |\exercise|\oarg{opt} command. % This command typesets \textbf{\exercisename}, as a document -% subsection, followed by automatic numbering, -% unique for the whole document. -% The optional parameter \meta{opt} is used to put additional text -% on the same title line, for example to precise a subject or a marking scheme. -% |\exercise[(to begin)]| yields: +% subsection, followed by automatic numbering +% unique to the entire document. +% The optional parameter \meta{opt} is utilized to include additional text +% on the same title line, such as specifying a subject or a marking scheme. +% Thus, using |\exercise[(to begin)]| results in: % % \exercise[(to begin)] % \psframe(-0.25,1.3)(12.75,-0.3) -% Try to use this first command now, it's easy. +% Give this initial command a try; it's straightforward. % % \bigskip % To bring additional text closer to the exercise number, -% we can use |\unskip| which eliminates preceding space, -% and also |\hrulefill| can be put in the optional argument -% to produce an horizontal rule. -% See the following example, obtained with \\ +% we can employ |\unskip| which removes any preceding space. +% Take a look at the following example, achieved with % |\exercise[\unskip*** (difficult)]|: % \exercise[\unskip*** (difficult)] % \psframe(-0.25,1.3)(12.75,-0.3) % Calculate $1+1$. % % \bigskip -% Several settings can be changed by refining the following commands. +% ^^A Various settings can be modified by refining the following commands. % -% \medskip +% ^^A \medskip % \DescribeMacro{\exercisename} -% The word ``\exercisename'' has automatic translation in a few languages -% \footnote{Translation is currently integrated into the package -% for the following languages: French, German, Spanish, Italian, Portuges.} -% according to the loaded language (by \textsf{babel} or \textsf{polyglossia}). -% It can be redefined, with |\renewcommand|, -% or better you can use (in the preamble) macros from the \textsf{translations} -% package (allowing dynamic language change), \eg \\ +% The term ``\exercisename'' is automatically translated into various languages +% \footnote{Currently, translation is integrated into the package +% for the following languages: French, German, Spanish, Italian, and Portuguese.} +% depending on the language that is loaded (via \textsf{babel} or \textsf{polyglossia}). +% You can redefine it using |\renewcommand|. +% A better approach is to use macros from the \textsf{translations} +% package by Clemens Niederberger (which allows dynamic language switching), \eg % |\DeclareTranslation{Swedish}{exesheet-exercise}{\"Ovning}}|. % +% \smallskip % \DescribeMacro{\labelexercise} -% This command calls |\exercisename| following by the exercise number. -% It can be redefined. For example, to add a period after the exercise number: +% This command combines |\exercisename| with the exercise number and +% can be redefined. For instance, if you want to include a period after the exercise number, +% you can redefine it as follows:\\ % |\renewcommand{\labelexercise}{\exercisename~\theexercise.}| -% +% +% \smallskip % \DescribeMacro{\theexercise} -% To change only the numbering type, redefine -% the |\theexercise| command, based on the |exercise| counter. +% If you wish to alter only the numbering style, you can redefine +% the |\theexercise| command based on the |exercise| counter. % +% \smallskip % \DescribeMacro{\labelexercisestyle} -% This macro (which is empty by default) allows to define a particular style -% for exercise titles. In the present document, we defined in the preamble: +% This macro, which is initially empty, enables the definition of a specific style +% for exercise titles. In this document, we have set the following in the preamble: % |\renewcommand{\labelexercisestyle}{\rmfamily\color{black}}| -% \footnote{In the present document, to highlight real sections and subsections titles, -% their color and font have been modified with the +% \footnote{In this document, real section and subsection titles have been highlighted by +% modifying their color and font using the % \texttt{\bs allsectionsfont} macro from the \textsf{sectsty} package.}. % % \medskip % \DescribeMacro{\exercise*} % The starred version |\exercise*|\oarg{opt}\marg{label} -% allows to choose another \meta{label} for a particular exercise -% and removes the numbering. For instance: -% |\exercise*[(Fermat's theorem)]{Problem}| yields: +% permits the selection of an alternative \meta{label} for a specific exercise +% while omitting the numbering. For instance: +% |\exercise*[(Fermat's theorem)]{Problem}| results in: % % \exercise*[(Fermat's theorem)]{Problem} % \psframe(-0.25,1.3)(12.75,-0.7) @@ -266,126 +273,132 @@ % for any integer $n$ greater than 2. % % \subsection{The \texttt{\bs subpart} command} -% % \DescribeMacro{\subpart} -% An exercise may contain several parts that we obtain -% with the |\subpart|\oarg{opt} command, typeset like a sub-subsection. +% An exercise may consist of multiple parts, which can be created using +% the |\subpart|\oarg{opt} command. +% The part title is typeset similar to a sub-subsection. +% % \exercise % \subpart[(preliminary)] % \psframe(-0.25,1.95)(12.75,-1.85) -% First of all, prepare your cup of tea. +% To begin, prepare your cup of tea. % \subpart -% Now you are ready to make the current exercise. -% +% Now you are ready to proceed with the current exercise. % \bigskip -% The following macros manage formatting in the same way as for |\exercise|. +% +% \pagebreak +% The following macros manage formatting in the same manner as for |\exercise|. % % \medskip % \DescribeMacro{\thesubpart} -% By default, the subpart numbering uses letters : A, B, C, etc. -% This numbering type can be redefined with the |\thesubpart| command based on -% the |subpart| counter, for instance |\renewcommand\thesubpart{\arabic{subpart}}|. +% By default, subpart numbering employs letters : A, B, C, and so on. +% This numbering style can be modified using the |\thesubpart| command, which relies on +% the |subpart| counter. For example, you can redefine it as follows: +% |\renewcommand\thesubpart{\arabic{subpart}}|. % +% \smallskip % \DescribeMacro{\subpartname} \DescribeMacro{\labelsubpart} % \DescribeMacro{\labelsubpartstyle} % The |\subpart| command -% uses |\subpartname| (with automatic translation in a few languages -% according to the selected language), -% |\labelsubpart| and |\labelsubpartstyle|, which can be changed. +% utilizes |\subpartname| (with automatic translation in several languages +% according to the chosen language), as well as +% |\labelsubpart| and |\labelsubpartstyle|, all of which can be modified. % % \medskip % \DescribeMacro{\subpart*} -% Like |\exercise*|, the starred version |\subpart*|\oarg{opt}\marg{label} -% allows to freely typeset the subpart \marg{label}, for instance -% |\subpart*{First part}|. +% Similar to |\exercise*|, the starred version |\subpart*|\oarg{opt}\marg{label} +% permits an alternative \meta{label} and omits the numbering. For instance, +% you can use |\subpart*{First part}|. % % \subsection{The \texttt{\bs annex} command} % \DescribeMacro{\annex} -% The |\annex|\oarg{opt} command typesets the title \textbf{ANNEX}, -% in uppercase letters, centered -% and in the subsection style, -% with an optional parameter, added on the same line. +% The |\annex|\oarg{opt} command composes the title \textbf{ANNEX} +% in uppercase letters, centered, using the subsection style, +% with an optional parameter that will be added on the same line. % % \vspace{-\baselineskip} % \noindent\psframe(-0.25,-0.3)(12.75,-1.3) -% \annex[(to return)] +% \annex[(to be returned)] % % \bigskip % \DescribeMacro{\annexname} -% The word ``\annexname'' has automatic translation in a few languages. -% It can be extended to other languages or modified by redefining |\annexname| -% or with macros from the \textsf{translations} package. +% The term ``\annexname'' is automatically translated into several languages. +% It can be extended to additional languages or altered by redefining |\annexname| +% or by utilizing macros from the \textsf{translations} package. % +% \smallskip % \DescribeMacro{\annexstyle} -% The annex title style is set by the |\annexstyle| macro, -% defined as follows: |\newcommand\annexstyle{\MakeUppercase}|. -% This command may be redefined as one wants. +% The style of the annex title is determined by the |\annexstyle| macro, +% which is defined as follows: |\newcommand\annexstyle{\MakeUppercase}|. +% This command may be redefined according to your preferences. % -% \subsection{Exercise titles in table of contents} \label{toc} +% \subsection{Exercise titles in the table of contents} \label{toc} % \DescribeMacro{[exetoc=\meta{bool}]} % By default, the titles \textbf{\exercisename}, \textbf{\subpartname} -% or \textbf{\annexname}, appear in the table of contents -% (or in the pdf file summary when \textsf{hyperref} package is used). -% To avoid this, you can set the option \texttt{exetoc=false} (default is \texttt{true}). -% But notice that title optional arguments will always be ignored in the table of contents. +% and \textbf{\annexname} are included in the table of contents if there is any +% (or in the PDF file's summary when the \textsf{hyperref} package is utilized). +% To prevent this, you can set the package option \texttt{exetoc=false} +% (with the default being \texttt{true}). +% However, note that optional title arguments will always be ignored in the table of contents. % % \subsection{Short exercises: the \texttt{\bs exe} command} % \DescribeMacro{\exe} -% The |\exe| command starts an exercise by the abbreviation \textbf{\exname}.\ -% followed by the exercise number, -% without using sectioning commands, and the exercise body begins on the same -% line. An exercise starts a new paragraph without indentation. +% The |\exe| command initiates an exercise with the abbreviation \textbf{\exname}.\@ +% followed by the exercise number. This is achieved without +% utilizing sectioning commands, and the exercise content begins on the same +% line. An exercise begins a new paragraph without any indentation. % -% \exe This is a short exercise who -% can contain several paragraphs or questions however. +% \exe This is a brief exercise that can encompass several +% paragraphs or questions. % % \noindent\psframe(-0.25,1.4)(12.75,-1.2) -% \indent Here for example starts a new paragraph. -% \exe This is another short exercise. +% \indent Here for example a new paragraph begins. +% \exe This is another concise exercise. % % \bigskip % \DescribeMacro{\exname} \DescribeMacro{\exlabel} \DescribeMacro{\exsepmark} -% The abbreviation \textbf{\exname} may be changed by +% The abbreviation \textbf{\exname} can be modified by % redefining |\exname| or with macros from the \textsf{translations} package. -% The |\exlabel| macro calls |\exname| following by a period then the exercise number, -% and |\exsepmark| typesets a long dash. -% One can change these features by redefining these commands. +% The |\exlabel| macro combines |\exname| with a period then the exercise number +% (given by the \texttt{exercise} counter), +% while |\exsepmark| typesets a long dash. +% You can alter these characteristics by redefining these commands. % % \medskip % \DescribeMacro{\exe*} -% The starred version prints no separator as shown below: +% The starred version doesn't display a separator, as demonstrated below: % % \vspace{-\baselineskip} % \noindent\psframe(-0.25,-0.35)(12.75,-1.1) -% \exe* Another short exercise without separator. +% \exe* Another short exercise without a separator. % % \section{Enumerations and lists} % % \subsection{List settings} \label{setlist} % \DescribeEnv{enumerate} \DescribeMacro{\item} -% Enumeration lists are intended to represent questions and sub-questions -% inside exercises. For a good highlight, -% labels are typeset in bold. -% Moreover, they are left aligned, at the start of the line, -% without indentation, and the vertical space between items -% is increased compared with \LaTeX\ standard lists. -% These settings are done by the |\setlist| command -% \footnote{Labels may also be changed occasionally in an optional argument +% Enumeration lists are designed to represent questions and sub-questions +% within exercises. To provide clear emphasis, +% labels are formatted in bold. +% Additionally, these labels are aligned to the left, positioned at the start of the line +% without indentation, and the vertical spacing between items +% is increased compared to standard \LaTeX{} lists. +% These formatting adjustments are achieved using the |\setlist| command +% \footnote{Labels can also be modified by providing an optional argument, % \eg \texttt{\bs begin\{enumerate\}[A.]}, -% or globally thanks to \texttt{\bs labelenumi} -% and \texttt{\bs labelenumii} commands.} -% from the \textsf{enumitem} package of Javier Bezos. -% Lists with \texttt{itemize} environment are kept in their default +% or globally through the use of \texttt{\bs labelenumi} +% and \texttt{\bs labelenumii} commands.}, +% a feature from the \textsf{enumitem} package by Javier Bezos. +% Lists created with the \texttt{itemize} environment retain their default % configuration % \footnote{The \texttt{french} option of the \textsf{babel} package -% alters \texttt{itemize} lists behavior and uses long dashes +% changes the behavior of \texttt{itemize} lists and employs long dashes % as labels for each list level. -% This behavior is problematic when mathematics follows the dash -% symbol because the latter may be confused with the minus sign. -% Default \texttt{itemize} lists are restored.}. +% This behavior can cause issues when mathematical content follows the dash +% symbol, as it might be mistaken for the minus sign. +% The default \texttt{itemize} list style is reinstated to address this concern.}. % % \vspace{-\baselineskip} -% \noindent\psframe(-0.25,-0.35)(12.75,-3.6) +% \noindent\psframe(-0.25,-0.35)(12.75,-3.9) % \exercise % \begin{enumerate} % \item First question @@ -398,23 +411,24 @@ % % \smallskip % \DescribeMacro{[setlist=\meta{bool}]} -% One can avoid enumeration list alterations and restore \LaTeX\ -% default settings with the option |[setlist=false]| -% (default value is \texttt{true} of course). +% To prevent changes to enumeration lists and revert to the default \LaTeX{} +% settings, you can utilize the package option |setlist=false| +% (with the default value being \texttt{true} of course). % % \subsection{List of exercises : the \texttt{exenumerate} environment} % \DescribeEnv{exenumerate} -% When an exercise sheet is made of short independent questions, -% it would be ill-advised to display the complete title \textbf{\exercisename} for each. -% In addition to the |\exe| command, previously presented, -% we provide an even lighter solution with the |exenumerate| environment. -% It's only an enumeration list in which -% spaces between items are further increased compared to those of \texttt{enumerate}. -% Below is an example (the main list is an \texttt{exenumerate} environment but the -% sub-list is produced with common \texttt{enumerate} environments): +% When an exercise sheet consists of short, independent questions, +% it might be unreasonable to display the full title \textbf{\exercisename} for each one. +% In addition to the previously mentioned |\exe| command, +% we offer an even more streamlined solution using the |exenumerate| environment. +% This environment is essentially an enumeration list with increased spacing +% between items, compared to the \texttt{enumerate} environment. +% Here is an example (the main list uses the \texttt{exenumerate} environment, while the +% sub-list is created using the standard \texttt{enumerate} environment): % -% \vspace{-\baselineskip} -% \noindent\psframe(-0.25,-0.3)(12.75,-5.3) +% \pagebreak +% ^^A \vspace{-\baselineskip} +% \noindent\psframe(-0.25,-0.3)(12.75,-6) % \begin{exenumerate} % \item Translate the following sentences in English: % \begin{enumerate} @@ -424,47 +438,50 @@ % \item Translate the following sentence in German: % \par Donec aliquet, tortor sed accumsan bibendum, erat ligula aliquet magna, % vitae ornare odio metus a mi. -% \item Translate the following sentences in French: +% \item Translate the following sentence in French: % Cum sociis natoque penatibus % et magnis dis parturient montes, nascetur ridiculus mus. % \end{exenumerate} % % \medskip -% The environment takes an optional parameter, like \texttt{enumerate}, -% which enables, among others, -% to typeset alternative list labels, \eg +% The environment takes an optional parameter, similar to \texttt{enumerate}, +% that allows, among others things, +% the typesetting of alternative list labels, \eg % |\begin{exenumerate}[A.]|. -% There are many other options (see the \textsf{enumitem} package documentation). +% There are numerous other options available +% (refer to the \textsf{enumitem} package documentation for details). % -% \subsection{Items aligned by row: \texttt{tablenum1$\mid$a}, \texttt{tablitem}} +% \subsection{Items aligned by row: \texttt{tablenum1}, \texttt{tablenuma}, \texttt{tablitem}} % \DescribeEnv{tablenum1} % \DescribeEnv{tablenuma} % \DescribeEnv{tablitem} -% These three environments are used to typeset short questions (\texttt{tablenum1}), +% These three environments are employed to typeset brief questions (\texttt{tablenum1}), % sub-questions (\texttt{tablenuma}) or \texttt{itemize} lists (\texttt{tablitem}) -% on the same line. They have the same syntax: +% on the same line. They share the same syntax: % |\begin{tablenum1}|\oarg{opt}|(|\meta{cols}|)|. -% The \meta{cols} parameter is the number of columns used by the environment. It must be -% \emph{in parentheses}. This parameter can be omitted, then its value is 2. -% As for classic lists, each item begins with the |\item| command. -% -% These three environments are defined by the -% |\NewTasksEnvironment| macro, from the \textsf{tasks} package by Clemens Niederberger. -% They take an optional argument \meta{opt} -% explained in the documentation of this package, -% \eg |label=\arabic*)| produces an Arabic numbering -% following by a closing parenthesis (like in \texttt{enumitem} package). -% There are also many possibilities to place items in an original way, -% for instance, the |\item*| command allows to +% The \meta{cols} parameter denotes the number of columns utilized by the environment. +% It must be enclosed \emph{in parentheses}. +% This parameter can be omitted, in which case its default value is 2. +% Similar to conventional lists, each item is initiated with the |\item| command. +% +% These three environments are defined using the +% |\NewTasksEnvironment| macro from the \textsf{tasks} package by Clemens Niederberger. +% They accept an optional argument \meta{opt}, which is +% explained in the documentation of this package. +% For example, similar to the \texttt{enumitem} package, +% |label=\arabic*)| produces an Arabic numbering +% followed by a closing parenthesis. +% Additionally there are numerous possibilities for arranging items in original ways. +% For instance, the |\item*| command allows you to % specify the number of columns the item is supposed to span. -% In the following example, -% the five |\item| are placed in order between +% In the subsequent example, +% the five |\item| commands are sequentially positioned between % |\begin{tablenum1}(3)| and |\end{tablenum1}|. -% Notice that numbering is made line by line. +% It's important to notice that numbering occurs line by line in this context. % % \exercise -% \psframe(-0.25,1.3)(12.75,-2.7) -% Give the derivative of the following functions: +% \psframe(-0.25,1.3)(12.75,-2.8) +% Provide the derivative of the following functions: % \begin{tablenum1}(3) % \item $\ds f(x) = \frac{1-x^2}{\mathrm{e}^x +\mathrm{e}^{-x}}$, % \item $\ds g(x) = \ln \left( \frac{1-x}{1+x^2}\right)$, @@ -475,27 +492,55 @@ % % \smallskip % For \texttt{tablenuma}, labels are -% letters (a, b, c, \ldots) surrounded -% by parentheses. This cannot be modified globally, -% except by redefining the environment with |\RenewTasksEnvironment|. -% If the \textsf{exesheet} package is called with the option \texttt{setlist=false}, -% labels of \texttt{tablenum1} and \texttt{tablenuma} environments -% are displayed with indentation and in normal font instead of bold. +% letters (a, b, c, \ldots) enclosed in +% parentheses. This cannot be globally altered, +% except by redefining the environment using |\RenewTasksEnvironment|. +% If the \textsf{exesheet} package is invoked with the option \texttt{setlist=false}, +% labels within \texttt{tablenum1} and \texttt{tablenuma} environments +% will be presented with indentation and in regular font rather than bold. +% +% \medskip +% \DescribeEnv{tablenuma*} \DescribeEnv{tablitem*} +% When you intend to utilize \texttt{tablenuma} (or \texttt{tablitem}) +% immediately after inserting the |\item| command +% within an \texttt{enumerate} environment, +% a vertical misplacement occurs, as demonstrated in the following example: +% \begin{enumerate} +% \item +% \begin{tablenuma}(3) \item One \item Two \item Three \end{tablenuma} +% \end{enumerate} +% +% To achieve proper vertical spacing in such cases, we offer +% the starred environments \texttt{tablenuma*} and \texttt{tablitem*}, +% with corrected alignment as shown below: +% +% \noindent\psframe(-0.25,0.05)(12.75,-1) +% \psline[linewidth=0.1pt,linecolor=green,linestyle=dashed](0, -0.63)(10.5, -0.63) +% \begin{enumerate} +% \item +% \begin{tablenuma*}(3) \item One \item Two \item Three \end{tablenuma*} +% \end{enumerate} +% +% \medskip +% If the vertical alignment is still not optimal, include +% |\mbox{}\vspace|\marg{height} just before invoking |\begin{tablenuma*}| +% (or |\begin{tablitem*}|), where \meta{height} can be a positive or negative length. % % \subsection{Items aligned by column: \texttt{colsenum}, \texttt{colsitem}} % \DescribeEnv{colsenum} -% To get numbering of items by column, we provide the -% \texttt{colsenum} environment: |\begin{colsenum}|\oarg{opt}\marg{cols}. -% The mandatory parameter is the number of columns -% and the optional one will be passed to \texttt{enumerate}, -% allowing, for example, to change the type of numbering (a, A, etc.). -% To use this environment, we have to load the +% To achieve numbering of items by column, the +% \texttt{colsenum} environment is available: +% |\begin{colsenum}|\oarg{opt}\marg{cols}. +% The mandatory parameter is the number of columns, +% and the optional parameter will be passed to the \texttt{enumerate} environment, +% allowing you to change the numbering type (\eg a, A, etc.), among other possibilities. +% To use this environment, you need to load the % \textsf{multicol} package in the preamble. -% Here an example with |\begin{colsenum}{3}|: +% Here's an example with |\begin{colsenum}{3}|: % % \exercise % \psframe(-0.25,1.3)(12.75,-2.65) -% Give the derivative of the following functions: +% Provide the derivative of the following functions: % \begin{colsenum}{3} % \item $\ds f(x) = \frac{1-x^2}{\mathrm{e}^x +\mathrm{e}^{-x}}$, % \item $\ds g(x) = \ln \left( \frac{1-x}{1+x^2}\right)$, @@ -506,18 +551,19 @@ % % \medskip % \DescribeEnv{colsenum*} -% We will notice that, on each line, items are not necessarily well -% aligned, which can produce inelegant effects. -% On the other hand, the \texttt{colsenum} environment doesn't try to align columns -% from the bottom by adjusting space between items. -% If we want to get this -% (which is the default option in \textsf{multicol}), we have the -% \texttt{colsenum*} environment (same syntax than \texttt{colsenum}). -% Here what we get in that case, with the same exercise: +% We will observe that, on each line, items are not necessarily properly +% aligned, which can result in ungraceful effects. +% On the other hand the \texttt{colsenum} environment doesn't attempt to align columns +% from the bottom by adjusting the spacing between items. +% If we desire this alignment +% (which is the default behavior in \textsf{multicol}), we can use the +% \texttt{colsenum*} environment (with the same syntax as \texttt{colsenum}). +% Here's what we obtain with \texttt{colsenum*}, using the same exercise: % +% \pagebreak % \exercise % \psframe(-0.25,1.3)(12.75,-2.65) -% Give the derivative of the following functions: +% Provide the derivative of the following functions: % \begin{colsenum*}{3} % \item $\ds f(x) = \frac{1-x^2}{\mathrm{e}^x +\mathrm{e}^{-x}}$, % \item $\ds g(x) = \ln \left( \frac{1-x}{1+x^2}\right)$, @@ -527,25 +573,25 @@ % \end{colsenum*} % % \medskip -% We can see that these alignments are less good than those -% obtained by row numbering. The column numbering -% may nevertheless be preferable when there are many items with variable heights, -% and a number of items which can be different from one column to the other. -% Moreover, an advantage of \texttt{colsenum} is that the choice of labels -% is automatic depending on the list level (and the language), +% We can observe that these alignments are not as elegant as those +% achieved through row numbering. However, column numbering +% might still be more suitable when dealing with numerous items of varying heights, +% and especially when the number of items can differ from column to column. +% Additionally, a benefit of \texttt{colsenum} is that the label selection +% is automatic based on the list level (and the language), % unlike \texttt{tablenum1} or \texttt{tablenuma}. % % \bigskip % \DescribeEnv{colsitem} % \DescribeEnv{colsitem*} -% For \texttt{itemize} lists, the environment \texttt{colsitem} -% produces items aligned by column rather than by lines as for -% \texttt{tablitem}: +% For \texttt{itemize} lists, the \texttt{colsitem} environment +% generates items aligned by column, unlike the line-by-line alignment of +% \texttt{tablitem}. To use it, simply employ % |\begin{colsitem}|\oarg{opt}\marg{cols}. The optional parameter, -% which is passed to the underlying \texttt{itemize} environment, -% allows to change the item label (bullet by default). -% And, as for \texttt{colsenum*}, the \texttt{colsitem*} environment -% produces an alignment of columns from the bottom. +% passed to the underlying \texttt{itemize} environment, +% permits the modification of the item label (bullet by default). +% Furthermore, just like \texttt{colsenum*}, the \texttt{colsitem*} environment +% produces column alignment from the bottom. % % \section{Questions and solutions} % @@ -553,58 +599,63 @@ % \label{output} % % \DescribeEnv{questions} \DescribeEnv{answers} -% The package provides the two environments \texttt{questions} and \texttt{answers} -% to make optionally appear or disappear questions and answers of exercises. +% The package offers two environments, \texttt{questions} and \texttt{answers}, +% which allow you to optionally show or hide questions and answers within exercises. % % \bigskip % \DescribeMacro{[output=\meta{opt}]} -% The output is controlled by the \texttt{output} key option: it takes three -% recognized values: \texttt{questions}, \texttt{answers}, \texttt{both}. -% The \texttt{questions} value allows to display questions without answers, -% \texttt{answers} displays answers without questions, -% \texttt{both} (the default option) displays both. +% The output is governed by the \texttt{output} key option which recognizes three +% values: \texttt{questions}, \texttt{answers}, and \texttt{both}. +% The \texttt{questions} value shows only questions without answers, +% \texttt{answers} displays answers without questions, and +% \texttt{both} (the default option) displays both questions and answers. % % \bigskip % \DescribeMacro{\correctionstyle} \DescribeMacro{correctioncolor} +% In the default case where both questions and answers are displayed, +% the answers are typeset using the |\correctionstyle| style, +% which utilizes the color \texttt{correctioncolor}. +% You can modify this color using the |\definecolor| macro +% \footnote{The \texttt{\bs definecolor} command is provided by the \textsf{xcolor} package +% developed by Uwe Kern, which is automatically loaded by \textsf{exesheet}.}. +% By default, |\definecolor{correctioncolor}{rgb}{0,0.2,0.6}| is used, +% resulting in a kind of dark blue. +% +% \medskip % \DescribeMacro{\correctionname} -% In the case (by default) where questions and answers are displayed both, -% answers are then typeset in the style -% |\correctionstyle|, which uses the color \texttt{correctioncolor}. -% This color may be changed with the |\definecolor| macro -% \footnote{from the \textsf{xcolor} package by Uwe Kern -% which is loaded by \textsf{exesheet}.} -% (by default |\definecolor{correctioncolor}{rgb}{0,0.2,0.6}| = kind of dark blue). -% Moreover, with \texttt{output=both} +% Furthermore, when using \texttt{output=both} % the title \textbf{\correctionname} is displayed at the beginning % of \texttt{answers} environments. -% It is defined by the |\correctionname| macro (with translation in a few languages -% and that can changed: -% for example you may prefer ``Solution'' -% than ``\correctionname''). -% The style defined by |\correctionstyle| will apply to the title -% as for the whole environment. -% Here an example. +% This title is defined by the |\correctionname| macro, +% with translation available in several languages, and it can also be modified. +% For instance you might prefer ``Solution'' +% over ``\correctionname''. +% The style defined by |\correctionstyle| will be applied to the title +% as well as the entire environment. +% Here's an example to illustrate this: % -% \vspace{-\baselineskip} -% \noindent\psframe(-0.25,-0.25)(12.75,-6.7) +% \pagebreak +% ^^A \vspace{-\baselineskip} +% \noindent\psframe(-0.25,-0.25)(12.75,-6.9) % \exercise % \begin{questions} % \begin{enumerate} % \item Is the \textsf{exesheet} package useful ? -% \item Isn't there any other packages that deal with exercises ? +% \item Aren't there any other packages that deal with exercises ? % \end{enumerate} % \end{questions} % \begin{answers} % \begin{enumerate} -% \item Yes, the \textsf{exesheet} package is useful for teachers. -% \item There are many other packages that deal with exercises, and -% give the ability to produce separately questions and solutions, for example -% \textsf{exercise} by Paul Pichaureau, \textsf{exercises} by Roger Jud, -% \textsf{exsheets} (superseded by \textsf{xsim}) by Clemens Niederberger, +% \item Yes, the \textsf{exesheet} package is indeed useful for teachers. +% \item There are numerous other packages that handle exercises and +% provide the capability to create questions and solutions separately. +% For instance the +% \textsf{exercise} package by Paul Pichaureau, \textsf{exercises} by Roger Jud, +% \textsf{exsheets} (now superseded by \textsf{xsim}) by Clemens Niederberger, % \textsf{exframe} by Niklas Beisert, % \textsf{exam} by Philip Hirschhorn, % \textsf{answers} by Mike Piff and Joseph Wright, -% \textsf{probsoln} by Nicola Talbot, etc. +% \textsf{probsoln} by Nicola Talbot, and more. % \end{enumerate} % \end{answers} % @@ -613,235 +664,242 @@ % the word ``\correctionname'' is not displayed. % % \subsection{About the title ``\correctionname'' in \texttt{answers} environments} -% Internally, we have used the |\comment| and |\endcomment| macros +% Internally, we have utilized the |\comment| and |\endcomment| macros % from the \textsf{versions} package by Uwe Lück. -% Other excellent packages allow to manage -% selectively piece of code. Let us mention -% \textsf{verbatim} by Rainer Schöpf, \textsf{comment} by Victor Eijkhout, +% Several other outstanding packages also enable selective management of code portions. +% Notably, the \textsf{verbatim} package by Rainer Schöpf, +% \textsf{comment} by Victor Eijkhout, % \textsf{version} by Donald Arseneau and Stephen Bellantoni, % \textsf{optional} by Donald Arseneau % and \textsf{codesection} by Matthias Pospiech. % -% The \textsf{versions} package provides furthermore +% Moreover the \textsf{versions} package includes % the |\includeversion|\marg{env} and -% |\excludeversion|\marg{env} macros who allow to make appear or disappear -% any environment \meta{env} and these optional environments -% may be nested -% \footnote{The \textsf{codesection} package also allows -% such nesting, including in the preamble, as well as -% the \textsf{optional} package, but the latter manages only short optional code.}. +% |\excludeversion|\marg{env} macros which allow for the inclusion or exclusion of +% any environment \meta{env}. These ``optional'' environments +% can be nested +% \footnote{The \textsf{codesection} package also supports +% such nesting, including within the preamble, as well as +% the \textsf{optional} package, but the latter manages only short sections of optional code.}. % % However the \texttt{questions} and \texttt{answers} environments -% perform another task, not only making appear or disappear piece of text. -% In what format should the output yield the title \textbf{\correctionname} -% and at which level should it be put in the table of contents -% (or in the summary of the pdf file)? -% In fact it depends on which level the environment has been nested. -% We can make a single \texttt{answers} environment for the whole -% sheet or an \texttt{answers} environment -% for each exercise, for each exercise part, for each question or sub-question. -% In fact, the typeset of the title \textbf{\correctionname} -% and his level in the table of contents will be computed by the environment. +% serve a broader purpose beyond merely displaying or hiding text. +% For instance, you can choose to have a single answers environment +% for the entire sheet, or alternatively, have separate answers environments +% for each exercise, exercise part, question, or sub-question. +% The format in which the title \textbf{\correctionname} should appear +% in the output, and its placement in the table of contents +% or PDF file summary, depends on the nesting level of the environment. +% In fact, the rendering of the \textbf{\correctionname} title and its corresponding +% table of contents level will be automatically calculated by the environment. % % \medskip % \DescribeEnv{answers\oarg{level}} -% Nevertheless, one can imagine twisted situations in which -% the title level will not be correct. -% Moreover, the user may want to change the level of the title. -% It is then possible to force the level of the title ``\correctionname'' -% with |\begin{answers}|\oarg{level}. +% However, there are perhaps twisted situations in which +% the title level may not always be accurate. +% Furthermore, users might wish to adjust the title's level themselves. +% To achieve this, you can manually set the level of the title ``\correctionname'' +% using |\begin{answers}|\oarg{level}. % The optional \meta{level} parameter is defined as follows: -% 1 for section level titles, -% 2 for subsections (like \textbf{\exercisename}), -% 3 for sub-subsections (like \textbf{\partname}), -% another number for lower levels -% (that will not appear in the table of contents). +% 1 for section-level titles, +% 2 for subsections (akin \textbf{\exercisename}), +% 3 for sub-subsections (similar to \textbf{\partname}), +% other numbers for lower levels +% (which won't appear in the table of contents or in the PDF file’s summary). % -% \pagebreak +% \smallskip % \DescribeMacro{answers*} -% The starred version \texttt{answers*} makes the title -% \textbf{\correctionname} completely disappear. +% The starred version \texttt{answers*}, completely hides the +% \textbf{\correctionname} title. % % \subsection{Commands \texttt{\bs question}, \texttt{\bs answer} and \texttt{\bs answerspace}} % \label{answerspace} % \DescribeMacro{\question}\DescribeMacro{\answer} -% Instead of \texttt{questions} and \texttt{answers} environments, -% we can also use simple |\question|\marg{ques} and |\answer|\marg{ans} macros -% in which display of \meta{ques} and \meta{ans} arguments -% are controlled by the same previous key option \texttt{output=\meta{opt}}. -% It may be more suitable when questions and answers are short, for instance -% if you want to display the answer after each question item. -% The title ``\correctionname'' will not appear on the beginning -% of each answer; answers are typeset with |\correctionstyle| +% Instead of using \texttt{questions} and \texttt{answers} environments, +% we can also employ the simpler |\question|\marg{ques} and |\answer|\marg{ans} macros. +% The visibility of \meta{ques} and \meta{ans} content is +% regulated by the same previous \texttt{output=\meta{opt}} key option. +% This approach might be more fitting for brief questions and answers, such as when +% you wish to display the answer immediately after each question item. +% The title ``\correctionname'' won't appear at the start +% of each answer with the |\answer| macro. +% The answers are formatted using |\correctionstyle| % if \texttt{output=both}. -% But these commands don't work with \texttt{verbatim} text inside, -% whereas \texttt{questions} and \texttt{answers} environments allow that. +% However these commands do not support \texttt{verbatim} text within them, +% unlike the \texttt{questions} and \texttt{answers} environments which do. % % \bigskip % \DescribeMacro{\answerspace} -% Some teachers are used to give to their students documents in which questions are typeset -% but instead of answers you have blank space, so that the paper is intended to be -% fulfilled by the students. -% For this purpose, thanks to a suggestion of Maxime Chupin, -% we provide the macro |\answerspace|\oarg{height}, -% in which the parameter height is a valid length, \eg |\answerspace{3cm}|. +% Some teachers are accustomed to providing their students with documents +% where questions are typeset, leaving blank spaces instead of answers. +% This layout allows students to fill in their responses on the paper. +% To achieve this, thanks to a suggestion from Maxime Chupin, +% we offer the |\answerspace|\marg{height} macro, +% in which the parameter \meta{height} is a valid length, +% \eg |\answerspace{3cm}|. % +% \medskip % \DescribeMacro{[answerspace=\meta{bool}]} -% This vertical space display is optional and is controlled by the key -% \texttt{answerspace} which can be \texttt{true} or \texttt{false} (by default). -% Of course this macro is not intended to be placed inside \texttt{answers} -% environments, but anywhere else. +% The blank spaces introduced by |\answerspace| can be displayed +% or hidden, controlled by the +% \texttt{answerspace} option key, which can be set to either +% \texttt{true} or \texttt{false} (the default). +% Of course the |\answerspace| macro is not meant to be used within \texttt{answers} +% environments. % % \section{Marginal notes for marking scheme} % -% The \textsf{exesheet} package allows to display in margins a marking -% scheme with comments and explanations about answers. +% The \textsf{exesheet} package enables the display of a detailed marking +% scheme in the margins, along with comments and explanations about answers. % % \subsection{The \texttt{\bs points} command}\label{points} % \DescribeMacro{\points} % The |\points|\marg{pts} command displays the number of points awarded for an exercise. -% It is intended to be entered in the optional argument of the +% It is intended to be included in the optional argument of the % |\exercise| command -% \footnote{Using this command in the optional argument of -% \texttt{\bs exercise} is incompatible with -% the \textsf{memoir} class which redefines section commands.}. -% For instance -% |\exercise[\points{5}]| yields: +% \footnote{However using this command in the optional argument of +% \texttt{\bs exercise} is not compatible with +% the \textsf{memoir} class, as the \textsf{memoir} class redefines section commands.}. +% In the following example, we used +% |\exercise[\points{5}]|: % \exercise[\points{5}] % \psframe(-0.25,1.3)(12.75,-0.4) % Try to read this document to the end without drinking tea and you get five points. % % \bigskip -% When only correction is displayed in an exercise, the |\points| macro is patched -% to suppress the display of points. -% An extended solution for printing answers with the scale will be presented -% in section \ref{totalpoints}, including a new |\totalpoints| macro. +% When only the correction is displayed in an exercise, the |\points| macro doesn't +% show the points. +% A more comprehensive solution for printing answers along with the point scale +% will be presented +% in section \ref{totalpoints}, which includes another |\totalpoints| macro. % % \bigskip % \DescribeMacro{\pointsname} \DescribeMacro{\pointname} -% The word ``\pointsname'' (or in the singular ``\pointname'' -% if \meta{pts} is inferior to 2), is added and, like before, -% gets automatic translation in a few languages -% (and can be changed). +% The term ``\pointsname'' (or ``\pointname'' in the singular +% if \meta{pts} is less than 2), is appended and +% is automatically translated into several languages +% (and can also be modified). % +% \smallskip % \DescribeMacro{\pointsstyle} \DescribeMacro{pointscolor} -% The style used by the |\points| command may be redefined with |\pointsstyle|. -% The color is set by |pointscolor| with the |\definecolor| command, -% and you can change it, -% \eg: |\definecolor{pointscolor}{named}{blue}|. +% You can adjust the |\points| command's style through |\pointsstyle|. +% The color setting (red by default) is managed by |pointscolor| using |\definecolor|, +% for example you can declare: |\definecolor{pointscolor}{named}{blue}|. % % \subsection{The \texttt{\bs pts} command} \label{pts} % \DescribeMacro{\pts} -% When exercises are typeset with the |\exe| macro, +% When exercises are typeset using the |\exe| macro % or as a list with the \texttt{exenumerate} environment, -% the marking scheme can be displayed in the margin, on the line where -% we put the |\pts|\marg{num} command (in general the first line of the exercise). -% The \meta{num} parameter is the number of points assigned to the exercise. -% Below what we obtain with with |\exe\pts{3}... \exe\pts{1.5}...| +% the marking scheme can be shown in the margin, aligned with the line where +% the |\pts|\marg{num} command is placed (typically the first line of the exercise). +% The \meta{num} parameter represents the number of points assigned to the exercise. +% Here's an example with |\exe\pts{3}... \exe\pts{1.5}...| % % \vspace{-\baselineskip} % \noindent\psframe(-3.0,-0.25)(12.75,-1.95) -% \exe \pts{3} The first exercise with a marking scheme. +% \exe \pts{3} The first short exercise with a marking scheme. % \exe \pts{1.5} The second one. % % \bigskip % \DescribeMacro{\ptsname} \DescribeMacro{\ptname} % \DescribeMacro{ptscolor} \DescribeMacro{\ptsstyle} % The abbreviation ``\ptsname'' (or ``\ptname'' -% when the number of points is inferior to 2) -% is automatically added with macros |\ptsname| or |\ptname| -% (translated in a few languages if \textsf{babel} ore \textsf{polyglossia} are loaded). -% The display color of the points is defined by \texttt{ptscolor}, which can be changed -% with |\definecolor|: by default |\definecolor{ptscolor}{named}{red}|. -% The display style is defined by |\ptsstyle|: among other things, it adds parenthesis around. +% when the number of points is less than 2) +% is added automatically using |\ptsname| or |\ptname| macros +% (translated in several languages +% if \textsf{babel} or \textsf{polyglossia} is loaded). +% The point's display color is defined by \texttt{ptscolor}, changeable via +% |\definecolor| (red by default). +% The display style is determined by |\ptsstyle|, which among other things, +% adds parenthesis around. % % \bigskip % \DescribeMacro{[display=\meta{opt}]} -% The display of the marking scheme is controlled by the -% option key \texttt{display}. -% By default |display=none| and the marking scheme will not be displayed. -% Use |display=pts| to make it appear. -% More details about this key are given in \ref{margin}. +% The marking scheme visibility is controlled by the +% \texttt{display} option key. +% The default option is |display=none|, keeping the marking scheme hidden. +% To reveal the marking scheme, use |display=pts|. +% More details are available in section \ref{margin}. % % \medskip % \DescribeMacro{[marginpos=\meta{opt}]} -% The side where to place the scale is controlled by the |marginpos| key option -% whose possible values are (first) \texttt{left} or \texttt{right}. -% The default is \texttt{left} -% (although the default behavior of \LaTeX{} is to place marginal notes on the right side). -% This option has no effect when -% |display=none|. -% -% For a \emph{two side} document, the default behavior is to typeset text in the outer margin -% which will be enlarged relatively to the inner margin (that contains the binding). -% The outer margin is on the right hand side for odd pages and on the left hand side -% for even pages. So the \texttt{marginpos} key option can take those two additional -% values. -% When you give a \texttt{left} or \texttt{right} value with a two side document, -% it will be converted to default value, \texttt{outer}, with a warning message. +% The positioning of the scale is determined by the |marginpos| option key, +% typically \texttt{left} or \texttt{right}. +% The default value is \texttt{left} +% even though \LaTeX{} positions marginal notes on the right side by default. +% This option has no impact when |display=none|. +% +% For a two-sided document, the default behavior is to place text in the outer margin, +% which is wider than the inner margin (that contains the binding). +% The outer margin aligns with the right side on odd pages and with the left side +% on even pages. Therefore, the \texttt{marginpos} option can also take the +% values \texttt{inner} or \texttt{outer}. +% If you specify \texttt{left} or \texttt{right} when the \texttt{twoside} mode is activated, +% this value will be converted to \texttt{outer}, accompanied by a warning message. % % \medskip -% \DescribeMacro{twoside mode} -% For a document is in twoside mode, marginal notes sometimes appear on the wrong -% side of a page. This is a known bug of \LaTeX\ for which the solution -% is to call the package \textsf{mparhack} (what is done by \textsf{exesheet} -% for a twoside mode document) and to \emph{run \LaTeX\ twice}. -% If necessary you get a warning message to rerun. +% With the \texttt{twoside} mode, marginal notes might occasionally +% appear on the wrong side of a page. +% This is a known \LaTeX{} bug, and the solution involves using +% the \textsf{mparhack} package (which \textsf{exesheet} automatically includes +% for documents in two-side mode) and \emph{running \LaTeX{} twice}. +% If necessary, a warning message will prompt you to perform the re-run. % % \subsection{Commands \texttt{\bs totalexe}, \texttt{\bs note*} and \texttt{\bs note}} % % \label{note} -% To give a more detailed marking scheme, we get -% the following commands. +% For a more comprehensive marking scheme, the following commands are available. % % \medskip % \DescribeMacro{\totalexe} -% |\totalexe|\marg{num} displays the total number of points of an exercise, -% by default inside an oval box, with the word ``\ptsname'' (or ``\ptname'') -% added and in bold red. -% In the next example, the exercise title has been obtained with |\exercise[\totalexe{4}]|. +% The |\totalexe|\marg{num} macro displays the total number of points of an exercise. +% By default, it appears inside an oval box, with the addition of the word +% ``\ptsname'' (or ``\ptname'') in bold red. +% In the following example, the exercise title has been generated +% using |\exercise[\totalexe{4}]|. % % \medskip % \DescribeMacro{\note*} -% For each answer or solution in the correct version, the command -% |\note*|\marg{num} states the number of points of that question. -% The appearance is somewhat different from the one obtained with |\pts|: -% by default the number is displayed without being followed by ``\ptsname'' or ``\ptname'', -% without parenthesis, and in bold. -% In the answer 3 of the next example, just after |\item|, we used: |\note*{1.5}|. +% For each answer or solution in the correct version, the +% |\note*|\marg{num} command indicates the number of points allocated to that question. +% The appearance slightly varies compared to |\pts|: +% by default the number is displayed in bold without the ``\ptsname'' or ``\ptname'' suffix, +% and without parenthesis. +% In the following example, for answer 3, +% we employed |\note*{1.5}|, placed right after |\item|. % % \medskip % \DescribeMacro{\note} -% The |\note|\marg{comment} macro is used to give details about the marking scheme -% and to indicate how points are awarded. -% In a comment argument you can use |\\| to get a line break, -% or even |\\[|\meta{height}|]| to increase the line break from \meta{height}. +% The |\note|\marg{comment} macro is utilized to provide additional information +% regarding the marking scheme and to explain how points are assigned. +% In the \meta{comment} argument you can use |\\| to create a line break +% or even |\\[|\meta{height}|]| to adjust the line spacing by \meta{height}. % % \DescribeMacro{\note\oarg{num}} -% It is often convenient to put |\note*|\marg{num}|\note|\marg{comment} -% at the beginning of an answer. In that case \LaTeX\ will place the margin -% notes one under the other and will protest with: -% \texttt{LaTeX Warning: Marginpar on page \ldots\@ moved.} \\ -% This is not a real problem because generally \LaTeX\ is able to -% manage the placement of these -% marginal notes, one below the other. Nevertheless, one can avoid unnecessary protests by -% compacting both commands in a single one and typing the number of points -% as an optional argument of note: +% Placing |\note*|\marg{num}|\note|\marg{comment} +% at the beginning of an answer is often practical. +% In such cases \LaTeX{} will align the margin +% notes vertically, which leads to a warning like: +% \texttt{LaTeX Warning: Marginpar on page \ldots\@ moved.} +% However, this warning is not an issue, as \LaTeX{} can usually handle the arrangement +% of these marginal notes, stacking them one below the other. +% Nonetheless, to prevent unnecessary warnings, you can combine both commands into a +% single one by specifying the number of points as an optional argument of the |\note| command: % |\note|\oarg{num}\marg{comment}. % -% The first comment on the following example is obtained (just after |\item|) with\\ +% The initial comment in the following example is generated (immediately after |\item|) using % |\note[1]{0.5 for the anti-derivative\\0.5 for simplifying}|. % % \exercise[\totalexe{4}] \label{totalexe} % \begin{questions} % \psframe(-3.5,1.3)(12.75,-14) -% For each following question, say if the assertion is true or false. -% Justify the answer carefully. +% For each subsequent question, determine whether the statement is true or false. +% Provide a thorough justification for your answer. % \begin{tablenum1} % \item $\ds \int_{0}^{\sqrt{3}}\frac{1}{x+\sqrt{3}} \,\mathrm{d}x = \ln 2$, % \item $\ds \int_{2}^{\mathrm{e}} \frac{1}{x\ln x} \,\mathrm{d}x = -\ln 2$, -% \item* The function $F$ defined on $\mathbf{R}$ by -% $F(x) = \ds \int_{0}^{x}\frac{1}{t^2+t+1}\,\mathrm{d} t$ is increasing on $\mathbf{R}$. +% \item* The function $F$, defined on $\mathbf{R}$ by +% $F(x) = \ds \int_{0}^{x}\frac{1}{t^2+t+1}\,\mathrm{d} t$, is increasing on $\mathbf{R}$. % \end{tablenum1} % \end{questions} % @@ -857,8 +915,8 @@ % \] % \textbf{TRUE}. % -% \item \note[1.5]{1 for the anti-derivative \\0.5 for final value \\[2ex] -% other method: $\frac{1}{x \ln x} >0$ on $[2, \mathrm{e}]$ +% \item \note[1.5]{1 for the anti-derivative \\0.5 for the final value \\[2ex] +% Other method: $\frac{1}{x \ln x} >0$ on $[2, \mathrm{e}]$ % whereas $-\ln2<0$ % } % We have $\ds\frac{1}{x \ln x}= \frac{\frac{1}{x}}{\ln x}= \frac{u'(x)}{u(x)}$ @@ -871,8 +929,8 @@ % \textbf{FALSE}. % % \item \note*{1.5} -% The function $F$ defined on $\mathbf{R}$ by -% \[ F(x)= \int_{0}^{x}\frac{1}{t^2+t+1}\, \mathrm{d}t \] +% The function $F$, defined on $\mathbf{R}$ by +% \[ F(x)= \int_{0}^{x}\frac{1}{t^2+t+1}\, \mathrm{d}t, \] % is derivable on $\mathbf{R}$ and its derivative is such that % $F'(x)=\frac{1}{x^2+x+1}$. % \note{0.5 for $F'$\\1 for the sign of $F'$ and conclusion} @@ -882,164 +940,167 @@ % \textbf{TRUE}. % \end{enumerate} % \end{answers} -% In the comment of answer 2, a wider vertical space is produced at line break -% with the optional argument |\\[2ex]|. -% The last comment, not placed beside the number of points of answer 3, -% has been produced by placing on the first line after the formula: +% In the comment for answer 2, a larger vertical space is created with +% the optional argument |\\[2ex]| for line break. +% The last comment, which isn't positioned next to the points number, +% was produced by placing the following on the first line after the formula: % |\note{0.5 for $F'$\\1 for the sign of $F'$ and conclusion}|. % % \medskip % \DescribeMacro{markingcolor} \DescribeMacro{\markingstyle} \DescribeMacro{\ptsboxlength} -% The points display color, in |\totalexe| and |\note*|, -% is defined by \texttt{markingcolor} -% and the style by |\markingstyle|, which are modifiable. -% The oval box produced by |\totalexe| is obtained with the |\ovalbox| command -% of the \textsf{fancybox} package (by Timothy Van Zandt), +% The color and style for displaying points in |\totalexe| and |\note*| +% can be customized using \texttt{markingcolor} and |\markingstyle|, respectively. +% The oval box produced by |\totalexe| is created using the |\ovalbox| command +% from the \textsf{fancybox} package (by Timothy Van Zandt), % with corner arcs set by |\cornersize{1}|. -% The length of the box is not adjusted to content but depends on the value -% of |\ptsboxlength| in order to keep uniform appearance -% from one exercise to the other. +% The box's length is determined by +% |\ptsboxlength|, and not by the box's content, to ensure uniformity across exercises. % % \medskip % \DescribeMacro{notecolor} \DescribeMacro{\notestyle} -% Comment notes are typeset by default in a dark green color +% By default, comment notes are typeset in a dark green color % defined by |\definecolor{notecolor}{rgb}{0.0,0.4,0.0}|. -% The style of the comment is set by the |\notestyle| macro. +% The style of the comment is determined by the |\notestyle| macro. % % \subsection{Margin notes options} \label{margin} % % \DescribeMacro{[display=\meta{opt}]} -% The \texttt{display} key option controls how the marking scheme -% will be displayed: as seen previously (subsection \ref{pts}), -% \texttt{display=none} displays nothing. With \texttt{display=pts} -% the numbers passed as argument to |\pts|, |\totalexe|, |\note*| -% or as optional argument of |\note|\oarg{num}\texttt{\{...\}} will be displayed. -% The last possible value is \texttt{display=notes} which displays the full marginal -% notes with points and comments (the mandatory argument of |\note|) -% as seen in the previous example. +% The \texttt{display} key option governs the presentation of the marking scheme: +% as discussed previously (subsection \ref{pts}), +% \texttt{display=none} shows nothing. When using \texttt{display=pts} +% the numbers provided as arguments to |\pts|, |\totalexe|, |\note*| +% or as optional arguments of |\note|\oarg{num}\texttt{\{...\}} will be exhibited. +% The final option is \texttt{display=notes} which reveals the complete marginal +% notes, containing points and comments (the mandatory argument of |\note|), +% as illustrated in the previous example. % % \medskip % \DescribeMacro{[marginpos=\meta{opt}]} -% As seen previously in subsection \ref{pts}, the side where to place the scale is controlled -% by the \texttt{marginpos} key option -% whose possible values are \texttt{left} and \texttt{right} -% (or \texttt{inner} and \texttt{outer} if the document is in two side mode). +% As previously mentioned in subsection \ref{pts}, the side on which +% to position the scale is determined by the \texttt{marginpos} key option, +% with possible values of \texttt{left} and \texttt{right} +% (or \texttt{inner} and \texttt{outer} if the document is in \texttt{twoside} mode). % % \medskip % \DescribeMacro{[marginwidth=\meta{opt}]} -% The key option \texttt{marginwidth} controls margins layout. -% The possible values are -% \texttt{standard}, \texttt{expand} or \texttt{unset}. +% The margin layout is governed by the \texttt{marginwidth} key option, +% which can take one of the following values: +% \texttt{standard}, \texttt{expand}, or \texttt{unset}. % % This option has no effect when \texttt{display=none}. -% In that case, left and right margins have same width, -% except for a two side mode document for which the ratio between left and right -% margin is 2:3. -% Otherwise the key \texttt{marginwidth} acts as follow: +% In this case, both the left and right margins have the same width, +% except in a two-sided document where the ratio between the left and right +% margins is 2:3. +% Otherwise the \texttt{marginwidth} key option behaves as follows: % \begin{description} % \item[\texttt{standard}] -% The left margin is enlarged and the -% right one is reduced, with a ratio of 3:2 (or 2:3 if \texttt{marginpos=left}). -% The text body is shifted without altering the text width. -% The margin paragraph width remains relatively short; it depends also on page geometry. -% This option is not suitable for verbose comments. +% The left margin is widened, and the +% right margin is reduced, with a ratio of 3:2 (or 2:3 if \texttt{marginpos=right}). +% The text body is shifted without changing its width. +% The margin paragraph width remains relatively short +% (depends on page geometry). +% This option is not ideal for lengthy comments. % -% \item[\texttt{expand}] It is the default value. -% The behavior is the same than with the -% \texttt{standard} value if \texttt{display=pts}, but if \texttt{display=notes} -% the margin is expanded with a ratio of 3:1 (or 1:3) and margin paragraph width -% is increased. -% -% \item[\texttt{unset}] The previous settings may not suit to anyone, -% so you have this other option. -% In that case, no setting will be proceeded on the margin width and you -% can make your own setting. For that, you have the convenient macro |\geometry| +% \item[\texttt{expand}] (default value)\enskip +% The behavior is the same as with the +% \texttt{standard} value when \texttt{display=pts}. However, when \texttt{display=notes}, +% the margin expands with a ratio of 3:1 (or 1:3) and the width of margin paragraphs +% increases. +% +% \item[\texttt{unset}] This option is provided for cases where the previous settings +% are not suitable. +% In this case, no adjustments are made to the margin width. Instead, you can define +% your own settings using the convenient |\geometry| macro % from the \textsf{geometry} package (by Hideo Umeki). -% For example you can put in the preamble +% For instance, you can place the following in the preamble: % \centeredline{|\geometry{hmarginratio=2:1,marginparwidth=2.5cm}|.} % -% If \texttt{marginpos=right}, you must invert the ratio, \eg 1:2 instead of 2:1. +% If \texttt{marginpos=right}, you need to invert the ratio, \eg 1:2 instead of 2:1. % If \texttt{marginwidth} is not set to \texttt{unset}, % such a command will have no effect. % \end{description} -% The margin settings are valid -% for the whole document and must be set in the preamble. +% Margin settings are applicable to the entire document +% and need to be configured in the preamble. % % \medskip % \DescribeMacro{[noteragged=\meta{opt}]} -% For the mandatory argument of |\note|, text alignment in margins -% is controlled by the package option \texttt{noteragged}, -% which can take the following values: +% The package option \texttt{noteragged} controls the text alignment within the margins +% for the mandatory argument of |\note|. +% It offers the following values: % \texttt{left}, \texttt{right}, \texttt{center}, \texttt{justify} or \texttt{twoside}. -% The default value is \texttt{noteragged=left}. It means that the text -% is right aligned, which is a common behavior for text in the left margin; -% \texttt{noteragged=right} yields a left aligned text; -% \texttt{justify} means that the text is justified, which is the default setting -% of \LaTeX\ marginal notes. -% Finally \texttt{noteragged=twoside} is equivalent to \texttt{noteragged=left} for odd pages -% and \texttt{noteragged=right} for even pages, if the document is in two side mode. -% It has no effect otherwise (the default value \texttt{noteragged=left} will be taken -% and a warning message appears in the shell). +% The default value is \texttt{noteragged=left}, resulting in right-aligned text, +% which is common for text in the left margin. +% When \texttt{noteragged=right}, the text is left-aligned text. +% Using \texttt{justify} makes the text justified, aligning with +% \LaTeX's default behavior for marginal notes. +% Finally \texttt{noteragged=twoside} aligns text to the left on odd pages +% and to the right on even pages in a two-sided document. +% It has no effect otherwise (the default \texttt{noteragged=left} is used +% and a warning message appears in the terminal). % % When \texttt{display} is not set to \texttt{notes}, the \texttt{noteragged} option -% has no effect because it concerns only text put in mandatory argument of |\note|. +% has no impact, as it specifically applies to text within the mandatory argument of |\note|. % % \subsection{The \texttt{\bs totalpoints} command} \label{totalpoints} % % \DescribeMacro{\totalpoints} -% The |\totalpoints|\marg{num} macro is intended -% to replace |\points| when using a detailed marking scheme. -% When the scale is not displayed, -% it is equivalent to |\points| and when the scale is displayed, -% it is equivalent to |\totalexe|. -% For example, in the exercise \ref{totalexe}, we should use -% |\totalpoints| rather than |\totalexe|, -% because, when the detailed marking scheme is not displayed, the total points will be typeset -% as in the exercise \ref{points} rather than in the margin. +% The |\totalpoints|\marg{num} macro serves as a replacement for +% |\points| when using a comprehensive marking scheme. +% When the scale isn't visible, +% it functions similarly to |\points|, and when the scale is shown, +% it's akin to |\totalexe|. +% For instance, in the exercise \ref{totalexe}, it's preferable to use +% |\totalpoints| instead of |\totalexe|, +% as when the detailed marking scheme isn't displayed, the total points will be typeset +% in a manner similar to exercise \ref{points} rather than in the margin. % % \subsection{Marking scheme consistency checking}\label{scale} % % \DescribeMacro{[checkpts=\meta{bool}]} % The marking scheme can be checked % \footnote{Thanks to Denis Bitouzé for his suggestion about this feature.} -% with the keyval option \texttt{[checkpts=true]}, +% using the key-val option \texttt{checkpts=true}; % the default value is \texttt{false}. % % \medskip -% For each exercise, the sum of points awarded for each question (with |\pts|, |\note*| -% or |\note[ ]| is compared to the total of the exercise given in -% |\points|, |\totalexe| or |totalpoints|. -% A warning message appear in the shell to indicate if the scale is valid or not -% for the exercise. For example: +% For each exercise, the cumulative points allocated to each question (via |\pts|, |\note*| +% or |\note[ ]| are compared to the exercise's total specified in +% |\points|, |\totalexe| or |\totalpoints|. +% A warning message will be displayed in the shell to indicate whether +% the scale is valid +% for the exercise or not. For example: % \begin{center} -% \texttt{Package exesheet warning: Exercise 3: sum of points is 4.5pt instead of 5pt.} +% \texttt{Package exesheet warning: Exercise 3: Sum of points is 4.5pt instead of 5pt.} % \end{center} -% Depending on your language, you can use comma notation numbers (4,5 as well as 4.5). -% The checking takes place at the beginning of the next exercise. If no points are specified -% for the questions, no warning message will be displayed at this level. +% Both comma notation (\eg 4,5) and decimal point format (\eg 4.5) +% may be accepted, depending on your chosen language. +% The validation occurs at the beginning of the subsequent exercise. +% No warning messages will be presented at this level if no points are specified +% for the questions. % % \medskip % \DescribeMacro{\totalsheet} -% At the end of the sheet, the last exercise is checked, then a global checking -% is made on the whole sheet. For that, the total points of the sheet must be specified -% in the preamble with the |\totalsheet|\marg{total} macro -% (else you get a warning message). -% If subtotal points have been awarded for exercises, the global comparison -% is between the sum of these subtotals and the total of points recorded -% with the |\totalsheet| macro. -% If not, the audit covers the sum of points awarded for each individual question. -% A warning message indicates the result of this last checking. -% Finally a last message indicate if all the scale controls have been successfully +% At the end of the sheet, the last exercise is checked, +% followed by a global examination of the entire sheet. +% This last task requires knowledge of the total points for the sheet. To achieve this, use +% the |\totalsheet|\marg{total} macro in the preamble; +% otherwise, a warning message will be displayed. +% If subtotals have been assigned to exercises, the overall comparison +% is made between the sum of these subtotals and the total points recorded +% using the |\totalsheet| macro. +% If not, the evaluation encompasses the sum of points for each individual question. +% A subsequent warning message indicates the outcome of this last verification. +% Finally, a message indicates whether all scale controls have been successfully % passed or not. % % \section{Options} \label{options} % % \subsection{Summary of available options} % -% Here we present a summary table of available options. Explanations of use -% are given in the corresponding sections. -% The default value is typeset in bold. +% Here we provide a summary table of the available options. Details on their usage +% can be found in the respective sections. +% The default value is displayed in bold. % % \begin{center} \ttfamily % \setlength{\extrarowheight}{1pt} @@ -1061,69 +1122,70 @@ % \end{tabular} % \end{center} % -% When an invalid key is passed, an error is produced, but -% when a value is not recognized, a warning message occur:\\ -% \texttt{Value `\meta{value}'\ is not supported by option `\meta{key}'\ +% When an invalid key is provided, an error is generated. However, +% if a value is not recognized, a warning message will appear:\\ +% \texttt{Value `\meta{value}'\ is not supported by `\meta{key}' option % on input line \ldots} \\ -% For each option, you can set them with class or package calling: \eg \\ +% For each option, you can set them through the class or package invocation, \eg % |\usepackage[output=answers,display=notes,noteragged=right]{exesheet}| % % \bigskip % \DescribeMacro{\exesheetset} -% You can also use the |\exesheetset|\{list of \meta{key}=\meta{value} options\} +% You can also use the |\exesheetset|\{list of \meta{key}=\meta{value}\} % command. -% Nevertheless, only the options \texttt{output}, \texttt{answerspace}, \texttt{display}, +% Note that some options, \texttt{output}, \texttt{answerspace}, \texttt{display}, % and \texttt{noteragged}, -% can be changed dynamically, even in the document body, although this is not really expected. -% The others are usable in the preamble only. -% Dynamic options are processed at each call, the others will be processed once, -% at begin document. +% can be changed dynamically, even within the document, +% while the others are applicable in the preamble exclusively. +% Dynamic options are processed with each call, whereas the others are processed once, +% when the document begins. % \hypertarget{correct}{} % % \bigskip % \DescribeMacro{[correct=\meta{opt}]} -% A special option, \texttt{correct}, can be used only when calling the \textsf{exesheet} -% class or in combination with the \textsf{schooldocs} package. -% Its effect is to add ``\correctname'' (or its translation) -% in the document title and headers. -% Possible values are: \texttt{true}, \texttt{false} (by default) or \texttt{conditional}. -% The value \texttt{correct=conditional}, means \texttt{true} if answers are displayed, -% \texttt{false} otherwise. +% A special option, \texttt{correct}, can be employed when using the \textsf{exesheet} +% \emph{class} or in conjunction with the \textsf{schooldocs} package. +% This option adds ``\correctname'' (or its translation) +% to the document title and headers. +% Possible values are: \texttt{true}, \texttt{false} (default) or \texttt{conditional}. +% When set to \texttt{correct=conditional}, it behaves as \texttt{true} +% when answers are displayed and \texttt{false} when they're not. % % \subsection{Alternative (deprecated) commands} % -% Previously to version 2.0, we used some special commands to set output and display options. -% Thanks to a suggestion of Maxime Chupin, keyval options have been implemented -% in the package. -% Although the latter is more convenient, -% the old commands will be presented here -% and maintained for now, for compatibility reasons. -% When using them, a warning message will appear, but these commands still work. -% However previous options \texttt{nosetlist} and \texttt{notoc} +% Prior to version 2.0, we used specialized commands to configure +% output and display options. +% Thanks to a suggestion from Maxime Chupin, we have now implemented \emph{key=value} +% options in the package. +% Although the latter is more user-friendly, +% the older commands are still supported for compatibility reasons and are outlined here. +% While these commands will trigger a warning message, they remain functional. +% However, the previous options \texttt{nosetlist} and \texttt{notoc} % are no longer supported. % % \bigskip % \DescribeMacro{\questionsonly} \DescribeMacro{\answersonly} -% These two commands are equivalent to respectively \texttt{output=questions} -% and \texttt{output=answers}. +% The command |\questionslonly| is equivalent to setting \texttt{output=questions} +% and |\answersonly| means \texttt{output=answers}. % % \medskip % \DescribeMacro{\displaypts} \DescribeMacro{\displaypoints} -% These two commands are now equivalent to \texttt{display=pts}. -% -% \medskip % \DescribeMacro{\displaynotes}\DescribeMacro{\displaynotesright} -% These two commands mean \texttt{display=notes} -% and moreover \texttt{marginpos=right} for the latter. +% The commands |\displaypts| and |\displaypoints| +% are equivalent to setting \texttt{display=pts}; +% |\displaynotes| means \texttt{display=notes}, +% and |\displaynotesright| corresponds to +% \texttt{display=notes} and \texttt{marginpos=right}. % % \StopEventually{} % % \section{Implementation} % % \subsection{Options and required packages} -% The \texttt{exesheet} class is based on the \texttt{article} class -% and passes to it all its unknown options. -% |\ProcessKeyvalOptions*| is useless in class, will be done by the package. +% The \texttt{exesheet} class is build upon the \texttt{article} class +% and transfers all its unknown options to it. The use of +% |\ProcessKeyvalOptions*| is unnecessary within the class +% as it will be managed by the package. % \begin{macrocode} %<*class> \RequirePackage{kvoptions} @@ -1145,18 +1207,20 @@ %</class> % \end{macrocode} % -% Then options are defined thanks to \textsf{kvoptions} package (based on \textsf{keyval}). -% String options are processed in separate macros -% defined in the corresponding sections of each. -% These process macros will be executed when package is loaded -% (at end of package because |\exs@process...| aren't recognized at the beginning), -% or at begin document for options whose -% effect cannot be changed dynamically -% and must be set in the preamble -% (they will be processed once). -% -% A special case is \texttt{setlist} when used with \textsf{babel-french}. -% It will then be processed immediately and disabled (see below for explanations). +% Options are established using the \textsf{kvoptions} package (build on \textsf{keyval}). +% String options are managed through distinct macros +% that are defined in their respective sections. +% For options whose effects cannot be dynamically altered +% and must be configured in the preamble, they are processed once +% upon the start of the document. +% The other options are executed upon package loading +% (at the end of the package, as |\exs@process...| +% commands are not recognized at the outset). +% +% A distinct case emerges with \texttt{setlist} when utilized in conjunction with +% \textsf{babel-french}. +% In this instance, it is processed immediately and subsequently disabled +% (further clarification follows below). % % \begin{macrocode} %<*package> @@ -1187,7 +1251,7 @@ \newif\ifexesheet@multicol \@ifpackageloaded{multicol}{ \exesheet@multicoltrue}{\exesheet@multicolfalse} - % to set the rule to the right color in answers environments + % configuring the rule color within answers environments \exs@process@setlist \exs@process@marginpos \exs@process@marginwidth @@ -1202,23 +1266,26 @@ % \end{macrocode} % \begin{macro}{\exesheetset} -% The macro |\exesheetset| can receive keyval options. -% It can be used anywhere in the document to modify some settings, -% but has no effect on non dynamic options if called outside the preamble; -% thanks to |\DisableKeyValOption| a warning message occur in that case. +% The |\exesheetset| macro can accept key-val options and +% can be utilized anywhere in the document to adjust certain settings. +% However, it won't affect non dynamic options if called outside the preamble. +% In such cases a warning message occur due to the use of |\DisableKeyValOption|. % \begin{macrocode} \def\exesheetset#1{\setkeys{exesheet}{#1}\exs@process@dynoptions} % \end{macrocode} % \end{macro} -% Now we load several packages. -% The \texttt{shortlabel} option in the \textsf{enumitem} package allows to use labels like in -% the \textsf{enumerate} package \eg 1., a), A. etc. +% Now, we load several packages. +% If the \textsf{geometry} package is already loaded, it will not be reloaded +% to prevent an option clash. +% The \texttt{shortlabel} option in the \textsf{enumitem} package allows the use +% of labels similar to +% the \textsf{enumerate} package such as 1., a), A., and so on. % The \textsf{mparhack} package (by Tom Sgouros and Stefan Ulrich) -% is loaded only for two side mode documents. +% is loaded exclusively for documents in \texttt{twoside} mode. % \begin{macrocode} \RequirePackage{ifthen} -\RequirePackage{geometry} +\@ifpackageloaded{geometry}{}{\RequirePackage{geometry}} \RequirePackage{xcolor} \RequirePackage[shortlabels]{enumitem} \RequirePackage{tasks} @@ -1231,14 +1298,14 @@ % \end{macrocode} % % \subsection{Internationalization} -% Here we define keywords and their translation in French, German, Spanish -% Italian, Portuguese, thanks to macros of the \textsf{translations} package -% by Clemens Niederberger. It detects the used language -% loaded by \textsf{babel} or \textsf{polyglossia}. +% Here we define keywords along with their translations in French, German, Spanish +% Italian, Portuguese. We achieve this using macros from the \textsf{translations} package +% by Clemens Niederberger. This package automatically detects the language being used, +% as loaded by \textsf{babel} or \textsf{polyglossia}. % -% Accented characters cannot be used here because they are not recognized +% Accented characters cannot be utilized here, as they might not be recognized % if \textsf{inputenc} is loaded after \textsf{exesheet}. -% So we have used basic \LaTeX\ control sequences to produce them. +% As a workaround, we rely on basic \LaTeX{} control sequences to generate them. % % \begin{macrocode} \DeclareTranslationFallback{exesheet-exercise}{Exercise} @@ -1297,7 +1364,7 @@ \DeclareTranslation{Italian}{exesheet-ex}{Es} \DeclareTranslation{Italian}{exesheet-points}{punti} \DeclareTranslation{Italian}{exesheet-point}{punto} -\DeclareTranslation{Italian}{exesheet-correction}{correzione} +\DeclareTranslation{Italian}{exesheet-correction}{Correzione} \DeclareTranslation{Italian}{exesheet-pts}{pti} \DeclareTranslation{Italian}{exesheet-pt}{pt} @@ -1325,26 +1392,27 @@ % % \subsection{Titles} % -% The \texttt{exercise} counter numbers exercises for the whole document -% regardless of any section. -% To reset the counter at some point, just write |\setcounter{exercise}{0}| -% and for an automatic reset at each section, -% add in the preamble \\ +% The \texttt{exercise} counter assigns numbers to exercises throughout the entire document, +% regardless of sections. +% To reset the counter manually, simply use |\setcounter{exercise}{0}|. +% For an automatic reset at each new section, +% include the following code in the preamble \\ % |\makeatletter \@addtoreset{exercise}{section} \makeatother|. % -% The parts counter depends on \texttt{exercise} and is reset -% at each new exercise. +% The parts counter depends on the \texttt{exercise} counter and is reset +% with each new exercise. % -% Commands |\labelexercisestyle| and |\labelsubpartstyle| -% are empty, but allow to personalize the style, for instance:\\ +% The commands |\labelexercisestyle| and |\labelsubpartstyle| +% are initially empty, but they allow you to customize the styling. For example:\\ % |\renewcommand\labelexercisestyle{\sffamily}|. % -% The |\exe@check| macro checks the marking scheme, it will be defined +% The |\exe@check| macro, responsible for verifying the marking scheme, will be defined % in section \ref{MSoptions}. -% By default, the table of contents displays the titles of exercises and parts, -% |\ifexesheet@exetoc| is \texttt{true}. -% To display in it only exercise titles but not parts, -% place in the preamble |\setcounter{tocdepth}{2}|. +% +% By default, the table of contents includes both exercises and parts titles, +% as controlled by the boolean |\ifexesheet@exetoc|. +% To only display exercise titles in the table of contents while omitting parts, +% include the following code in the preamble: |\setcounter{tocdepth}{2}|. % % \begin{macro}{\exercise} % \begin{macrocode} @@ -1354,7 +1422,7 @@ \newcommand{\labelexercisestyle}{} \newcommand*{\@exercise}[1][]{% \ifexesheet@checkpts \exe@check{\labelexercise} \fi - % curiously the \execheck must be done before \refstepcounter ! + % curiously, the \execheck must be performed before \refstepcounter ! \refstepcounter{exercise} \subsection*{\labelexercisestyle\labelexercise\enskip #1} \ifexesheet@exetoc @@ -1425,9 +1493,9 @@ % \subsection{Enumerations and lists} % % \begin{macro}{\exenumerate} -% The |\setlist| command comes from the \textsf{enumitem} package -% (|\setenumerate| is obsolete). By default |itemsep=1ex| for lists of first level, -% and |leftmargin=1.5em| allows to align labels on the start of lines. +% The |\setlist| command is part of the \textsf{enumitem} package +% (|\setenumerate| is deprecated). By default, |itemsep=1ex| is set for first-level lists, +% and |leftmargin=1.5em| is used to align labels with the start of lines. % \begin{macrocode} \newenvironment{exenumerate}[1][]{% \setlist[enumerate]{font=\bfseries} @@ -1440,13 +1508,13 @@ % \end{macrocode} % \end{macro} -% When using \textsf{babel} with the option \texttt{french}, -% \texttt{itemize} lists are modified with the same dash label for each list level. -% These modifications are canceled here to restore default -% \LaTeX\ \texttt{itemize} lists (labels and spaces). -% We have create the |\standardfrenchlists| command which must be called into -% |AtBeginDocument| or not, depending on whether -% \textsf{exesheet} is loaded before \textsf{babel} or after. +% When using the \textsf{babel} package with the \texttt{french} option, +% \texttt{itemize} lists are altered to use the same dash label for each list level. +% These modifications are undone here to revert to the default +% \LaTeX\ \texttt{itemize} lists, including labels and spaces. +% We have created the |\standardfrenchlists| command, which should be invoked within the +% |AtBeginDocument| command, depending on whether +% \textsf{exesheet} is loaded before or after \textsf{babel}. % \begin{macrocode} \newcommand\standardfrenchlists{% \@ifpackagewith{babel}{french}{ @@ -1460,18 +1528,18 @@ \def\exs@process@setlist{% must be executed at begin document \ifexesheet@setlist - \standardfrenchlists % if exesheet is loaded before babel package + \standardfrenchlists % if exesheet is loaded before babel \setlist[enumerate]{font=\bfseries} \setlist[enumerate,1]{topsep=1.5ex plus 1ex minus 1ex,leftmargin=1.5em} \fi % \end{macrocode} % \DescribeEnv{tablenum1} \DescribeEnv{tablenuma} -% The |\NewTasks| command comes from the \textsf{tasks} package. -% It allows to define environments \texttt{tablenum1}, \texttt{tablenuma} -% and \texttt{tablitem}. -% Horizontal spaces are adjusted to get good alignments with -% items of other \texttt{enumerate} (or \texttt{itemize}) environments. +% The |\NewTasks| command is part of the \textsf{tasks} package. +% It enables the definition of the environments \texttt{tablenum1}, +% \texttt{tablenuma} and \texttt{tablitem}. +% Horizontal spacing is adjusted to ensure proper alignment with +% items in other \texttt{enumerate} (or \texttt{itemize}) environments. % \begin{macrocode} \ifexesheet@setlist \NewTasksEnvironment[label=\arabic*.,label-format=\bfseries, @@ -1502,6 +1570,22 @@ after-item-skip=0.5ex plus 0.5ex minus 0.5ex]{tablitem}[\item](2) % \end{macrocode} +% \DescribeEnv{tablenuma*} \DescribeEnv{tablitem*} +% The starred environments \texttt{tablenuma*} and \texttt{tablitem*} +% are designed to be employed within an \texttt{enumerate} environment, +% precisely at the outset of an |\item|, in order to achieve correct horizontal +% alignment. +% The length of |-1.667\baselineskip| has been tested with various font families and sizes. +% It functions properly. +% \begin{macrocode} +\newenvironment{tablenuma*}{% + \mbox{}\vspace{-1.667\baselineskip}\begin{tablenuma}}{ + \end{tablenuma}} +\newenvironment{tablitem*}{% + \mbox{}\vspace{-1.667\baselineskip}\begin{tablitem}}{ + \end{tablitem}} + +% \end{macrocode} % \DescribeEnv{colsenum} % \begin{macrocode} \newenvironment{colsenum}[2][]{% @@ -1556,9 +1640,9 @@ % \subsection{Questions and answers} % % \begin{macro}{\exs@process@output} -% |exesheet@questions| and |exesheet@answers| booleans -% control the display of corresponding environments. -% They are set by the \texttt{output} key option in the +% The booleans |exesheet@questions| and |exesheet@answers| +% governs the visibility of their corresponding environments. +% These booleans are configured through the \texttt{output} key option within the % |\exs@process@output| macro. % \begin{macrocode} \newboolean{exesheet@questions}\setboolean{exesheet@questions}{true} @@ -1578,7 +1662,7 @@ \setboolean{exesheet@answers}{true} }{% else \PackageWarning{exesheet}{Value `\exesheet@output' - is not supported by option `output'} + is not supported by `output' option} }}} } @@ -1586,22 +1670,22 @@ % \end{macro} % % \begin{environment}{questions} -% We use the \textsf{versions} package by Uwe Lück -% who provides |\comment| and |\endcomment| macros, -% that allow the magic of conditional displays (we can also find them -% in \textsf{verbatim} or \textsf{version} packages). -% The noteworthy \textsf{codesection} package, allows to encapsulate -% optional code between the macros |\BeginCodeSection|\marg{skip} -% and |\EndCodeSection|\marg{skip}, -% both in the text body and in the preamble, -% but these macros cannot be used inside an environment -% as we did here for |\comment| and |\endcomment|. -% -% Some tests are made by |\ifthenelse{\bolean{...}}| -% because |\comment| and |\endcomment| causes some hassle +% We utilize the \textsf{versions} package developed by Uwe Lück, +% which introduces the macros |\comment| and |\endcomment|. +% These macros facilitate conditional displays, a technique also employed +% in the \textsf{verbatim} and \textsf{version} packages. +% Additionally, the notable \textsf{codesection} package offers the capability +% to enclose optional code between |\BeginCodeSection|\marg{skip} +% and |\EndCodeSection|\marg{skip} macros, +% both in the text body and the preamble. +% However, these macros cannot be used within an environment +% as we've done here with |\comment| and |\endcomment|. +% Several of our tests use the \LaTeX{} syntax |\ifthenelse{\bolean{...}}| +% since |\comment| and |\endcomment| can sometimes interfere % with the \TeX\ structure |\if| \ldots |\else| \ldots |\fi|. -% The two counters |exe@ini| and |subpart@ini| are used in -% the following |\set@toclevel| macro. +% +% The two counters |exe@ini| and |subpart@ini| are employed in +% the subsequent |\set@toclevel| macro. % \begin{macrocode} \newcounter{exe@ini} \newcounter{subpart@ini} @@ -1617,13 +1701,14 @@ % \end{environment} % \begin{environment}{answers} % The internal macro |\set@toclevel| calculates the title level (counter |toc@level|) -% to get a correct typesetting of the word ``\correctionname'' at the start of an -% \texttt{answers} environment (when \texttt{questions} and \texttt{answers} are -% displayed together). The principle is to compare the state of counters -% \texttt{exercise} and \texttt{subpart} with those saved at the time of -% the call of the \texttt{questions} environment. The |\@enumdepth| counter indicates the -% \texttt{enumerate} list level in which we are (0 = out of lists). -% The optional parameter of the \texttt{answers} environment allows to force this title level. +% to ensure correct typesetting of ``\correctionname'' at the start of an +% \texttt{answers} environment, when \texttt{questions} and \texttt{answers} are +% displayed together. It involves comparing the \texttt{exercise} and \texttt{subpart} +% counters with their values at the time of the \texttt{questions} environment call. +% The |\@enumdepth| counter indicates the +% current \texttt{enumerate} list level (with 0 indicating outside of any list). +% The optional parameter of the \texttt{answers} environment permits +% the explicit specification of this title level. % \begin{macrocode} \newcounter{@toclevel} \newcommand{\set@toclevel}[1][]{ @@ -1642,7 +1727,7 @@ % \end{macrocode} % The internal macro |\typeset@correctionname|, -% typesets the word ``\correctionname'' at the right level. +% displays the term ``\correctionname'' at the appropriate level. % \begin{macrocode} \definecolor{correctioncolor}{rgb}{0,0.2,0.6} % kind of dark blue \newcommand{\correctionstyle}{\color{correctioncolor}} @@ -1673,7 +1758,7 @@ } % \end{macrocode} -% Then we can write the \texttt{answers} environment. +% Then we proceed to define the \texttt{answers} environment. % \begin{macrocode} \newenvironment{answers}[1][]{% #1 is the optional level \ifthenelse{\boolean{exesheet@answers}}{% @@ -1694,8 +1779,8 @@ % \end{macrocode} % In the \texttt{answers} environment, when placing |\correctionstyle| -% before |\subsubsection| (case of |\typeset@correctionname|), -% the preceding vertical space may be too wide. +% before |\subsubsection| (as in the case of |\typeset@correctionname|), +% the preceding vertical space may become too wide. % \end{environment} % % \begin{macro}{\question} @@ -1715,8 +1800,8 @@ % \end{macrocode} % \end{macro} % \begin{macro}{\answerspace} -% The \texttt{answerspace} macro was a suggestion of Maxime Chupin -% to permit students to write answers on the given paper. +% The |\answerspace| macro was suggested by Maxime Chupin +% to allow students space for writing their answers on the provided paper. % \begin{macrocode} \newcommand\answerspace[1]{ \ifexesheet@answerspace \par\vspace{#1} \fi} @@ -1726,15 +1811,15 @@ % % \subsection{Marking scheme options processing} \label{MSoptions} % -% Options \texttt{display}, \texttt{marginpos}, \texttt{marginwidth} -% and \texttt{noteragged} are processed with the following internal commands. +% The options \texttt{display}, \texttt{marginpos}, \texttt{marginwidth} +% and \texttt{noteragged} are handled using the following internal commands. % % \medskip -% The \texttt{display} key option sets the value of the two booleans +% The \texttt{display} key option determines the value of the two booleans % |exesheet@pts| and |exesheet@notes|. -% |exesheet@pts| controls the display of the content of |\pts| and of optional arguments -% of |\note|, -% whereas |exesheet@notes| controls mandatory arguments of |\note|. +% The |exesheet@pts| boolean controls the display of the content of |\pts| +% and optional arguments of |\note|, +% while the |exesheet@notes| boolean controls mandatory arguments of |\note|. % % \begin{macro}{\exs@process@display} % \begin{macrocode} @@ -1755,28 +1840,28 @@ \setboolean{exesheet@notes}{false} }{% else \PackageWarning{exesheet}{Value `\exesheet@display' - is not supported by option `display'} + is not supported by `display' option} }}} } % \end{macrocode} % \end{macro} % \begin{macro}{\exs@process@marginpos} -% The \texttt{marginpos} key option takes value \texttt{left} (the default) or \texttt{right} -% (or \texttt{inner} and \texttt{outer}). In practice \texttt{inner} is equivalent to -% \texttt{left} -% but, in two side mode, \texttt{left} (the default value) or \texttt{right} -% are converted to \texttt{outer} (the default value for two side mode). +% The \texttt{marginpos} key option takes the values \texttt{left} (the default value) +% or \texttt{right} (or \texttt{inner} and \texttt{outer}). +% In practice, \texttt{inner} is equivalent to \texttt{left}, +% but in two-sided mode, the values \texttt{left} or \texttt{right} +% are converted to \texttt{outer} (which is then the default value for two-sided mode). % \begin{macrocode} \newboolean{exesheet@leftmargin} \def\exs@process@marginpos{ \ifthenelse{\equal{\exesheet@marginpos}{left}}{ \if@twoside% - \PackageWarningNoLine{exesheet}{Default `marginpos' option + \PackageWarningNoLine{exesheet}{The default `marginpos' option \MessageBreak - for two side documents is `outer'.\MessageBreak - Use `inner' to change the side} + for two-sided documents is `outer'.\MessageBreak + To change the side, use `inner'} \def\exesheet@marginpos{outer} \setboolean{exesheet@leftmargin}{false} \normalmarginpar @@ -1787,10 +1872,10 @@ }{% else if \ifthenelse{\equal{\exesheet@marginpos}{right}}{ \if@twoside% - \PackageWarningNoLine{exesheet}{Default `marginpos' option + \PackageWarningNoLine{exesheet}{The default `marginpos' option \MessageBreak - for two side documents is `outer'.\MessageBreak - Use `inner' to change the side} + for two-sided documents is `outer'.\MessageBreak + To change the side, use `inner'} \def\exesheet@marginpos{outer} \fi \setboolean{exesheet@leftmargin}{false} @@ -1804,26 +1889,25 @@ \setboolean{exesheet@leftmargin}{false} \normalmarginpar }{% else - \PackageWarningNoLine{exesheet}{Value `\exesheet@marginpos' - is not supported by option `marginpos'} + \PackageWarningNoLine{exesheet}{The value `\exesheet@marginpos' + is not supported by the `marginpos' option} }}}} } % \end{macrocode} % \end{macro} % \begin{macro}{\exs@process@marginwidth} -% The \texttt{marginwidth} option changes the ratio between left and right margins -% depending on what has to be displayed in the margin (only points or full -% notes) -% \footnote{So that the effect on the margin ratio is correct, this option is processed -% at begin document, after other commands -% that also could alter page geometry.}. -% -% When \texttt{display=notes}, the additional length \texttt{1\,in} matches +% The \texttt{marginwidth} option adjusts the ratio between left and right margins +% based on what needs to be displayed in the margin (points only or full notes) +% \footnote{To ensure the accurate effect on the margin ratio, this option is processed +% at beginning of the document, after other commands +% that could potentially alter the page geometry.}. +% +% When \texttt{display=notes}, the additional length of \texttt{1\,in} corresponds to % the default free space to the left of |\oddsidemargin|. % % The macros |\standardmarginwidthfactor| and |\largemarginwidthfactor| -% represent the ratio between total margin width and |\marginparwidth|. +% represent the ratios between the total margin width and |\marginparwidth|. % % \begin{macrocode} \def\standardmarginwidthfactor{0.6} @@ -1847,7 +1931,7 @@ \def\exesheet@smallmargins{ \geometry{hmarginratio=1:1} - \leftnotemarginwidth{\standardmarginwidthfactor} % right gives the same + \leftnotemarginwidth{\standardmarginwidthfactor} } \def\exesheet@standardmargins{ \ifexesheet@leftmargin @@ -1876,7 +1960,7 @@ \else \exesheet@smallmargins \fi - }{% else display=pts or notes + }{% else display=pts or display=notes \exesheet@standardmargins } }{% else if @@ -1897,33 +1981,34 @@ \ifthenelse{\equal{\exesheet@marginwidth}{unset}}{ % do nothing }{% else - \PackageWarningNoLine{exesheet}{Value `\exesheet@marginwidth' - is not supported by option `marginwidth'} + \PackageWarningNoLine{exesheet}{The value `\exesheet@marginwidth' + is not supported by the `marginwidth' option} }}} } % \end{macrocode} % \end{macro} -% For a two side mode document, the package \textsf{geometry} doesn't set the margin -% paragraph width correctly by default, it's too large. So we made here an explicit setting -% useful in the case of \texttt{marginwidth=unset}. Otherwise, the setting is -% made by the \texttt{marginwidth} key option. +% For a two-sided document, the \textsf{geometry} package doe not correctly set +% the width of the margin paragraph by default; it's too wide. +% Therefore we provide an explicit setting here, which is +% useful when \texttt{marginwidth=unset}. Otherwise, the setting is +% handled by the \texttt{marginwidth} key option. % % \begin{macrocode} \if@twoside \rightnotemarginwidth{0.5} \fi % \end{macrocode} % \begin{macro}{\exs@process@noteragged} -% The noteragged option takes one of the following values: +% The noteragged option can take one of the following values: % \texttt{left}, \texttt{right}, \texttt{center}, \texttt{justify} or \texttt{twoside}. -% -% |\marginpar| with optional parameter makes the job for a two side document. -% We then use |\noteraggedleft| and |\noteraggedright| instead of |\noteragged|. -% % Commands |\RaggedLeft|, |\RaggedRight|, |\Centering| and |\justifying| -% come from the \textsf{ragged2e} package by Martin Schröder. -% They give better results as standard commands -% |\raggedleft|, |\raggedright| (or |\centering|). -% The default \LaTeX\ setting for marginal notes is justifying. +% When working with a two-sided document, |\marginpar| can be used with an optional parameter +% to distinguish left from right contents. +% In this context, we employ |\noteraggedleft| and |\noteraggedright| instead of |\noteragged|. +% The \textsf{ragged2e} package by Martin Schröder offers the commands +% |\RaggedLeft|, |\RaggedRight|, |\Centering|, and |\justifying|. +% These commands yield better results compared to the standard +% |\raggedleft|, |\raggedright| and |\centering| commands. +% Margin paragraphs are justified by default in \LaTeX. % \begin{macrocode} \newcommand{\noteragged}{} \newcommand{\noteraggedleft}{} @@ -1966,11 +2051,11 @@ \renewcommand{\noteraggedright}{\RaggedRight} \else \PackageWarning{exesheet}{Invalid option `noteragged=twoside' - when the document \MessageBreak is not in two side mode} + when the document \MessageBreak is not in two-side mode} \fi }{% else - \PackageWarning{exesheet}{Value `\exesheet@noteragged' - is not supported by option `noteragged'} + \PackageWarning{exesheet}{The value `\exesheet@noteragged' + is not supported by the `noteragged' option} }}}}} } @@ -1978,20 +2063,19 @@ % \end{macro} % % \begin{macro}{\exs@process@checkpts} -% The scale control option is based on length calculus. -% By default these calculus are local but we need to make them global, -% therefore the two first macros |\gsetlength| and |\gaddtolength|. -% In them we must avoid to produce a too large space at the place -% where |\marginpar| is called, therefore all \% symbols at end of lines. -% -% For each question, points assigned will be added in |\sum@pts| -% and, for each exercise, points are accumulated in |\sum@exe|. -% These lengths are compared to |\exe@total| and |\sheet@total|. -% |\exe@check| is called at the beginning of each exercise -% (when macro |\points|, |\totalexe| or |\totalpoints| is called) -% to check the previous one, -% and also in the |\exs@process@checkpts| at end of document -% to check the last exercise. +% The scale control option relies on calculations with \emph{lengths}, +% which need to have a \emph{global} scope. +% To achieve this, we employ the macros |\gsetlength| and |\gaddtolength|. +% These macros include \% symbols at the end of lines to avoid expanded blank +% spaces. +% +% For questions, assigned points will be added in |\sum@pts|, +% while for exercises, points accumulate in |\sum@exe|. +% These lengths are compared against |\exe@total| and |\sheet@total|. +% The |\exe@check| macro validates the calculations of the previous exercise +% when triggered by |\points|, |\totalexe| or |\totalpoints| macros. +% It is also invoked within |\exs@process@checkpts| at the document's end +% for a final check on the last exercise. % \begin{macrocode} \newlength{\sheet@total} \newlength{\sum@exe} @@ -2001,14 +2085,14 @@ \newboolean{scale@valid} \setboolean{scale@valid}{true} -\gdef\gsetlength#1#2{% to get global length values +\gdef\gsetlength#1#2{% for obtaining global length values \begingroup \setlength\skip@{#2}% local assignment to a scratch register \global#1=\skip@% global assignment to #1 - \endgroup % \skip@ is restored by end of group + \endgroup % \skip@ is restored at the end of the group } -\gdef\gaddtolength#1#2{% percent symbol necessary here ! +\gdef\gaddtolength#1#2{% percent symbol necessary here! \begingroup \setlength\skip@{#1}% \addtolength\skip@{#2}% @@ -2022,26 +2106,26 @@ }{ \ifthenelse{\lengthtest{\exe@total = \sum@pts}}{ \PackageWarningNoLine{exesheet}{\exe@label: - scale \the\exe@total\space is valid} + The scale of \the\exe@total\space is valid} }{ \PackageWarningNoLine{exesheet}{\exe@label: - sum of points is + Sum of points is \the\sum@pts\space instead of \the\exe@total} \setboolean{scale@valid}{false} } \gsetlength{\sum@pts}{0pt} } - \def\exe@label{#1} % for the next exercise + \def\exe@label{#1} % for the upcoming exercise } \def\exs@process@checkpts{ \ifexesheet@checkpts \ifthenelse{\lengthtest{\sheet@total = 0pt}}{ - \PackageWarningNoLine{exesheet}{Option checkpts is true; + \PackageWarningNoLine{exesheet}{Option checkpts is true, \MessageBreak - but you didn't use \string\totalsheet\space + but \string\totalsheet\space is missing in the preamble. \MessageBreak - See the documentation for more information} + See documentation} }{} \gsetlength{\sum@exe}{0pt} \gsetlength{\exe@total}{0pt} @@ -2072,8 +2156,8 @@ \ifthenelse{\boolean{scale@valid}}{ \PackageWarningNoLine{exesheet}{Scale is valid} }{ - \PackageWarningNoLine{exesheet}{Scale is NOT valid ! - See above} + \PackageWarningNoLine{exesheet}{INVALID SCALE! + Refer to above} } } \fi @@ -2098,9 +2182,9 @@ \ifthenelse{\boolean{exesheet@questions}}{\exesheet@points{#1}}{}} % \end{macrocode} -% Percent symbols are necessary to avoid spaces between the -% |\fbox| and its inner text. -% Without |\lengthtest|, the test |#1 < 2| doesn't work with decimal numbers +% To prevent spaces between the |\fbox| and its inner text, +% percent symbols are necessary. +% The test |#1 < 2| doesn't work with decimal numbers without |\lengthtest|, % but it works with lengths. % \end{macro} % \DescribeMacro{\pts} @@ -2124,15 +2208,15 @@ % \end{macrocode} % % \begin{macro}{\totalexe} -% In the following macros using -% |\marginpar|, percent symbols and |\ignorespaces| are necessary -% to avoid an enlarged blank space in the text (or the margin) -% where these macros are inserted. +% In the subsequent macros that utilize +% |\marginpar|, the presence of percent symbols and |\ignorespaces| is essential +% to prevent the occurrence of expanded blank spaces in the text (or the margin), +% where these macros are incorporated. % \begin{macrocode} \definecolor{markingcolor}{named}{red} \newcommand{\markingstyle}[1]{\footnotesize\sffamily% \centering\color{markingcolor}\textbf{#1}} - % inner arguments allow boxed styles + % inner arguments enable the implementation of boxed styles \newlength{\ptsboxlength} \setlength{\ptsboxlength}{3.1em} \cornersize{1} @@ -2161,16 +2245,16 @@ % \end{macro} % % \begin{macro}{\note} -% Boolean \texttt{exesheet@pts} and \texttt{exesheet@notes} control -% the display of marginal notes. If \texttt{exesheet@pts} is \texttt{false}, +% The booleans \texttt{exesheet@pts} and \texttt{exesheet@notes} control +% the display of marginal notes. If \texttt{exesheet@pts} is set to \texttt{false}, % \DescribeMacro{\note*} % \texttt{exesheet@notes} will be ignored. -% |\noindent| is necessary when using |\justifying| from the \textsf{ragged2e} +% |\noindent| is required when using |\justifying| from the \textsf{ragged2e} % package. -% Inside the |\note@marginpar| macro, double braces around |\markingstyle| -% avoid some unattended style in the mandatory argument of |\note|. -% A vicious error occur when using |\if| \ldots |\fi| structure inside -% the |\note@marginpar| macro instead of |\ifthenelse| +% Within the |\note@marginpar| macro, enclosing |\markingstyle| in double braces +% helps prevent unintended formatting within the mandatory argument of |\note|. +% A vicious error occurs when using an |\if| \ldots |\fi| structure +% instead of |\ifthenelse| inside |\note@marginpar| % (but only if |@twoside| is \texttt{true}). % \begin{macrocode} \definecolor{notecolor}{rgb}{0.0, 0.4, 0.0} % kind of dark green @@ -2237,71 +2321,70 @@ \ifexesheet@answers \correct \fi }{}} }{ - \PackageWarningNoLine{exesheet}{Package `schooldocs' must be loaded + \PackageWarningNoLine{exesheet}{The `correct' option requires \MessageBreak - to use the `correct' option} + the `schooldocs' package to be loaded} }} } % \end{macrocode} % \end{macro} % -% The following macros are maintained for now -% only for compatibility reasons. +% For the time being, the following macros are kept for compatibility reasons. % \begin{macrocode} \newcommand{\questionsonly}{ - \PackageWarning{exesheet}{Command \string\questionsonly\space - is deprecated, \MessageBreak - use `output=questions' as package option instead} + \PackageWarning{exesheet}{The command \string\questionsonly\space + is deprecated; \MessageBreak + use the package option `output=questions' instead} \renewcommand\exesheet@output{questions} \exs@process@output } \newcommand{\answersonly}{ - \PackageWarning{exesheet}{Command \string\answersonly\space - is deprecated, \MessageBreak - use `output=answers' as package option instead} + \PackageWarning{exesheet}{The command \string\answersonly\space + is deprecated; \MessageBreak + use the package option `output=answers' instead} \renewcommand\exesheet@output{answers} \exs@process@output } \newcommand{\displaypts}{% - \PackageWarning{exesheet}{Command \string\displaypts\space - is deprecated, \MessageBreak - use `display=pts' as package option instead} + \PackageWarning{exesheet}{The command \string\displaypts\space + is deprecated; \MessageBreak + use the package option `display=pts' instead} \renewcommand\exesheet@display{pts} \exs@process@display } \newcommand{\displaypoints}{% - \PackageWarning{exesheet}{Command \string\displaypoints\space - is deprecated, \MessageBreak - use `display=pts' as package option instead} + \PackageWarning{exesheet}{The command \string\displaypoints\space + is deprecated; \MessageBreak + use the package option `display=pts' instead} \renewcommand\exesheet@display{pts} \exs@process@display } \newcommand*{\displaynotes}[1][\RaggedLeft]{% % \renewcommand{\noteragged}{#1} no effect now! - \PackageWarning{exesheet}{Command \string\displaynotes\space - is deprecated, \MessageBreak - use `display=notes' as package option instead} + \PackageWarning{exesheet}{The command \string\displaynotes\space + is deprecated; \MessageBreak + use the package option `display=notes' instead} \renewcommand\exesheet@display{notes} \exs@process@display \renewcommand{\noteragged}{#1} } \newcommand*{\displaynotesright}[1][\RaggedRight]{% % \renewcommand{\noteragged}{#1} no effect now! - \PackageWarning{exesheet}{Command \string\displaynotes\space - is deprecated, \MessageBreak - use `display=notes, margin=right' as package options instead} + \PackageWarning{exesheet}{The command \string\displaynotes\space + is deprecated; \MessageBreak + use the package options `display=notes, margin=right' instead} \renewcommand\exesheet@display{notes} \exs@process@display \renewcommand\exesheet@margin{right} \renewcommand{\noteragged}{#1} } -\PackageInfo{exesheet}{Environment `tablenum' is deprecated \MessageBreak - and replaced by `tablenum1'. \MessageBreak - Options `notoc' and `nosetlist' \MessageBreak - are no longer supported\@gobble} - % gobble allow to suppress line number +\PackageInfo{exesheet}{The environment `tablenum' is deprecated + \MessageBreak and has been replaced by `tablenum1'. + \MessageBreak The options `notoc' and `nosetlist' + \MessageBreak are no longer supported\@gobble} + % \@gobble suppresses the line number here %</package> % \end{macrocode} % |