diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/xsim/xsim_manual.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/xsim/xsim_manual.tex | 100 |
1 files changed, 68 insertions, 32 deletions
diff --git a/Master/texmf-dist/doc/latex/xsim/xsim_manual.tex b/Master/texmf-dist/doc/latex/xsim/xsim_manual.tex index 96a6613159a..53c620c1bb7 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: pdflatex: { action: nonstopmode } % !arara: biber +% !arara: pdflatex: { action: nonstopmode } % arara: pdflatex: { action: nonstopmode } % arara: pdflatex: { action: nonstopmode } -% !arara: pdflatex: { action: nonstopmode } % ---------------------------------------------------------------------------- % the XSIM package % @@ -13,7 +13,7 @@ % Web: https://github.com/cgnieder/xsim % E-Mail: contact@mychemistry.eu % ---------------------------------------------------------------------------- -% Copyright 2017 Clemens Niederberger +% Copyright 2017--2018 Clemens Niederberger % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 @@ -51,7 +51,7 @@ \begin{document} -\section{Licence, Requirements and \textsc{readme}} +\section{Licence, Requirements and \texorpdfstring{\textsc{readme}}{README}} \license \xsim\ loads the packages \pkg{expl3}~\cite{bnd:l3kernel}, @@ -76,7 +76,7 @@ using an up to date \TeX\ distribution, anyway. It has been quite a while since I first published \pkg{exsheets}~\cite{pkg:exsheets} in June 2012. Since then it has gained a user base and a little bit of popularity as the number of questions on tex.sx -shows (103~at the time of writing)~\cite{texsx:tagged/exsheets}. User +shows (119~at the time of writing)~\cite{texsx:tagged/exsheets}. User questions, bug reports and feature requests improved it over the time. It still has a version number starting with a zero, though, which in my versioning system means I still consider it experimental. @@ -244,8 +244,8 @@ More details on those two environments can be found in section~\vref{sec:using-printing}. \section{How the Exercise Environments Work}\label{sec:how-exerc-envir} -Both enviroments write the contents of their bodies verbatim to external files -following a certain naming structure: +Both the exercise and the solution enviroments write the contents of their +bodies verbatim to external files following a certain naming structure: \begin{itemize} \item \code{\meta{jobname}-\meta{type}-\meta{id}-exercise|solution-body.tex} @@ -258,18 +258,18 @@ example have been written to files named \item \verbcode+xsim_manual-exercise-1-exercise-body.tex+ and \item \verbcode+xsim_manual-exercise-1-solution-body.tex+, respectively. \end{itemize} -Details on the \meta{type} of an exercise will be given in -section~\vref{sec:new-exercise-types}. \emph{The \meta{id} of an exercise is - a positive integer unique to each exercise environment regardless if the - exercise is being printed or used at all.} - These external files are input when the respective exercise or solution is printed. An advantage of using external files is that \emph{verbatim material - is allowed} inside the environments. Each of those files contains some -information about itself and where and why it was generated\footnote{In this - example the sourcecode line number is misleading as the example where the - file was generated itself was an external file where the \env{exercise} - environment indeed \emph{was} on line~1.}: + is allowed} inside the environments. Details on the \meta{type} of an +exercise will be given in section~\vref{sec:new-exercise-types}. \emph{The + \meta{id} of an exercise is a positive integer unique to each exercise + environment regardless if the exercise is being printed or used at all.} + +Each of those files contains some information about itself and where and why +it was generated\footnote{In this example the sourcecode line number is + misleading as the example where the file was generated itself was an + external file where the \env{exercise} environment indeed \emph{was} on + line~1.}: \inputsourcecode{exercises/xsim_manual-exercise-1-exercise-body.tex} @@ -288,10 +288,10 @@ order to deal with this somehow \xsim\ offers the following option: \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:} +as the \env{filecontents} environment. \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 + \begin{exercise}[points=2] % this comment will cause trouble Lorem ipsum \end{exercise} \end{sourcecode} @@ -313,6 +313,23 @@ as the \env{filecontents}. \emph{This also means that you \emph{cannot} have Using the \option{clear-aux} option might help to reduce erroneous exercises. \end{bewareofthedog} +\begin{bewareofthedog} + A lot of the lines \xsim\ writes to the auxfile and reads in a subsequent + run look like this: +\begin{sourcecode} + \XSIM {points}{exercise-2=={4}|exercise-10=={2.5}|problem-11=={5}} +\end{sourcecode} + As you can see different entries of the various properties of exercises are + separated with a \code{|}. This means that you cannot use this symbol + inside properties. This is why \xsim\ provides an option to change this + marker. +\end{bewareofthedog} +\begin{options} + \keyval{split-aux-lists}{string}\Default{\code{|}} + Set\sinceversion{0.11} the string that is used to separate the property + entries in the auxfile. +\end{options} + \section{New Exercise Types}\label{sec:new-exercise-types} It is easy to define new exercise environments together with a corresponding @@ -479,6 +496,10 @@ Exercise like the \env{exercise} environment and possibly others defined with Holds the chapter counter value of an exercise (\ie, what you usually know as \cs*{arabic}\Marg{chapter}). \emph{Only if a command \cs*{chapter} \emph{and} a counter \code{chapter} exist.} + \propval{sectioning}{section numbers} + Holds five brace groups which in turn hold the section numbers (integers) + of the exercise in the order + \marg{chapter}\marg{section}\marg{subsection}\marg{subsubsection}\marg{paragraph}. \end{properties} Some of these \acsp*{prop} are fixed and cannot be set by the user. Those @@ -679,6 +700,9 @@ and how to use exercise tags for selection. property named \meta{tag}. In addition two options are defined: an option named \code{\meta{tag}} which can be used for selection and an boolean option \code{\meta{tag}/ignore-untagged}. + \command{ProvideExerciseTagging}[\marg{tag}] + The\sinceversion{0.11} same as \cs{DeclareExerciseTagging} but does + nothing when \meta{tag} already exists. \end{commands} The two existing tagging groups have been defined and preset with the following code: @@ -998,6 +1022,9 @@ At last now an example using external files, collections and tags: \section{Printing Random Exercises From a Collection} \xsim\ provides the possibility of selecting random exercises from a collection (\cf~section~\vref{sec:collecting-exercises}). +\begin{bewareofthedog} + Please be aware that this feature is \emph{not} available in \XeLaTeX! +\end{bewareofthedog} \begin{commands} \command{printrandomexercises}[\oarg{options}\marg{number}] This command prints \meta{number} random exercises from the collection @@ -1356,6 +1383,14 @@ yourself in order to achieve certain layouts\footnote{I plan to incorporate \meta{between} as a separator and \meta{between last two} as separator between the last two tags of the list. If the list only consists of two tags \meta{between two} is used as separator. + \command{IfExerciseTagSet\TF}[\marg{value}\marg{true}\marg{false}] + In\sinceversion{0.11} order to insert text (also \emph{outside} of + exercises) depending on the chosen tags this command lets you check if + value \meta{value} has been set for \property{tags}. + \command{IfExerciseTopicSet\TF}[\marg{value}\marg{true}\marg{false}] + In\sinceversion{0.11} order to insert text (also \emph{outside} of + exercises) depending on the chosen tags this command lets you check if + value \meta{value} has been set for \property{topics}. \end{commands} \subsubsection{Further Commands for Usage in Template Definitions} @@ -1379,7 +1414,7 @@ yourself in order to achieve certain layouts\footnote{I plan to incorporate exercise type or -- if no type has been given -- to \meta{code}. \expandable\command{IfInsideSolution\TF}[\marg{true}\marg{false}] Tests if the template is used inside a solution environment or not. - \expandable\command{IfPrintSolution\TF}[\marg{true}\marg{false}] + \expandable\command{IfSolutionPrint\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}] @@ -2057,11 +2092,12 @@ The usage is now as follows: \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 -necessary definitions in a file called: +\xsim\changedversion{0.11} 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 necessary definitions in a file +called: \begin{center} - \code{xsim.math-exam.code.tex} + \code{xsim.style.math-exam.code.tex} \end{center} The first command in the file should be \cs{xsimstyle}\Marg{math-exam}. This file can now be loaded into your document using @@ -2091,11 +2127,11 @@ code~11 (letter). The formal description of the commands: \begin{commands} \command{xsimstyle}[\sarg\marg{style name}] - The first command in a \xsim\ style file called \code{xsim.\meta{style - name}.code.tex} which defines the \xsim\ style \meta{style name}. The - starred version activates expl3 syntax\footnote{Those users who want this - will know what it means. If you don't know what it means you will not - need it.}. + The\changedversion{0.11} first command in a \xsim\ style file called + \code{xsim.style.\meta{style name}.code.tex} which defines the \xsim\ + style \meta{style name}. The starred version activates expl3 + syntax\footnote{Those users who want this will know what it means. If you + don't know what it means you will not need it.}. \command{loadxsimstyle}[\marg{csv list of style names}] Load one or more styles into the document. \end{commands} @@ -2242,8 +2278,8 @@ The repository of this package\footnote{GitHub: \url{http://www.ctan.org/pkg/xsim/}} currently includes \theexamplefiles~example documents demonstrating how different aspects of this package work or how different kinds of problems can be solved or how different -kinds of layouts can be achieved as well as how solve concrete problems that -have come up in different \LaTeX\ forums. +kinds of layouts can be achieved as well as how to solve concrete problems +that have come up in different \LaTeX\ forums. \listexamplefiles |