summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/xsim/xsim_manual.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/xsim/xsim_manual.tex')
-rw-r--r--Master/texmf-dist/doc/latex/xsim/xsim_manual.tex100
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