exesheet (29oct23)

git-svn-id: svn://tug.org/texlive/trunk@68692 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 80 insertions, 70 deletions

diff --git a/Master/texmf-dist/source/latex/exesheet/exesheet.dtx b/Master/texmf-dist/source/latex/exesheet/exesheet.dtx
index 443bef29918..7f57f4195e5 100644
--- a/Master/texmf-dist/source/latex/exesheet/exesheet.dtx
+++ b/Master/texmf-dist/source/latex/exesheet/exesheet.dtx
@@ -23,7 +23,7 @@
 %<class>\ProvidesClass{exesheet}
 %<package>\ProvidesPackage{exesheet}
 %<*class|package>
-[2023/10/25 v2.3 .dtx exesheet file]
+[2023/10/28 v2.4 .dtx exesheet file]
 %</class|package>
 %<*driver>
 \documentclass{ltxdoc}
@@ -152,13 +152,20 @@
 % \changes{v2.3}{2023/10/24}{
 %    - new implementation of marking scheme checking:
 %        checking is done in points or totalpoints instead of exercise command,
-%    - correct ref macro for tablenuma using ref implementation in tasks, 
+%    - correct ref macro for tablenuma using ref option in tasks, 
 %        available since 2020/08/19
 %    - new commands question* and answer* for executing code when 
 %        questions are displayed but not answers, or the contrary
 %    - using basic languages (with lower case first letter) instead of aliases
 %        in translations commands}
 %
+% \changes{v2.4}{2013/10/28}{
+%    - a small mistake in the documentation about the example of the tablenuma environment
+%        is now corrected
+%    - other small changes in the documentation
+%    - lack of percent symbols at end of lines in the exe@check macro causes an unwanted
+%        space in points macro}
+%
 % \GetFileInfo{exesheet.dtx}
 %
 % \maketitle
@@ -197,8 +204,8 @@
 % 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,
-% with optional explanations or remarks, 
+% Finally \textsf{exesheet} enables to display a detailed marking scheme 
+% in the margin, with optional explanations or remarks, 
 % and offering consistency control.
 %
 % Many settings can be customized, and various options are available 
@@ -251,7 +258,7 @@
 % \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|.
+% You can alter it by modifying |\exercisename|.
 % 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}}|.
@@ -304,7 +311,7 @@
 % \bigskip
 %
 % \pagebreak
-% The following macros manage formatting in the same manner as for |\exercise|.
+% The following macros allow customization in the same manner as for |\exercise|.
 %
 % \medskip
 % \DescribeMacro{\thesubpart}
@@ -350,11 +357,11 @@
 % which is defined as follows: |\newcommand\annexstyle{\MakeUppercase}|.
 % This command may be redefined according to your preferences.
 %
-% \subsection{Exercise titles in the table of contents} \label{toc}
+% \subsection{Titles in the table of contents} \label{toc}
 % \DescribeMacro{[exetoc=\meta{bool}]}
 % By default, the titles \textbf{\exercisename}, \textbf{\subpartname} 
-% 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). 
+% 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.
@@ -378,9 +385,9 @@
 % The abbreviation \textbf{\exname} can be modified by
 % redefining |\exname| or with macros from the \textsf{translations} package.
 % The |\exlabel| macro combines |\exname| with a period then the exercise number
-% (given by the \texttt{exercise} counter),
+% (given by the same \texttt{exercise} counter),
 % while |\exsepmark| typesets a long dash.
-% You can alter these characteristics by redefining these commands.
+% These characteristics can be altered by redefining these commands.
 %
 % \medskip
 % \DescribeMacro{\exe*}
@@ -427,25 +434,25 @@
 % \eg \texttt{\bs begin\{enumerate\}[A.]},
 % or globally through the redefinition of \texttt{\bs labelenumi} 
 % or \texttt{\bs labelenumii} commands.}.
-% You can change global label font formatting using the syntax 
+% Label font formatting can be changed globally using
 % |\setlist[enumerate]{font=...}|
 % (called \emph{after} |\begin{document}|).
 %
 % Lists created with the \texttt{itemize} environment retain their default 
 % configuration
 % \footnote{However, the \texttt{french} option of the \textsf{babel} package
-% changes the behavior of \texttt{itemize} lists and employs long dashes
+% changes the appearance of \texttt{itemize} lists and employs long dashes
 % as labels for each list level.
-% This behavior can cause issues when mathematical content follows the dash
+% This can cause issues when mathematical content follows the dash
 % symbol, as it might be mistaken for the minus sign.
 % Thus, with the option \texttt{setlist=true}, the default \LaTeX{}
 % \texttt{itemize} list style is 
-% reinstated. The \texttt{\bs frenchsetup} command (from the
-% \textsf{babel-french} package) can achieve several other settings.}.
+% reinstated with \texttt{\bs frenchsetup\{StandardLists=true\}}.}.
+% ^^A The \texttt{\bs frenchsetup} command can also achieve other settings.}.
 %
 % \medskip
 % \DescribeMacro{[setlist=\meta{bool}]}
-% The package option |setlist=false|  prevents changes to enumeration and itemize lists 
+% The package option |setlist=false|  prevents changes to enumeration lists 
 % and reverts to the default \LaTeX{} settings 
 % (the default value is \texttt{true}).
 %
@@ -521,14 +528,15 @@
 % \item $\ds l(x) = \int_{\frac{1}{x}}^{x}\frac{1}{\ln t}\, \mathrm{d}t$.
 % \end{tablenum1}
 %
-% ^^A \smallskip
+% \smallskip
 % For \texttt{tablenuma}, labels are letters, a, b, c, \ldots, enclosed in parentheses. 
 %
 % \DescribeMacro{\labelenumone}\DescribeMacro{\labelenuma}
 % You can change the labels by redefining the macros |\labelenumone| 
 % (for \texttt{tablenum1}) and |\labelenuma| (for \texttt{tablenuma}), 
-% using the \texttt{task} counter,
-% \eg |\renewcommand\labelenuma{\Alph{task}.}| yields the labels \textbf{A.}, \textbf{B.}, \ldots
+% using the \texttt{task} counter:
+% \eg |\renewcommand\labelenuma{\Alph{task}.}| yields the labels 
+% \textbf{A.}, \textbf{B.}, \ldots
 %
 % \smallskip
 % If the \textsf{exesheet} package is invoked with the option \texttt{setlist=false},
@@ -544,18 +552,18 @@
 % 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}
-%
+% a vertical misplacement may occur.
+% ^^A as demonstrated in the following example:
+% ^^A \begin{enumerate}
+% ^^A \item 
+% ^^A \begin{tablenuma}(3) \item One \item Two \item Three \end{tablenuma}
+% ^^A \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,-0.9)
-% \psline[linewidth=0.1pt,linecolor=green,linestyle=dashed](0, -0.57)(10.5, -0.57)
+% \noindent\psframe(-0.25,0.05)(12.75,-0.97)
+% \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*}
@@ -568,8 +576,8 @@
 %
 % \subsection{Items aligned by column: \texttt{colsenum}, \texttt{colsitem}}
 % \DescribeEnv{colsenum}    
-% To achieve numbering of items by column, the
-% \texttt{colsenum} environment is available:
+% To achieve 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 parameter will be passed to the underlying \texttt{enumerate} environment,
@@ -591,18 +599,17 @@
 %
 % \medskip
 % \DescribeEnv{colsenum*}
-% We will observe that, on each line, items are not necessarily properly
+% It may be observed 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 vertical spacing between items.
-% If we desire this alignment
-% (which is the default behavior in \textsf{multicol}), we can use the
+% If you desire this alignment
+% (which is the default behavior in \textsf{multicol}), you can use the
 % \texttt{colsenum*} environment (with the same syntax as \texttt{colsenum}).
 % Here's what we obtain with \texttt{colsenum*}:
 %
-% \pagebreak
 % \exercise
-% \psframe(-0.25,1.3)(12.75,-2.65)
+% \psframe(-0.25,1.3)(12.75,-2.67)
 % Calculate the derivative of the following functions:
 % \begin{colsenum*}{3}
 % \item $\ds f(x) = \frac{1-x^2}{\mathrm{e}^x +\mathrm{e}^{-x}}$,
@@ -639,7 +646,8 @@
 % \label{output}
 %
 % \DescribeEnv{questions} \DescribeEnv{answers}
-% The package offers two environments, \texttt{questions} and \texttt{answers},
+% The \textsf{exesheet} package offers two environments, 
+% \texttt{questions} and \texttt{answers},
 % which allow you to optionally show or hide questions and answers within exercises.
 %
 % \bigskip
@@ -686,7 +694,7 @@
 % \end{questions}
 % \begin{answers}
 % \begin{enumerate}
-% \item Yes, the \textsf{exesheet} package is indeed useful for teachers.
+% \item The \textsf{exesheet} package is 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
@@ -800,8 +808,8 @@
 %
 % \section{Marking scheme commands} 
 %
-% The \textsf{exesheet} package enables the display of a detailed marking
-% scheme in the margins, along with optional comments and explanations about answers.
+% The \textsf{exesheet} package provides several commands to display a marking
+% scheme, with optional comments and explanations about answers in the margins.
 %
 % \subsection{The \texttt{\bs points} command}\label{points}
 % \DescribeMacro{\points}
@@ -818,11 +826,11 @@
 % Try to read this document to the end without drinking tea and you get five points.
 %
 % \bigskip
-% When only the correction is displayed in an exercise, the |\points| macro doesn't
+% When only the answers are displayed in an exercise, the |\points| macro doesn't
 % show the points.
-% Printing answers along with the point scale 
-% will be discussed
-% in section \ref{totalpoints}, which includes another |\totalpoints| macro.
+% Further, we provide another macro, which displays points
+% in \texttt{questions} like here, and differently in \texttt{answers} environments
+% (see section \ref{totalpoints}).
 %
 % \bigskip
 % \DescribeMacro{\pointsname} \DescribeMacro{\pointname}
@@ -1098,13 +1106,14 @@
 % \DescribeMacro{\totalpoints}
 % 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,
+% When the scale is not displayed,
+% it functions similarly to |\points| (visible in questions but not in answers),
+% and when the scale is shown,
 % it's akin to |\totalexe|.
 % For instance, in exercise \ref{totalexe}, we could have used |\totalpoints| 
-% instead of |\totalexe|. In this case,
-% when the detailed marking scheme is not displayed, the total points would be presented
-% similarly to exercise \ref{points} rather than being absent.
+% instead of |\totalexe|. Thus,
+% if the detailed marking scheme is not displayed, the total points would be presented
+% similarly to exercise \ref{points}.
 %
 % \subsection{Marking scheme consistency checking}\label{scale}
 %
@@ -1127,7 +1136,7 @@
 % Both comma notation (\eg 4,5) and decimal point format (\eg 4.5)
 % may be accepted, depending on your chosen language.
 % The control is made at the beginning of the subsequent exercise,
-% inside |\points|, |\totalexe| or |totalpoints| macros.
+% inside the |\points|, |\totalexe| or |\totalpoints| macros.
 % No deep checking will be processed at this level if no points are displayed
 % for the questions inside the exercise (with \texttt{display=none} option).
 %
@@ -1190,7 +1199,7 @@
 % 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,
-% at |\begin{document}|.
+% at the beginning of the document.
 % \hypertarget{correct}{}
 %
 % \bigskip
@@ -1271,7 +1280,7 @@
 %
 % A distinct case is to mention with \texttt{setlist} when utilized in conjunction with
 % \textsf{babel-french}.
-% In this instance, this option is processed immediately and subsequently disabled 
+% In this instance, this option is processed immediately
 % (further clarification follows below).
 % 
 %    \begin{macrocode}
@@ -1577,7 +1586,7 @@
 % 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
+% |\AtBeginDocument| command or immediately, depending on whether
 % \textsf{exesheet} is loaded before or after \textsf{babel}.
 %    \begin{macrocode}
 \newcommand\standardfrenchlists{%
@@ -1849,8 +1858,8 @@
 }{\ifthenelse{\boolean{exesheet@answers}}{}{\endcomment}}
 
 %    \end{macrocode}
-% In the \texttt{answers} environment, when placing |\correctionstyle|
-% before |\subsubsection| (as in the case of |\typeset@correctionname|),
+% When placing |\correctionstyle| before |\subsubsection|
+% in the \texttt{answers} environment (as in the case of |\typeset@correctionname|),
 % the preceding vertical space may become too wide.
 % \end{environment}
 %
@@ -2066,7 +2075,7 @@
 %    \end{macrocode}
 % \end{macro}
 % For a two-sided document, the \textsf{geometry} package does not correctly set 
-% the width of the margin paragraph by default; it's too wide. 
+% the default width of the margin paragraph; 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.
@@ -2151,7 +2160,8 @@
 % 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
+% Percent symbols at end of lines are necessary to prevent unwanted spaces.
+% |\exe@check| 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}
@@ -2176,23 +2186,23 @@
     \endgroup
 }
 
-\def\exe@check{ 
-    \ifthenelse{\lengthtest{\sum@pts = 0pt}}{
+\def\exe@check{%
+    \ifthenelse{\lengthtest{\sum@pts = 0pt}}{%
     % do not check, no points or first exercise begins
-    \ifthenelse{\equal{\exe@currentlabel}{none}}{}{
+    \ifthenelse{\equal{\exe@currentlabel}{none}}{}{%
         \PackageWarningNoLine{exesheet}{\exe@currentlabel: 
-            \the\exe@total}}
-    }{
-        \ifthenelse{\lengthtest{\exe@total = \sum@pts}}{
+            \the\exe@total}}%
+    }{%
+        \ifthenelse{\lengthtest{\exe@total = \sum@pts}}{%
             \PackageWarningNoLine{exesheet}{\exe@currentlabel:
-                Sum of points \the\exe@total\space is valid}
-        }{
+                Sum of points \the\exe@total\space is valid}%
+        }{%
         \PackageWarningNoLine{exesheet}{\exe@currentlabel:
             Sum of points is \the\sum@pts\space
-            instead of \the\exe@total}
-        \setboolean{scale@valid}{false}
-        }
-    } 
+            instead of \the\exe@total}%
+        \setboolean{scale@valid}{false}%
+        }%
+    }%
 }
 
 \def\exs@process@checkpts{
@@ -2276,8 +2286,8 @@
 \newcommand*{\points}[1]{%
     \ifthenelse{\boolean{exesheet@questions}}{\hfill
         \pointsstyle{#1~%
-            \ifthenelse{\lengthtest{#1pt < 2pt}}{\pointname}{\pointsname}}        
-        \check@points{#1}
+            \ifthenelse{\lengthtest{#1pt < 2pt}}{\pointname}{\pointsname}}%      
+        \check@points{#1}%
     }{}
 }