diff options
author | Karl Berry <karl@freefriends.org> | 2017-09-20 22:36:23 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2017-09-20 22:36:23 +0000 |
commit | baaddc3c242540fcc6eef178a4576c34df84c339 (patch) | |
tree | 3dd7e8072b95be228ebfff3acb9f40f0e7823b88 /Master/texmf-dist/doc/latex/xsim/xsim_manual.tex | |
parent | 6fdb207f55c75b496f116c760eab2e1640de2b88 (diff) |
xsim (20sep17)
git-svn-id: svn://tug.org/texlive/trunk@45355 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/xsim/xsim_manual.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/xsim/xsim_manual.tex | 228 |
1 files changed, 146 insertions, 82 deletions
diff --git a/Master/texmf-dist/doc/latex/xsim/xsim_manual.tex b/Master/texmf-dist/doc/latex/xsim/xsim_manual.tex index 2e351c7a64e..96a6613159a 100644 --- a/Master/texmf-dist/doc/latex/xsim/xsim_manual.tex +++ b/Master/texmf-dist/doc/latex/xsim/xsim_manual.tex @@ -1,8 +1,8 @@ -% !arara: pdflatex: { action: nonstopmode } -% !arara: biber % arara: pdflatex: { action: nonstopmode } +% !arara: biber % arara: pdflatex: { action: nonstopmode } % arara: pdflatex: { action: nonstopmode } +% !arara: pdflatex: { action: nonstopmode } % ---------------------------------------------------------------------------- % the XSIM package % @@ -282,8 +282,20 @@ order to deal with this somehow \xsim\ offers the following option: given. Exercises will be written to and included from this path. \emph{The path must exist on your system before you can use it!} This document uses \keyis{path}{exercises}. + \keyval{file-extension}{string}\Default{\code{tex}} + \sinceversion{0.10}This option let's you choose the extension of the + auxiliary files. \end{options} +Another thing to keep in mind: the environment in many ways works the same way +as the \env{filecontents}. \emph{This also means that you \emph{cannot} have + comments on the first line of the environments:} +\begin{sourcecode} + \begin{exercise}[points=2] % this will cause trouble + Lorem ipsum + \end{exercise} +\end{sourcecode} + \begin{bewareofthedog} \xsim\ writes a lot of stuff to the auxfile for re-using information on subsequent compilations. If you add exercises, change properties \etc\ it @@ -486,17 +498,18 @@ others can be set using the optional argument of the exercise environment. \command{DeclareExerciseProperty}[\barg\sarg\narg\marg{property}] Declares the property \meta{property}. - If used with the optional \barg\ star a unique property is defined which - means that each exercise must have a property value distinct from all - other exercises (all means all -- \emph{independent from the exercise type}). - - If used with the optional \sarg\ a boolean property is defined which - means that it only should get the values \code{true} or \code{false} and - if used without value it gets the value \code{true} instead of an empty - value. If any other value is used the property is set to - \code{false}. A boolean option obviously cannot be unique. The optional - \sarg\ takes precedence over the optional \barg, \ie, if both are present - the property is boolean \emph{but not} unique. + If used with the optional \barg\ a \textbf{unique property} is defined + which means that each exercise must have a property value distinct from + all other exercises (all means all -- \emph{independent from the exercise + type}). + + If used with the optional \sarg\ a \textbf{boolean property} is defined + which means that it only should get the values \code{true} or \code{false} + and if used without value it gets the value \code{true} instead of an + empty value. If any other value is used the property is set to + \code{false}. A boolean property obviously cannot be unique. The + optional \sarg\ takes precedence over the optional \barg, \ie, if both are + present the property is boolean \emph{but not} unique. If used with the optional \narg\ a property is defined which won't get updated through subsequent compilation runs but is only set when the @@ -527,7 +540,7 @@ This is better demonstrated with an example: The power of properties will get more clear when reading section~\vref{sec:styl-exerc-templ} about templates. -\subsection{A Special Kind of Property: Exercise Goals}\label{sec:goals} +\subsection[Exercise Goals]{A Special Kind of Property: Exercise Goals}\label{sec:goals} Exercise goals are a generic concept in \xsim\ for exercise properties like \property{points} or \property{bonus-points}. Those are properties which can @@ -652,7 +665,7 @@ Here is how you could mimick the command \cs*{totalpoints} from \end{sourcecode} -\subsection{A Special Kind of Property: Exercise Tags}\label{sec:tags} +\subsection[Exercise Tags]{A Special Kind of Property: Exercise Tags}\label{sec:tags} Exercise tags are a generic concept in \xsim\ for exercise properties like \property{tags} or \property{topics}. Those are properties which can (only) @@ -679,13 +692,13 @@ This means that these options are available: \keyval{tags}{csv list of tags} Choose the set of tags whose associated exercises should be printed. \keyval{topics}{csv list of topics} - Choose the set of tags whose associated exercises should be printed. - \keybool{ignore-tagging}\Module{tags}\Default{false} + Choose the set of topics whose associated exercises should be printed. + \keybool{ignore-untagged}\Module{tags}\Default{false} If set to true exercises with no tags will be printed even if tags have been chosen with the option \option{tags}. - \keybool{ignore-tagging}\Module{topics}\Default{true} - If set to true exercises with no topics will be printed even if tags have - been chosen with the option \option{topics}. + \keybool{ignore-untagged}\Module{topics}\Default{true} + If set to true exercises with no topics will be printed even if topics + have been chosen with the option \option{topics}. \end{options} It may happen that you choose certain tags for printing and want one or two @@ -978,7 +991,7 @@ At last now an example using external files, collections and tags: once and only \emph{after it has been collected}. No guaranties are given that properties are set correctly if you use the collection before. You usually also will make sure that the exercises in a collection are unique, - \ie, that an exercises is not part of several collections -- at least not if + \ie, that an exercise is not part of several collections -- at least not if both collections are printed in the same document. \end{bewareofthedog} @@ -1014,10 +1027,10 @@ Valid options for this command are: \printrandomexercises[collection=foo]{2} \end{example} -The example above of course doesn't make much sense but if have a collection -which collects exercises from an external file and the exercise haven't been -printed in the document before then you will get a list of subsequently -numbered exercises. +The example above of course doesn't make much sense but if you have a +collection which collects exercises from an external file and the exercises +haven't been printed in the document before then you will get a list of +subsequently numbered exercises. \section{Printing Solutions}\label{sec:printing-solutions} @@ -1044,12 +1057,12 @@ There are different commands for printing the solutions to exercises: \printsolutionstype{exercise} \end{example} -The options can be diveded into two groups. The ones in the first group +The options can be divided into two groups. The ones in the first group modify the layout. \begin{options} - \keybool{headings}\Default{true} + \keybool{headings}\Module{print-solutions}\Default{true} If true a heading for each exercise type is inserted. - \keyval{headings-template}{template}\Default{default} + \keyval{headings-template}{template}\Module{print-solutions}\Default{default} The heading template used when \keyis{headings}{true}. \end{options} @@ -1057,15 +1070,18 @@ The ones in the second group set conditions selecting which solutions are printed. If you combine those conditions a solution is printed if it meets either of the conditions. \begin{options} - \keychoice{section}{\default{true},false,\meta{integer}}\Default{false} + \keychoice{section}{\default{true},false,\meta{integer}}\Module{print-solutions}% + \Default{false} If you set \keyis{section}{true} only solutions of exercises of the current section are printed. If you set \keyis{section}{4} only solutions of exercises in a section with number~$4$ are printed. - \keychoice{chapter}{\default{true},false,\meta{integer}}\Default{false} + \keychoice{chapter}{\default{true},false,\meta{integer}}\Module{print-solutions}% + \Default{false} If you set \keyis{chapter}{true} only solutions of exercises of the current chapter are printed. If you set \keyis{chapter}{4} only solutions of exercises in a chapter with number~$4$ are printed. - \keychoice{collection}{false,\meta{collection name}}\Default{false} + \keychoice{collection}{false,\meta{collection name}}\Module{print-solutions}% + \Default{false} If used only solutions of exercises belonging to collection \meta{collection name} are printed. \end{options} @@ -1169,6 +1185,34 @@ yourself in order to achieve certain layouts\footnote{I plan to incorporate section~\vref{sec:template-examples} but at the time of writing this is still up in the air.}. +\subsection{Templates Provided by the Package} +\xsim\ comes with a few predefined layouts: +\begin{description} + \item[\code{default}] The template activated per default and the only one + available without further action. + \item[\code{runin}] A layout rather similar to the one by package + \pkg{exsheets}, see section~\vref{sec:runin-template}. Available through + the style file \code{layouts} (see section~\vref{sec:style-files} for more + information on style files\index{style file}). + \item[\code{margin}] A layout rather similar to the one by package + \pkg{exsheets}, see section~\ref{sec:margin-template}. Available through + the style file \code{layouts} (see section~\vref{sec:style-files} for more + information on style files\index{style file}). +\end{description} + +\collectexercises{layouts} +\begin{exercise}[subtitle=The Subtitle,points=2.5,ID=showlayout] + Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Ut purus elit, + vestibulum ut, placerat ac, adipiscing vitae, felis. Curabitur dictum + gravida mauris. Nam arcu libero, nonummy eget, consectetuer id, vulputate a, + magna. Donec vehicula augue eu neque. Pellentesque habitant morbi tristique + senectus et netus et malesuada fames ac turpis egestas. Mauris ut leo. Cras + viverra metus rhoncus sem. +\end{exercise} +\collectexercisesstop{layouts} + +\listlayouts + \subsection{Commands for Usage in Template Definitions} \subsubsection{Goals} \begin{commands} @@ -1213,7 +1257,11 @@ yourself in order to achieve certain layouts\footnote{I plan to incorporate current exercise. Inside the \meta{true} branch you can refer to the retrieved value either with \code{\#1} or with \cs{PropertyValue}. \emph{This command expands its contents inside a group.} - \command{GetExerciseIdForProperty}[\marg{property}\marg{value}] + \command{GetExerciseBody}[\Marg{exercise\textnormal{|}solution}] + \sinceversion{0.10}Retrieves the environment body of either the + \code{exercise} or the corresponding \code{solution} of the current + exercise. + \expandable\command{GetExerciseIdForProperty}[\marg{property}\marg{value}] Retrieves the property \property{id} of the exercise where the property \meta{property} has the value \meta{value}. \emph{This only works for \emph{unique} properties!} @@ -1221,9 +1269,19 @@ yourself in order to achieve certain layouts\footnote{I plan to incorporate Retrieves the property \property{type} of the exercise where the property \meta{property} has the value \meta{value}. \emph{This only works for \emph{unique} properties!} - \command{SetExerciseProperty}[\marg{type}\marg{id}\marg{property}\marg{value}] - Set the property \meta{property} of exercise of type \meta{type} and id - \meta{id} to \meta{value}. + \command{SetExerciseProperty}[\marg{property}\marg{value}] + \changedversion{0.9}Set the property \meta{property} of the current + exercise to \meta{value}. + \command{SetExpandedExerciseProperty}[\marg{property}\marg{value}] + \sinceversion{0.9}Expand \meta{value} \cs*{edef}-like and set the property + \meta{property} of the current exercise to the result of the expansion. + \command{ExerciseSetProperty}[\marg{type}\marg{id}\marg{property}\marg{value}] + \sinceversion{0.9}Set the property \meta{property} of the exercise of type + \meta{type} and id \meta{id} to \meta{value}. + \command{ExerciseSetExpandedProperty}[\marg{type}\marg{id}\marg{property}\marg{value}] + \sinceversion{0.9}Expand \meta{value} \cs*{edef}-like and set the property + \meta{property} of the exercise of type \meta{type} and id \meta{id} to + the result of the expansion. \expandable\command{IfExerciseBooleanProperty\TF}[\marg{property}% \marg{true}\marg{false}] Checks wether the boolean property \meta{property} has value \code{true} @@ -1259,14 +1317,28 @@ yourself in order to achieve certain layouts\footnote{I plan to incorporate \subsubsection{Parameters} \begin{commands} \expandable\command{GetExerciseParameter}[\marg{parameter}] - Retrieves the value of the parameter \meta{paramater} for the current exercise. + Retrieves the value of the parameter \meta{paramater} for the current + exercise type. + \command{GetExerciseParameter\TF}[\marg{parameter}\marg{true}\marg{false}] + \sinceversion{0.9}Retrieves the value of the parameter \meta{paramater} + for the current exercise type. Inside the \meta{true} branch you can refer + to the retrieved value either with \code{\#1} or with \cs{ParameterValue}. + \emph{This command expands its contents inside a group.} \expandable\command{GetExerciseName} Retrieves the value of the parameter \parameter{exercise-name} for the current exercise or of the parameter \parameter{solution-name} for the current solution. - \expandable\command{ExerciseParameterGet}[\marg{type}\marg{id}\marg{parameter}] + \expandable\command{ExerciseParameterGet}[\marg{type}\marg{parameter}] Retrieves the value of the parameter \meta{parameter} for the exercise of type \meta{type} with id \meta{id}. + \expandable\command{IfExerciseParameterSet\TF}[\marg{parameter}% + \marg{true}\marg{false}] + \sinceversion{0.9}Test if the parameter \meta{parameter} has been set for + the current exercise type. + \expandable\command{ExerciseParameterIfSet\TF}[\marg{type}\marg{parameter}% + \marg{true}\marg{false}] + \sinceversion{0.9}Test if the parameter \meta{parameter} has been set for + the exercise type \meta{type}. \end{commands} \subsubsection{Tags} @@ -1288,6 +1360,10 @@ yourself in order to achieve certain layouts\footnote{I plan to incorporate \subsubsection{Further Commands for Usage in Template Definitions} \begin{commands} + \command{UseExerciseTemplate}[\marg{type}\marg{name}] + Retrieve template \meta{name} of type \meta{type}. This can be useful if + you want to define a template which just adds some code to an existing + template (an automated \cs*{label}, say). \expandable\command{ExerciseType} Can be used to refer to the current exercise type. \expandable\command{ExerciseID} @@ -1306,6 +1382,8 @@ yourself in order to achieve certain layouts\footnote{I plan to incorporate \expandable\command{IfPrintSolution\TF}[\marg{true}\marg{false}] Tests if the option \option{print} for the solutions of the current \cs{ExerciseType} is set to \code{true} or \code{false}. + \command{IfExistSolution\TF}[\marg{true}\marg{false}] + \sinceversion{0.9}Tests if a solution for the current exercise exists. \command{ForEachPrintedExerciseByType}[\marg{code}] Loops over each \emph{printed} exercise ordered by the exercise types and within each type by id. Inside \meta{code} you can refer to several @@ -1459,8 +1537,8 @@ Below the definition of the \code{default} exercise template provided by \marginpar {% \IfInsideSolutionF{\rule{1.2cm}{1pt}\slash}% - \PropertyValue - \GetExercisePropertyT{bonus-points}{~(+\PropertyValue)}% + \printgoal{\PropertyValue} + \GetExercisePropertyT{bonus-points}{~(+\printgoal{\PropertyValue})}% ~\XSIMtranslate {point-abbr}% }% }% @@ -1493,7 +1571,7 @@ problems in this manual have been defined: \IfInsideSolutionF{% \GetExercisePropertyT{points}{ % notice the space (% - \PropertyValue + \printgoal{\PropertyValue} \IfExerciseGoalSingularTF{points} {\XSIMtranslate{point}} {\XSIMtranslate{points}}% @@ -1525,6 +1603,7 @@ See it in action: \end{example} \subsubsection{Mimicking \pkg*{exsheets}' \code{runin} Template} +\label{sec:runin-template} The following example shows how you could mimick \pkg*{exsheets}' \code{runin} template. The outcome isn't exactly the same since \pkg{exsheets} doesn't use @@ -1539,69 +1618,51 @@ would use a real sectioning command for the title. \Needspace*{2\baselineskip} \noindent \textbf{\XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}}% - \GetExercisePropertyT{subtitle}{ \textit{#1}} % - \GetExercisePropertyT{points}{% - \marginpar{% - \PropertyValue - \GetExercisePropertyT{bonus-points}{+\PropertyValue}% - \,\IfExerciseGoalSingularTF{points} - {\XSIMtranslate{point}} - {\XSIMtranslate{points}}% + \GetExercisePropertyT{subtitle}{ \textit{#1}} % <<< notice the space + \IfInsideSolutionF{% + \GetExercisePropertyT{points}{% + \marginpar{% + \printgoal{\PropertyValue}% + \GetExercisePropertyT{bonus-points}{+\printgoal{\PropertyValue}}% + \,\IfExerciseGoalSingularTF{points} + {\XSIMtranslate{point}} + {\XSIMtranslate{points}}% + }% }% }% } {} \end{sourcecode} -See it in action: -\begin{example} - \xsimsetup{exercise/template=runin} - \renewcommand*\theexercise{\arabic{exercise}.} - \begin{exercise}[subtitle=exsheets' runin,points=2.5] - \lipsum[4] - \end{exercise} -\end{example} - \subsubsection{Mimicking \pkg*{exsheets}' \code{margin} Template} +\label{sec:margin-template} The following example shows how you could mimick \pkg*{exsheets}' \code{margin} template. \begin{sourcecode} - \usepackage{needspace} \DeclareExerciseEnvironmentTemplate{margin} {% - \par\vspace{\baselineskip} - \Needspace*{2\baselineskip} - \noindent - \llap{% + \trivlist + \item[\llap{% \smash{% \tabular[t]{@{}r@{}} \textbf{\XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}} \IfExercisePropertySetT{points}{% \tabularnewline (% - \GetExerciseProperty{points}% - \GetExercisePropertyT{bonus-points}{+#1}% + \printgoal{\GetExerciseProperty{points}}% + \GetExercisePropertyT{bonus-points}{+\printgoal{#1}}% \,\XSIMtranslate{point-abbr}% )% }% \endtabular - } % notice the space - }% + }% + }]\relax } - {} + {\endtrivlist} \end{sourcecode} -See it in action: -\begin{example} - \xsimsetup{exercise/template=margin} - \renewcommand*\theexercise{\arabic{exercise}.} - \begin{exercise}[subtitle=exsheets' margin,points=2.5] - \lipsum[4] - \end{exercise} -\end{example} - \subsubsection{The Headings Templates}\label{sec:headings-templates} \xsim\ defines four heading templates which only differ by which text they output: @@ -1758,7 +1819,7 @@ exercise type or to \meta{code}. \section{Exercise Translations}\label{sec:exerc-transl} \begin{commands} - \command{DeclareExerciseTranslation}[\marg{keyword}\marg{language}\marg{translation}] + \command{DeclareExerciseTranslation}[\marg{language}\marg{keyword}\marg{translation}] Declare the translation of \meta{keyword} for language \meta{language}. \command{DeclareExerciseTranslations}[\marg{keyword}\marg{translations}] Declare the translations of \meta{keyword} for several languages at once. @@ -1936,11 +1997,11 @@ resolve your problems. \subsection{\code{! TeX capacity exceeded, sorry [text input levels=15].} Why?} Did you try to use an exercise or solution in a macro of some sort? This -generally will fail\footnote{The reasons are not entirely clear to me.}. But -there should never be the need to hide the environments inside of a macro, -anyway. +generally will fail\footnote{The reasons are similar to the ones given here: + \url{https://tex.stackexchange.com/a/295422/}.}. But there should never be +the need to hide the environments inside of a macro, anyway. -\subsection{\code{Runaway argument? !File ended while scanning use of \^\^M.} Why?} +\subsection{\code{Runaway argument? !File ended while scanning use of \^{}\^{}M.} Why?} Did you try to use an exercise or solution in a macro of some sort? This generally will fail. But there should never be the need to hide the environments inside of a macro, anyway. @@ -1993,7 +2054,8 @@ The usage is now as follows: \end{exercise} \end{example} -\subsection{\dots Create and Use \xsim\ Style Files?} +\subsection{\dots Create and Use \xsim\ Style Files?}\label{sec:style-files} +\index{style file|(} \xsim\ offers you the possibility to create own \emph{style files}. Let's say you want to have a style called \code{math-exam}. Then you need to save all @@ -2044,6 +2106,8 @@ The formal description of the commands: additional features. \end{bewareofthedog} +\index{style file|)} + \subsection{\dots Print All Solutions Grouped by Section?} Here is an idea how to get a list of all solutions grouped by the section the corresponding exercises are appearing in. |