From 23096896d90fa4e84c769e8e310fad6173aa910d Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 31 Jan 2021 21:33:37 +0000 Subject: xsim (31jan21) git-svn-id: svn://tug.org/texlive/trunk@57572 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/xsim/HISTORY | 178 ++ Master/texmf-dist/doc/latex/xsim/README | 46 +- .../doc/latex/xsim/examples/xsim.blanks.pdf | Bin 29952 -> 38256 bytes .../doc/latex/xsim/examples/xsim.blanks.tex | 1 - .../latex/xsim/examples/xsim.boxed-headings.pdf | Bin 38376 -> 38372 bytes .../latex/xsim/examples/xsim.code-and-output.pdf | Bin 30938 -> 30939 bytes .../latex/xsim/examples/xsim.code-and-output.tex | 2 +- .../doc/latex/xsim/examples/xsim.collections.pdf | Bin 33206 -> 30259 bytes .../doc/latex/xsim/examples/xsim.collections.tex | 44 +- .../doc/latex/xsim/examples/xsim.crossref.pdf | Bin 38749 -> 38748 bytes .../doc/latex/xsim/examples/xsim.crossref.tex | 2 +- .../latex/xsim/examples/xsim.description-list.pdf | Bin 41167 -> 41171 bytes .../xsim/examples/xsim.different-point-types.pdf | Bin 42153 -> 42156 bytes .../doc/latex/xsim/examples/xsim.difficulties.pdf | Bin 31555 -> 31763 bytes .../doc/latex/xsim/examples/xsim.floating.pdf | Bin 37708 -> 37717 bytes .../doc/latex/xsim/examples/xsim.golatex-80640.pdf | Bin 46308 -> 46317 bytes .../doc/latex/xsim/examples/xsim.golatex-80640.tex | 1 - .../doc/latex/xsim/examples/xsim.golatex-91339.pdf | Bin 65379 -> 64956 bytes .../doc/latex/xsim/examples/xsim.golatex-91339.tex | 3 +- .../xsim/examples/xsim.grade-distribution.pdf | Bin 23204 -> 23204 bytes .../doc/latex/xsim/examples/xsim.hints.pdf | Bin 45719 -> 45722 bytes .../doc/latex/xsim/examples/xsim.hints.tex | 7 +- .../doc/latex/xsim/examples/xsim.issues-49.pdf | Bin 0 -> 95608 bytes .../doc/latex/xsim/examples/xsim.issues-49.tex | 122 + .../doc/latex/xsim/examples/xsim.listings.pdf | Bin 45738 -> 45747 bytes .../doc/latex/xsim/examples/xsim.listings.tex | 2 +- .../latex/xsim/examples/xsim.listofexercises.pdf | Bin 57220 -> 57220 bytes .../latex/xsim/examples/xsim.multiplechoice.pdf | Bin 31016 -> 31019 bytes .../doc/latex/xsim/examples/xsim.pointsums.pdf | Bin 28127 -> 28126 bytes .../latex/xsim/examples/xsim.randomexercises.pdf | Bin 23102 -> 23048 bytes .../latex/xsim/examples/xsim.randomexercises.tex | 18 +- .../doc/latex/xsim/examples/xsim.texsx-13635.pdf | Bin 86047 -> 86049 bytes .../doc/latex/xsim/examples/xsim.texsx-13635.tex | 2 + .../doc/latex/xsim/examples/xsim.texsx-155630.pdf | Bin 20045 -> 20048 bytes .../doc/latex/xsim/examples/xsim.texsx-155630.tex | 3 +- .../doc/latex/xsim/examples/xsim.texsx-199360.pdf | Bin 56153 -> 56106 bytes .../doc/latex/xsim/examples/xsim.texsx-299534.pdf | Bin 48094 -> 48095 bytes .../doc/latex/xsim/examples/xsim.texsx-299534.tex | 2 +- .../doc/latex/xsim/examples/xsim.texsx-305110.pdf | Bin 36968 -> 36974 bytes .../doc/latex/xsim/examples/xsim.texsx-308883.pdf | Bin 27155 -> 27157 bytes .../doc/latex/xsim/examples/xsim.texsx-338165.pdf | Bin 57235 -> 56911 bytes .../doc/latex/xsim/examples/xsim.texsx-338165.tex | 38 +- .../doc/latex/xsim/examples/xsim.texsx-350028.pdf | Bin 130569 -> 130588 bytes .../doc/latex/xsim/examples/xsim.texsx-350028.tex | 80 +- .../doc/latex/xsim/examples/xsim.texsx-369065.pdf | Bin 65721 -> 65714 bytes .../doc/latex/xsim/examples/xsim.texsx-369065.tex | 36 +- .../doc/latex/xsim/examples/xsim.texsx-369636.pdf | Bin 46504 -> 91296 bytes .../doc/latex/xsim/examples/xsim.texsx-369636.tex | 27 +- .../doc/latex/xsim/examples/xsim.texsx-369803.pdf | Bin 55079 -> 55077 bytes .../doc/latex/xsim/examples/xsim.texsx-369803.tex | 24 +- .../doc/latex/xsim/examples/xsim.texsx-370642.pdf | Bin 28426 -> 28428 bytes .../xsim/examples/xsim.texsx-391530-exercises.tex | 12 + .../doc/latex/xsim/examples/xsim.texsx-391530.pdf | Bin 25040 -> 26102 bytes .../doc/latex/xsim/examples/xsim.texsx-391530.tex | 35 +- .../doc/latex/xsim/examples/xsim.texsx-395273.pdf | Bin 50580 -> 50575 bytes .../doc/latex/xsim/examples/xsim.texsx-466584.pdf | Bin 0 -> 60453 bytes .../doc/latex/xsim/examples/xsim.texsx-466584.tex | 56 + .../doc/latex/xsim/examples/xsim.texsx-498299.pdf | Bin 42513 -> 42514 bytes .../doc/latex/xsim/examples/xsim.texsx-498299.tex | 1 + .../doc/latex/xsim/examples/xsim.texsx-576998.pdf | Bin 0 -> 49333 bytes .../doc/latex/xsim/examples/xsim.texsx-576998.tex | 135 ++ .../doc/latex/xsim/examples/xsim.texsx-580636.pdf | Bin 0 -> 51800 bytes .../doc/latex/xsim/examples/xsim.texsx-580636.tex | 92 + .../doc/latex/xsim/examples/xsim.texwelt-15093.pdf | Bin 36256 -> 36259 bytes .../doc/latex/xsim/examples/xsim.texwelt-15093.tex | 1 - .../doc/latex/xsim/examples/xsim.texwelt-23968.pdf | Bin 46008 -> 46009 bytes .../doc/latex/xsim/examples/xsim.texwelt-23968.tex | 7 +- .../doc/latex/xsim/examples/xsim.texwelt-6698.pdf | Bin 43899 -> 43907 bytes .../doc/latex/xsim/examples/xsim.texwelt-6698.tex | 1 - .../doc/latex/xsim/examples/xsim.various.pdf | Bin 86646 -> 86588 bytes .../doc/latex/xsim/examples/xsim.various.tex | 3 +- Master/texmf-dist/doc/latex/xsim/xsim-manual.pdf | Bin 0 -> 1308757 bytes Master/texmf-dist/doc/latex/xsim/xsim-manual.tex | 2439 ++++++++++++++++++++ Master/texmf-dist/doc/latex/xsim/xsim.history | 158 -- Master/texmf-dist/doc/latex/xsim/xsim.ideas | 29 - Master/texmf-dist/doc/latex/xsim/xsim_manual.pdf | Bin 1269638 -> 0 bytes Master/texmf-dist/doc/latex/xsim/xsim_manual.tex | 2421 ------------------- 77 files changed, 3186 insertions(+), 2842 deletions(-) create mode 100644 Master/texmf-dist/doc/latex/xsim/HISTORY create mode 100644 Master/texmf-dist/doc/latex/xsim/examples/xsim.issues-49.pdf create mode 100644 Master/texmf-dist/doc/latex/xsim/examples/xsim.issues-49.tex create mode 100644 Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-391530-exercises.tex create mode 100644 Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-466584.pdf create mode 100644 Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-466584.tex create mode 100644 Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-576998.pdf create mode 100644 Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-576998.tex create mode 100644 Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-580636.pdf create mode 100644 Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-580636.tex create mode 100644 Master/texmf-dist/doc/latex/xsim/xsim-manual.pdf create mode 100644 Master/texmf-dist/doc/latex/xsim/xsim-manual.tex delete mode 100644 Master/texmf-dist/doc/latex/xsim/xsim.history delete mode 100644 Master/texmf-dist/doc/latex/xsim/xsim.ideas delete mode 100644 Master/texmf-dist/doc/latex/xsim/xsim_manual.pdf delete mode 100644 Master/texmf-dist/doc/latex/xsim/xsim_manual.tex (limited to 'Master/texmf-dist/doc/latex/xsim') diff --git a/Master/texmf-dist/doc/latex/xsim/HISTORY b/Master/texmf-dist/doc/latex/xsim/HISTORY new file mode 100644 index 00000000000..0d3f7d417a1 --- /dev/null +++ b/Master/texmf-dist/doc/latex/xsim/HISTORY @@ -0,0 +1,178 @@ +-------------------------------------------------------------------------- + +XSIM -- eXercise Sheets IMproved + +-------------------------------------------------------------------------- +Clemens Niederberger +Web: https://github.com/cgnieder/xsim +E-Mail: contact@mychemistry.eu +-------------------------------------------------------------------------- +Copyright 2017--2020 Clemens Niederberger + +This work may be distributed and/or modified under the +conditions of the LaTeX Project Public License, either version 1.3 +of this license or (at your option) any later version. +The latest version of this license is in + http://www.latex-project.org/lppl.txt +and version 1.3 or later is part of all distributions of LaTeX +version 2005/12/01 or later. + +This work has the LPPL maintenance status `maintained'. + +The Current Maintainer of this work is Clemens Niederberger. +-------------------------------------------------------------------------- + +HISTORY: + + v0.0 2017/02/09 - start with coding the first ideas + v0.1 2017/03/19 - first draft which actually seems to do everything as + planned + v0.2 2017/03/21 - bugfix in the verbwrite module + - add `use!' and `print!' properties + - add the concepts of `noupdate' and `boolean' properties + v0.4 2017/03/24 - \IfExerciseBooleanPropertyTF + - \GetExercisePropertyTF, \PropertyValue + - \printallsolutions + - \UseExerciseTemplate + - bug fix in solution environments: now get printed again + when option `print=true' is used + - bug fix to the translations of the solution list headings: + exercise name instead of exercise type is now printed + - \AddtoExerciseTypeGoal, \AddtoExerciseGoal + \AddtoExerciseTypeGoalPrint, \AddtoExerciseGoalPrint, + \ExerciseGoalValuePrint + - \addpoints, \addbonus, \points, \printgoal + v0.5 2017/03/30 - add style file mechanism + - make solution print conditions `section' and `chapter' + combinable + v0.5a 2017/04/15 - fix wrong translation of the `default-heading' + v0.5b 2017/04/16 - add \SetExerciseProperty + v0.6 2017/04/27 - official interface for grade distributions + - refine hook management (environment module) + v0.6a 2017/04/28 - refine \blank command, add documentation for said command + v0.7 2017/05/09 - \xsim_list_length:n + - new boolean property `used' + - when an exercise is collected the counter isn't stepped + but only when the exercise is inserted for the first + time; when this happens the new property `used' is set to + `true' + - make setting boolean properties case insensitive + - add missing pieces to manual (eg `page' property...) + - \TotalExerciseGoals and \TotalExerciseTypeGoals + - \XSIMifchapterTF + - \xsim_if_goal_sum:nnnTF and friends, + \IfExerciseTypeGoalsSumTF and \IfExerciseGoalsSumTF + - some more hints in the manual regarding collections + v0.8 2017/05/18 - bug fix in \xsim_set_property:nnnn + - random exercise lists from collections + - \xsim_collection_count:n + - \GetExerciseIdForProperty and \GetExerciseTypeForProperty + for unique properties + - set property `print=false' during collection and only to + true when the corresponding exercises actually are + printed + - do not insert \par at the beginning and end of exercises + and solutions; this should be left to the templates! + - new option `print-collection/print' which allows to + choose between exercises, solutions, and both to be + printed + - new parameter `solution-counter' in order to avoid + possible conflicts with existing counters + v0.8a 2017/05/19 - \IfPrintSolutionTF + v0.8b 2017/05/23 - use \printgoal in default environment template + - \xsim_print_goal:nnn now expands input to a number + v0.9 2017/06/20 - \xsimstyle's behaviour now matches the description in + the manual + - add style file `layouts' which at the moment provides the + two exercise templates `runin' and `margin' + - \printforexercises , \xsim_print_type_code:nnnnn + - \IfExerciseParameterSetTF + - \GetExerciseParameterTF + - change syntax of \SetExerciseProperty + - \SetExpandedExerciseProperty + - \ExerciseSetProperty, \ExerciseSetExpandedProperty + - property `sectioning' + - \IfExistSolutionTF + v0.10 2017/09/19 - \xsim_input:nnn + - \GetExerciseBody + - option `blank/fill' + - bug fix in \xsim_start_collection:nn + - added further examples to package + - new option `file-extension' + v0.10a 2017/10/01 - bug fix: grading table options can now be set with + \xsimsetup (issue 15) + v0.11 2018/02/12 - change name requirement for style files in order to + prevent possible name clashes with module files + - fix bug in \SetExerciseProperty and + \SetExpandedExerciseProperty + - fix bug when xsimverb is used standalone (issue 21) + - add option `split-aux-lists' (issue 18) + - \IfExerciseTagSetTF and \IfExerciseTopicSetTF + - introduce a \xsim_if__value:nTF for each tag + kind + - \ProvideExerciseTagging + v0.12 2019/09/30 - add parameter versions for the plural forms of exercise + and solution names + - bug fixes (issues 37, 39, 43, 47) + v0.13 2019/10/06 - experimental package option `no-files' + v0.14 2019/10/13 - new exercise parameters `exercise-heading' and + `solution-heading' + - new options `exercise/heading' and `solution/heading' as + interface for setting the new parameters + - new command \GetExerciseHeadingF for using the new + parameters in environment templates + - change the environment template `default' to use the new + \GetExerciseHeadingF and output a \par at the end + - make argument of \xsimsetup long + - new template `minimal' + - new option `load-style' + - new example `texwelt-23968' (long and short solutions) + v0.14a 2019/10/19 - fix \xsim_if_exercise_exist:nnTF to obey the `no-files' + option + v0.15 2019/11/02 - use own auxiliary file per default and add option + `use-aux' + v0.16 2019/11/10 - fix issue due to usage of own auxiliary file + - \XSIMatbegindocument and \XSIMatenddocument + - \xprintexercise, \xprintsolution, \xsimprint, \xsimxprint + 2019/12/29 - bugfix in `xsimverb' + v0.16a 2020/01/16 - adapt to renaming of string case changing functions + v0.17 2020/02/21 - prefer lazy boolean evaluation if possible + - remove spurious \par at the beginning of typeset + exercises + - add `blank' option, implements issue #31 + - add `solution' property, implements issue #33 + - fix issue #27 + - implement issue #2 + - don't allow package options to be set with \xsimsetup + v0.18 2020/02/23 - fix issue #56 + - change \printexercise and \printsolution to accept a + clist of either ids or IDs (or mixed) + - new templates in the `layouts' style + v0.19 2020/03/16 - improve performance + - only set \ExerciseID and \ExerciseType locally to ensure + correct values when exercises (of different types) are + nested + - new load-time option `debug' - only for development + v0.19a 2020/03/19 - fix missing-variant-bug introduced with the last update + v0.19b 2020/04/04 - fix bug in new attribute mechanism which was a problem + when `no-files` has been used + v0.20 2021/01/31 - switch to one sty file per package + - use LaTeX's new hooks + - declare undeclared variables + - new exercise setup mechanism which clearly determines the + difference between definition, usage, and printing of an + exercise; this also solves the problem with added goals + in the exercise body in a collection + - re-write collection mechanism: + * changes the behaviour of \collectexercises but doesn't + require external files any more and more importantly + doesn't require inputting files several times for + multiple collections + * drop \collectexercisestype + * new \(de)activatecollection + * new options `collect' and `/collect' + - small improvements in performance + - new parameters `within' and `the-counter' + - make `no-files' the default + - new examples + - various small fixes diff --git a/Master/texmf-dist/doc/latex/xsim/README b/Master/texmf-dist/doc/latex/xsim/README index 5923c8045b4..3407220a293 100644 --- a/Master/texmf-dist/doc/latex/xsim/README +++ b/Master/texmf-dist/doc/latex/xsim/README @@ -1,6 +1,6 @@ -------------------------------------------------------------------------- -XSIM 2020/04/04 v0.19b -XSIMVERB 2019/12/29 v0.1a +XSIM 2021/01/31 v0.20 +XSIMVERB 2021/01/31 v0.3 eXercise Sheets IMproved @@ -9,15 +9,15 @@ Clemens Niederberger Web: https://github.com/cgnieder/xsim E-Mail: contact@mychemistry.eu -------------------------------------------------------------------------- -Copyright 2017--2020 Clemens Niederberger +Copyright 2017--2021 Clemens Niederberger This work may be distributed and/or modified under the -conditions of the LaTeX Project Public License, either version 1.3 +conditions of the LaTeX Project Public License, either version 1.3c of this license or (at your option) any later version. The latest version of this license is in http://www.latex-project.org/lppl.txt -and version 1.3 or later is part of all distributions of LaTeX -version 2005/12/01 or later. +and version 1.3c or later is part of all distributions of LaTeX +version 2008/05/04 or later. This work has the LPPL maintenance status `maintained'. @@ -26,30 +26,10 @@ The Current Maintainer of this work is Clemens Niederberger. The xsim package consists of the code files: xsim.sty xsimverb.sty - xsim.auxfile.code.tex - xsim.base.code.tex - xsim.blanks.code.tex - xsim.collections.code.tex - xsim.definitions.code.tex - xsim.environments.code.tex - xsim.exercises.code.tex - xsim.goals.code.tex - xsim.grades.code.tex - xsim.interface.code.tex - xsim.modules.code.tex - xsim.properties.code.tex - xsim.random.code.tex - xsim.solutions.code.tex - xsim.style.layouts.code.tex - xsim.tags.code.tex - xsim.templates.code.tex - xsim.translations.code.tex - xsim.verbwrite.code.tex -------------------------------------------------------------------------- The xsim package consists of the documentation files: - README - xsim.history, xsim.ideas - xsim_manual.tex, xsim_manual.pdf + README HISTORY + xsim-manual.tex, xsim-manual.pdf xsim-manual.cls -------------------------------------------------------------------------- The xsim package consists of the example files: @@ -84,12 +64,16 @@ The xsim package consists of the example files: xsim.texsx-370642.tex, xsim.texsx-370642.pdf xsim.texsx-391530.tex, xsim.texsx-391530.pdf xsim.texsx-395273.tex, xsim.texsx-395273.pdf - xsim.texsx-498299.tex, xsim.texsx-498299.pdf, + xsim.texsx-466584.tex, xsim.texsx-466584.pdf + xsim.texsx-498299.tex, xsim.texsx-498299.pdf + xsim.texsx-576998.tex, xsim.texsx-576998.pdf + xsim.texsx-580636.tex, xsim.texsx-580636.pdf xsim.texwelt-6698.tex, xsim.texwelt-6698.pdf xsim.texwelt-15093.tex, xsim.texwelt-15093.pdf xsim.texwelt-23968.tex, xsim.texwelt-23968.pdf - xsim.golatex-16824.tex, xsim.golatex-16824.pdf - xsim.golatex-18844.tex, xsim.golatex-18844.pdf + xsim.golatex-80640.tex, xsim.golatex-80640.pdf + xsim.golatex-91339.tex, xsim.golatex-91339.pdf + xsim.issues-49.tex, xsim.issues-49.pdf -------------------------------------------------------------------------- If you have any ideas, questions, suggestions or bugs to report, please feel free to contact me. diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.blanks.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.blanks.pdf index dd26d671570..84a8e09b332 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.blanks.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.blanks.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.blanks.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.blanks.tex index b479e961c2c..f32b81a1290 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.blanks.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.blanks.tex @@ -1,5 +1,4 @@ \documentclass{article} -\usepackage[utf8]{inputenc} \usepackage[ngerman]{babel} \usepackage{xsim,lipsum,xcolor} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.boxed-headings.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.boxed-headings.pdf index 99ba5bbc2a6..fb9ff49f982 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.boxed-headings.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.boxed-headings.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.code-and-output.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.code-and-output.pdf index 72894ac9a63..4626e8c9820 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.code-and-output.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.code-and-output.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.code-and-output.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.code-and-output.tex index 66afaf9b8ad..15b1a7dea00 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.code-and-output.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.code-and-output.tex @@ -46,7 +46,7 @@ \bigskip -\begin{code}[] +\begin{code} blubber \LaTeX \end{code} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.collections.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.collections.pdf index fd785cc0574..e7ccda79cf0 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.collections.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.collections.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.collections.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.collections.tex index 990391e0915..5f75082a420 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.collections.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.collections.tex @@ -1,12 +1,19 @@ \documentclass{article} \usepackage{xsim} +\usepackage{lipsum} -\DeclareExerciseCollection{foo-easy} -\DeclareExerciseCollection{foo-medium} +\DeclareExerciseCollection[difficulty=easy]{easy} +\DeclareExerciseCollection[difficulty=medium]{medium} \DeclareExerciseTagging{difficulty} -\usepackage{lipsum} -\begin{filecontents*}{foo.tex} +\xsimsetup{collect} + +\begin{document} + +\begin{exercise}[use,print] + outside before +\end{exercise} + \begin{exercise}[difficulty=easy,points=1] foo one \lipsum[4] \end{exercise} @@ -25,38 +32,13 @@ \begin{solution} foo three \lipsum[4] \end{solution} -\end{filecontents*} - -\begin{document} - -\begin{exercise} - outside before -\end{exercise} - -\collectexercises{foo-easy} -\xsimsetup{difficulty=easy} -\input{foo.tex} -\collectexercisesstop{foo-easy} -% collection `foo-easy' now contains all exercises of file `foo.tex' tagged -% with `difficulty=easy' - -\collectexercises{foo-medium} -\xsimsetup{difficulty=medium} -\input{foo.tex} -\collectexercisesstop{foo-medium} -% collection `foo-medium' now contains all exercises of file `foo.tex' -% tagged with `difficulty=medium' \section{Easy} -\printcollection{foo-easy} +\printcollection{easy} \section{Medium} -\printcollection{foo-medium} +\printcollection{medium} \printsolutions[difficulty=medium] -\section{All Exercises and Their Solutions Again, in Order of Appearance} - -\printcollection[print=both]{all exercises} - \end{document} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.crossref.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.crossref.pdf index 8151a0cef3f..19843c41850 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.crossref.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.crossref.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.crossref.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.crossref.tex index fa2fbbb509d..0a6c8f4eab9 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.crossref.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.crossref.tex @@ -2,7 +2,7 @@ \usepackage{xsim,lipsum,hyperref} \DeclareExerciseHeadingTemplate{custom} - {\section{\XSIMtranslate{default-heading}}} + {\section{\XSIMexpandcode{\XSIMtranslate{default-heading}}}} \DeclareExerciseEnvironmentTemplate{custom} {% diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.description-list.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.description-list.pdf index d506ad960bc..b05b3276c9c 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.description-list.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.description-list.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.different-point-types.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.different-point-types.pdf index b1de5d63253..781831ddf80 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.different-point-types.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.different-point-types.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.difficulties.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.difficulties.pdf index 846f19e2012..4963fb48363 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.difficulties.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.difficulties.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.floating.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.floating.pdf index e2e96537ef1..c1352837eb5 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.floating.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.floating.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.golatex-80640.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.golatex-80640.pdf index 76cf1617cbd..068dc15fef4 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.golatex-80640.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.golatex-80640.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.golatex-80640.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.golatex-80640.tex index 5ccdff63a45..7ac1f158006 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.golatex-80640.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.golatex-80640.tex @@ -1,6 +1,5 @@ % http://golatex.de/viewtopic,p,80640.html \documentclass[fontsize=12pt,parskip=half]{scrartcl} -\usepackage[utf8]{inputenc} \usepackage[T1]{fontenc} \usepackage[ngerman]{babel} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.golatex-91339.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.golatex-91339.pdf index 97cb4659e06..189210a8a3e 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.golatex-91339.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.golatex-91339.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.golatex-91339.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.golatex-91339.tex index 8ae03971c56..ae02ca0344c 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.golatex-91339.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.golatex-91339.tex @@ -1,6 +1,5 @@ % http://golatex.de/viewtopic,p,91339.html -\documentclass[18pt,a4paper]{article} -\usepackage[utf8]{inputenc} +\documentclass[a4paper]{article} \usepackage[ngerman]{babel} \usepackage{xsim,tcolorbox} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.grade-distribution.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.grade-distribution.pdf index 248358c4a16..2de9ff1358e 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.grade-distribution.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.grade-distribution.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.hints.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.hints.pdf index a34fbd8f79c..4b13a435d60 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.hints.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.hints.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.hints.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.hints.tex index 10a0bffed9e..82d89f6944b 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.hints.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.hints.tex @@ -10,13 +10,8 @@ \newcommand\printhints{% \begin{description} \ForEachUsedExerciseByType{% - \def\ExerciseType{##1}% - \def\ExerciseID{##2}% \GetExercisePropertyT{hint} - {% - \item[\XSIMmixedcase{\GetExerciseName}~##3] - ####1% - }% + {\item[\XSIMmixedcase{\GetExerciseName}~##3]####1}% }% \end{description} } diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.issues-49.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.issues-49.pdf new file mode 100644 index 00000000000..3ea1c70ace8 Binary files /dev/null and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.issues-49.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.issues-49.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.issues-49.tex new file mode 100644 index 00000000000..f9baf0a6015 --- /dev/null +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.issues-49.tex @@ -0,0 +1,122 @@ +\documentclass{article} +\usepackage{xsim} + +\xsimsetup{ + load-style = layouts , + exercise/template = runin , + solution/template = runin +} + +\usepackage{tasks,fontawesome,fmtcount,multicol} +\NewTasksEnvironment[label=\Alph*),label-width=12pt]{choices}[\choice] +\newcommand*\correct{\thetask\expanded{\SetExerciseProperty{choice}{\thetask}}} + +\NewTasksEnvironment[label=\Roman*,label-width=12pt]{options}[\option] + +\DeclareExerciseProperty{choice} + +\newcommand*\pkg[1]{\texttt{#1}} +\newcommand*\cls[1]{\texttt{#1}} + +\newcommand\EA[2]{\IfInsideSolutionTF{#2}{#1}} +\newcommand\answer[1]{\IfInsideSolutionT{#1}} + +\begin{document} + +\section{List of exercises} +Solve and answer the following exercises. + +\begin{exercise} + Factor $x^{2}-2x+1$ +\end{exercise} +\begin{solution} + $\left(x-1\right)^{2}$ +\end{solution} +\begin{exercise} + Factor $3x+3y+3z$ +\end{exercise} +\begin{solution} + $3(x+y+z)$ +\end{solution} + +\begin{exercise}[solution] + \EA{True or false?}{} + \begin{tasks}(2) + \task \EA{$\alpha > \delta$}{False} + \task \EA{\LaTeX2e\ is cool?}{Very True!} + \end{tasks} +\end{exercise} + +\begin{exercise}[subtitle=Talking Linux,solution] + \begin{tasks}(2) + \task \EA{You use linux?}{Yes} + \task \EA{Usually uses the package manager?}{Yes} + \end{tasks} +\end{exercise} + +\begin{exercise}[solution] + \EA{Rate the following \LaTeX\ packages and classes.}{} + \begin{tasks}(\EA{3}{1}) + \task \EA{\cls{xsim-exam}}{doesn't exist for now} + \task \EA{\pkg{xsim}}{very good} + \task \EA{\pkg{exsheets}}{obsolete} + \end{tasks} +\end{exercise} + +\begin{exercise} + \begin{choices}(5) + \choice value + \choice value + \choice value + \choice[\correct] correct + \choice value + \end{choices} +\end{exercise} +\begin{solution} + \GetExerciseProperty{choice} +\end{solution} + +\begin{exercise} + \begin{options}(3) + \option $2\alpha+2\delta=90^{\circ}$ + \option $\alpha=\delta$ + \option $\angle EDF=45^{\circ}$ + \end{options} + \begin{choices}(4) + \choice I only + \choice[\correct] II only + \choice I and II only + \choice I and III only + \choice I, II, and III + \end{choices} +\end{exercise} +\begin{solution} + \GetExerciseProperty{choice} +\end{solution} + +\begin{exercise} + \begin{tasks}[label=(\arabic*),label-width=13pt](2) + \task $2\alpha+2\delta=90^{\circ}$ + \task $\angle EDF=45^{\circ}$ + \end{tasks} + \begin{choices}(3) + \choice Alternative A + \choice Alternative B + \choice[\correct] Alternative C + \choice Alternative D + \choice Alternative E + \end{choices} +\end{exercise} +\begin{solution} + \GetExerciseProperty{choice} +\end{solution} + +\clearpage + +\section{Solutions} +\raggedcolumns +\begin{multicols}{2} + \printsolutions[headings=false] +\end{multicols} + +\end{document} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.listings.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.listings.pdf index 0d388f2c708..8383fd8b0c7 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.listings.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.listings.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.listings.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.listings.tex index 6dd302feb09..a5fe951bebf 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.listings.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.listings.tex @@ -3,7 +3,7 @@ \usepackage{xcolor} \usepackage{listings} -\usepackage{xsim} +\usepackage[use-files]{xsim} \lstset{ frame=single, diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.listofexercises.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.listofexercises.pdf index 8050ee8f90a..46bf9b89e4a 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.listofexercises.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.listofexercises.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.multiplechoice.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.multiplechoice.pdf index 02dac6c4df9..0e49066a701 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.multiplechoice.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.multiplechoice.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.pointsums.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.pointsums.pdf index aa822a1bd7a..225595afe3b 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.pointsums.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.pointsums.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.randomexercises.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.randomexercises.pdf index 773d34f495b..670825d54ab 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.randomexercises.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.randomexercises.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.randomexercises.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.randomexercises.tex index 60877b1a4ab..aafb3ddae10 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.randomexercises.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.randomexercises.tex @@ -1,10 +1,10 @@ \documentclass{article} \usepackage{xsim} -\DeclareExerciseCollection{foo} +\xsimsetup{collect} + +\begin{document} -\usepackage{filecontents} -\begin{filecontents*}{random.tex} \begin{exercise}[ID=A] exercise A \end{exercise} @@ -41,18 +41,10 @@ \begin{solution} solution F \end{solution} -\end{filecontents*} - -\begin{document} - -\collectexercises{foo} -\input{random.tex} -\collectexercisesstop{foo} \section*{Exercises} -\printrandomexercises[collection=foo,exclude=D]{3} +\printrandomexercises[collection=all exercises,exclude=D]{3} -\section*{Solutions} -\printsolutions* +\printsolutions \end{document} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-13635.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-13635.pdf index af889a6709f..ff493e35919 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-13635.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-13635.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-13635.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-13635.tex index 3b52ce46b24..c0d08a567f0 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-13635.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-13635.tex @@ -27,6 +27,8 @@ \DeclareExerciseCollection{prime numbers} \DeclareExerciseCollection{Zeta function} +\xsimsetup{collect} + \begin{document} \collectexercises{prime numbers} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-155630.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-155630.pdf index 6c9fc4482af..40bacabc8e8 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-155630.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-155630.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-155630.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-155630.tex index 2edb7bfdad2..015f52db0f9 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-155630.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-155630.tex @@ -3,10 +3,10 @@ \usepackage{xsim} \DeclareExerciseCollection{foo} +\xsimsetup{collect} \begin{document} -\collectexercises{foo} \begin{exercise} foo \end{exercise} @@ -16,7 +16,6 @@ \begin{exercise} baz \end{exercise} -\collectexercisesstop{foo} % shuffle around for a different version: \printexercise{exercise}{1} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-199360.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-199360.pdf index 94925495985..8c1d7cc9d59 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-199360.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-199360.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-299534.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-299534.pdf index c006aeb34c3..c9500e089fa 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-299534.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-299534.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-299534.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-299534.tex index 1c2be46df39..e330f3d256a 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-299534.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-299534.tex @@ -1,7 +1,7 @@ % http://tex.stackexchange.com/q/299534/ \documentclass{article} \usepackage{pythontex} -\usepackage{xsim} +\usepackage[use-files]{xsim} \begin{document} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-305110.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-305110.pdf index fb92e875a91..4b9558d90ff 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-305110.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-305110.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-308883.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-308883.pdf index eb27dce140c..02039dbc683 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-308883.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-308883.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-338165.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-338165.pdf index 4b5a09474d0..9e8168af2f5 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-338165.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-338165.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-338165.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-338165.tex index a0b204f914e..72ee108668d 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-338165.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-338165.tex @@ -10,26 +10,24 @@ \tcbuselibrary{breakable, skins} \settasks{ label = \arabic*. } -\DeclareExerciseEnvironmentTemplate{boxed} - {% - \tcolorbox[ - enhanced , - attach boxed title to top center = {yshift=-7.5pt} , - colback = white , colbacktitle = white , - coltitle = black , colframe = black , - boxed title style = { colframe = white } , - fonttitle=\bfseries, - sharp corners=all, - breakable, - title= - \XSIMmixedcase{\GetExerciseName}% - \IfInsideSolutionF{% - ~\GetExerciseProperty{counter}% - \IfExercisePropertySetT{subtitle}{: \GetExerciseProperty{subtitle}}% - }% - ] - } - {\endtcolorbox} +\DeclareExerciseEnvironmentTemplate{boxed}{% + \tcolorbox[ + enhanced , + attach boxed title to top center = {yshift=-7.5pt} , + colback = white , colbacktitle = white , + coltitle = black , colframe = black , + boxed title style = { colframe = white } , + fonttitle=\bfseries, + sharp corners=all, + breakable, + title= + \XSIMmixedcase{\GetExerciseName}% + \IfInsideSolutionF{% + ~\GetExerciseProperty{counter}% + \IfExercisePropertySetT{subtitle}{: \GetExerciseProperty{subtitle}}% + }% + ] +}{\endtcolorbox} \xsimsetup{ exercise/template = boxed , diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-350028.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-350028.pdf index 36645464fc0..2f58a0fde7f 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-350028.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-350028.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-350028.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-350028.tex index 8f49a92f600..f0d977a131e 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-350028.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-350028.tex @@ -5,48 +5,44 @@ \usepackage[most]{tcolorbox} \tcbuselibrary{skins,breakable} -\DeclareExerciseEnvironmentTemplate{tcolorbox} - {% - \tcolorbox[ - enhanced, - colframe=green!20!black, - colback=yellow!10!white, - coltitle=green!40!black, - fonttitle=\bfseries, - underlay={% - \begin{tcbclipinterior} - \shade[ - inner color=\IfInsideSolutionTF{red!50!yellow}{green!80!yellow}, - outer color=yellow!10!white] - (interior.north west) circle (2cm); - \draw[help lines,step=5mm,yellow!80!black,shift={(interior.north west)}] - (interior.south west) grid (interior.north east); - \end{tcbclipinterior}% - }, - attach title to upper=\quad, - title = \XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter} - \IfExercisePropertySetT{points}{% - (\GetExerciseProperty{points} - \IfExerciseGoalSingularTF{points} - {\XSIMtranslate{point}} - {\XSIMtranslate{points}})% - }]% - \IfInsideSolutionT{\label{solution:\ExerciseID}}% - } - {% - \endtcolorbox - \vspace*{\baselineskip} - \IfInsideSolutionTF - {% - \noindent Exercise~\GetExerciseProperty{counter} is on - page~\GetExerciseProperty{page}.% - } - {% - \noindent The solution of this exercise is on - page~\pageref{solution:\ExerciseID}.% - }% - \vspace{\baselineskip} - } +\DeclareExerciseEnvironmentTemplate{tcolorbox}{% + \tcolorbox[ + enhanced, + colframe=green!20!black, + colback=yellow!10!white, + coltitle=green!40!black, + fonttitle=\bfseries, + underlay={% + \begin{tcbclipinterior} + \shade[ + inner color=\IfInsideSolutionTF{red!50!yellow}{green!80!yellow}, + outer color=yellow!10!white] + (interior.north west) circle (2cm); + \draw[help lines,step=5mm,yellow!80!black,shift={(interior.north west)}] + (interior.south west) grid (interior.north east); + \end{tcbclipinterior}% + }, + attach title to upper=\quad, + title = \XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter} + \IfExercisePropertySetT{points}{% + (\GetExerciseProperty{points} + \IfExerciseGoalSingularTF{points} + {\XSIMtranslate{point}} + {\XSIMtranslate{points}})% + }]% + \IfInsideSolutionT{\label{solution:\ExerciseID}}% +}{% + \endtcolorbox + \vspace*{\baselineskip} + \IfInsideSolutionTF{% + \noindent Exercise~\GetExerciseProperty{counter} is on + page~\GetExerciseProperty{page}.% + }{% + \noindent The solution of this exercise is on + page~\pageref{solution:\ExerciseID}.% + }% + \vspace{\baselineskip} +} \xsimsetup{ exercise/template = tcolorbox , diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369065.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369065.pdf index 6aa9ab572bb..fea54f626b2 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369065.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369065.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369065.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369065.tex index b62b85127a4..f35149c8ea1 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369065.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369065.tex @@ -11,28 +11,24 @@ solution/print=true } -\DeclareExerciseEnvironmentTemplate{cyan-box} - {% - \begin{tcolorbox}[arc=0mm,boxrule=1pt,colback=white,colframe=cyan,leftrule=3mm] - \textsf{% - \MakeUppercase{% - \XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}% - }% +\DeclareExerciseEnvironmentTemplate{cyan-box}{% + \begin{tcolorbox}[arc=0mm,boxrule=1pt,colback=white,colframe=cyan,leftrule=3mm] + \textsf{% + \MakeUppercase{% + \XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}% }% - \GetExercisePropertyT{subtitle}{ \textit{#1}}% - \quad - } - {\end{tcolorbox}} - -\DeclareExerciseEnvironmentTemplate{red} - {% - \par - \Needspace*{2\baselineskip} - \noindent - \textsf{\textcolor{red}{\MakeUppercase{\XSIMmixedcase{\GetExerciseName}}}}% + }% + \GetExercisePropertyT{subtitle}{ \textit{#1}}% \quad - } - {\par\bigskip} +}{\end{tcolorbox}} + +\DeclareExerciseEnvironmentTemplate{red}{% + \par + \Needspace*{2\baselineskip} + \noindent + \textsf{\textcolor{red}{\MakeUppercase{\XSIMmixedcase{\GetExerciseName}}}}% + \quad +}{\par\bigskip} \begin{document} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369636.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369636.pdf index 2bc106f3035..96bd157b683 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369636.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369636.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369636.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369636.tex index e13b8653f4c..73ab7868f63 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369636.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369636.tex @@ -5,7 +5,6 @@ \usepackage[T1]{fontenc} \usepackage{fourier} \usepackage{tgpagella} -\usepackage[utf8]{inputenc} \usepackage{xsim,needspace,adjustbox,scrextend} @@ -14,20 +13,18 @@ exercise/template = square } -\DeclareExerciseEnvironmentTemplate{square} - {% - \Needspace*{2\baselineskip}% - \addmargin[0pt]{.15\textwidth}% - \par\noindent - \adjustbox{ - fbox = 1pt 0pt, - lap = {\textwidth}, - valign = t, - set vsize = {0pt}{0pt} - }{\rule{0pt}{20pt}\hspace{20pt}}% - \textbf{\GetExerciseProperty{counter}} % - } - {\endaddmargin\vspace{\baselineskip}} +\DeclareExerciseEnvironmentTemplate{square}{% + \Needspace*{2\baselineskip}% + \addmargin[0pt]{.15\textwidth}% + \par\noindent + \adjustbox{ + fbox = 1pt 0pt, + lap = {\textwidth}, + valign = t, + set vsize = {0pt}{0pt} + }{\rule{0pt}{20pt}\hspace{20pt}}% + \textbf{\GetExerciseProperty{counter}} % +}{\endaddmargin\vspace{\baselineskip}} \usepackage{lipsum} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369803.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369803.pdf index 73eab39f10b..3e5f8d663b1 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369803.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369803.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369803.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369803.tex index 58b6800f937..e91e795353d 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369803.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-369803.tex @@ -1,6 +1,5 @@ % https://tex.stackexchange.com/q/369803 \documentclass[a4paper,parskip=half]{scrartcl} -\usepackage[utf8]{inputenc} \usepackage[ngerman]{babel} \usepackage{amsmath} @@ -12,19 +11,16 @@ \usepackage{xsim,siunitx} \DeclareExerciseTagging{difficulty} -\DeclareExerciseEnvironmentTemplate{custom} - {% - \subsection* - {% - \XSIMmixedcase{\GetExerciseName}\nobreakspace - \GetExerciseProperty{counter}% - \IfInsideSolutionF - {% - \IfExercisePropertySetT{subtitle} - { {\normalfont(\GetExerciseProperty{subtitle})}}% - }% - }% - }{} +\DeclareExerciseEnvironmentTemplate{custom}{% + \subsection*{% + \XSIMmixedcase{\GetExerciseName}\nobreakspace + \GetExerciseProperty{counter}% + \IfInsideSolutionF{% + \IfExercisePropertySetT{subtitle} + { {\normalfont(\GetExerciseProperty{subtitle})}}% + }% + }% +}{} \xsimsetup{ exercise/name = \XSIMtranslate{question} , diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-370642.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-370642.pdf index 13933e80c3b..7d70b52d3ac 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-370642.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-370642.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-391530-exercises.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-391530-exercises.tex new file mode 100644 index 00000000000..716921adc01 --- /dev/null +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-391530-exercises.tex @@ -0,0 +1,12 @@ +\begin{question} + Who is the Defence Minister? +\end{question} +\begin{question} + Who is the Home Minister? +\end{question} +\begin{question} + Who is the Finance Minister? +\end{question} +\begin{question} + Who is the External Affairs Minister? +\end{question} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-391530.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-391530.pdf index 137c8587693..1446d0345e3 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-391530.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-391530.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-391530.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-391530.tex index 1deafe5fb00..2d76cae57ed 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-391530.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-391530.tex @@ -14,28 +14,23 @@ \DeclareExerciseProperty{title} \makeatletter -\DeclareExerciseEnvironmentTemplate{named} - {% - \subsection*{% - \GetExercisePropertyTF{title} - {#1} - {??\@latex@warning{Please give an exercise title}}% - }% - } - {} +\DeclareExerciseEnvironmentTemplate{named}{% + \subsection*{% + \GetExercisePropertyTF{title} + {#1} + {??\@latex@warning{Please give an exercise title}}% + }% +}{} \makeatother -\DeclareExerciseEnvironmentTemplate{item} - {\item} - {} - +\DeclareExerciseEnvironmentTemplate{item}{\item}{} \DeclareExerciseCollection{exercise-pool} -\xsimsetup{ - exercise/template = named -} +\xsimsetup{ exercise/template = named } -\begin{filecontents*}{\jobname-exercises.tex} +\begin{document} + +\collectexercises{exercise-pool} \begin{question} Who is the Defence Minister? \end{question} @@ -48,12 +43,6 @@ \begin{question} Who is the External Affairs Minister? \end{question} -\end{filecontents*} - -\begin{document} - -\collectexercises{exercise-pool} -\input{\jobname-exercises.tex} \collectexercisesstop{exercise-pool} \begin{exercise}[title=Answer the following in one sentence:] diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-395273.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-395273.pdf index c3796c8ee0c..056b14e833d 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-395273.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-395273.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-466584.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-466584.pdf new file mode 100644 index 00000000000..83c20f646b6 Binary files /dev/null and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-466584.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-466584.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-466584.tex new file mode 100644 index 00000000000..1f30d3c1b8d --- /dev/null +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-466584.tex @@ -0,0 +1,56 @@ +% https://tex.stackexchange.com/q/466584 +\documentclass{article} +\usepackage{xsim} +\usepackage{needspace} +\usepackage{tasks} + +\DeclareExerciseEnvironmentTemplate{exandsol}{% + \par\vspace{\baselineskip} + \Needspace*{2\baselineskip} + \noindent\sffamily + \textbf{\XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}}% + \GetExercisePropertyT{subtitle}{\hspace{3em}{\small#1}}\par + \normalfont +}{} + +\DeclareExerciseEnvironmentTemplate{flushright}{% + \begin{flushright} + \begin{minipage}{.4\linewidth} + \textsf{Solutions:}\par\normalfont +}{% + \end{minipage}% + \end{flushright}% +} + +\xsimsetup{ + exercise/within = section , + exercise/template = exandsol , + solution/template = flushright , + solution/print = true +} + +\renewcommand*\theexercise{\thesection-\arabic{exercise}} +\newcommand\QA[2]{\IfInsideSolutionTF{#2}{#1}} + +\newcommand*\answer[1]{% + \begingroup + \def\ExerciseType{exercise}% + \IfSolutionPrintT{\printsolution{exercise}{#1}}% + \endgroup +} + +\begin{document} + +\setcounter{section}{1} +\setcounter{exercise}{30} + +\begin{exercise}[ID=one,solution,subtitle=Factorize as much as possible the following expressions.] + \begin{tasks} + \task \QA{$(2x-3)^2 - (3x-2)^2 =$}{$-(x+5)(5x-1)$} + \task \QA{$(x^2-25) - 2(5-x)(x+6) =$}{$(x+5)(3x-17)$} + \task \QA{$2x(x+2) + (x+1)^2 + 2 =$}{$3(x+1)^2$} + \end{tasks} +\end{exercise} +\answer{one} + +\end{document} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-498299.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-498299.pdf index 99e8314406f..41c97e72546 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-498299.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-498299.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-498299.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-498299.tex index 6716d52e7e7..6b37b4c5186 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-498299.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-498299.tex @@ -1,3 +1,4 @@ +% https://tex.stackexchange.com/q/498299 \documentclass{article} \usepackage[no-files]{xsim} \usepackage{tasks} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-576998.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-576998.pdf new file mode 100644 index 00000000000..b3aa8369269 Binary files /dev/null and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-576998.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-576998.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-576998.tex new file mode 100644 index 00000000000..ee2947bbb53 --- /dev/null +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-576998.tex @@ -0,0 +1,135 @@ +% https://tex.stackexchange.com/q/576998 +\documentclass[twocolumn]{book} +\usepackage{xsim} + +\DeclareExerciseEnvironmentTemplate{number-only}{% + \par\noindent + \textbf{\GetExerciseProperty{counter}}% + \GetExercisePropertyT{subtitle}{ \textit{#1}} % +}{\par} + +\newcommand\printsectionexercises{% + \ForEachUsedExerciseByType{% + \ifnum\ExercisePropertyGet{##1}{##2}{chapter-value}=\value{chapter} + \ifnum\ExercisePropertyGet{##1}{##2}{section-value}=\value{section} + \XSIMprint{exercise}{##1}{##2}% + \fi + \fi + }% +} + +\renewcommand\printsolutions{% + \def\currentchapter{}% + \def\currentsection{}% + \def\lastchapter{}% + \def\lastsection{}% + \ForEachUsedExerciseByType{% + \let\lastchapter\currentchapter + \let\lastsection\currentsection + \edef\currentchapter{\ExercisePropertyGet{##1}{##2}{chapter-value}}% + \edef\currentsection{\ExercisePropertyGet{##1}{##2}{section-value}}% + \ifx\lastchapter\currentchapter\else + \section*{Chapter \ExercisePropertyGet{##1}{##2}{chapter}} + \fi + \ifx\lastsection\currentsection\else + \subsection*{Exercises \ExercisePropertyGet{##1}{##2}{section}} + \fi + \XSIMprint{solution}{##1}{##2}% + }% +} + +\xsimsetup{ + exercise/template = number-only , + solution/template = number-only , + exercise/within = section , + exercise/the-counter = \arabic{exercise}. , + exercise/print = false +} + +\begin{document} + +\setcounter{chapter}{13} +\chapter{} +\section{Cats as pets} +Text text text\dots +\begin{exercise} + Draw a cat. +\end{exercise} +\begin{solution} + Drawing a cat. +\end{solution} + +Text text text\dots +\begin{exercise} + Bathe a cat. +\end{exercise} +\begin{solution} + Bathing a cat. +\end{solution} + +Text text text\dots +\begin{exercise} + Trace the history of cats through time. +\end{exercise} +\begin{solution} + Tracing the history of cats through time. +\end{solution} + +\subsection*{Exercises \thesection} +\printsectionexercises + +\section{Frogs as pets} +Text text text\dots +\begin{exercise} + Lick a frog. +\end{exercise} +\begin{solution} + Licking a frog. +\end{solution} + +Text text text\dots +\begin{exercise} + Bathe a frog. +\end{exercise} +\begin{solution} + Bathing a frog. +\end{solution} + +Text text text\dots +\begin{exercise} + Feed a frog. +\end{exercise} +\begin{solution} + Feeding a frog. +\end{solution} + +\subsection*{Exercises \thesection} +\printsectionexercises + +\setcounter{chapter}{20} +\chapter{} + +\section{The joys of fish} +Text text text\dots +\begin{exercise} + Catch a fish. +\end{exercise} +\begin{solution} + Catching a fish. +\end{solution} + +Text text text\dots +\begin{exercise} + Draw a fish. +\end{exercise} +\begin{solution} + Drawing a fish. +\end{solution} + +\subsection*{Exercises \thesection} +\printsectionexercises + +\chapter*{Solutions to the exercises} +\printsolutions + +\end{document} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-580636.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-580636.pdf new file mode 100644 index 00000000000..d51eb48607c Binary files /dev/null and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-580636.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-580636.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-580636.tex new file mode 100644 index 00000000000..a6f2be66513 --- /dev/null +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texsx-580636.tex @@ -0,0 +1,92 @@ +% https://tex.stackexchange.com/q/580636/ +\documentclass{article} +\usepackage[use-files]{xsim} + +\usepackage[colorlinks,allcolors=blue]{hyperref} + +\DeclareExerciseProperty{hints} +\newcounter{hint} +\renewcommand\theHhint{\ExerciseID.\arabic{hint}} +\newcounter{hints} +\newcounter{step} + +\NewDocumentEnvironment{hint}{}{% + \stepcounter{hint}% + \XSIMsetfilebegin{% + \par + \refstepcounter{hint}\label{hint:\ExerciseID:\arabic{hint}}% + \noindent\textbf{Hint~\thehint\ to exercise \GetExerciseProperty{counter}}% + \hfill Back to exercise \ref{ex:\ExerciseID}\par + \noindent + }% + \XSIMsetfileend{\par\addvspace{\bigskipamount}}% + \XSIMfilewritestart{\jobname-hint-\ExerciseID-\arabic{hint}.tex}% +}{% + \XSIMfilewritestop + \stepcounter{hints}% + \SetExpandedExerciseProperty{hints}{\arabic{hints}}% +} + +\DeclareExerciseEnvironmentTemplate{hints}{% + \setcounter{hint}{0}% + \setcounter{hints}{0}% + \par\noindent + \textbf{\XSIMmixedcase{\GetExerciseName}\GetExerciseProperty{counter}:}\hfill + \IfExercisePropertySetT{hints}{% + \setcounter{step}{0}% + \def\hintcomma{\def\hintcomma{, }}% + Hint\ifnum\GetExerciseProperty{hints}=1\else s\fi: + \loop\unless\ifnum\value{step}=\GetExerciseProperty{hints} + \stepcounter{step}% + \hintcomma\ref{hint:\ExerciseID:\arabic{step}}% + \repeat + \par\noindent + }% +}{\par\addvspace{\bigskipamount}} + +\xsimsetup{ + exercise/within = section , + exercise/begin-hook = \label{ex:\ExerciseID} , + exercise/template = hints +} + +\newcommand\printhints{% + \ForEachUsedExerciseByType{% + \setcounter{step}{0}% + \setcounter{hint}{0}% + \loop\unless\ifnum\value{step}=\GetExerciseProperty{hints} + \stepcounter{step}% + \input{\jobname-hint-\ExerciseID-\arabic{step}.tex}% + \repeat + }% +} + +\begin{document} + +\section{Exercises} +\begin{exercise} + Description of the exercise. Run the following command +\begin{verbatim} +print("Hello world") +Verbatim &^%$&\content +\end{verbatim} +\begin{hint} + Run the example from the command line with the python command. +\end{hint} +\begin{hint} + The solution is 42. +\end{hint} +\end{exercise} + +\begin{exercise} + Another exercise +\begin{hint} + The first ten million years were the worst. Some \verb+&$+. +\end{hint} +\end{exercise} + + +\section{Hints} +\printhints + +\end{document} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-15093.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-15093.pdf index 3dc9fb16494..b58d9595999 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-15093.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-15093.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-15093.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-15093.tex index 1f3fcfefcb7..d003cc03afa 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-15093.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-15093.tex @@ -1,6 +1,5 @@ % http://texwelt.de/wissen/fragen/15093/ \documentclass[paper=a4]{scrartcl} -\usepackage[utf8]{inputenc} \usepackage[ngerman]{babel} \usepackage{xsim,needspace} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-23968.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-23968.pdf index e9816a97930..ac8b2c3d399 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-23968.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-23968.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-23968.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-23968.tex index bf205bb7fb5..5203bdee8ad 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-23968.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-23968.tex @@ -18,13 +18,8 @@ \newcommand\printshortsolutions{% \begin{description} \ForEachUsedExerciseByType{% - \def\ExerciseType{##1}% - \def\ExerciseID{##2}% \GetExercisePropertyT{shortsolution} - {% - \item[Short Solution ##3] - ####1% - }% + {\item[Short Solution ##3]####1}% }% \end{description} } diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-6698.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-6698.pdf index 000663bf445..f8b96093281 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-6698.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-6698.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-6698.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-6698.tex index 9e388b9f690..51523e8bcd1 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-6698.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.texwelt-6698.tex @@ -1,6 +1,5 @@ % http://texwelt.de/wissen/fragen/6698/ \documentclass{article} -\usepackage[utf8]{inputenc} \usepackage[ngerman]{babel} \usepackage{needspace} diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.various.pdf b/Master/texmf-dist/doc/latex/xsim/examples/xsim.various.pdf index d0406e830ce..aba5075c388 100644 Binary files a/Master/texmf-dist/doc/latex/xsim/examples/xsim.various.pdf and b/Master/texmf-dist/doc/latex/xsim/examples/xsim.various.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/examples/xsim.various.tex b/Master/texmf-dist/doc/latex/xsim/examples/xsim.various.tex index 1b7b13f98b3..55430103246 100644 --- a/Master/texmf-dist/doc/latex/xsim/examples/xsim.various.tex +++ b/Master/texmf-dist/doc/latex/xsim/examples/xsim.various.tex @@ -1,5 +1,6 @@ \documentclass{article} -\usepackage{xsim,lipsum,tcolorbox} +\usepackage[use-files]{xsim} +\usepackage{lipsum,tcolorbox} \DeclareExerciseType{question}{ exercise-env = question , diff --git a/Master/texmf-dist/doc/latex/xsim/xsim-manual.pdf b/Master/texmf-dist/doc/latex/xsim/xsim-manual.pdf new file mode 100644 index 00000000000..93245d124d2 Binary files /dev/null and b/Master/texmf-dist/doc/latex/xsim/xsim-manual.pdf differ diff --git a/Master/texmf-dist/doc/latex/xsim/xsim-manual.tex b/Master/texmf-dist/doc/latex/xsim/xsim-manual.tex new file mode 100644 index 00000000000..329f602acf5 --- /dev/null +++ b/Master/texmf-dist/doc/latex/xsim/xsim-manual.tex @@ -0,0 +1,2439 @@ +% !arara: pdflatex: { interaction: nonstopmode } +% !arara: biber +% arara: pdflatex: { interaction: nonstopmode } +% arara: pdflatex: { interaction: nonstopmode } +% !arara: pdflatex: { interaction: nonstopmode } +% ---------------------------------------------------------------------------- +% the XSIM package +% +% eXercise Sheets IMproved +% +% ---------------------------------------------------------------------------- +% Clemens Niederberger +% Web: https://github.com/cgnieder/xsim +% E-Mail: contact@mychemistry.eu +% ---------------------------------------------------------------------------- +% Copyright 2017--2021 Clemens Niederberger +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3c +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2008/05/04 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Clemens Niederberger. +% ---------------------------------------------------------------------------- +% If you have any ideas, questions, suggestions or bugs to report, please +% feel free to contact me. +% ---------------------------------------------------------------------------- +\documentclass{xsim-manual} + +\begin{filecontents*}[overwrite]{\jobname.bib} +@online{texsx:tagged/exsheets, + title = {Questions tagged `exsheets'} , + author = {various} , + url = {http://tex.stackexchange.com/questions/tagged/exsheets} , + urldate = {2020-02-21} +} +\end{filecontents*} +\addbibresource{\jobname.bib} + +\begin{document} + +\section{Licence, Requirements and \texorpdfstring{\textsc{readme}}{README}} +\license + +\xsim\ loads the packages \pkg{expl3}~\cite{bnd:l3kernel}, +\pkg{xparse}~\cite{bnd:l3packages}, \pkg{array}~\cite{pkg:array} +\pkg{booktabs}~\cite{pkg:booktabs} and +\pkg{translations}~\cite{pkg:translations}. All of these packages are present +on a modern and up to date \TeX\ distribution such as \TeX~Live or MiK\TeX\ so +no further action should be needed. When you are using \xsim\ you should be +using an up to date \TeX\ distribution, anyway. + +\begin{bewareofthedog} + Please be aware that \xsim\ is in an experimental state and actively + developed. Many aspects may change from one update to another until a + stable version~1 will be reached. However, I will try my best to keep the + interface stable. + + Newer versions of \xsim\ may depend on newer versions of the support + packages. Remember: it is always dangerous to update single packages. + Always update your \TeX\ distribution if you want an up to date version of a + package. Be careful: if you're in the middle of an important project it + might be better to wait with the update until you've finished the project. + Every update might be breaking some things. +\end{bewareofthedog} + +\section{Motivation, Background} + +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 (151~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. + +This is due to several facts. It lacks a few features which I consider +essential for a full version~1. For one thing it is not possible to have +several kinds of exercises numbered independently. Using verbatim material +such as listings inside exercises and solutions is not possible and the +current workaround isn't that ideal either. One request which dates back +quite a while now was to have different types of points to exercises\ldots + +All of those aren't easy to add due to the way \pkg{exsheets} is implemented +right now. As a consequence I wanted to re-implement \pkg{exsheets} for a long +time. This is what lead to \xsim. Internally the package works completely +different. + +\begin{bewareofthedog} + \xsim\ will be the official successor of \pkg{exsheets} which is now + considered obsolete but will stay alive and will still receive bugfix + releases. However, new features will not be added to \pkg{exsheets} any + more. +\end{bewareofthedog} + +\section{How to Read the Manual}\label{sec:how-read-manual} + +\subsection{Nomenclature} + +Throughout this manual certain terms are used. This section explains their +meaning in this manual. + +\acuseall +\printacronyms[heading=none] + +\subsection{Package Options}\label{sec:package-options} +\xsim\ has these package options: +\begin{options} + \opt{verbose} + Writes extensive information about what \xsim\ is doing into the log + file. + \opt{final} + If used the exercise and solution environments will not rewrite the + environment body files. + \opt{clear-aux} + If used every time the total number of exercise changes \xsim\ will write + \emph{less} information to the auxiliary file on the next run and only if + the number of exercises stays stable between compilations the needed + information will be written to the auxiliary file. \emph{This needs more + compilations until everything stabilizes but should reduce the + probability of possibly faulty exercises after changes to the document.} + The \option{final} option automatically disables this option. See also + sections~\vref{sec:how-exerc-envir} and~\vref{sec:resolve-getting}. + \opt{no-files}\Default{true} + \sinceversion{0.13}This option prevents \xsim\ from writing the exercises + and solutions to external files. This will keep your working folder + ``clean'' but will also prevent using verbatim material in exercises and + solutions. + \opt{use-files}\Default{false} + \sinceversion{0.20}This is the opposite of the option \option{no-files}. + \opt{use-aux} + \sinceversion{0.15}With this option enabled \xsim\ will use the regular + auxiliary file \cs*{jobname}\code{.aux} instead of its own auxiliary file + \cs*{jobname}\code{.xsim}. + \opt{blank} + \sinceversion{0.17}With this option enabled \xsim\ will not define the + default environments \env{exercise} and \env{solution}. +\end{options} + +Those options are load-time options and are used the usual way as package +options: +\begin{sourcecode} + \usepackage[use-files]{xsim} +\end{sourcecode} +\begin{bewareofthedog} + Although those options technically belong to the \module{package} module + (see also section~\vref{sec:setting-options}) it is \emph{not} possible to + set them via \cs{xsimsetup}. +\end{bewareofthedog} + +\subsection{Setting Options}\label{sec:setting-options} +Apart from the package options already described in +section~\vref{sec:package-options} \xsim\ has further options. All those +options are set using the following command: +\begin{commands} + \command{xsimsetup}[\marg{options}] + Set up \xsim's package options and all other options described at + other places in the manual. +\end{commands} +Options can be \enquote{toplevel} options or options belonging to a module: +\begin{options} + \keyval*{toplevel}{value} + A toplevel option. + \keyval*{sublevel}{value}\Module*{module} + A sublevel option belonging to the module \module*{module} +\end{options} +Both kinds of options are set with the setup command: +\begin{sourcecode} + \xsimsetup{ + toplevel = {value} , + module/sublevel = {value} + } +\end{sourcecode} + +\subsection{Command descriptions} + +Some commands do have a \expandablesymbol\ symbol printed next to their +names. This indicates that the command is expandable, \ie, it is usable in an +\cs*{edef} or \cs*{write} context and will expand according to its +description. All other commands are engine protected, \ie, in the sense of +\eTeX's \cs*{protected}. + +Some command name descriptions end with \code{\TF}. +\begin{commands} + \command*{SomeCommand\TF}[\meta{arguments}\marg{true}\marg{false}] + A command with maybe some arguments and ending with the two arguments + \meta{true} and \meta{false}. +\end{commands} +This means two things: the command is a conditional which tests something and +depending on the outcome of the test leaves either the \meta{true} argument +(\code{T}) or the \meta{false} argument (\code{F}) in the input stream. It +also means two additional commands exist: +\begin{commands} + \command*{SomeCommandT}[\meta{arguments}\marg{true}] + The same as \cs*{SomeCommandTF} but only with the \meta{true} argument and + no \meta{false} argument. + \command*{SomeCommandF}[\meta{arguments}\marg{false}] + The same as \cs*{SomeCommandTF} but only with the \meta{false} argument and + no \meta{true} argument. +\end{commands} + +\section{Exercises and Solutions} + +The two predefined environments for exercises and solutions are the following +ones\footnote{When you load \xsim\ with the \option{blank} those environments + will \emph{not} be defined!}: +\begin{environments} + \environment{exercise}[\oarg{\acsp*{prop}}] + Input and typeset an exercise. See section~\vref{sec:exercise-properties} + for details on exercise \acsp*{prop}. + \environment{solution}[\oarg{options}] + Input and typeset the solution to the exercise of the previous + \env{exercise} environment. See section~\vref{sec:printing-solutions} for + details on options of solutions. +\end{environments} + +\begin{example} + \begin{exercise} + A first example for an exercise. + \end{exercise} + \begin{solution} + A first example for a solution. + \end{solution} +\end{example} + +As can be seen in the example a solution is not printed with the default +setup. This can be changed using the following option. +\begin{options} + \keybool{print}\Module{solution}\Default{false} + Set if solutions are printed or not. +\end{options} + +The option (belonging to the module \module*{solution}) can either be set +locally as option to the \env{solution} environment +\begin{sourcecode} + \begin{solution}[print=true] + A first example for a solution. + \end{solution} +\end{sourcecode} +or with the setup command for all following solutions: +\begin{sourcecode} + \xsimsetup{ + solution/print = true + } +\end{sourcecode} + +There is an completely analoguous option for the \env{exercise} environment: +\begin{options} + \keybool{print}\Module{exercise}\Default{true} + Set if exercises are printed or not. +\end{options} +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} +\sinceversion{0.13}Depending on the options +\option{no-files}/\option{use-files} the bodies of exercises and solutions is +either just another property (see section~\vref{sec:exercise-properties}) -- +this is the default behavior -- or is written to an external file. + +If the option \keyis{no-files}{true} is set the exercise and solution bodies +are saved as properties \property{exercise-body} and +\property{solution-body}. This is the default behavior of \xsim\ since +version~0.20 and should work fine in most cases. One obvious downsise is that +verbatim material cannot be used in exercises and solutions. + +If the option \keyis{use-files}{true} is set both the exercise and the +solution environments 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} +\end{itemize} +The name starts with the name of the job (which is the name of the document +itself) followed by type and id of the corresponding exercise and then +followed by the environment type. For example both environments from the first +example have been written to files named +\begin{itemize} + \item \verbcode+xsim-manual-exercise-1-exercise-body.tex+ and + \item \verbcode+xsim-manual-exercise-1-solution-body.tex+, respectively. +\end{itemize} +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. 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} + +Arguably one downside of the approach using external files for each exercise +and its solution is that your project folder will be cluttered with files. In +order to deal with this somehow \xsim\ offers the following option: +\begin{options} + \keyval{path}{path name}\Default + With this option a subfolder or path within the main project folder can be + 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 + external files. +\end{options} + +\begin{bewareofthedog} + Another thing to keep in mind: the environment in many ways works the same + way as the \env{filecontents} environment. \emph{This also means that you + \emph{cannot} have comments or \cs*{label}s or anything else on the first + line of the environments!} +\end{bewareofthedog} +\begin{sourcecode} + \begin{exercise}[points=2] % this comment will cause trouble + Lorem ipsum + \end{exercise} +\end{sourcecode} + +\begin{bewareofthedog} + \xsimauxfileinfo +\end{bewareofthedog} + +\begin{bewareofthedog} + A lot of the lines \xsim\ writes to the auxiliary file 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 \code{||}. This means that you cannot use this symbol + combination inside properties. For this reason \xsim\ provides an option to + change the 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 auxiliary file. +\end{options} + +\section{New Exercise Types}\label{sec:new-exercise-types} + +It is easy to define new exercise environments together with a corresponding +solution environment using the following command: +\begin{commands} + \command{DeclareExerciseType}[\marg{type}\marg{parameters}] + Declare a new exercise type analoguous to the \env{exercise} and + \env{solution} environments. +\end{commands} +Declaring a new exercise type will also define a new command: +\begin{commands} + \command{numberof\meta{exercise-env}s} + These commands hold the absolut number of used exercises of type + \meta{type}. The meaning of \meta{exercise-env} will become clear below + when the exercise parameters are explained. It is always the same as the + exercise environment name. +\end{commands} +\begin{example} + There are \numberofexercises~exercises and \numberofproblems~problem in this + manual. +\end{example} +\xsim's pre-defined environment pair\changedversion{0.14} has been defined as +follows: +\begin{sourcecode} + \DeclareExerciseType{exercise}{ + exercise-env = exercise , + solution-env = solution , + exercise-name = \XSIMtranslate{exercise} , + exercises-name = \XSIMtranslate{exercises} , + solution-name = \XSIMtranslate{solution} , + solutions-name = \XSIMtranslate{solutions} , + exercise-template = default , + solution-template = default , + exercise-heading = \subsection* , + solution-heading = \subsection* + } +\end{sourcecode} + +The above already is an example for almost all parameters that can (and often +must) be set. Here is the complete list: +\begin{parameters} + \paraval{exercise-env}{exercise environment name} + The name for the environment used for the exercises of type \meta{type}. + \emph{This parameter is mandatory.} It can't be changed afterwards. + \paraval{solution-env}{solution environment name} + The name for the environment used for the solutions of type \meta{type}. + \emph{This parameter is mandatory.} It can't be changed afterwards. + \paraval{exercise-name}{exercise name} + The name of the exercises of type \meta{type} -- used for typesetting. + \emph{This parameter is mandatory.} + \paraval{exercises-name}{exercises name} + The\sinceversion{0.12} plural name of the exercises of type \meta{type} -- + used for typesetting. If this is not set explicitly an \code{s} is + appended to the singular name. + \paraval{solution-name}{solution name} + The name of the solutions of type \meta{type} -- used for typesetting. + \emph{This parameter is mandatory.} + \paraval{solutions-name}{solutions name} + The\sinceversion{0.12} plural name of the solutions of type \meta{type} -- + used for typesetting. If this is not set explicitly an \code{s} is + appended to the singular name. + \paraval{exercise-template}{exercise template} + The template used for typesetting the exercises of type \meta{type}. + \emph{This parameter is mandatory.} See + section~\vref{sec:styl-exerc-templ} for details on templates. + \paraval{solution-template}{solution template} + The template used for typesetting the exercises of type \meta{type}. + \emph{This parameter is mandatory.} See + section~\vref{sec:styl-exerc-templ} for details on templates. + \paraval{counter}{counter name} + The counter used for the exercises of type \meta{type}. If not explicitly + set the counter with the same name as \parameter{exercise-env} is used. + Otherwise the specified counter is used. This enables to have different + types of exercises sharing a common counter. \emph{This parameter can't + be changed afterwards.} If the explicit or implicit counter does not + exist, yet, it will be defined. + \paraval{within}{counter name} + \sinceversion{0.20}Adds \parameter{counter} to the reset list of + \meta{counter name} by applying \cs*{counterwithin}. + \paraval{the-counter}{code} + \sinceversion{0.20}Redefines the corresponding representation command + \cs*{the...} of \parameter{counter} to \meta{code}. + \paraval{solution-counter}{counter name} + The counter used for the solutions of type \meta{type}. If not explicitly + set the counter with the same name as \parameter{solution-env} is used. + Otherwise the specified counter is used. This enables to have different + types of solutions sharing a common counter although this doesn't actually + make much sense. But it can be useful to avoid using an already existing + counter. \emph{This parameter can't be changed afterwards.} If the + explicit or implicit counter does not exist, yet, it will be defined. The + sole purpose of this counter is to be able to label solutions so they can + be \cs*{pageref}ed. + \paraval{number}{integer} + An internal parameter that is used to keep track of the number of + exercises of a type. This parameter cannot be set or changed by the + user. + \paraval{exercise-heading}{exercise heading command} + The\sinceversion{0.14} command used for typesetting of the heading of + exercises of type \meta{type} -- used for typesetting with the command + \cs{GetExerciseHeadingF}. + \paraval{solution-heading}{solution heading command} + The\sinceversion{0.14} command used for typesetting of the heading of + solutions of type \meta{type} -- used for typesetting with the command + \cs{GetExerciseHeadingF}. +\end{parameters} + +It is possible to change some of the parameters after an exercise type has +been defined. Those include \parameter{exercise-name}, +\parameter{solution-name}, \parameter{exercise-template}, and +\parameter{solution-template}. It is also possible to define new parameters. +\begin{commands} + \command{DeclareExerciseParameter}[\sarg\marg{parameter}] + Declares the new parameter \meta{parameter}. The optional star declares a + fixed parameter which cannot be changed once it is set. \emph{You + probably will never need this command. Most tasks can be solved using + properties (see section~\vref{sec:exercise-properties}) instead.} + \command{SetExerciseParameter}[\marg{type}\marg{parameter}\marg{value}] + Usable to set a single parameter to a new value. + \command{SetExerciseParameters}[\marg{type}\marg{parameters}] + Set several parameters at once. \meta{parameters} is a csv list of + key/value pairs. +\end{commands} +If you try to set an already set but fixed parameter like +\parameter{exercise-env} a warning will be written to the log file. For all +parameters that can be changed also options exist wich can be set via +\cs{xsimsetup}. They are explained in +section~\vref{sec:environment-options-hooks}. + +\begin{bewareofthedog} + All exercises of a type use the parameters + (\eg, \parameter{exercise-template}) that are \emph{currently active}. If + you want exercises with a different look or different names in the same + document you should use different exercises types. +\end{bewareofthedog} + +\section{Exercise Properties}\label{sec:exercise-properties} + +\subsection{Predefined Properties} + +Exercise like the \env{exercise} environment and possibly others defined with +\cs{DeclareExerciseType} have a number of predefined \acsp*{prop}: +\begin{properties} + \propval{id}{integer} + Holds the internal id of an exercise. \emph{Cannot be set by the user}. + \propval{ID}{text} + Holds the user id of an exercise if defined. Otherwise it is equal to + \property{id}. + \propval{counter}{text} + Holds the counter value representation of an exercise (\ie, what you + usually know as \cs*{the\meta{counter}}). \emph{Cannot be set by the + user}. + \propval{counter-value}{integer} + Holds the counter value of an exercise (\ie, what you usually know as + \cs*{the}\cs*{value}\marg{counter}). \emph{Cannot be set by the user}. + \propval{subtitle}{text} + Holds the subtitle of an exercise. + \propval{points}{number} + Holds the reachable points of an exercise. + \propval{bonus-points}{number} + Holds the reachable bonus-points of an exercise. + \propbool{print} + Holds the print boolean of an exercise. + \propbool{print\bang} + Holds a special print boolean of an exercise, see + page~\pageref{property:print!}. + \propbool{use} + Holds the usage boolean of an exercise. + \propbool{use\bang} + Holds a special usage boolean of an exercise, see + page~\pageref{property:print!}. + \propbool{used} + True if an exercise has been used at least once. For an existing exercise + this is only false for exercises that have been collected + (\cf~section~\vref{sec:collecting-exercises}). + \propbool{solution} + \sinceversion{0.17}Holds the solution boolean of an exercise. If this is + true then a solution has the same text\slash environment body as the + corresponding exercise. (This might be useful for multiple choice + questions for example.) + \propval{tags}{csv list of tags} + Holds the list of tags the exercise should be associated with. + \propval{topics}{csv list of topics} + Holds the list of topics the exercise should be associated with. + \propval{page}{text} + Holds the page counter value representation of an exercise \\ + (\ie, what you usually know as \cs*{thepage}). + \propval{page-value}{integer} + Holds the page counter value of an exercise \\ + (\ie, what you usually know as \cs*{the}\cs*{value}\Marg{page}). + \propval{section}{text} + Holds the section counter value representation of an exercise \\ + (\ie, what you usually know as \cs*{thesection}). + \propval{section-value}{integer} + Holds the section counter value of an exercise \\ + (\ie, what you usually know as \cs*{the}\cs*{value}\Marg{section}). + \propval{chapter}{text} + Holds the chapter counter value representation of an exercise \\ + (\ie, what you usually know as \cs*{thechapter}). \\ + \emph{Only if a command \cs*{chapter} \emph{and} a counter \code{chapter} + exist.} + \propval{chapter-value}{integer} + Holds the chapter counter value of an exercise \\ + (\ie, what you usually know as \cs*{the}\cs*{value}\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}. + \propval{exercise-body}{\TeX code} + When\sinceversion{0.13} the package option \option{no-files} is set this + property is defined and holds the environment body of an exercise. + \propval{solution-body}{\TeX code} + When\sinceversion{0.13} the package option \option{no-files} is set this + property is defined and holds the environment body of the corresponding + solution. +\end{properties} + +Some of these \acsp*{prop} are fixed and cannot be set by the user. Those +include \property{id}, \property{counter}, and \property{counter-value}. The +others can be set using the optional argument of the exercise environment. + +\begin{example} + \begin{exercise}[subtitle={This is a subtitle},points=4,bonus-points=1] + An exercise where some properties have been set. + \end{exercise} +\end{example} + +\subsection{Declaring Own Properties} + +\xsim\ offers the possibility to declare additional exercise properties: +\begin{commands} + \command{DeclareExerciseProperty}[\barg\sarg\narg\marg{property}] + Declares the property \meta{property}. + + 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 + exercise is used. + \command{DeclareExercisePropertyAlias}[\marg{property 1}\marg{property 2}] + Declares \meta{property 1} to be an alias of \meta{property 2}. This + means that each time \meta{property 2} is set \meta{property 1} will be + set to the same value \emph{unless} it has been set already. As an + example: property \property{ID} is an alias of property \property{id}. +\end{commands} + +This is better demonstrated with an example: +\begin{example} + \begin{exercise} + \verb+\GetExerciseProperty{id}+: \GetExerciseProperty{id} \par + \verb+\GetExerciseAliasProperty{ID}+: \GetExerciseAliasProperty{ID} \par + \verb+\GetExerciseProperty{ID}+: \GetExerciseProperty{ID} + \end{exercise} + \begin{exercise}[ID=foo-bar] + \verb+\GetExerciseProperty{id}+: \GetExerciseProperty{id} \par + \verb+\GetExerciseAliasProperty{ID}+: \GetExerciseAliasProperty{ID} \par + \verb+\GetExerciseProperty{ID}+: \GetExerciseProperty{ID} + \end{exercise} +\end{example} + +The power of properties will get more clear when reading +section~\vref{sec:styl-exerc-templ} about templates. + +\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 +(only) get a decimal number as value the sum of which is calculated and +available (after a compilation) throughout the document. +\begin{commands} + \command{DeclareExerciseGoal}[\marg{goal}] + Declare a new exercise goal named \meta{goal} and also a property called + \meta{goal}. + \command{TotalExerciseTypeGoal}[\marg{type}\marg{goal}\marg{singular}\marg{plural}] + Get the sum of goal \meta{goal} for all exercises of type \meta{type}. + \meta{singular} and \meta{plural} are placed after the sum in the input + stream depending on whether the sum equals~$1$ or not. + \command{TotalExerciseTypeGoals}[\marg{type}\marg{list of + goals}\marg{singular}\marg{plural}] + Get the sum of goal all goals in \meta{list of goals} for all exercises of + type \meta{type}. The goal names in \meta{list of goals} must be + separated with \code{+}. \meta{singular} and \meta{plural} are placed + after the sum in the input stream depending on whether the sum equals~$1$ + or not. + \command{TotalExerciseGoal}[\marg{goal}\marg{singular}\marg{plural}] + Get the sum of goal \meta{goal} for all exercises. \meta{singular} and + \meta{plural} are placed after the sum in the input stream depending on + whether the sum equals~$1$ or not. + \command{TotalExerciseGoals}[\marg{list of + goals}\marg{singular}\marg{plural}] + Get the sum of goal all goals in \meta{list of goals} for all exercises. + The goal names in \meta{list of goals} must be separated with + \code{+}. \meta{singular} and \meta{plural} are placed after the sum in + the input stream depending on whether the sum equals~$1$ or not. + \command{AddtoExerciseTypeGoal}[\marg{type}\marg{goal}\marg{value}] + Adds \meta{value} to the goal \meta{goal} of exercise type \meta{type}. + \command{AddtoExerciseTypeGoalPrint}[\marg{type}\marg{goal}\marg{value}% + \marg{singular}\marg{plural}] + Adds \meta{value} to the goal \meta{goal} of exercise type \meta{type}. + The value and -- depending on wether the value equals $1$ or not -- + \meta{singular} or \meta{plural} are left in the input stream. + \command{AddtoExerciseGoal}[\marg{goal}\marg{value}] + Adds \meta{value} to the goal \meta{goal} of the current exercise + type. (To be used within exercises.) + \command{AddtoExerciseTypeGoalPrint}[\marg{goal}\marg{value}% + \marg{singular}\marg{plural}] + Adds \meta{value} to the goal \meta{goal} of the current exercise type. + The value and -- depending on wether the value equals $1$ or not -- + \meta{singular} or \meta{plural} are left in the input stream. (To be used + within exercises.) + \command{ExerciseGoalValuePrint}[\marg{value}\marg{singular}\marg{plural}] + Print \meta{value} and -- depending on wether the value equals $1$ or not -- + \meta{singular} or \meta{plural}. + \command{printgoal}[\marg{value}] + Print \meta{value} according to option \option{goal-print}. Defined in + terms of \cs{ExerciseGoalValuePrint}. + \command{printpoints}[\marg{type}] + Print the sum of points for all exercises of type \meta{type} followed by + an appropriate translation of the words \enquote{point} or + \enquote{points}, respectively\footnote{See section~\vref{sec:exerc-transl} + for details on the definition and usage of language dependent words.}. + Defined in terms of \cs{TotalExerciseTypeGoal}. + \command{printtotalpoints} + Print the sum of points for all exercises followed by an appropriate + translation of the words \enquote{point} or \enquote{points}, + respectively. Defined in terms of \cs{TotalExerciseGoal}. + \command{addpoints}[\sarg\marg{value}] + Adds \meta{value} to the points of the current exercise type. (To be used + within exercises.) Prints the value followed by an appropriate + translation of the words \enquote{point} or \enquote{points}, + respectively. The starred version prints nothing. Defined in terms of + \cs{AddtoExerciseGoal} and \cs{AddtoExerciseGoalPrint}. + \command{points}[\marg{value}] + Print \meta{value} followed by an appropriate translation of the words + \enquote{point} or \enquote{points}, respectively. Defined in terms of + \cs{ExerciseGoalValuePrint}. + \command{printbonus}[\marg{type}] + Print the sum of bonus points for all exercises of type \meta{type} + followed by an appropriate translation of the words \enquote{point} or + \enquote{points}, respectively. Defined in terms of + \cs{TotalExerciseTypeGoal}. + \command{printtotalbonus} + Print the sum of bonus points for all exercises followed by an appropriate + translation of the words \enquote{point} or \enquote{points}, + respectively. Defined in terms of \cs{TotalExerciseGoal}. + \command{addbonus}[\sarg\marg{value}] + Adds \meta{value} to the bonus points of the current exercise type. (To be + used within exercises.) Prints the value followed by an appropriate + translation of the words \enquote{point} or \enquote{points}, + respectively. The starred version prints nothing. Defined in terms of + \cs{AddtoExerciseGoal} and \cs{AddtoExerciseGoalPrint}. +\end{commands} + +The two existing goals are defined with +\begin{sourcecode} + \DeclareExerciseGoal{points} + \DeclareExerciseGoal{bonus-points} +\end{sourcecode} + +When goal values are printed the decimal number is fed to a function which can +be changed using the following option: +\begin{options} + \keyval{goal-print}{code}\Default{\#1} + How to format goal values. Use \code{\#1} to refer to the actual number. +\end{options} + +At last some examples for a custom command: let's say you want a command which +prints the complete sum for all exercises of all exercise types of both +\property{points} \emph{and} \property{bonus-points} added up: +\begin{sourcecode} + \NewDocumentCommand\printsumofpointsandbonus{}{% + \TotalExerciseGoals{points+bonus-points} + {\,\XSIMtranslate{point}} + {\,\XSIMtranslate{points}}% + } +\end{sourcecode} +Here is how you could mimick the command \cs*{totalpoints} from +\pkg{exsheets}: +\begin{sourcecode} + \NewDocumentCommand\pointsandbonus{}{% + \TotalExerciseGoal{points}{}{}% + \IfExerciseGoalsSumF{bonus-points}{=0} + {\,(+\,\TotalExerciseGoal{bonus-points}{}{})}% + \,\XSIMtranslate{points}% + } +\end{sourcecode} + + +\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) +get a csv list of strings as value. Those strings can be used to selectively +use exercises. See section~\vref{sec:using-printing} for details on +\emph{usage} of exercises and the difference to \emph{printing} an exercise +and how to use exercise tags for selection. +\begin{commands} + \command{DeclareExerciseTagging}[\marg{tag}] + This defines an exercise tagging group named \meta{tag}. It also defines a + 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: +\begin{sourcecode} + \DeclareExerciseTagging{tags} + \DeclareExerciseTagging{topics} + \xsimsetup{tags/ignore-untagged=false} +\end{sourcecode} +This means that these options are available: +\begin{options} + \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 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-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 +exercises to be printed or used even if they don't match the tagging +criteria. For this reason two additional properties exist which can be set to +an exercise:\label{property:print!} +\begin{properties} + \propbool{print\bang} + If set to true the exercise will be printed (and thus used) regardless of + other conditions. + \propbool{use\bang} + If set to true the exercise will be used regardless of other conditions. +\end{properties} + +\section{Using and Printing an Exercise}\label{sec:using-printing} +\subsection{What the Environments do} + +When an exercise is started with \environ{exercise} (or other environments +defined through \cs{DeclareExerciseType}) then three things happen depending +on the setup: +\begin{enumerate} + \item where the environment is placed in the document the \textbf{base + setup} happens: this sets the \property{id} of the exercise and sets the + properties chosen in the optional argument. + \item in the default setting also the \textbf{usage setup} happens: this + increments the counter and sets the counter related properties like + \property{counter}. Also the properties related to section numbers and the + \property{page} are set. + \item in the default setting also the \textbf{print setup} happens: this + mostly does nothing. It initiates recording goals that are set inside of + the exercise body. +\end{enumerate} + +Depending on wether the option \module{exercise}\code{/}\option{use} has been +set to \code{false} or wether the property \property{use} has been set to +\code{false} the \emph{usage setup} can be delayed. The usage the happens +when the exercise is \emph{inserted} the first time elsewhere in the document, +for example as part of a collection, see +section~\vref{sec:collecting-exercises}. + +Depending on wether the option \module{exercise}\code{/}\option{print} has +been set to \code{false} or if the property \property{print} has been set to +\code{false} the \emph{print setup} can be suppressed. It happens each time +an exercise is inserted. + +\begin{example} + \begin{exercise}[print=false,ID=invisible] + This exercise will not be printed but the exercise counter will be + incremented nonetheless. Its solution will be printed in the list of + solutions. + \end{exercise} + \begin{solution} + The solution of the exercise that has not been printed. + \end{solution} +\end{example} + +The schematic structure of an exercise is shown in +figure~\vref{fig:schematic-structure}. + +\begin{figure} + \centering + \begin{tikzpicture} + \node[draw,minimum width=.7\linewidth] at (0,0) {pre hook}; + \node[draw,minimum width=.7\linewidth] at (0,-1) {begin template code}; + \node[draw,minimum width=.7\linewidth] at (0,-2) {begin hook}; + \node[draw,minimum width=.7\linewidth] at (0,-3) {environment body}; + \node[draw,minimum width=.7\linewidth] at (0,-4) {end hook}; + \node[draw,minimum width=.7\linewidth] at (0,-5) {end template code}; + \node[draw,minimum width=.7\linewidth] at (0,-6) {post hook}; + \end{tikzpicture} + \caption{Schematic structure of an exercise or solution.}\label{fig:schematic-structure} +\end{figure} + +\subsection{Environment Options \& Hooks}\label{sec:environment-options-hooks} + +For each exercise type there are the following options for both environments, +the environments' names are the module names for the options (here using the +\enquote{exercise} type): +\begin{options} + \keybool{print}\Module{exercise}\Default{true} + Determines if exercises of type \enquote{exercise} are printed. + \keybool{use}\Module{exercise}\Default{true} + Determines if exercises of type \enquote{exercise} are used. + \keybool{collect}\Module{exercise}\Default{false} + \sinceversion{0.20}Sets both \option{print} and \option{use} to + \code{false} when \keyis{collect}{true} is set and vice versa. + \keyval{within}{counter}\Module{exercise}\Default + \changedversion{0.20}Adds the exercise counter to the reset list of the + counter \meta{counter} using \cs*{counterwithin}. \emph{Beware that if + the counter is a shared counter this will affect \emph{all objects} + using this counter!} + \keyval{the-counter}{code}\Module{exercise} + An interface for redefining the counter representation command + \cs*{the\meta{counter}}. + \keyval{template}{template}\Module{exercise} + An interface for \cs{SetExerciseParameter}\Marg{exercise}% + \Marg{exercise-template}\marg{template}. + \keyval{template}{template}\Module{solution} + An interface for \cs{SetExerciseParameter}\Marg{exercise}% + \Marg{solution-template}\marg{template}. + \keyval{name}{name}\Module{exercise} + An interface for \cs{SetExerciseParameter}\Marg{exercise}% + \Marg{exercise-name}\marg{name}. + \keyval{name}{name}\Module{solution} + An interface for \cs{SetExerciseParameter}\Marg{exercise}% + \Marg{solution-name}\marg{name}. + \keyval{heading}{heading command}\Module{exercise} + An\sinceversion{0.14} interface for \cs{SetExerciseParameter}% + \Marg{exercise}\Marg{exercise-heading}\marg{heading command}. + \keyval{heading}{heading command}\Module{solution} + An\sinceversion{0.14} interface for \cs{SetExerciseParameter}% + \Marg{exercise}\Marg{solution-heading}\marg{heading command}. + \keyval{pre-hook}{code}\Module{exercise}\Default + The code for the \emph{pre exercise hook} for exercises of the type + \enquote{exercise}. + \keyval{begin-hook}{code}\Module{exercise}\Default + The code for the \emph{begin exercise hook} for exercises of the type + \enquote{exercise}. + \keyval{end-hook}{code}\Module{exercise}\Default + The code for the \emph{end exercise hook} for exercises of the type + \enquote{exercise}. + \keyval{post-hook}{code}\Module{exercise}\Default + The code for the \emph{post exercise hook} for exercises of the type + \enquote{exercise}. + \keybool{print}\Module{solution}\Default{false} + Determines if solutions of type \enquote{exercise} are printed. + \keyval{pre-hook}{code}\Module{solution}\Default + The code for the \emph{pre solution hook} for solutions of the type + \enquote{exercise}. + \keyval{begin-hook}{code}\Module{solution}\Default + The code for the \emph{begin solution hook} for solutions of the type + \enquote{exercise}. + \keyval{end-hook}{code}\Module{solution}\Default + The code for the \emph{end solution hook} for solutions of the type + \enquote{exercise}. + \keyval{post-hook}{code}\Module{solution}\Default + The code for the \emph{post solution hook} for solutions of the type + \enquote{exercise}. + % TODO +\end{options} + +\subsection{(Re-) Inserting a Certain Exercise} +If you know type and \property{id} of an exercise you can (re-)insert every +existing exercise, \ie, every exercise whose external file exists. +\begin{commands} + \command{printexercise}[\marg{type}\marg{csv of ids}] + \changedversion{0.17}Inserts the exercise or exercises of type + \meta{type} with the \property{id}s or \property{ID}s given in \meta{csv + of ids}. + \command{xprintexercise}[\marg{type}\marg{csv of ids}] + \sincechanged{0.16}{0.17}The same as \cs{printexercise} but expands + \meta{type} and the items of \meta{csv of ids} before it uses them. +\end{commands} +\begin{example} + \printexercise{exercise}{invisible} +\end{example} + +\section{Collecting Exercises}\label{sec:collecting-exercises} + +\begin{bewareofthedog} + The whole collection mechanism has been changed completely with + version~0.20. Please check this section carefully and update and adapt your + collections. +\end{bewareofthedog} + +\subsection{Background} +\xsim\ knows the concept of \emph{exercise collections}. A collection of +exercises can be used in two cases, basically: +\begin{enumerate} + \item When you want to print a certain group of exercises several times. In + this case you add the exercise to a collection while also using it in the + running text. Somewhere later (or earlier actually) in the document you + can the reprint the collection\footnote{There is another way to do that, + but\dots}. + \item If you only want to print exercises which have certain tags. Maybe + you have some kind of exercise library in an external which you include + into you document and want to print only those exercises which fit + certain conditions. +\end{enumerate} +Each collection must have a unique name with which you can refer to the +corresponding collection. A collection is realized by declaring the +collection in the preamble and by activating the collection. + +\subsection{Usage} +\subsubsection{Declaring collections} +\emph{A collection must be declared in the preamble.} Using a pair of +commands explained below exercises between those commands are added to the +corresponding collection but not printed. After a collection is completed the +collection can be printed as often as needed. +\begin{commands} + \command{DeclareExerciseCollection}[\oarg{tag values}\marg{collection name}] + Define a new collection \meta{collection name} in the document preamble. + An example could look like this: + \cs{DeclareExerciseCollection}\Oarg{topics=algebra,level=1}\Marg{easy-algebra}. + Choosing tags automatically activates the collection which means that all + exercises which fit the tags are automatically added to the new + collection. +\end{commands} + +\subsubsection{Activating collections} +If a collection is not activated per default in can be activated (or +deactivated in the opposite case) with these commands: +\begin{commands} + \command{activatecollection}[\marg{collection name}] + \sinceversion{0.20}Activates the collection \meta{collection name} which + now collects all exercises until the collection is + deactivated. \meta{collection name} can be a csv list of collection + names. + \command{deactivatecollection}[\marg{collection name}] + \sinceversion{0.20}Deactivates the collection \meta{collection name}. + \meta{collection name} can be a csv list of collection names. +\end{commands} +These commands do not influence exercises in other ways other than adding them +to collections. +\begin{commands} + \command{collectexercises}[\marg{collection name}] + Activates the collection \meta{collection name} which now collects all + exercises until the collection is deactivated, starts a group with + \cs*{begingroup} and sets the option \option{collect}, see below. + \command{collectexercisesstop}[\marg{collection name}] + Deactivates the collection \meta{collection name} and ends a group with + \cs*{endgroup}. +\end{commands} +\begin{options} + \keybool{collect}\Default{false} + A shortcut option which sets the options + \module{\meta{type}}\code{/}\module{collect} for each exercise type. +\end{options} + +\subsubsection{Printing collections} +\begin{commands} + \command{printcollection}[\oarg{options}\marg{collection name}] + Prints the collection \meta{collection name}, \ie, all exercises collected + earlier. This command cannot be used before the corresponding collection + has been closed correctly. +\end{commands} +Valid options are the following: +\begin{options} + \keybool{headings}\Module{print-collection}\Default{false} + If true a heading for each exercise type is inserted. + \keyval{headings-template}{template}\Module{print-collection}\Default{collection} + The heading template used when \keyis{headings}{true}. + \keychoice{print}{exercises,solutions,both}\Module{print-collection}\Default{exercises} + Determines wether \cs{printcollection} prints the exercises or the + solutions of the collection. When you choose \code{both} exercises and + solutions are printed alternately. +\end{options} + +Those options can also be set via \cs{xsimsetup} using the module +\module{print-collection}. + +\begin{bewareofthedog} + Please be aware that exercises are not used or printed while they are + collected. Nonetheless the property \property{use} is set to \code{true} + (so that solutions can be printed even if the exercises are not) and the + property \property{print} is set to \code{false}. Also their counters are + \emph{not stepped} during the process. This only happens when they are + printed the first time, \cf~the \property{used} property. At that time + also the properties \property{page}, \property{section} and + \property{chapter} are set and the property \property{print} is set to + \code{true}. +\end{bewareofthedog} + +The usage should be clear: +\begin{example} + \collectexercises{foo} + \begin{exercise} + This exercise is added to the collection `foo'. + \end{exercise} + \begin{exercise} + This exercise is also added to the collection `foo'. + \end{exercise} + \begin{exercise} + So is this. + \end{exercise} + \begin{exercise} + As well as this one. + \end{exercise} + \collectexercisesstop{foo} +\end{example} +Once the collection is closed it can be printed: +\begin{example} + \printcollection{foo} +\end{example} + +You can open several collections at the same time: +\begin{sourcecode} + \collectexercises{foo} + ... + \activatecollection{bar} + ... + \deactivatecollection{foo} + ... + \collectexercisesstop{bar} +\end{sourcecode} +Exercises will be added to each open collection. + +There is one generic collection called \enquote{\code{all exercises}}. As the +name already suggests it will hold all exercises. So if you say +\begin{sourcecode} + \printcollection{all exercises} +\end{sourcecode} +all exercises will be printed. + +\begin{bewareofthedog} + If you use \cs*{label}s inside of exercises and you print exercises more + than once in your document (by reusing a collection for example) you will + get +\begin{sourcecode} + LaTeX Warning: There were multiply-defined labels. +\end{sourcecode} + Equally if you have environments like \environ{equation} which step a + counter inside an exercise or solution the counter will be stepped each time + the exercise is used. +\end{bewareofthedog} + +At last now an example using external files, collections and tags: +\begin{sourcecode} + % preamble: + % \DeclareExerciseCollection{foo-easy} + % \DeclareExerciseCollection{foo-medium} + % \DeclareExerciseTagging{difficulty} + + % document: + \collectexercises{foo-easy} + \xsimsetup{difficulty=easy} + \input{foo.tex} + \collectexercisesstop{foo-easy} + % collection `foo-easy' now contains all exercises of file `foo.tex' tagged + % with `difficulty=easy' + + \collectexercises{foo-medium} + \xsimsetup{difficulty=medium} + \input{foo.tex} + \collectexercisesstop{foo-medium} + % collection `foo-medium' now contains all exercises of file `foo.tex' + % tagged with `difficulty=medium' +\end{sourcecode} + +\begin{bewareofthedog} + The recommended usage is similar to the last example. Actually a collection + can be printed \emph{before} it is opened, too. (This needs \emph{at least} + two compilations, though.) However, it is safer printing a collection only + 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 exercise is not part of several collections -- at least not if + both collections are printed in the same document. +\end{bewareofthedog} + +\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 + chosen with option \option{collection}, see below. When this command is + used it generates a random list of integers which is written to the + \code{aux} file. On the subsequent compilations the according exercises + are printed. \emph{If you want to regenerate the random list you have to + delete the \code{aux} file before compiling.} +\end{commands} +Valid options for this command are: +\begin{options} + \keybool{sort}\Module{random}\Default{true} + Determines wether the random chosen exercises should be sorted according + to their order of definition in the collection or not. + \keyval{collection}{collection}\Module{random}\Default{all exercises} + The collection from which the exercises are to be chosen from. + \keyval{exclude}{csv list of ids}\Module{random} + A list of \property{id}s or \property{ID}s of exercises \emph{not} to be + chosen. + \keychoice{print}{exercises,solutions,both}\Module{random}\Default{exercises} + Determines wether \cs{printrandomexercises} prints the exercises or the + solutions. When you choose \code{both} exercises and solutions are + printed alternately. +\end{options} + +\begin{example} + \printrandomexercises[collection=foo]{2} +\end{example} + +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} + +There are different commands for printing the solutions to exercises: +\begin{commands} + \command{printsolutionstype}[\sarg\oarg{options}\marg{exercise type}] + Prints the solutions of all used exercises of type \meta{exercise type}. + The starred version only prints the solutions of all printed exercises of + type \meta{exercise type}. + \command{printsolutions}[\sarg\oarg{options}] + Prints the solutions of all used exercises of all types ordered by type. + The starred version only prints the solutions of all printed exercises of + all types. + \command{printallsolutions}[\sarg\oarg{options}] + Prints the solutions of all used exercises of all types ordered by + appearance in the document. The starred version only prints the solutions + of all printed exercises of all types. + \command{printsolution}[\oarg{options}\marg{type}\marg{id}] + Prints the solution of the exercise of type \meta{type} with the + \property{id} \meta{id}. + \command{xprintsolution}[\marg{type}\marg{id}] + \sinceversion{0.16}The same as \cs{printsolution} but expands \meta{type} + and \meta{id} before it uses them. +\end{commands} + +\begin{example} + \printsolutionstype{exercise} +\end{example} + +The options can be divided into two groups. The ones in the first group +modify the layout. +\begin{options} + \keybool{headings}\Module{print-solutions}\Default{true} + If true a heading for each exercise type is inserted. + \keyval{headings-template}{template}\Module{print-solutions}\Default{default} + The heading template used when \keyis{headings}{true}. +\end{options} + +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}}\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}}\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}}\Module{print-solutions}% + \Default{false} + If used only solutions of exercises belonging to collection + \meta{collection name} are printed. +\end{options} + +The conditions can be combined. The following call will only print solutions +from exercises in section~3 of chapter~2: +\begin{sourcecode} + \printsolutions[chapter=2,section=3] +\end{sourcecode} + +\begin{bewareofthedog} + The selection per section or per chapter relies on the \emph{counter + numbers} of the sections or chapters, respectively. This means if section + numbers are reset (\eg\ by \cs*{chapter} or \cs*{appendix}) and you have + exercises from \emph{different} sections with \emph{the same section number} + the solutions of \emph{all those exercises} will be printed. This means you + only should use the \option{section} selection when section are the top + document level headings (apart from parts) and you have no exercises in the + appendix. Similar considerations are valid for the \option{chapter} + selection. +\end{bewareofthedog} + +All options can also be set via \cs{xsimsetup} using the module +\module{print-solutions}. + +\begin{example} + \printsolutions[section=4,headings-template=per-section] +\end{example} + +\begin{example} + \printsolution{exercise}{5} +\end{example} + +\section{Grading Tables}\label{sec:grading-tables} +When you create exercises it may not only be desirable to be able to add +points and bonus-points to a question (see section~\vref{sec:goals} about +exercise goals) but also to be able to output a grading table. \xsim\ has +built-in means for this. +\begin{commands} + \command{gradingtable}[\oarg{options}] + Print a grading table. +\end{commands} +Valid options for this command are +\begin{options} + \keyval{template}{template}\Default{default} + Choose the template used for the grading table. + \keyval{type}{exercise type}\Default + Choose the exercise type for which the table is printed. +\end{options} +Both option defaults can be changed with \cs{xsimsetup} setting the options +using \module{grading-table}: +\begin{sourcecode} + \xsimsetup{ + grading-table/template = default* + } +\end{sourcecode} + +An example: +\begin{example} + \gradingtable[type=exercise] +\end{example} + +Or using the \enquote{\code{default*}} template: +\begin{example} + \gradingtable[template=default*,type=exercise] +\end{example} + +Available templates and how to define new ones are explained in +sections~\vref{sec:grad-table-templ} and~\vref{sec:template-examples}. \xsim\ +per default provides two templates \enquote{\code{default}} and +\enquote{\code{default*}}, the first one has a vertical layout, the second a +horizontal layout. Both templates can be used per type like in the examples +above or for all types at once by leaving the specification \option{type} +away: +\begin{example} + \gradingtable +\end{example} + +\section{Styling the Exercises -- Templates}\label{sec:styl-exerc-templ} + +\subsection{Background} +Whenever \xsim\ outputs something to be typeset it uses so-called templates +for the task. \xsim\ knows of three different kinds of templates: +\begin{itemize} + \item environment templates (see section~\vref{sec:envir-templ}), + \item heading templates (see section~\vref{sec:heading-templates}) and + \item grading table templates (see section~\vref{sec:grad-table-templ}) +\end{itemize} + +The most important one for the styling of the exercises are the environment +templates. Those templates give you complete control over the look and +arrangement of an exercise. To be able to do this \xsim\ provides a large +number of commands which can be used only inside template +definitions\footnote{The last sentence is wrong: those commands can be used + anywhere but most of them only give useful results inside of templates.}. +Those commands are explained in the next section. Their usage will hopefully +become clear in the examples in section~\vref{sec:template-examples}. Having +full control over the layout comes at a price: you need to be able to program +yourself in order to achieve certain layouts\footnote{I plan to incorporate + the most common layouts -- and maybe some fancy ones, too -- in the examples + 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}. + \item[\code{minimal}] A\sinceversion{0.13} minimalistic layout, see + section~\ref{sec:minimal-template}. As the others inspired by an + \pkg{exsheets} layout. Available through the style file \code{layouts}. + \item[\code{inline}] A\sinceversion{0.18} minimalistic layout, the same as + \code{minimal} but doesn't add \cs*{par} at the beginning and end. + Available through the style file \code{layouts}. + \item[\code{centered}] A\sinceversion{0.18} layout with a centered heading. + Available through the style file \code{layouts}. +\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} + \command{IfExerciseGoal\TF}[\marg{goal}\marg{relation and + value}\marg{true}\marg{false}] + Checks the sum of goal \meta{goal} against \meta{relation and value}. + \command{IfExerciseGoalSingular\TF}[\marg{goal}\marg{true}\marg{false}] + Checks if the value of the goal \meta{goal} of the current exercise + equals~$1$. This is the same as \\ + \cs{IfExerciseGoalTF}\marg{goal}\Marg{=1}\marg{true}\marg{false}. + \command{IfExerciseTypeGoalsSum\TF}[\marg{type}\marg{list of + goals}\marg{relation and value}\marg{true}\marg{false}] + Ckecks the sum of all goals in \meta{list of goals} for the exercises of + type \meta{type} against \meta{relation and value}. + \command{IfExerciseGoalsSum\TF}[\marg{type}\marg{list of + goals}\marg{relation and value}\marg{true}\marg{false}] + Ckecks the sum of all goals in \meta{list of goals} for all exercises of + all types against \meta{relation and value}. + \command{TotalExerciseTypeGoal}[\marg{goal}\marg{type}\marg{singular}\marg{plural}] + Print the sum of goal \meta{goal} for the exercises of type \meta{type} + and append \meta{singular} or \meta{plural} depending on wether the sum + equals~$1$ or not. + \command{TotalExerciseGoal}[\marg{goal}\marg{singular}\marg{plural}] + Print the sum of goal \meta{goal} for all exercises of all types + and append \meta{singular} or \meta{plural} depending on wether the sum + equals~$1$ or not. +\end{commands} + +\subsubsection{Properties} +\begin{commands} + \expandable\command{IfExercisePropertyExist\TF}[\marg{property}\marg{true}% + \marg{false}] + Tests wether an exercise property with the name \meta{property} is defined. + \command{IfExercisePropertySet\TF}[\marg{property}\marg{true}\marg{false}] + Tests wether the exercise property \meta{property} has been set for the + current exercise. + \expandable\command{GetExerciseProperty}[\marg{property}] + Retrieves the value of the property \meta{property} for the current + exercise. + \command{GetExerciseProperty\TF}[\marg{property}\marg{true}\marg{false}] + Tests wether the exercise property \meta{property} has been set for the + 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{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!} + \command{GetExerciseTypeForProperty}[\marg{property}\marg{value}] + 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{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} + or \meta{false} and leaves the corresponding argument in the input + stream. Gives an error if \meta{property} is not a boolean property. + \expandable\command{GetExerciseAliasProperty}[\marg{property}] + Retrieves the value of the property of which \meta{property} is an alias + of for the current exercise. + \command{SaveExerciseProperty}[\marg{property}\meta{macro}] + Saves the value of the property \meta{property} for the current + exercise in macro \meta{macro}. + \command{GlobalSaveExerciseProperty} + Globally saves the value of the property \meta{property} for the current + exercise in macro \meta{macro}. + \command{ExercisePropertyIfSet\TF}[\marg{type}\marg{id}\marg{property}% + \marg{true}\marg{false}] + Test if the property \meta{property} has been set for the exercise of type + \meta{type} with id \meta{id}. + \expandable\command{ExercisePropertyGet}[\marg{type}\marg{id}\marg{property}] + Retrieves the value of the property \meta{property} for the exercise of type + \meta{type} with id \meta{id}. + \expandable\command{ExercisePropertyGetAlias}[\marg{type}\marg{id}\marg{property}] + Retrieves the value of the property of which \meta{property} is an alias + of for the exercise of type \meta{type} with id \meta{id}. + \command{ExercisePropertySave}[\marg{type}\marg{id}\marg{property}\meta{macro}] + Saves the value of the property \meta{property} for the exercise of type + \meta{type} with id \meta{id} in macro \meta{macro}. + \command{ExercisePropertyGlobalSave}[\marg{type}\marg{id}\marg{property}\meta{macro}] + Globally saves the value of the property \meta{property} for the exercise + of type \meta{type} with id \meta{id} in macro \meta{macro}. +\end{commands} + +\subsubsection{Parameters} +\begin{commands} + \expandable\command{GetExerciseParameter}[\marg{parameter}] + 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{GetExerciseHeadingF}[\marg{false}] + \sinceversion{0.14}Retrieves the value of the parameter + \parameter{exercise-heading} for the current exercise or of the parameter + \parameter{solution-heading} for the current solution. Inserts + \meta{false} if the corresponding parameter has not been set. + \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} +\begin{commands} + \command{ForEachExerciseTag}[\marg{type}\marg{code}] + Loops over all tags of tag type \meta{type} for the current exercise + applying \meta{code} each time. Inside \meta{code} you can refer to the + corresponding tag with \code{\#1}. + \command{ListExerciseTags}[\marg{type}\marg{between}] + Lists all tags of tag type \meta{type} for the current exercise using + \meta{between} as a separator. + \command{UseExerciseTags}[\marg{type}\marg{between + two}\marg{between}\marg{between last two}] + Lists all tags of tag type \meta{type} for the current exercise using + \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} +\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} + Can be used to refer to the current exercise id. + \expandable\command{ExerciseText} + Can be used inside solutions to retrieve the text of the corresponding + solution. This is propably seldom useful as in most use cases the + exercise property \property{solution} is the easier alternative. + \expandable\command{ExerciseCollection} + Can be used in certain templates to refer to the collection that is + currently inserted. + \expandable\command{numberofusedexercises} + Holds the total number of used exercises. Useful in table template + definitions. + \expandable\command{ExerciseTableType}[\marg{code}] + In table template definitions this macro either expands to the given + 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{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}] + \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 + properties of the corresponding exercise: + \begin{itemize} + \item \code{\#1}: the type of the exercise + \item \code{\#2}: the id of the exercise + \item \code{\#3}: the \property{counter} property of the exercise + \item \code{\#4}: the \property{subtitle} property of the exercise + \item \code{\#5}: the \property{points} property of the exercise + \item \code{\#6}: the \property{bonus-points} property of the exercise + \end{itemize} + \command{ForEachUsedExerciseByType}[\marg{code}] + Loops over each \emph{used} exercise ordered by the exercise types and + within each type by id. Inside \meta{code} you can refer to several + properties of the corresponding exercise: + \begin{itemize} + \item \code{\#1}: the type of the exercise + \item \code{\#2}: the id of the exercise + \item \code{\#3}: the \property{counter} property of the exercise + \item \code{\#4}: the \property{subtitle} property of the exercise + \item \code{\#5}: the \property{points} property of the exercise + \item \code{\#6}: the \property{bonus-points} property of the exercise + \end{itemize} + \command{ForEachPrintedExerciseByID}[\marg{code}] + Loops over each \emph{printed} exercise order by the exercise id. Inside + \meta{code} you can refer to several properties of the corresponding + exercise: + \begin{itemize} + \item \code{\#1}: the type of the exercise + \item \code{\#2}: the id of the exercise + \item \code{\#3}: the \property{counter} property of the exercise + \item \code{\#4}: the \property{subtitle} property of the exercise + \item \code{\#5}: the \property{points} property of the exercise + \item \code{\#6}: the \property{bonus-points} property of the exercise + \end{itemize} + \command{ForEachUsedExerciseByID}[\marg{code}] + Loops over each \emph{used} exercise order by the exercise id. Inside + \meta{code} you can refer to several properties of the corresponding + exercise: + \begin{itemize} + \item \code{\#1}: the type of the exercise + \item \code{\#2}: the id of the exercise + \item \code{\#3}: the \property{counter} property of the exercise + \item \code{\#4}: the \property{subtitle} property of the exercise + \item \code{\#5}: the \property{points} property of the exercise + \item \code{\#6}: the \property{bonus-points} property of the exercise + \end{itemize} + \command{XSIMprint}[\Marg{exercise|solution}\marg{type}\marg{id}] + \sincechanged{0.16}{0.17}Inserts the either the exercise or the solution + of type \meta{type} with the \property{id} or \property{ID} \meta{id}. + \command{XSIMxprint}[\Marg{exercise|solution}\marg{type}\marg{id}] + The same as \cs{XSIMprint} but expands \meta{type} and \meta{id} before it + uses them.\sincechanged{0.16}{0.17} + \expandable\command{XSIMtranslate}[\marg{keyword}] + Delivers the translation of \meta{keyword} according to the current + document language (in the meaning of a \pkg{babel}~\cite{pkg:babel} or + \pkg{polyglossia}~\cite{pkg:polyglossia} language). Existing keywords and + keyword translations (and how to add new ones) are explained in + section~\vref{sec:exerc-transl}. + \command{XSIMexpandcode}[\marg{code}] + Expands \meta{code} like \cs*{edef} does and leaves the result in the + input stream. + \expandable\command{XSIMifchapter\TF}[\marg{true}\marg{false}] + Returns \meta{true} if both a macro \cs*{chapter} and a counter + \code{chapter} are defined and \meta{false} otherwise. + \command{XSIMmixedcase}[\marg{code}] + Converts the full expansion of \meta{code} to mixed case: \\ + \verbcode+\XSIMmixedcase{this is some text}+ \XSIMmixedcase{this is some + text} \\ + \emph{This command expands \meta{code} before converting it}. + \command{XSIMputright}[\meta{macro}\marg{code}] + Extends the macro definition of \meta{macro} with \meta{code} putting it + to the right. This is more or less a local version of the LaTeX kernel + macro \cs*{g@addto@macro}. + \expandable\command{XSIMifeq\TF}[\marg{code 1}\marg{code + 2}\marg{true}\marg{false}] + Checks if the full expansion of \meta{code 1} and \meta{code 2} is the + same tokenlist. + \expandable\command{XSIMifblank\TF}[\marg{code}\marg{true}\marg{false}] + Checks if the full expansion of \meta{code} is blank (\ie, if it is empty + or only consists of spaces). + \command{XSIMatbegindocument}[\marg{code}] + \sinceversion{0.16}Adds \meta{code} to \xsim's begin document hook. + Should be used inside style files instead of \cs*{AtBeginDocument}. + \command{XSIMatenddocument}[\marg{code}] + \sinceversion{0.16}Adds \meta{code} to \xsim's end document hook. + Should be used inside style files instead of \cs*{AtEndDocument}. +\end{commands} + +\subsection{Declaring Templates} +\subsubsection{Environment Templates}\label{sec:envir-templ} +\begin{commands} + \command{DeclareExerciseEnvironmentTemplate}[\marg{name}\marg{begin + code}\marg{end code}] + Declare the environment template \meta{name}. +\end{commands} +Environment templates are used by the exercise and solution environments. +Those are the templates set with the parameters \parameter{exercise-template} +and \parameter{solution-template}. + +The predefined template is called \enquote{\code{default}}, see +section~\vref{sec:exercise-templ-default}. + +\subsubsection{Heading Templates}\label{sec:heading-templates} +\begin{commands} + \command{DeclareExerciseHeadingTemplate}[\marg{name}\marg{code}] + Declare the heading template \meta{name}. +\end{commands} +Heading templates are used by \cs{printsolutions}, \cs{printsolutionstype} and +\cs{printcollection}. Those are the templates set with the option +\option{headings-template} of the modules \module{print-solutions} and +\module{print-collection}. + +The predefined templates are \enquote{\code{default}}, +\enquote{\code{collection}}, \enquote{\code{per-section}} and +\enquote{\code{per-chapter}} see section~\vref{sec:headings-templates}. + +\subsubsection{Grading Table Templates}\label{sec:grad-table-templ} +\begin{commands} + \command{DeclareExerciseTableTemplate}[\marg{name}\marg{code}] + Declare the grading table template \meta{name}. +\end{commands} +Table templates are used by \cs{gradingtable}. Those are the templates set +with the option \option{template} of module \module{grading-table} + +The predefined templates are \enquote{\code{default}} and +\enquote{\code{default*}}, see sections~\vref{sec:table-templ-default} +and~\vref{sec:table-templ-default*}. + +\subsection{Create and Use \xsim\ Style Files}\label{sec:style-files} +\index{style file|(} + +\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.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 +\cs{loadxsimstyle}\Marg{math-exam} or by using +\cs{xsimsetup}\Marg{load-style=math-exam}: +\begin{sourcecode} + \documentclass[DIV=18,parskip=half]{scrartcl} + \usepackage[T1]{fontenc} + \usepackage[utf8]{inputenc} + + \usepackage[clear-aux]{xsim} + \loadxsimstyle{math-exam} + + \title{Math Exam \#3} + \date{2017-03-28} +\end{sourcecode} + +In this style file stuff like template and property definitions should +happen. This is more or less a convenient way to +\begin{itemize} + \item keep the preamble \enquote{clean} and + \item define re-usable styles without the need of copying the document + preamble to another document. +\end{itemize} +A style file is like a package or class file, \ie, \code{@} has category +code~11 (letter). + +The formal description of the commands: +\begin{commands} + \command{xsimstyle}[\sarg\marg{style name}] + 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} +\begin{options} + \keyval{load-style}{csv list of style names} + Another\sinceversion{0.14} interface for \cs{loadxsimstyle}\marg{csv list + of style names}. +\end{options} + +\begin{bewareofthedog} + At the moment this mechanism offers no advantages over creating a custom + package or simply \cs*{input}ing a file. Future versions might provide + additional features. +\end{bewareofthedog} + +\index{style file|)} + +\subsection{Examples}\label{sec:template-examples} + +The repository of this package\footnote{GitHub: + \url{https://github.com/cgnieder/xsim/}, CTAN: + \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, see +section~\vref{sec:example-files}. + +\subsubsection{The \code{default} Exercise Template}\label{sec:exercise-templ-default} + +Below the definition\changedversion{0.14} of the \code{default} exercise +template provided by \xsim\ is shown: + +\begin{sourcecode} + \DeclareExerciseEnvironmentTemplate{default}{% + \GetExerciseHeadingF{\subsection*}% + {% + \XSIMmixedcase{\GetExerciseName}\nobreakspace + \GetExerciseProperty{counter}% + \IfInsideSolutionF + {% + \GetExercisePropertyT{subtitle} + { {\normalfont\itshape\PropertyValue}}% + }% + } + \GetExercisePropertyT{points} + {% + \marginpar + {% + \IfInsideSolutionF{\rule{1.2cm}{1pt}\slash}% + \printgoal{\PropertyValue} + \GetExercisePropertyT{bonus-points}{~(+\printgoal{\PropertyValue})}% + ~\XSIMtranslate {point-abbr}% + }% + }% + } + {\par} +\end{sourcecode} + +\subsubsection{A New Exercise Type Using \pkg*{tcolorbox}} +Let's say we want exercises to be put in a \env*{tcolorbox}. We want a bold +title and. if given, an italic subtitle. Exercises should also have the +points after the subtitle in parentheses if given. Let's also say we want +those to be an additional exercise type in addition to the ones \xsim\ already +provides. This is shown with the following code which is also how the +problems in this manual have been defined: + +\begin{sourcecode} + \DeclareExerciseEnvironmentTemplate{tcolorbox} + {% + \tcolorbox[ + colback = red!5!white , + colframe = red!75!black , + colbacktitle = yellow!50!red , + coltitle = red!25!black , + breakable , + drop shadow , + beforeafter skip = .5\baselineskip , + title = + \textbf{\GetExerciseName~\GetExerciseProperty{counter}}% + \GetExercisePropertyT{subtitle}{ \textit{\PropertyValue}}% + \IfInsideSolutionF{% + \GetExercisePropertyT{points}{ % notice the space + (% + \printgoal{\PropertyValue} + \IfExerciseGoalSingularTF{points} + {\XSIMtranslate{point}} + {\XSIMtranslate{points}}% + )% + }% + }% + ]% + } + {\endtcolorbox} + + \DeclareExerciseType{problem}{ + exercise-env = problem , + solution-env = answer , + exercise-name = Problem , + solution-name = Answer , + exercise-template = tcolorbox , + solution-template = tcolorbox + } +\end{sourcecode} + +See it in action: +\begin{example} + \begin{problem}[subtitle=My subtitle,points=5] + This is a problem using a subtitle and points. + \end{problem} + \begin{answer} + This is the answer to problem~\GetExerciseProperty{counter}. + \end{answer} +\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 +\cs*{marginpar} but the result should look very similar. A safer definition +would use a real sectioning command for the title. + +\begin{sourcecode} + \usepackage{needspace} + \DeclareExerciseEnvironmentTemplate{runin} + {% + \par\vspace{\baselineskip} + \Needspace*{2\baselineskip} + \noindent + \textbf{\XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}}% + \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} + +\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} + \DeclareExerciseEnvironmentTemplate{margin} + {% + \trivlist + \item[\llap{% + \smash{% + \tabular[t]{@{}r@{}} + \textbf{\XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}} + \IfExercisePropertySetT{points}{% + \tabularnewline + (% + \printgoal{\GetExerciseProperty{points}}% + \GetExercisePropertyT{bonus-points}{+\printgoal{#1}}% + \,\XSIMtranslate{point-abbr}% + )% + }% + \endtabular + }% + }]\relax + } + {\endtrivlist} +\end{sourcecode} + +\subsubsection{A \code{minimal} Template} +\label{sec:minimal-template} + +This shows the implementation of the \code{minimal} template: +\begin{sourcecode} + \DeclareExerciseEnvironmentTemplate{minimal} + {% + \par + \textbf{\GetExerciseProperty{counter}}% + \IfInsideSolutionF{% + \GetExercisePropertyT{points}{% + \GetExercisePropertyT{bonus-points}{+\printgoal{\PropertyValue}}% + \,\IfExerciseGoalSingularTF{points} + {\XSIMtranslate{point}} + {\XSIMtranslate{points}}% + }% + }% + } + {\par} +\end{sourcecode} + +\subsubsection{The Headings Templates}\label{sec:headings-templates} +\xsim\ defines four heading templates which only differ by which text they +output: +\begin{sourcecode} + \DeclareExerciseHeadingTemplate{default} + {\section*{\XSIMtranslate{default-heading}}} + \DeclareExerciseHeadingTemplate{collection} + {\section*{\XSIMtranslate{collection-heading}}} + \DeclareExerciseHeadingTemplate{per-section} + {\section*{\XSIMtranslate{per-section-heading}}} + \DeclareExerciseHeadingTemplate{per-chapter} + {\section*{\XSIMtranslate{per-chapter-heading}}} +\end{sourcecode} +Section~\vref{sec:exerc-transl} shows how the translations are defined. + +\subsubsection{The \code{default} Table Template}\label{sec:table-templ-default} +This template is the one used for grading tables per default. It has a +vertical layout. + +\begin{sourcecode} + \DeclareExerciseTableTemplate{default}{% + \XSIMputright\ExerciseTableCode{% + \toprule + \XSIMifblankF{\ExerciseType} + {\XSIMmixedcase{\GetExerciseParameter{exercise-name}}} + & + \XSIMmixedcase{\XSIMtranslate{points}} & + \XSIMtranslate{reached} \\ + \midrule + }% + \ForEachUsedExerciseByType{% + \XSIMifeqT{#1}{\ExerciseTableType{#1}} + {% + \XSIMifblankT{\ExerciseTableType{}} + {% + \XSIMputright\ExerciseTableCode{% + \XSIMmixedcase{\ExerciseParameterGet{#1}{exercise-name} }% + }% + }% + \XSIMputright\ExerciseTableCode + {#3 & \XSIMifblankTF{#5}{\printgoal{0}}{\printgoal{#5}} & \\ }% + }% + } + \XSIMputright\ExerciseTableCode{% + \midrule + \XSIMtranslate{total} & + \XSIMifblankTF{\ExerciseType} + {\TotalExerciseGoal{points}{}{}} + {\TotalExerciseTypeGoal{\ExerciseType}{points}{}{}} & + \\ \bottomrule + }% + \XSIMexpandcode{% + \noexpand\begin{tabular}{\XSIMifblankTF{\ExerciseType}{l}{c}cc} + \noexpand\ExerciseTableCode + \noexpand\end{tabular}% + }% + } +\end{sourcecode} + +The part +\begin{sourcecode} + \XSIMifblankTF{\ExerciseType}{ ... }{ ... } +\end{sourcecode} +repeatedly checks if an exercise type has been given for the table. This +makes it possible to design the table differently if it is for one exercise +type only (the \code{true} case) or for all exercise types (the \code{false} +case). \cs*{ExerciseTableType}\marg{code} either expands to the given +exercise type or to \meta{code}. + +\subsubsection{The \code{default*} Table Template}\label{sec:table-templ-default*} +The second of the predefined grading table templates. It has a horizontal +layout. +\begin{bewareofthedog} + If you have a lot of exercises the width of a table with this layout may + exceed the text width of the document! +\end{bewareofthedog} + +\begin{sourcecode} + \DeclareExerciseTableTemplate{default*}{% + \XSIMputright\ExerciseTableCode{% + \toprule + \XSIMifblankF{\ExerciseType} + {\XSIMmixedcase{\GetExerciseParameter{exercise-name}}} + &% + }% + \ForEachUsedExerciseByType{% + \XSIMifeqT{#1}{\ExerciseTableType{#1}} + { + \XSIMifblankT{\ExerciseTableType{}} + {% + \XSIMputright\ExerciseTableCode{% + \XSIMmixedcase{\ExerciseParameterGet{#1}{exercise-name} }% + }% + }% + \XSIMputright\ExerciseTableCode{#3 &} + }% + }% + \XSIMputright\ExerciseTableCode{% + \XSIMtranslate{total} \\ + \midrule + \XSIMmixedcase{\XSIMtranslate{points}} & + }% + \ForEachUsedExerciseByType{% + \XSIMifeqT{#1}{\ExerciseTableType{#1}} + {% + \XSIMputright\ExerciseTableCode{% + \XSIMifblankTF{#5}{\printgoal{0}}{\printgoal{#5}} &}% + }% + }% + \XSIMputright\ExerciseTableCode{% + \XSIMifblankTF{\ExerciseType} + {\TotalExerciseGoal{points}{}{}} + {\TotalExerciseTypeGoal{\ExerciseType}{points}{}{}}% + \\ \midrule + \XSIMtranslate{reached} &% + }% + \ForEachUsedExerciseByType{% + \XSIMifeqT{#1}{\ExerciseTableType{#1}} + {\XSIMputright\ExerciseTableCode{&}}% + }% + \XSIMputright\ExerciseTableCode{ \\ \bottomrule }% + \edef\numberofcolumns{% + \XSIMifblankTF{\ExerciseType} + {\numberofusedexercises} + {\csname numberof \ExerciseType s\endcsname}% + }% + \XSIMifeqF{\numberofcolumns}{0} + {% + \begin{tabular}{l*{\numberofcolumns}{c}c} + \ExerciseTableCode + \end {tabular}% + }% + } +\end{sourcecode} + +The part +\begin{sourcecode} + \XSIMifblankTF{\ExerciseType}{ ... }{ ... } +\end{sourcecode} +repeatedly checks if an exercise type has been given for the table. This +makes it possible to design the table differently if it is for one exercise +type only (the \code{true} case) or for all exercise types (the \code{false} +case). \cs*{ExerciseTableType}\marg{code} either expands to the given +exercise type or to \meta{code}. + +\section{Exercise Translations}\label{sec:exerc-transl} + +\begin{commands} + \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. + See an example of the usage below. + \expandable\command{XSIMtranslate}[\marg{keyword}] + Delivers the translation of \meta{keyword} according to the current + document language (in the meaning of a \pkg{babel}~\cite{pkg:babel} or + \pkg{polyglossia}~\cite{pkg:polyglossia} language). + \command{ForEachExerciseTranslation}[\marg{code}] + Loops over all translations of all keywords known to \xsim. Inside + \meta{code} you can refer to the keyword with \code{\#1}, to the language + with \code{\#2}, and to the translation with \code{\#3}. +\end{commands} + +As an example how to use \cs{DeclareExerciseTranslations} here is how the +translations for \code{exercise} have been defined: + +\begin{sourcecode} + \DeclareExerciseTranslations{exercise}{ + Fallback = exercise , + English = exercise , + French = exercice , + German = \"Ubung + } +\end{sourcecode} + +Table~\vref{tab:translation-keys} shows all existing keywords with all +predefined translations. + +\ForEachExerciseTranslation{ + \appto\translationtable{\texttt{#1} & #2 & \texttt{\detokenize{#3}} \\} +} + +\begin{longtable}{llp{.55\linewidth}} + \caption{Translation keywords predefined by \xsim.} + \label{tab:translation-keys} \\ + \toprule + \bfseries keyword & \bfseries language & \bfseries translation \\ + \midrule + \endfirsthead + \toprule + \bfseries keyword & \bfseries language & \bfseries translation \\ + \midrule + \endhead + \bottomrule + \endlastfoot + \midrule + & & \hfill\emph{continues} \\ + \endfoot + \translationtable +\end{longtable} + +\section{Cloze Tests and Blank Lines} + +Similar to \pkg{exsheets} \xsim\ provides a command \cs{blank}: +\begin{commands} + \command{blank}[\sarg\oarg{options}\marg{text to be filled in}] + Creates a blank in normal text or in an exercise but fills the text of its + argument if inside a solution. If used at the \emph{begin of a paragraph} + \cs{blank} will do two things: it will set the linespread according to an + option explained below and will insert \cs*{par} after the lines. The + starred version doesn't do these things. +\end{commands} + +Those are the options for customization: +\begin{options} + \keyval{blank-style}{code}\Module{blank}\Default{\cs*{underline}\Marg{\#1}} + Instructions for typesetting the blank cloze. Refer to the filled in + space with \code{\#1}. + \keyval{filled-style}{code}\Module{blank}\Default{\cs*{underline}\Marg{\#1}} + Instructions for typesetting the filled cloze. Refer to the filled in text + with \code{\#1} + \keyval{style}{code} + Shortcut for setting both \option{blank-style} and \option{filled-style} + at once. + \keyval{scale}{decimal number}\Module{blank}\Default{\code{1}} +\textsc{} Scales the blank to \meta{decimal number} times its natural width. + \keyval{width}{dim}\Module{blank}\Default + Sets the blank to a width of \meta{dim}. This takes precendence over + \option{scale}. + \keyval{linespread}{decimal number}\Module{blank}\Default{\code{1}} + Set the linespread for the blank lines. This only has an effect if + \cs{blank} is used at the begin of a paragraph. + \keyval{line-increment}{dim}\Module{blank}\Default{\code{0.001\cs*{linewidth}}} + The blank line is built in multiples of this value. If the value is too + large you may end up with uneven lines. If the value is too small you may + end up with a non-ending compilation. Experiment with values to find the + suiting one for your use case. + \keyval{line-minimum-length}{dim}\Module{blank}\Default{\code{2em}} + The minimal length a line must have before it is built step by step. +\end{options} + +\begin{example} + This is a \blank{blank} outside in normal text. + \begin{exercise} + Try to fill in \blank[width=4cm]{these} blanks. All of them + \blank{are created} by using the \cs{blank} \blank{command}. + \end{exercise} + \xsimsetup{blank/filled-style=\textcolor{red}{#1}} + \begin{solution}[print] + Try to fill in \blank[width=4cm]{these} blanks. All of them + \blank{are created} by using the \cs{blank} \blank{command}. + \end{solution} +\end{example} +A number of empty lines are easily created by setting the \option{width} +option: +\begin{example} + Write up the pros and cons of \xsim\ over \pkg{exsheets}: + + \blank[width=4.8\linewidth,linespread=1.5]{} +\end{example} + +\edef\lastsection{\arabic{section}} + +\appendix + +\section{Future Plans} + +\xsim\ is complete in so far as it is perfectly usable to create exams or +exercise and solution sections in books with the most freedom in layout +already. But still there are features which would be useful additions. Below +I list all ideas that I currently plan to add to \xsim: +\begin{itemize} + \item a document class \code{xsim-exam} for creating exams; this class + should itself feature the possibility of creating different versions of an + exam, maybe already provide multiple choice questions and so on; one could + also think about automatic creation of running headers and footers, \ie, + means for changing the layout of the exam; following the spirit of \xsim\ + this should probably be done using templates as well. +\end{itemize} +I am very open to suggestions regarding features, both in general and +specifically regarding the document class. + +\section{FAQ \& How to\dots} +This section serves as a kind of gallery showing solutions to common +problems. I expect this section to grow over the years. Some examples +especially regarding other layouts are also shown in example files added to +this package. + +\subsection{\dots Know if \xsim\ Needs Another Compilation?} +If \xsim\ wants you to recompile your document it issues a warning and writes +the following to the logfile: +\begin{sourcecode} + Package xsim Warning: Exercise properties may have changed. Rerun to get them + (xsim) synchronized. +\end{sourcecode} +So just check the logfile regularly (which you should be doing anyway) and +keep your eyes open. + +\subsection{\dots Resolve Getting Repeatedly Wrong Exercise Properties or + Wrong Exercise Lists?}\label{sec:resolve-getting} +\xsimauxfileinfo + +\subsection{\dots Resolve Strange Errors After Updating?} +\xsim\ writes a lot of stuff to the auxiliary file. An update may well change +how this is done so deleting the auxiliary file and doing a few fresh +compilations may 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 if you also use the option \option{use-files}\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?} +Did you try to use an exercise or solution in a macro of some sort? This +generally will fail if you also use the option \option{use-files}. But there +should never be the need to hide the environments inside of a macro, anyway. + +\subsection{\dots Put a Star (or Another Symbol) in Headings of Exercises That + Are Special?} + +The code below shows one possible modification of an exercise template which +allows to easily create bonus exercises: +\begin{sourcecode} + % preamble: + \usepackage{amsymb} + % declare boolean property: + \DeclareExerciseProperty*{bonus} + \DeclareExerciseEnvironmentTemplate{bonus} + {% + \subsection* + {% + % test for boolean property and insert star symbol if true: + \IfExerciseBooleanPropertyT{bonus}{\llap{$\bigstar$ }Bonus }% + \XSIMmixedcase{\GetExerciseName}\nobreakspace + \GetExerciseProperty{counter}% + \IfInsideSolutionF + {% + \IfExercisePropertySetT{subtitle} + { {\normalfont\itshape\GetExerciseProperty{subtitle}}}% + }% + } + \GetExercisePropertyT{points} + {% + \marginpar + {% + \IfInsideSolutionF{\rule{1.2cm}{1pt}\slash}% + \PropertyValue + \GetExercisePropertyT{bonus-points} + {\nobreakspace(+\PropertyValue)}% + \nobreakspace\XSIMtranslate{point-abbr}% + }% + }% + } + {} +\end{sourcecode} + +The usage is now as follows: +\begin{example} + \xsimsetup{exercise/template = bonus} + % set the boolean property to true + \begin{exercise}[bonus] + A bonus question. + \end{exercise} +\end{example} + +\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. +\begin{sourcecode} + % preamble: + % \usepackage{etoolbox} + % \newcounter{sections} + + % document: + \setcounter{sections}{1} + \whileboolexpr + { test {\ifnumless{\value{sections}}{\value{section}+1}} } + { + \printsolutions[section=\value{sections},headings-template=per-section] + \stepcounter{sections} + } +\end{sourcecode} +For this manual we then get the following list\footnote{Taking care of the + fact that we're in the appendix now which means we can't use + \cs*{value}\Marg{section}. Therefore this manual does + \cs*{edef}\cs*{lastsection}\Marg{\cs*{arabic}\Marg{section}} right before + \cs*{appendix}}. + +\newcounter{sections} +\setcounter{sections}{1} +\whileboolexpr + { test {\ifnumless{\value{sections}}{\lastsection+1}} } + { + \printsolutions[section=\value{sections},headings-template=per-section] + \stepcounter{sections} + } + +\section{The \pkg*{xsimverb} package}\label{sec:xsimverb-package} +\xsim\ comes bundled with another package called +\pkg{xsimverb}\xsimverbversion. This package loads a very small subset of +\xsim\ which allows to create environments that write their contents verbatim +to external files. It provides the following commands (which of course are +also available in \xsim, too): + +\begin{commands} + \command{XSIMfilewritestart}[\sarg\marg{file name}] + Start writing to the file named \meta{file name}. This should be the + \emph{last} command in the \emph{begin} definition of an environment. If + is is used in an environment with arguments where the \emph{last} argument + is optional you should check if the optional argument is given and use + the starred version if the test is negative. This is demonstrated in an + example below using \pkg{xparse}'s \cs{NewDocumentEnvironment}. \emph{If + you want an environment with only an optional argument you \emph{should} + use \pkg{xparse}'s commands to define it. Due to the way how + \cs*{newenvironment} scans for optional arguments you'll otherwise may + end up with leading spaces gobbled from the first line in your + environment.} + \command{XSIMfilewritestop} + Stop writing to the file. This should be the \emph{first} command in the + \emph{end} definition of an environment. + \command{XSIMsetfilebegin}[\marg{code}] + This command can be used to write something to the external file + \emph{before} the environment contents. Must be set before + \cs{XSIMfilewritestart} in the \emph{begin} definition. + \command{XSIMsetfileend}[\marg{code}] + This command can be used to write something to the external file + \emph{after} the environment contents. Must be set before + \cs{XSIMfilewritestart} in the \emph{begin} definition. + \command{XSIMgobblechars}[\marg{integer}] + Determines how many characters are cut off of the beginning of each line + of the environment body before it is written to the file. The default + value is~$0$. +\end{commands} + +The following code shows an example of how to use those commands: +\begin{sourcecode} + \documentclass{article} + \usepackage{xsimverb,listings} + + \makeatletter + \NewDocumentEnvironment{example}{o} + {% + \XSIMsetfilebegin{\@percentchar\space file `\jobname.tmp'}% + \XSIMsetfileend{\@percentchar\space bye bye}% + \IfNoValueTF{#1} + {\XSIMfilewritestart*{\jobname.tmp}} + {\XSIMfilewritestart{\jobname.tmp}}% + } + {% + \XSIMfilewritestop + \lstinputlisting[language={[LaTeX]TeX}]{\jobname.tmp}% + \input{\jobname.tmp} + } + \makeatother + + \begin{document} + + \begin{example} + bla bla \LaTeX + \end{example} + + \end{document} +\end{sourcecode} + +The \code{tmp} file produced by the above example will contain the following +three lines (if the file itself was called \code{test.tex}): +\begin{sourcecode} + % file `test.tmp' + bla bla \LaTeX + % bye bye +\end{sourcecode} + +\section{All Exercise Examples} + +\begin{bewareofthedog} + You will notice that some exercises from + section~\vref{sec:template-examples} look differently in this section. That + is because all exercises of a type use the template that's \emph{currently + active}. If you want exercises with a different look you should use + different exercises types. +\end{bewareofthedog} + +The following list is created with this code: +\begin{sourcecode} + \xsimsetup{exercise/template = bonus} + \printcollection[headings]{all exercises} +\end{sourcecode} + +\xsimsetup{exercise/template = bonus} +\printcollection[headings]{all exercises} + +\section{All Solution Examples} +\printsolutions + +\section{Example Documents Coming With This Package}\label{sec:example-files} +The repository of this package\footnote{GitHub: + \url{https://github.com/cgnieder/xsim/}, CTAN: + \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 to solve concrete problems +that have come up in different \LaTeX\ forums. + +Besides showing excerpts of the code and the resulting pdf the examples below +also link to both the \code{tex} source the resulting pdf. + +\listexamplefiles + +\printbibliography + +\end{document} diff --git a/Master/texmf-dist/doc/latex/xsim/xsim.history b/Master/texmf-dist/doc/latex/xsim/xsim.history deleted file mode 100644 index f1b0f860f7d..00000000000 --- a/Master/texmf-dist/doc/latex/xsim/xsim.history +++ /dev/null @@ -1,158 +0,0 @@ --------------------------------------------------------------------------- - -XSIM -- eXercise Sheets IMproved - --------------------------------------------------------------------------- -Clemens Niederberger -Web: https://github.com/cgnieder/xsim -E-Mail: contact@mychemistry.eu --------------------------------------------------------------------------- -Copyright 2017--2020 Clemens Niederberger - -This work may be distributed and/or modified under the -conditions of the LaTeX Project Public License, either version 1.3 -of this license or (at your option) any later version. -The latest version of this license is in - http://www.latex-project.org/lppl.txt -and version 1.3 or later is part of all distributions of LaTeX -version 2005/12/01 or later. - -This work has the LPPL maintenance status `maintained'. - -The Current Maintainer of this work is Clemens Niederberger. --------------------------------------------------------------------------- - -HISTORY: - - v0.0 2017/02/09 - start with coding the first ideas - v0.1 2017/03/19 - first draft which actually seems to do everything as - planned - v0.2 2017/03/21 - bugfix in the verbwrite module - - add `use!' and `print!' properties - - add the concepts of `noupdate' and `boolean' properties - v0.4 2017/03/24 - \IfExerciseBooleanPropertyTF - - \GetExercisePropertyTF, \PropertyValue - - \printallsolutions - - \UseExerciseTemplate - - bug fix in solution environments: now get printed again - when option `print=true' is used - - bug fix to the translations of the solution list headings: - exercise name instead of exercise type is now printed - - \AddtoExerciseTypeGoal, \AddtoExerciseGoal - \AddtoExerciseTypeGoalPrint, \AddtoExerciseGoalPrint, - \ExerciseGoalValuePrint - - \addpoints, \addbonus, \points, \printgoal - v0.5 2017/03/30 - add style file mechanism - - make solution print conditions `section' and `chapter' - combinable - v0.5a 2017/04/15 - fix wrong translation of the `default-heading' - v0.5b 2017/04/16 - add \SetExerciseProperty - v0.6 2017/04/27 - official interface for grade distributions - - refine hook management (environment module) - v0.6a 2017/04/28 - refine \blank command, add documentation for said command - v0.7 2017/05/09 - \xsim_list_length:n - - new boolean property `used' - - when an exercise is collected the counter isn't stepped - but only when the exercise is inserted for the first - time; when this happens the new property `used' is set to - `true' - - make setting boolean properties case insensitive - - add missing pieces to manual (eg `page' property...) - - \TotalExerciseGoals and \TotalExerciseTypeGoals - - \XSIMifchapterTF - - \xsim_if_goal_sum:nnnTF and friends, - \IfExerciseTypeGoalsSumTF and \IfExerciseGoalsSumTF - - some more hints in the manual regarding collections - v0.8 2017/05/18 - bug fix in \xsim_set_property:nnnn - - random exercise lists from collections - - \xsim_collection_count:n - - \GetExerciseIdForProperty and \GetExerciseTypeForProperty - for unique properties - - set property `print=false' during collection and only to - true when the corresponding exercises actually are - printed - - do not insert \par at the beginning and end of exercises - and solutions; this should be left to the templates! - - new option `print-collection/print' which allows to - choose between exercises, solutions, and both to be - printed - - new parameter `solution-counter' in order to avoid - possible conflicts with existing counters - v0.8a 2017/05/19 - \IfPrintSolutionTF - v0.8b 2017/05/23 - use \printgoal in default environment template - - \xsim_print_goal:nnn now expands input to a number - v0.9 2017/06/20 - \xsimstyle's behaviour now matches the description in - the manual - - add style file `layouts' which at the moment provides the - two exercise templates `runin' and `margin' - - \printforexercises , \xsim_print_type_code:nnnnn - - \IfExerciseParameterSetTF - - \GetExerciseParameterTF - - change syntax of \SetExerciseProperty - - \SetExpandedExerciseProperty - - \ExerciseSetProperty, \ExerciseSetExpandedProperty - - property `sectioning' - - \IfExistSolutionTF - v0.10 2017/09/19 - \xsim_input:nnn - - \GetExerciseBody - - option `blank/fill' - - bug fix in \xsim_start_collection:nn - - added further examples to package - - new option `file-extension' - v0.10a 2017/10/01 - bug fix: grading table options can now be set with - \xsimsetup (issue 15) - v0.11 2018/02/12 - change name requirement for style files in order to - prevent possible name clashes with module files - - fix bug in \SetExerciseProperty and - \SetExpandedExerciseProperty - - fix bug when xsimverb is used standalone (issue 21) - - add option `split-aux-lists' (issue 18) - - \IfExerciseTagSetTF and \IfExerciseTopicSetTF - - introduce a \xsim_if__value:nTF for each tag - kind - - \ProvideExerciseTagging - v0.12 2019/09/30 - add parameter versions for the plural forms of exercise - and solution names - - bug fixes (issues 37, 39, 43, 47) - v0.13 2019/10/06 - experimental package option `no-files' - v0.14 2019/10/13 - new exercise parameters `exercise-heading' and - `solution-heading' - - new options `exercise/heading' and `solution/heading' as - interface for setting the new parameters - - new command \GetExerciseHeadingF for using the new - parameters in environment templates - - change the environment template `default' to use the new - \GetExerciseHeadingF and output a \par at the end - - make argument of \xsimsetup long - - new template `minimal' - - new option `load-style' - - new example `texwelt-23968' (long and short solutions) - v0.14a 2019/10/19 - fix \xsim_if_exercise_exist:nnTF to obey the `no-files' - option - v0.15 2019/11/02 - use own auxiliary file per default and add option - `use-aux' - v0.16 2019/11/10 - fix issue due to usage of own auxiliary file - - \XSIMatbegindocument and \XSIMatenddocument - - \xprintexercise, \xprintsolution, \xsimprint, \xsimxprint - 2019/12/29 - bugfix in `xsimverb' - v0.16a 2020/01/16 - adapt to renaming of string case changing functions - v0.17 2020/02/21 - prefer lazy boolean evaluation if possible - - remove spurious \par at the beginning of typeset - exercises - - add `blank' option, implements issue #31 - - add `solution' property, implements issue #33 - - fix issue #27 - - implement issue #2 - - don't allow package options to be set with \xsimsetup - v0.18 2020/02/23 - fix issue #56 - - change \printexercise and \printsolution to accept a - clist of either ids or IDs (or mixed) - - new templates in the `layouts' style - v0.19 2020/03/16 - improve performance - - only set \ExerciseID and \ExerciseType locally to ensure - correct values when exercises (of different types) are - nested - - new load-time option `debug' - only for development - v0.19a 2020/03/19 - fix missing-variant-bug introduced with the last update - v0.19b 2020/04/04 - fix bug in new attribute mechanism which was a problem - when `no-files` has been used diff --git a/Master/texmf-dist/doc/latex/xsim/xsim.ideas b/Master/texmf-dist/doc/latex/xsim/xsim.ideas deleted file mode 100644 index b23ebec899f..00000000000 --- a/Master/texmf-dist/doc/latex/xsim/xsim.ideas +++ /dev/null @@ -1,29 +0,0 @@ --------------------------------------------------------------------------- - -XSIM -- eXercise Sheets IMproved - --------------------------------------------------------------------------- -Clemens Niederberger -Web: https://github.com/cgnieder/xsim -E-Mail: contact@mychemistry.eu --------------------------------------------------------------------------- -Copyright 2017--2020 Clemens Niederberger - -This work may be distributed and/or modified under the -conditions of the LaTeX Project Public License, either version 1.3 -of this license or (at your option) any later version. -The latest version of this license is in - http://www.latex-project.org/lppl.txt -and version 1.3 or later is part of all distributions of LaTeX -version 2005/12/01 or later. - -This work has the LPPL maintenance status `maintained'. - -The Current Maintainer of this work is Clemens Niederberger. --------------------------------------------------------------------------- - -IDEAS: - -- a document class `xsim-exam' for creating exams -- a mechanism for providing variants of an exam - diff --git a/Master/texmf-dist/doc/latex/xsim/xsim_manual.pdf b/Master/texmf-dist/doc/latex/xsim/xsim_manual.pdf deleted file mode 100644 index dad403c26a2..00000000000 Binary files a/Master/texmf-dist/doc/latex/xsim/xsim_manual.pdf and /dev/null differ diff --git a/Master/texmf-dist/doc/latex/xsim/xsim_manual.tex b/Master/texmf-dist/doc/latex/xsim/xsim_manual.tex deleted file mode 100644 index 7b1df9ed5dd..00000000000 --- a/Master/texmf-dist/doc/latex/xsim/xsim_manual.tex +++ /dev/null @@ -1,2421 +0,0 @@ -% !arara: pdflatex: { interaction: nonstopmode } -% !arara: biber -% arara: pdflatex: { interaction: nonstopmode } -% arara: pdflatex: { interaction: nonstopmode } -% arara: pdflatex: { interaction: nonstopmode } -% ---------------------------------------------------------------------------- -% the XSIM package -% -% eXercise Sheets IMproved -% -% ---------------------------------------------------------------------------- -% Clemens Niederberger -% Web: https://github.com/cgnieder/xsim -% E-Mail: contact@mychemistry.eu -% ---------------------------------------------------------------------------- -% Copyright 2017--2020 Clemens Niederberger -% -% This work may be distributed and/or modified under the -% conditions of the LaTeX Project Public License, either version 1.3 -% of this license or (at your option) any later version. -% The latest version of this license is in -% http://www.latex-project.org/lppl.txt -% and version 1.3 or later is part of all distributions of LaTeX -% version 2005/12/01 or later. -% -% This work has the LPPL maintenance status `maintained'. -% -% The Current Maintainer of this work is Clemens Niederberger. -% ---------------------------------------------------------------------------- -% If you have any ideas, questions, suggestions or bugs to report, please -% feel free to contact me. -% ---------------------------------------------------------------------------- -\documentclass{xsim-manual} - -\begin{filecontents*}[overwrite]{\jobname.bib} -@online{texsx:romannumeral, - author = {Bruno Le Floch} , - title = {Cunning (La)TeX tricks} , - urldate = {2017-03-02} , - url = {http://tex.stackexchange.com/a/19769/} -} -@online{texsx:tagged/exsheets, - title = {Questions tagged `exsheets'} , - author = {various} , - url = {http://tex.stackexchange.com/questions/tagged/exsheets} , - urldate = {2020-02-21} -} -\end{filecontents*} -\addbibresource{\jobname.bib} - -\begin{document} - -\section{Licence, Requirements and \texorpdfstring{\textsc{readme}}{README}} -\license - -\xsim\ loads the packages \pkg{expl3}~\cite{bnd:l3kernel}, -\pkg{xparse}~\cite{bnd:l3packages}, \pkg{etoolbox}~\cite{pkg:etoolbox}, -\pkg{array}~\cite{pkg:array} \pkg{booktabs}~\cite{pkg:booktabs} and -\pkg{translations}~\cite{pkg:translations}. All of these packages are present -on a modern and up to date \TeX\ distribution such as \TeX~Live or MiK\TeX\ so -no further action should be needed. When you are using \xsim\ you should be -using an up to date \TeX\ distribution, anyway. - -\begin{bewareofthedog} - Newer versions of \xsim\ may depend on newer versions of the support - packages. Remember: it is always dangerous to update single packages. - Always update your \TeX\ distribution if you want an up to date version of a - package. Be careful: if you're in the middle of an important project it - might be better to wait with the update until you've finished the project. - Every update might be breaking some things. - - Please also be aware that \xsim\ is actively developed and many things may - still change. However, I will try my best to keep the interface stable. -\end{bewareofthedog} - -I'm currently thinking to make the option \option{no-files} the default -behavior of \xsim. There is a poll and discussion regarding this question on -\xsim's github page if you like to give your opinion on this. - -\begin{bewareofthedog} - The whole collection mechanism is likely to change completely in the - not-so-far future (let's say sometime in the six months from April~2020 or - so). -\end{bewareofthedog} - -\section{Motivation, Background} - -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 (143~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. - -This is due to several facts. It lacks a few features which I consider -essential for a full version~1. For one thing it is not possible to have -several kinds of exercises numbered independently. Using verbatim material -such as listings inside exercises and solutions is not possible and the -current workaround isn't that ideal either. One request which dates back -quite a while now was to have different types of points to exercises\ldots - -All of those aren't easy to add due to the way \pkg{exsheets} is implemented -right now. As a consequence I wanted to re-implement \pkg{exsheets} for a long -time. This is what lead to \xsim. Internally the package works completely -different. - -\begin{bewareofthedog} - \xsim\ will be the official successor of \pkg{exsheets} which is now - considered obsolete but will stay alive and will still receive bugfix - releases. However, new features will not be added to \pkg{exsheets} any - more. -\end{bewareofthedog} - -\section{How to Read the Manual}\label{sec:how-read-manual} - -\subsection{Nomenclature} - -Throughout this manual certain terms are used. This section explains their -meaning in this manual. - -\acuseall -\printacronyms[heading=none] - -\subsection{Package Options}\label{sec:package-options} -\xsim\ has these package options: -\begin{options} - \opt{verbose} - Writes extensive information about what \xsim\ is doing into the log - file. - \opt{final} - If used the exercise and solution environments will not rewrite the - environment body files. - \opt{clear-aux} - If used every time the total number of exercise changes \xsim\ will write - \emph{less} information to the auxiliary file on the next run and only if - the number of exercises stays stable between compilations the needed - information will be written to the auxiliary file. \emph{This needs more - compilations until everything stabilizes but should reduce the - probability of possibly faulty exercises after changes to the document.} - The \option{final} option automatically disables this option. See also - sections~\vref{sec:how-exerc-envir} and~\vref{sec:resolve-getting}. - \opt{no-files} - \sinceversion{0.13}This option prevents \xsim\ from writing the exercises - and solutions to external files. This will keep your working folder - ``clean'' but will also prevent using verbatim material in exercises and - solutions and will possibly slow processing further down. \emph{This - option is considered experimental. Feedback is very welcome.} - \opt{use-aux} - \sinceversion{0.15}With this option enabled \xsim\ will use the regular - auxiliary file \cs*{jobname}\code{.aux} instead of its own auxiliary file - \cs*{jobname}\code{.xsim}. - \opt{blank} - \sinceversion{0.17}With this option enabled \xsim\ will not define the - default environments \env{exercise} and \env{solution}. -\end{options} - -Those options are load-time options and are used the usual way as package -options: -\begin{sourcecode} - \usepackage[verbose]{xsim} -\end{sourcecode} -\begin{bewareofthedog} - Although those options technically belong to the \module{package} module - (see also section~\vref{sec:setting-options}) it is \emph{not} possible to - set them via \cs{xsimsetup}. -\end{bewareofthedog} - -\subsection{Setting Options}\label{sec:setting-options} -Apart from the package options already described in -section~\vref{sec:package-options} \xsim\ has further options. All those -options are set using the following command: -\begin{commands} - \command{xsimsetup}[\marg{options}] - Set up \xsim's package options and all other options described at - other places in the manual. -\end{commands} -Options can be \enquote{toplevel} options or options belonging to a module: -\begin{options} - \keyval*{toplevel}{value} - A toplevel option. - \keyval*{sublevel}{value}\Module*{module} - A sublevel option belonging to the module \module*{module} -\end{options} -Both kinds of options are set with the setup command: -\begin{sourcecode} - \xsimsetup{ - toplevel = {value} , - module/sublevel = {value} - } -\end{sourcecode} - -\subsection{Command descriptions} - -Some commands do have a \expandablesymbol\ symbol printed next to their -names. This indicates that the command is expandable, \ie, it is usable in an -\cs*{edef} or \cs*{write} context and will expand according to its -description. All other commands are engine protected, \ie, in the sense of -\eTeX's \cs*{protected}. - -Some command name descriptions end with \code{\TF}. -\begin{commands} - \command*{SomeCommand\TF}[\meta{arguments}\marg{true}\marg{false}] - A command with maybe some arguments and ending with the two arguments - \meta{true} and \meta{false}. -\end{commands} -This means two things: the command is a conditional which tests something and -depending on the outcome of the test leaves either the \meta{true} argument -(\code{T}) or the \meta{false} argument (\code{F}) in the input stream. It -also means two additional commands exist: -\begin{commands} - \command*{SomeCommandT}[\meta{arguments}\marg{true}] - The same as \cs*{SomeCommandTF} but only with the \meta{true} argument and - no \meta{false} argument. - \command*{SomeCommandF}[\meta{arguments}\marg{false}] - The same as \cs*{SomeCommandTF} but only with the \meta{false} argument and - no \meta{true} argument. -\end{commands} - -\section{Exercises and Solutions} - -The two predefined environments for exercises and solutions are the following -ones\footnote{When you load \xsim\ with the \option{blank} those environments - will \emph{not} be defined!}: -\begin{environments} - \environment{exercise}[\oarg{\acsp*{prop}}] - Input and typeset an exercise. See section~\vref{sec:exercise-properties} - for details on exercise \acsp*{prop}. - \environment{solution}[\oarg{options}] - Input and typeset the solution to the exercise of the previous - \env{exercise} environment. See section~\vref{sec:printing-solutions} for - details on options of solutions. -\end{environments} - -\begin{example} - \begin{exercise} - A first example for an exercise. - \end{exercise} - \begin{solution} - A first example for a solution. - \end{solution} -\end{example} - -As can be seen in the example a solution is not printed with the default -setup. This can be changed using the following option. -\begin{options} - \keybool{print}\Module{solution}\Default{false} - Set if solutions are printed or not. -\end{options} - -The option (belonging to the module \module*{solution}) can either be set -locally as option to the \env{solution} environment -\begin{sourcecode} - \begin{solution}[print=true] - A first example for a solution. - \end{solution} -\end{sourcecode} -or with the setup command for all following solutions: -\begin{sourcecode} - \xsimsetup{ - solution/print = true - } -\end{sourcecode} - -There is an completely analoguous option for the \env{exercise} environment: -\begin{options} - \keybool{print}\Module{exercise}\Default{true} - Set if exercises are printed or not. -\end{options} -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 the exercise and the solution environments 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} -\end{itemize} -The name starts with the name of the job (which is the name of the document -itself) followed by type and id of the corresponding exercise and then -followed by the environment type. For example both environments from the first -example have been written to files named -\begin{itemize} - \item \verbcode+xsim_manual-exercise-1-exercise-body.tex+ and - \item \verbcode+xsim_manual-exercise-1-solution-body.tex+, respectively. -\end{itemize} -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. 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} - -Arguably one downside of the approach using external files for each exercise -and its solution is that your project folder will be cluttered with files. In -order to deal with this somehow \xsim\ offers the following option: -\begin{options} - \keyval{path}{path name}\Default - With this option a subfolder or path within the main project folder can be - 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 - external files. -\end{options} - -\begin{bewareofthedog} - Another thing to keep in mind: the environment in many ways works the same - way as the \env{filecontents} environment. \emph{This also means that you - \emph{cannot} have comments or \cs*{label}s or anything else on the first - line of the environments!} -\end{bewareofthedog} -\begin{sourcecode} - \begin{exercise}[points=2] % this comment will cause trouble - Lorem ipsum - \end{exercise} -\end{sourcecode} - -If\sinceversion{0.13} you don't like all the external files and the problems -which come with them \emph{and} if you don't need any verbatim or similar -material inside the exercises and solutions then you can use the following -package option: -\begin{options} - \opt{no-files} - This package option prevents \xsim\ from writing the exercises and - solutions to external files. This will keep your working folder ``clean'' - but will also prevent using verbatim material in exercises and solutions - and will possibly slow processing further down. \emph{This option is - considered experimental. Feedback is very welcome.} -\end{options} - -\begin{bewareofthedog} - \xsimauxfileinfo -\end{bewareofthedog} - -\begin{bewareofthedog} - A lot of the lines \xsim\ writes to the auxiliary file 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 \code{||}. This means that you cannot use this symbol - combination inside properties. For this reason \xsim\ provides an option to - change the 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 auxiliary file. -\end{options} - -\section{New Exercise Types}\label{sec:new-exercise-types} - -It is easy to define new exercise environments together with a corresponding -solution environment using the following command: -\begin{commands} - \command{DeclareExerciseType}[\marg{type}\marg{parameters}] - Declare a new exercise type analoguous to the \env{exercise} and - \env{solution} environments. -\end{commands} -Declaring a new exercise type will also define a new command: -\begin{commands} - \command{numberof\meta{exercise-env}s} - These commands hold the absolut number of used exercises of type - \meta{type}. The meaning of \meta{exercise-env} will become clear below - when the exercise parameters are explained. It is always the same as the - exercise environment name. -\end{commands} -\begin{example} - There are \numberofexercises~exercises and \numberofproblems~problem in this - manual. -\end{example} -\xsim's pre-defined environment pair\changedversion{0.14} has been defined as -follows: -\begin{sourcecode} - \DeclareExerciseType{exercise}{ - exercise-env = exercise , - solution-env = solution , - exercise-name = \XSIMtranslate{exercise} , - exercises-name = \XSIMtranslate{exercises} , - solution-name = \XSIMtranslate{solution} , - solutions-name = \XSIMtranslate{solutions} , - exercise-template = default , - solution-template = default , - exercise-heading = \subsection* , - solution-heading = \subsection* - } -\end{sourcecode} - -The above already is an example for almost all parameters that can (and often -must) be set. Here is the complete list: -\begin{parameters} - \paraval{exercise-env}{exercise environment name} - The name for the environment used for the exercises of type \meta{type}. - \emph{This parameter is mandatory.} It can't be changed afterwards. - \paraval{solution-env}{solution environment name} - The name for the environment used for the solutions of type \meta{type}. - \emph{This parameter is mandatory.} It can't be changed afterwards. - \paraval{exercise-name}{exercise name} - The name of the exercises of type \meta{type} -- used for typesetting. - \emph{This parameter is mandatory.} - \paraval{exercises-name}{exercises name} - The\sinceversion{0.12} plural name of the exercises of type \meta{type} -- - used for typesetting. If this is not set explicitly an \code{s} is - appended to the singular name. - \paraval{solution-name}{solution name} - The name of the solutions of type \meta{type} -- used for typesetting. - \emph{This parameter is mandatory.} - \paraval{solutions-name}{solutions name} - The\sinceversion{0.12} plural name of the solutions of type \meta{type} -- - used for typesetting. If this is not set explicitly an \code{s} is - appended to the singular name. - \paraval{exercise-template}{exercise template} - The template used for typesetting the exercises of type \meta{type}. - \emph{This parameter is mandatory.} See - section~\vref{sec:styl-exerc-templ} for details on templates. - \paraval{solution-template}{solution template} - The template used for typesetting the exercises of type \meta{type}. - \emph{This parameter is mandatory.} See - section~\vref{sec:styl-exerc-templ} for details on templates. - \paraval{counter}{counter name} - The counter used for the exercises of type \meta{type}. If not explicitly - set the counter with the same name as \parameter{exercise-env} is used. - Otherwise the specified counter is used. This enables to have different - types of exercises sharing a common counter. \emph{This parameter can't - be changed afterwards.} If the explicit or implicit counter does not - exist, yet, it will be defined. - \paraval{solution-counter}{counter name} - The counter used for the solutions of type \meta{type}. If not explicitly - set the counter with the same name as \parameter{solution-env} is used. - Otherwise the specified counter is used. This enables to have different - types of solutions sharing a common counter although this doesn't actually - make much sense. But it can be useful to avoid using an already existing - counter. \emph{This parameter can't be changed afterwards.} If the - explicit or implicit counter does not exist, yet, it will be defined. The - sole purpose of this counter is to be able to label solutions so they can - be \cs*{pageref}ed. - \paraval{number}{integer} - An internal parameter that is used to keep track of the number of - exercises of a type. This parameter cannot be set or changed by the - user. - \paraval{exercise-heading}{exercise heading command} - The\sinceversion{0.14} command used for typesetting of the heading of - exercises of type \meta{type} -- used for typesetting with the command - \cs{GetExerciseHeadingF}. - \paraval{solution-heading}{solution heading command} - The\sinceversion{0.14} command used for typesetting of the heading of - solutions of type \meta{type} -- used for typesetting with the command - \cs{GetExerciseHeadingF}. -\end{parameters} - -It is possible to change some of the parameters after an exercise type has -been defined. Those include \parameter{exercise-name}, -\parameter{solution-name}, \parameter{exercise-template}, and -\parameter{solution-template}. It is also possible to define new parameters. -\begin{commands} - \command{DeclareExerciseParameter}[\sarg\marg{parameter}] - Declares the new parameter \meta{parameter}. The optional star declares a - fixed parameter which cannot be changed once it is set. \emph{You - probably will never need this command. Most tasks can be solved using - properties (see section~\vref{sec:exercise-properties}) instead.} - \command{SetExerciseParameter}[\marg{type}\marg{parameter}\marg{value}] - Usable to set a single parameter to a new value. - \command{SetExerciseParameters}[\marg{type}\marg{parameters}] - Set several parameters at once. \meta{parameters} is a csv list of - key/value pairs. -\end{commands} -If you try to set an already set but fixed parameter like -\parameter{exercise-env} a warning will be written to the log file. For all -parameters that can be changed also options exist wich can be set via -\cs{xsimsetup}. They are explained in -section~\vref{sec:environment-options-hooks}. - -\begin{bewareofthedog} - All exercises of a type use the parameters - (\eg, \parameter{exercise-template}) that are \emph{currently active}. If - you want exercises with a different look or different names in the same - document you should use different exercises types. -\end{bewareofthedog} - -\section{Exercise Properties}\label{sec:exercise-properties} - -\subsection{Predefined Properties} - -Exercise like the \env{exercise} environment and possibly others defined with -\cs{DeclareExerciseType} have a number of predefined \acsp*{prop}: -\begin{properties} - \propval{id}{integer} - Holds the internal id of an exercise. \emph{Cannot be set by the user}. - \propval{ID}{text} - Holds the user id of an exercise if defined. Otherwise it is equal to - \property{id}. - \propval{counter}{text} - Holds the counter value representation of an exercise (\ie, what you - usually know as \cs*{the\meta{counter}}). \emph{Cannot be set by the - user}. - \propval{counter-value}{integer} - Holds the counter value of an exercise (\ie, what you usually know as - \cs*{the}\cs*{value}\marg{counter}). \emph{Cannot be set by the user}. - \propval{subtitle}{text} - Holds the subtitle of an exercise. - \propval{points}{number} - Holds the reachable points of an exercise. - \propval{bonus-points}{number} - Holds the reachable bonus-points of an exercise. - \propbool{print} - Holds the print boolean of an exercise. - \propbool{print\bang} - Holds a special print boolean of an exercise, see - page~\pageref{property:print!}. - \propbool{use} - Holds the usage boolean of an exercise. - \propbool{use\bang} - Holds a special usage boolean of an exercise, see - page~\pageref{property:print!}. - \propbool{used} - True if an exercise has been used at least once. For an existing exercise - this is only false for exercises that have been collected - (\cf~section~\vref{sec:collecting-exercises}). - \propbool{solution} - \sinceversion{0.17}Holds the solution boolean of an exercise. If this is - true then a solution has the same text\slash environment body as the - corresponding exercise. (This might be useful for multiple choice - questions for example.) - \propval{tags}{csv list of tags} - Holds the list of tags the exercise should be associated with. - \propval{topics}{csv list of topics} - Holds the list of topics the exercise should be associated with. - \propval{page}{text} - Holds the page counter value representation of an exercise \\ - (\ie, what you usually know as \cs*{thepage}). - \propval{page-value}{integer} - Holds the page counter value of an exercise \\ - (\ie, what you usually know as \cs*{the}\cs*{value}\Marg{page}). - \propval{section}{text} - Holds the section counter value representation of an exercise \\ - (\ie, what you usually know as \cs*{thesection}). - \propval{section-value}{integer} - Holds the section counter value of an exercise \\ - (\ie, what you usually know as \cs*{the}\cs*{value}\Marg{section}). - \propval{chapter}{text} - Holds the chapter counter value representation of an exercise \\ - (\ie, what you usually know as \cs*{thechapter}). \\ - \emph{Only if a command \cs*{chapter} \emph{and} a counter \code{chapter} - exist.} - \propval{chapter-value}{integer} - Holds the chapter counter value of an exercise \\ - (\ie, what you usually know as \cs*{the}\cs*{value}\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}. - \propval{exercise-body}{\TeX code} - When\sinceversion{0.13} the package option \option{no-files} is set this - property is defined and holds the environment body of an exercise. - \propval{solution-body}{\TeX code} - When\sinceversion{0.13} the package option \option{no-files} is set this - property is defined and holds the environment body of the corresponding - solution. -\end{properties} - -Some of these \acsp*{prop} are fixed and cannot be set by the user. Those -include \property{id}, \property{counter}, and \property{counter-value}. The -others can be set using the optional argument of the exercise environment. - -\begin{example} - \begin{exercise}[subtitle={This is a subtitle},points=4,bonus-points=1] - An exercise where some properties have been set. - \end{exercise} -\end{example} - -\subsection{Declaring Own Properties} - -\xsim\ offers the possibility to declare additional exercise properties: -\begin{commands} - \command{DeclareExerciseProperty}[\barg\sarg\narg\marg{property}] - Declares the property \meta{property}. - - 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 - exercise is used. - \command{DeclareExercisePropertyAlias}[\marg{property 1}\marg{property 2}] - Declares \meta{property 1} to be an alias of \meta{property 2}. This - means that each time \meta{property 2} is set \meta{property 1} will be - set to the same value \emph{unless} it has been set already. As an - example: property \property{ID} is an alias of property \property{id}. -\end{commands} - -This is better demonstrated with an example: -\begin{example} - \begin{exercise} - \verb+\GetExerciseProperty{id}+: \GetExerciseProperty{id} \par - \verb+\GetExerciseAliasProperty{ID}+: \GetExerciseAliasProperty{ID} \par - \verb+\GetExerciseProperty{ID}+: \GetExerciseProperty{ID} - \end{exercise} - \begin{exercise}[ID=foo-bar] - \verb+\GetExerciseProperty{id}+: \GetExerciseProperty{id} \par - \verb+\GetExerciseAliasProperty{ID}+: \GetExerciseAliasProperty{ID} \par - \verb+\GetExerciseProperty{ID}+: \GetExerciseProperty{ID} - \end{exercise} -\end{example} - -The power of properties will get more clear when reading -section~\vref{sec:styl-exerc-templ} about templates. - -\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 -(only) get a decimal number as value the sum of which is calculated and -available (after a compilation) throughout the document. -\begin{commands} - \command{DeclareExerciseGoal}[\marg{goal}] - Declare a new exercise goal named \meta{goal} and also a property called - \meta{goal}. - \command{TotalExerciseTypeGoal}[\marg{type}\marg{goal}\marg{singular}\marg{plural}] - Get the sum of goal \meta{goal} for all exercises of type \meta{type}. - \meta{singular} and \meta{plural} are placed after the sum in the input - stream depending on whether the sum equals~$1$ or not. - \command{TotalExerciseTypeGoals}[\marg{type}\marg{list of - goals}\marg{singular}\marg{plural}] - Get the sum of goal all goals in \meta{list of goals} for all exercises of - type \meta{type}. The goal names in \meta{list of goals} must be - separated with \code{+}. \meta{singular} and \meta{plural} are placed - after the sum in the input stream depending on whether the sum equals~$1$ - or not. - \command{TotalExerciseGoal}[\marg{goal}\marg{singular}\marg{plural}] - Get the sum of goal \meta{goal} for all exercises. \meta{singular} and - \meta{plural} are placed after the sum in the input stream depending on - whether the sum equals~$1$ or not. - \command{TotalExerciseGoals}[\marg{list of - goals}\marg{singular}\marg{plural}] - Get the sum of goal all goals in \meta{list of goals} for all exercises. - The goal names in \meta{list of goals} must be separated with - \code{+}. \meta{singular} and \meta{plural} are placed after the sum in - the input stream depending on whether the sum equals~$1$ or not. - \command{AddtoExerciseTypeGoal}[\marg{type}\marg{goal}\marg{value}] - Adds \meta{value} to the goal \meta{goal} of exercise type \meta{type}. - \command{AddtoExerciseTypeGoalPrint}[\marg{type}\marg{goal}\marg{value}% - \marg{singular}\marg{plural}] - Adds \meta{value} to the goal \meta{goal} of exercise type \meta{type}. - The value and -- depending on wether the value equals $1$ or not -- - \meta{singular} or \meta{plural} are left in the input stream. - \command{AddtoExerciseGoal}[\marg{goal}\marg{value}] - Adds \meta{value} to the goal \meta{goal} of the current exercise - type. (To be used within exercises.) - \command{AddtoExerciseTypeGoalPrint}[\marg{goal}\marg{value}% - \marg{singular}\marg{plural}] - Adds \meta{value} to the goal \meta{goal} of the current exercise type. - The value and -- depending on wether the value equals $1$ or not -- - \meta{singular} or \meta{plural} are left in the input stream. (To be used - within exercises.) - \command{ExerciseGoalValuePrint}[\marg{value}\marg{singular}\marg{plural}] - Print \meta{value} and -- depending on wether the value equals $1$ or not -- - \meta{singular} or \meta{plural}. - \command{printgoal}[\marg{value}] - Print \meta{value} according to option \option{goal-print}. Defined in - terms of \cs{ExerciseGoalValuePrint}. - \command{printpoints}[\marg{type}] - Print the sum of points for all exercises of type \meta{type} followed by - an appropriate translation of the words \enquote{point} or - \enquote{points}, respectively\footnote{See section~\vref{sec:exerc-transl} - for details on the definition and usage of language dependent words.}. - Defined in terms of \cs{TotalExerciseTypeGoal}. - \command{printtotalpoints} - Print the sum of points for all exercises followed by an appropriate - translation of the words \enquote{point} or \enquote{points}, - respectively. Defined in terms of \cs{TotalExerciseGoal}. - \command{addpoints}[\sarg\marg{value}] - Adds \meta{value} to the points of the current exercise type. (To be used - within exercises.) Prints the value followed by an appropriate - translation of the words \enquote{point} or \enquote{points}, - respectively. The starred version prints nothing. Defined in terms of - \cs{AddtoExerciseGoal} and \cs{AddtoExerciseGoalPrint}. - \command{points}[\marg{value}] - Print \meta{value} followed by an appropriate translation of the words - \enquote{point} or \enquote{points}, respectively. Defined in terms of - \cs{ExerciseGoalValuePrint}. - \command{printbonus}[\marg{type}] - Print the sum of bonus points for all exercises of type \meta{type} - followed by an appropriate translation of the words \enquote{point} or - \enquote{points}, respectively. Defined in terms of - \cs{TotalExerciseTypeGoal}. - \command{printtotalbonus} - Print the sum of bonus points for all exercises followed by an appropriate - translation of the words \enquote{point} or \enquote{points}, - respectively. Defined in terms of \cs{TotalExerciseGoal}. - \command{addbonus}[\sarg\marg{value}] - Adds \meta{value} to the bonus points of the current exercise type. (To be - used within exercises.) Prints the value followed by an appropriate - translation of the words \enquote{point} or \enquote{points}, - respectively. The starred version prints nothing. Defined in terms of - \cs{AddtoExerciseGoal} and \cs{AddtoExerciseGoalPrint}. -\end{commands} - -The two existing goals are defined with -\begin{sourcecode} - \DeclareExerciseGoal{points} - \DeclareExerciseGoal{bonus-points} -\end{sourcecode} - -When goal values are printed the decimal number is fed to a function which can -be changed using the following option: -\begin{options} - \keyval{goal-print}{code}\Default{\#1} - How to format goal values. Use \code{\#1} to refer to the actual number. -\end{options} - -At last some examples for a custom command: let's say you want a command which -prints the complete sum for all exercises of all exercise types of both -\property{points} \emph{and} \property{bonus-points} added up: -\begin{sourcecode} - \NewDocumentCommand\printsumofpointsandbonus{}{% - \TotalExerciseGoals{points+bonus-points} - {\,\XSIMtranslate{point}} - {\,\XSIMtranslate{points}}% - } -\end{sourcecode} -Here is how you could mimick the command \cs*{totalpoints} from -\pkg{exsheets}: -\begin{sourcecode} - \NewDocumentCommand\pointsandbonus{}{% - \TotalExerciseGoal{points}{}{}% - \IfExerciseGoalsSumF{bonus-points}{=0} - {\,(+\,\TotalExerciseGoal{bonus-points}{}{})}% - \,\XSIMtranslate{points}% - } -\end{sourcecode} - - -\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) -get a csv list of strings as value. Those strings can be used to selectively -use exercises. See section~\vref{sec:using-printing} for details on -\emph{usage} of exercises and the difference to \emph{printing} an exercise -and how to use exercise tags for selection. -\begin{commands} - \command{DeclareExerciseTagging}[\marg{tag}] - This defines an exercise tagging group named \meta{tag}. It also defines a - 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: -\begin{sourcecode} - \DeclareExerciseTagging{tags} - \DeclareExerciseTagging{topics} - \xsimsetup{tags/ignore-untagged=false} -\end{sourcecode} -This means that these options are available: -\begin{options} - \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 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-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 -exercises to be printed or used even if they don't match the tagging -criteria. For this reason two additional properties exist which can be set to -an exercise:\label{property:print!} -\begin{properties} - \propbool{print\bang} - If set to true the exercise will be printed (and thus used) regardless of - other conditions. - \propbool{use\bang} - If set to true the exercise will be used regardless of other conditions. -\end{properties} - -\section{Using and Printing an Exercise}\label{sec:using-printing} -\subsection{What the Environments do} - -When an exercise is started with \environ{exercise} (or other environments -defined through \cs{DeclareExerciseType}) then different things happen -depending on different settings: -\begin{itemize} - \item If the \emph{insert mode} is active nothing happens, see - section~\vref{sec:collecting-exercises} for details on this. - \item Else the id integer is incremented. - \item If the exercise is \emph{used} the corresponding counter is stepped - and the exercise is added to the \enquote{use list}. The properties - \property{counter} and \property{use} are updated accordingly. - \item If an exercise is \emph{printed} then it is also \emph{used}. An - exercise that isn't used cannot be printed. Being printed means two - things: being added to the \enquote{print list} and being typeset at the - position where the exercise is placed in the source file. If an exercise - is \emph{not printed but used} it means that the counter will be stepped. - This can be useful for creating an exercise sheet only containing the - solutions for some exercises. - \item If an exercise is printed certain hooks and template code is inserted - around the environment body. -\end{itemize} - -\begin{example} - \begin{exercise}[print=false,ID=invisible] - This exercise will not be printed but the exercise counter will be - incremented nonetheless. Its solution will be printed in the list of - solutions. - \end{exercise} - \begin{solution} - The solution of the exercise that has not been printed. - \end{solution} -\end{example} - -The schematic structure of an exercise is shown in -figure~\vref{fig:schematic-structure}. - -\begin{figure} - \centering - \begin{tikzpicture} - \node[draw,minimum width=.7\linewidth] at (0,0) {pre hook}; - \node[draw,minimum width=.7\linewidth] at (0,-1) {begin template code}; - \node[draw,minimum width=.7\linewidth] at (0,-2) {begin hook}; - \node[draw,minimum width=.7\linewidth] at (0,-3) {environment body}; - \node[draw,minimum width=.7\linewidth] at (0,-4) {end hook}; - \node[draw,minimum width=.7\linewidth] at (0,-5) {end template code}; - \node[draw,minimum width=.7\linewidth] at (0,-6) {post hook}; - \end{tikzpicture} - \caption{Schematic structure of an exercise or solution.}\label{fig:schematic-structure} -\end{figure} - -\subsection{Environment Options \& Hooks}\label{sec:environment-options-hooks} - -For each exercise type there are the following options for both environments, -the environments' names are the module names for the options (here using the -\enquote{exercise} type): -\begin{options} - \keybool{print}\Module{exercise}\Default{true} - Determines if exercises of type \enquote{exercise} are printed. - \keybool{use}\Module{exercise}\Default{true} - Determines if exercises of type \enquote{exercise} are used. - \keyval{within}{counter}\Module{exercise}\Default - Adds the exercise counter to the reset list of the counter - \meta{counter}. \emph{Beware that if the counter is a shared counter - this will affect \emph{all objects} using this counter!} - \keyval{the-counter}{code}\Module{exercise} - An interface for redefining the counter representation command - \cs*{the\meta{counter}}. - \keyval{template}{template}\Module{exercise} - An interface for \cs{SetExerciseParameter}\Marg{exercise}% - \Marg{exercise-template}\marg{template}. - \keyval{template}{template}\Module{solution} - An interface for \cs{SetExerciseParameter}\Marg{exercise}% - \Marg{solution-template}\marg{template}. - \keyval{name}{name}\Module{exercise} - An interface for \cs{SetExerciseParameter}\Marg{exercise}% - \Marg{exercise-name}\marg{name}. - \keyval{name}{name}\Module{solution} - An interface for \cs{SetExerciseParameter}\Marg{exercise}% - \Marg{solution-name}\marg{name}. - \keyval{heading}{heading command}\Module{exercise} - An\sinceversion{0.14} interface for \cs{SetExerciseParameter}% - \Marg{exercise}\Marg{exercise-heading}\marg{heading command}. - \keyval{heading}{heading command}\Module{solution} - An\sinceversion{0.14} interface for \cs{SetExerciseParameter}% - \Marg{exercise}\Marg{solution-heading}\marg{heading command}. - \keyval{pre-hook}{code}\Module{exercise}\Default - The code for the \emph{pre exercise hook} for exercises of the type - \enquote{exercise}. - \keyval{begin-hook}{code}\Module{exercise}\Default - The code for the \emph{begin exercise hook} for exercises of the type - \enquote{exercise}. - \keyval{end-hook}{code}\Module{exercise}\Default - The code for the \emph{end exercise hook} for exercises of the type - \enquote{exercise}. - \keyval{post-hook}{code}\Module{exercise}\Default - The code for the \emph{post exercise hook} for exercises of the type - \enquote{exercise}. - \keybool{print}\Module{solution}\Default{false} - Determines if solutions of type \enquote{exercise} are printed. - \keyval{pre-hook}{code}\Module{solution}\Default - The code for the \emph{pre solution hook} for solutions of the type - \enquote{exercise}. - \keyval{begin-hook}{code}\Module{solution}\Default - The code for the \emph{begin solution hook} for solutions of the type - \enquote{exercise}. - \keyval{end-hook}{code}\Module{solution}\Default - The code for the \emph{end solution hook} for solutions of the type - \enquote{exercise}. - \keyval{post-hook}{code}\Module{solution}\Default - The code for the \emph{post solution hook} for solutions of the type - \enquote{exercise}. - % TODO -\end{options} - -\subsection{(Re-) Inserting a Certain Exercise} -If you know type and \property{id} of an exercise you can (re-)insert every -existing exercise, \ie, every exercise whose external file exists. -\begin{commands} - \command{printexercise}[\marg{type}\marg{csv of ids}] - \changedversion{0.17}Inserts the exercise or exercises of type - \meta{type} with the \property{id}s or \property{ID}s given in \meta{csv - of ids}. - \command{xprintexercise}[\marg{type}\marg{csv of ids}] - \sincechanged{0.16}{0.17}The same as \cs{printexercise} but expands - \meta{type} and the items of \meta{csv of ids} before it uses them. -\end{commands} -\begin{example} - \printexercise{exercise}{invisible} -\end{example} - -\section{Collecting Exercises}\label{sec:collecting-exercises} - -\begin{bewareofthedog} - The whole collection mechanism is likely to change completely in the - not-so-far future (let's say sometime in the six months from April~2020 or - so). -\end{bewareofthedog} - -\subsection{Background} -\xsim\ knows the concept of \enquote{exercise collections}. A collection of -exercises can be useful when you want to print a certain group of exercises -several times. Each collection must have a unique name with which you can -refer to the corresponding collection. A collection is realized by declaring -the collection and by surrounding the exercises belonging to the collection -with a certain pair of commands (this is explained in the next section). - -Let's say you have several files of math exercises where one only contains -geometry exercises and another only calculus exercises and so on. Surrounding -the \cs*{input} of each file with said pair of commands for a certain -collection all exercises of the corresponding file now are a collection which -then can be printed at once whereever you want the collection of exercises to -be printed. By choosing certain tags (see section~\vref{sec:tags}) inside -each collection you could even cherry-pick exercises from the external file. - -\subsection{Usage} -\emph{A collection must be declared in the preamble.} Using a pair of -commands explained below exercises between those commands are added to the -corresponding collection but not printed. After a collection is completed the -collection can be printed as often as needed. -\begin{commands} - \command{DeclareExerciseCollection}[\marg{collection name}] - Define a new collection \meta{collection name} in the document preamble. - \command{collectexercisestype}[\marg{collection name}\marg{exercise type}] - Opens the collection \meta{collection name} which now collects all - exercises of type \meta{exercise type} until the collection is closed with - \cs{collectexercisesstop}. Collections of other types are not - collected\footnote{This command starts a group with - \cs*{begingroup}!}. - \command{collectexercises}[\marg{collection name}] - Opens the collection \meta{collection name} which now collects all - exercises until the collection is closed with - \cs{collectexercisesstop}\footnote{This command starts a group with - \cs*{begingroup}!}. - \command{collectexercisesstop}[\marg{collection name}] - Closes the collection \meta{collection name}\footnote{This command ends - a group with \cs*{endgroup}!}. - \command{printcollection}[\oarg{options}\marg{collection name}] - Prints the collection \meta{collection name}, \ie, all exercises collected - earlier. This command cannot be used before the corresponding collection - has been closed correctly. -\end{commands} - -Valid options are the following: -\begin{options} - \keybool{headings}\Module{print-collection}\Default{false} - If true a heading for each exercise type is inserted. - \keyval{headings-template}{template}\Module{print-collection}\Default{collection} - The heading template used when \keyis{headings}{true}. - \keychoice{print}{exercises,solutions,both}\Module{print-collection}\Default{exercises} - Determines wether \cs{printcollection} prints the exercises or the - solutions of the collection. When you choose \code{both} exercises and - solutions are printed alternately. -\end{options} - -Those options can also be set via \cs{xsimsetup} using the module -\module{print-collection}. - -\begin{bewareofthedog} - Please be aware that exercises are not used or printed while they are - collected. Nonetheless the property \property{use} is set to \code{true} - (so that solutions can be printed even if the exercises are not) and the - property \property{print} is set to \code{false}. Also their counters are - \emph{not stepped} during the process. This only happens when they are - printed the first time, \cf~the \property{used} property. At that time - also the properties \property{page}, \property{section} and - \property{chapter} are set and the property \property{print} is set to - \code{true}. -\end{bewareofthedog} - -The usage should be clear: -\begin{example} - \collectexercises{foo} - \begin{exercise} - This exercise is added to the collection `foo'. - \end{exercise} - \begin{exercise} - This exercise is also added to the collection `foo'. - \end{exercise} - \begin{exercise} - So is this. - \end{exercise} - \begin{exercise} - As well as this one. - \end{exercise} - \collectexercisesstop{foo} -\end{example} -Once the collection is closed it can be printed: -\begin{example} - \printcollection{foo} -\end{example} - -You can open several collections at the same time: -\begin{sourcecode} - \collectexercises{foo} - ... - \collectexercisestype{bar}{exercises} - ... - \collectexercisesstop{bar} - ... - \collectexercisesstop{foo} -\end{sourcecode} -Exercises will be added to each open collection. - -There is one generic collection called \enquote{\code{all exercises}}. As the -name already suggests it will hold all exercises. So if you say -\begin{sourcecode} - \printcollection{all exercises} -\end{sourcecode} -all exercises will be printed. - -\begin{bewareofthedog} - If you use \cs*{label}s inside of exercises and you print exercises more - than once in your document (by reusing a collection for example) you will - get -\begin{sourcecode} - LaTeX Warning: There were multiply-defined labels. -\end{sourcecode} - Equally if you have environments like \environ{equation} which step a - counter inside an exercise or solution the counter will be stepped each time - the exercise is used. -\end{bewareofthedog} - -At last now an example using external files, collections and tags: -\begin{sourcecode} - % preamble: - % \DeclareExerciseCollection{foo-easy} - % \DeclareExerciseCollection{foo-medium} - % \DeclareExerciseTagging{difficulty} - - % document: - \collectexercises{foo-easy} - \xsimsetup{difficulty=easy} - \input{foo.tex} - \collectexercisesstop{foo-easy} - % collection `foo-easy' now contains all exercises of file `foo.tex' tagged - % with `difficulty=easy' - - \collectexercises{foo-medium} - \xsimsetup{difficulty=medium} - \input{foo.tex} - \collectexercisesstop{foo-medium} - % collection `foo-medium' now contains all exercises of file `foo.tex' - % tagged with `difficulty=medium' -\end{sourcecode} - -\begin{bewareofthedog} - The recommended usage is similar to the last example. Actually a collection - can be printed \emph{before} it is opened, too. (This needs \emph{at least} - two compilations, though.) However, it is safer printing a collection only - 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 exercise is not part of several collections -- at least not if - both collections are printed in the same document. -\end{bewareofthedog} - -\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 - chosen with option \option{collection}, see below. When this command is - used it generates a random list of integers which is written to the - \code{aux} file. On the subsequent compilations the according exercises - are printed. \emph{If you want to regenerate the random list you have to - delete the \code{aux} file before compiling.} -\end{commands} -Valid options for this command are: -\begin{options} - \keybool{sort}\Module{random}\Default{true} - Determines wether the random chosen exercises should be sorted according - to their order of definition in the collection or not. - \keyval{collection}{collection}\Module{random}\Default{all exercises} - The collection from which the exercises are to be chosen from. - \keyval{exclude}{csv list of ids}\Module{random} - A list of \property{id}s or \property{ID}s of exercises \emph{not} to be - chosen. - \keychoice{print}{exercises,solutions,both}\Module{random}\Default{exercises} - Determines wether \cs{printrandomexercises} prints the exercises or the - solutions. When you choose \code{both} exercises and solutions are - printed alternately. -\end{options} - -\begin{example} - \printrandomexercises[collection=foo]{2} -\end{example} - -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} - -There are different commands for printing the solutions to exercises: -\begin{commands} - \command{printsolutionstype}[\sarg\oarg{options}\marg{exercise type}] - Prints the solutions of all used exercises of type \meta{exercise type}. - The starred version only prints the solutions of all printed exercises of - type \meta{exercise type}. - \command{printsolutions}[\sarg\oarg{options}] - Prints the solutions of all used exercises of all types ordered by type. - The starred version only prints the solutions of all printed exercises of - all types. - \command{printallsolutions}[\sarg\oarg{options}] - Prints the solutions of all used exercises of all types ordered by - appearance in the document. The starred version only prints the solutions - of all printed exercises of all types. - \command{printsolution}[\oarg{options}\marg{type}\marg{id}] - Prints the solution of the exercise of type \meta{type} with the - \property{id} \meta{id}. - \command{xprintsolution}[\marg{type}\marg{id}] - \sinceversion{0.16}The same as \cs{printsolution} but expands \meta{type} - and \meta{id} before it uses them. -\end{commands} - -\begin{example} - \printsolutionstype{exercise} -\end{example} - -The options can be divided into two groups. The ones in the first group -modify the layout. -\begin{options} - \keybool{headings}\Module{print-solutions}\Default{true} - If true a heading for each exercise type is inserted. - \keyval{headings-template}{template}\Module{print-solutions}\Default{default} - The heading template used when \keyis{headings}{true}. -\end{options} - -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}}\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}}\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}}\Module{print-solutions}% - \Default{false} - If used only solutions of exercises belonging to collection - \meta{collection name} are printed. -\end{options} - -The conditions can be combined. The following call will only print solutions -from exercises in section~3 of chapter~2: -\begin{sourcecode} - \printsolutions[chapter=2,section=3] -\end{sourcecode} - -\begin{bewareofthedog} - The selection per section or per chapter relies on the \emph{counter - numbers} of the sections or chapters, respectively. This means if section - numbers are reset (\eg\ by \cs*{chapter} or \cs*{appendix}) and you have - exercises from \emph{different} sections with \emph{the same section number} - the solutions of \emph{all those exercises} will be printed. This means you - only should use the \option{section} selection when section are the top - document level headings (apart from parts) and you have no exercises in the - appendix. Similar considerations are valid for the \option{chapter} - selection. -\end{bewareofthedog} - -All options can also be set via \cs{xsimsetup} using the module -\module{print-solutions}. - -\begin{example} - \printsolutions[section=4,headings-template=per-section] -\end{example} - -\begin{example} - \printsolution{exercise}{5} -\end{example} - -\section{Grading Tables}\label{sec:grading-tables} -When you create exercises it may not only be desirable to be able to add -points and bonus-points to a question (see section~\vref{sec:goals} about -exercise goals) but also to be able to output a grading table. \xsim\ has -built-in means for this. -\begin{commands} - \command{gradingtable}[\oarg{options}] - Print a grading table. -\end{commands} -Valid options for this command are -\begin{options} - \keyval{template}{template}\Default{default} - Choose the template used for the grading table. - \keyval{type}{exercise type}\Default - Choose the exercise type for which the table is printed. -\end{options} -Both option defaults can be changed with \cs{xsimsetup} setting the options -using \module{grading-table}: -\begin{sourcecode} - \xsimsetup{ - grading-table/template = default* - } -\end{sourcecode} - -An example: -\begin{example} - \gradingtable[type=exercise] -\end{example} - -Or using the \enquote{\code{default*}} template: -\begin{example} - \gradingtable[template=default*,type=exercise] -\end{example} - -Available templates and how to define new ones are explained in -sections~\vref{sec:grad-table-templ} and~\vref{sec:template-examples}. \xsim\ -per default provides two templates \enquote{\code{default}} and -\enquote{\code{default*}}, the first one has a vertical layout, the second a -horizontal layout. Both templates can be used per type like in the examples -above or for all types at once by leaving the specification \option{type} -away: -\begin{example} - \gradingtable -\end{example} - -\section{Styling the Exercises -- Templates}\label{sec:styl-exerc-templ} - -\subsection{Background} -Whenever \xsim\ outputs something to be typeset it uses so-called templates -for the task. \xsim\ knows of three different kinds of templates: -\begin{itemize} - \item environment templates (see section~\vref{sec:envir-templ}), - \item heading templates (see section~\vref{sec:heading-templates}) and - \item grading table templates (see section~\vref{sec:grad-table-templ}) -\end{itemize} - -The most important one for the styling of the exercises are the environment -templates. Those templates give you complete control over the look and -arrangement of an exercise. To be able to do this \xsim\ provides a large -number of commands which can be used only inside template -definitions\footnote{The last sentence is wrong: those commands can be used - anywhere but most of them only give useful results inside of templates.}. -Those commands are explained in the next section. Their usage will hopefully -become clear in the examples in section~\vref{sec:template-examples}. Having -full control over the layout comes at a price: you need to be able to program -yourself in order to achieve certain layouts\footnote{I plan to incorporate - the most common layouts -- and maybe some fancy ones, too -- in the examples - 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}. - \item[\code{minimal}] A\sinceversion{0.13} minimalistic layout, see - section~\ref{sec:minimal-template}. As the others inspired by an - \pkg{exsheets} layout. Available through the style file \code{layouts}. - \item[\code{inline}] A\sinceversion{0.18} minimalistic layout, the same as - \code{minimal} but doesn't add \cs*{par} at the beginning and end. - Available through the style file \code{layouts}. - \item[\code{centered}] A\sinceversion{0.18} layout with a centered heading. - Available through the style file \code{layouts}. -\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} - \command{IfExerciseGoal\TF}[\marg{goal}\marg{relation and - value}\marg{true}\marg{false}] - Checks the sum of goal \meta{goal} against \meta{relation and value}. - \command{IfExerciseGoalSingular\TF}[\marg{goal}\marg{true}\marg{false}] - Checks if the value of the goal \meta{goal} of the current exercise - equals~$1$. This is the same as \\ - \cs{IfExerciseGoalTF}\marg{goal}\Marg{=1}\marg{true}\marg{false}. - \command{IfExerciseTypeGoalsSum\TF}[\marg{type}\marg{list of - goals}\marg{relation and value}\marg{true}\marg{false}] - Ckecks the sum of all goals in \meta{list of goals} for the exercises of - type \meta{type} against \meta{relation and value}. - \command{IfExerciseGoalsSum\TF}[\marg{type}\marg{list of - goals}\marg{relation and value}\marg{true}\marg{false}] - Ckecks the sum of all goals in \meta{list of goals} for all exercises of - all types against \meta{relation and value}. - \command{TotalExerciseTypeGoal}[\marg{goal}\marg{type}\marg{singular}\marg{plural}] - Print the sum of goal \meta{goal} for the exercises of type \meta{type} - and append \meta{singular} or \meta{plural} depending on wether the sum - equals~$1$ or not. - \command{TotalExerciseGoal}[\marg{goal}\marg{singular}\marg{plural}] - Print the sum of goal \meta{goal} for all exercises of all types - and append \meta{singular} or \meta{plural} depending on wether the sum - equals~$1$ or not. -\end{commands} - -\subsubsection{Properties} -\begin{commands} - \expandable\command{IfExercisePropertyExist\TF}[\marg{property}\marg{true}% - \marg{false}] - Tests wether an exercise property with the name \meta{property} is defined. - \command{IfExercisePropertySet\TF}[\marg{property}\marg{true}\marg{false}] - Tests wether the exercise property \meta{property} has been set for the - current exercise. - \expandable\command{GetExerciseProperty}[\marg{property}] - Retrieves the value of the property \meta{property} for the current - exercise. - \command{GetExerciseProperty\TF}[\marg{property}\marg{true}\marg{false}] - Tests wether the exercise property \meta{property} has been set for the - 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{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!} - \command{GetExerciseTypeForProperty}[\marg{property}\marg{value}] - 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{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} - or \meta{false} and leaves the corresponding argument in the input - stream. Gives an error if \meta{property} is not a boolean property. - \expandable\command{GetExerciseAliasProperty}[\marg{property}] - Retrieves the value of the property of which \meta{property} is an alias - of for the current exercise. - \command{SaveExerciseProperty}[\marg{property}\meta{macro}] - Saves the value of the property \meta{property} for the current - exercise in macro \meta{macro}. - \command{GlobalSaveExerciseProperty} - Globally saves the value of the property \meta{property} for the current - exercise in macro \meta{macro}. - \command{ExercisePropertyIfSet\TF}[\marg{type}\marg{id}\marg{property}% - \marg{true}\marg{false}] - Test if the property \meta{property} has been set for the exercise of type - \meta{type} with id \meta{id}. - \expandable\command{ExercisePropertyGet}[\marg{type}\marg{id}\marg{property}] - Retrieves the value of the property \meta{property} for the exercise of type - \meta{type} with id \meta{id}. - \expandable\command{ExercisePropertyGetAlias}[\marg{type}\marg{id}\marg{property}] - Retrieves the value of the property of which \meta{property} is an alias - of for the exercise of type \meta{type} with id \meta{id}. - \command{ExercisePropertySave}[\marg{type}\marg{id}\marg{property}\meta{macro}] - Saves the value of the property \meta{property} for the exercise of type - \meta{type} with id \meta{id} in macro \meta{macro}. - \command{ExercisePropertyGlobalSave}[\marg{type}\marg{id}\marg{property}\meta{macro}] - Globally saves the value of the property \meta{property} for the exercise - of type \meta{type} with id \meta{id} in macro \meta{macro}. -\end{commands} - -\subsubsection{Parameters} -\begin{commands} - \expandable\command{GetExerciseParameter}[\marg{parameter}] - 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{GetExerciseHeadingF}[\marg{false}] - \sinceversion{0.14}Retrieves the value of the parameter - \parameter{exercise-heading} for the current exercise or of the parameter - \parameter{solution-heading} for the current solution. Inserts - \meta{false} if the corresponding parameter has not been set. - \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} -\begin{commands} - \command{ForEachExerciseTag}[\marg{type}\marg{code}] - Loops over all tags of tag type \meta{type} for the current exercise - applying \meta{code} each time. Inside \meta{code} you can refer to the - corresponding tag with \code{\#1}. - \command{ListExerciseTags}[\marg{type}\marg{between}] - Lists all tags of tag type \meta{type} for the current exercise using - \meta{between} as a separator. - \command{UseExerciseTags}[\marg{type}\marg{between - two}\marg{between}\marg{between last two}] - Lists all tags of tag type \meta{type} for the current exercise using - \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} -\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} - Can be used to refer to the current exercise id. - \expandable\command{ExerciseText} - Can be used inside solutions to retrieve the text of the corresponding - solution. This is propably seldom useful as in most use cases the - exercise property \property{solution} is the easier alternative. - \expandable\command{ExerciseCollection} - Can be used in certain templates to refer to the collection that is - currently inserted. - \expandable\command{numberofusedexercises} - Holds the total number of used exercises. Useful in table template - definitions. - \expandable\command{ExerciseTableType}[\marg{code}] - In table template definitions this macro either expands to the given - 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{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}] - \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 - properties of the corresponding exercise: - \begin{itemize} - \item \code{\#1}: the type of the exercise - \item \code{\#2}: the id of the exercise - \item \code{\#3}: the \property{counter} property of the exercise - \item \code{\#4}: the \property{subtitle} property of the exercise - \item \code{\#5}: the \property{points} property of the exercise - \item \code{\#6}: the \property{bonus-points} property of the exercise - \end{itemize} - \command{ForEachUsedExerciseByType}[\marg{code}] - Loops over each \emph{used} exercise ordered by the exercise types and - within each type by id. Inside \meta{code} you can refer to several - properties of the corresponding exercise: - \begin{itemize} - \item \code{\#1}: the type of the exercise - \item \code{\#2}: the id of the exercise - \item \code{\#3}: the \property{counter} property of the exercise - \item \code{\#4}: the \property{subtitle} property of the exercise - \item \code{\#5}: the \property{points} property of the exercise - \item \code{\#6}: the \property{bonus-points} property of the exercise - \end{itemize} - \command{ForEachPrintedExerciseByID}[\marg{code}] - Loops over each \emph{printed} exercise order by the exercise id. Inside - \meta{code} you can refer to several properties of the corresponding - exercise: - \begin{itemize} - \item \code{\#1}: the type of the exercise - \item \code{\#2}: the id of the exercise - \item \code{\#3}: the \property{counter} property of the exercise - \item \code{\#4}: the \property{subtitle} property of the exercise - \item \code{\#5}: the \property{points} property of the exercise - \item \code{\#6}: the \property{bonus-points} property of the exercise - \end{itemize} - \command{ForEachUsedExerciseByID}[\marg{code}] - Loops over each \emph{used} exercise order by the exercise id. Inside - \meta{code} you can refer to several properties of the corresponding - exercise: - \begin{itemize} - \item \code{\#1}: the type of the exercise - \item \code{\#2}: the id of the exercise - \item \code{\#3}: the \property{counter} property of the exercise - \item \code{\#4}: the \property{subtitle} property of the exercise - \item \code{\#5}: the \property{points} property of the exercise - \item \code{\#6}: the \property{bonus-points} property of the exercise - \end{itemize} - \command{XSIMprint}[\Marg{exercise|solution}\marg{type}\marg{id}] - \sincechanged{0.16}{0.17}Inserts the either the exercise or the solution - of type \meta{type} with the \property{id} or \property{ID} \meta{id}. - \command{XSIMxprint}[\Marg{exercise|solution}\marg{type}\marg{id}] - The same as \cs{XSIMprint} but expands \meta{type} and \meta{id} before it - uses them.\sincechanged{0.16}{0.17} - \expandable\command{XSIMtranslate}[\marg{keyword}] - Delivers the translation of \meta{keyword} according to the current - document language (in the meaning of a \pkg{babel}~\cite{pkg:babel} or - \pkg{polyglossia}~\cite{pkg:polyglossia} language). Existing keywords and - keyword translations (and how to add new ones) are explained in - section~\vref{sec:exerc-transl}. - \command{XSIMexpandcode}[\marg{code}] - Expands \meta{code} like \cs*{edef} does and leaves the result in the - input stream. - \expandable\command{XSIMifchapter\TF}[\marg{true}\marg{false}] - Returns \meta{true} if both a macro \cs*{chapter} and a counter - \code{chapter} are defined and \meta{false} otherwise. - \command{XSIMmixedcase}[\marg{code}] - Converts the full expansion\footnote{This is a \cs*{romannumeral} - expansion~\cite{texsx:romannumeral}.\label{fn:romannumeral}} of - \meta{code} to mixed case: \\ - \verbcode+\XSIMmixedcase{this is some text}+ \XSIMmixedcase{this is some - text} \\ - \emph{This command expands \meta{code} before converting it}. - \command{XSIMputright}[\meta{macro}\marg{code}] - Extends the macro definition of \meta{macro} with \meta{code} putting it - to the right. This is more or less a local version of the LaTeX kernel - macro \cs*{g@addto@macro}. - \expandable\command{XSIMifeq\TF}[\marg{code 1}\marg{code - 2}\marg{true}\marg{false}] - Checks if the full expansion\footref{fn:romannumeral} of \meta{code 1} and - \meta{code 2} is the same tokenlist. - \expandable\command{XSIMifblank\TF}[\marg{code}\marg{true}\marg{false}] - Checks if the full expansion\footref{fn:romannumeral} of \meta{code} is - blank (\ie, if it is empty or only consists of spaces). - \command{XSIMatbegindocument}[\marg{code}] - \sinceversion{0.15a}Adds \meta{code} to \xsim's begin document hook. - Should be used inside style files instead of \cs*{AtBeginDocument}. - \command{XSIMatenddocument}[\marg{code}] - \sinceversion{0.15a}Adds \meta{code} to \xsim's end document hook. - Should be used inside style files instead of \cs*{AtEndDocument}. -\end{commands} - -\subsection{Declaring Templates} -\subsubsection{Environment Templates}\label{sec:envir-templ} -\begin{commands} - \command{DeclareExerciseEnvironmentTemplate}[\marg{name}\marg{begin - code}\marg{end code}] - Declare the environment template \meta{name}. -\end{commands} -Environment templates are used by the exercise and solution environments. -Those are the templates set with the parameters \parameter{exercise-template} -and \parameter{solution-template}. - -The predefined template is called \enquote{\code{default}}, see -section~\vref{sec:exercise-templ-default}. - -\subsubsection{Heading Templates}\label{sec:heading-templates} -\begin{commands} - \command{DeclareExerciseHeadingTemplate}[\marg{name}\marg{code}] - Declare the heading template \meta{name}. -\end{commands} -Heading templates are used by \cs{printsolutions}, \cs{printsolutionstype} and -\cs{printcollection}. Those are the templates set with the option -\option{headings-template} of the modules \module{print-solutions} and -\module{print-collection}. - -The predefined templates are \enquote{\code{default}}, -\enquote{\code{collection}}, \enquote{\code{per-section}} and -\enquote{\code{per-chapter}} see section~\vref{sec:headings-templates}. - -\subsubsection{Grading Table Templates}\label{sec:grad-table-templ} -\begin{commands} - \command{DeclareExerciseTableTemplate}[\marg{name}\marg{code}] - Declare the grading table template \meta{name}. -\end{commands} -Table templates are used by \cs{gradingtable}. Those are the templates set -with the option \option{template} of module \module{grading-table} - -The predefined templates are \enquote{\code{default}} and -\enquote{\code{default*}}, see sections~\vref{sec:table-templ-default} -and~\vref{sec:table-templ-default*}. - -\subsection{Create and Use \xsim\ Style Files}\label{sec:style-files} -\index{style file|(} - -\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.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 -\cs{loadxsimstyle}\Marg{math-exam} or by using -\cs{xsimsetup}\Marg{load-style=math-exam}: -\begin{sourcecode} - \documentclass[DIV=18,parskip=half]{scrartcl} - \usepackage[T1]{fontenc} - \usepackage[utf8]{inputenc} - - \usepackage[clear-aux]{xsim} - \loadxsimstyle{math-exam} - - \title{Math Exam \#3} - \date{2017-03-28} -\end{sourcecode} - -In this style file stuff like template and property definitions should -happen. This is more or less a convenient way to -\begin{itemize} - \item keep the preamble \enquote{clean} and - \item define re-usable styles without the need of copying the document - preamble to another document. -\end{itemize} -A style file is like a package or class file, \ie, \code{@} has category -code~11 (letter). - -The formal description of the commands: -\begin{commands} - \command{xsimstyle}[\sarg\marg{style name}] - 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} -\begin{options} - \keyval{load-style}{csv list of style names} - Another\sinceversion{0.14} interface for \cs{loadxsimstyle}\marg{csv list - of style names}. -\end{options} - -\begin{bewareofthedog} - At the moment this mechanism offers no advantages over creating a custom - package or simply \cs*{input}ing a file. Future versions might provide - additional features. -\end{bewareofthedog} - -\index{style file|)} - -\subsection{Examples}\label{sec:template-examples} - -The repository of this package\footnote{GitHub: - \url{https://github.com/cgnieder/xsim/}, CTAN: - \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, see -section~\vref{sec:example-files}. - -\subsubsection{The \code{default} Exercise Template}\label{sec:exercise-templ-default} - -Below the definition\changedversion{0.14} of the \code{default} exercise -template provided by \xsim\ is shown: - -\begin{sourcecode} - \DeclareExerciseEnvironmentTemplate{default}{% - \GetExerciseHeadingF{\subsection*}% - {% - \XSIMmixedcase{\GetExerciseName}\nobreakspace - \GetExerciseProperty{counter}% - \IfInsideSolutionF - {% - \GetExercisePropertyT{subtitle} - { {\normalfont\itshape\PropertyValue}}% - }% - } - \GetExercisePropertyT{points} - {% - \marginpar - {% - \IfInsideSolutionF{\rule{1.2cm}{1pt}\slash}% - \printgoal{\PropertyValue} - \GetExercisePropertyT{bonus-points}{~(+\printgoal{\PropertyValue})}% - ~\XSIMtranslate {point-abbr}% - }% - }% - } - {\par} -\end{sourcecode} - -\subsubsection{A New Exercise Type Using \pkg*{tcolorbox}} -Let's say we want exercises to be put in a \env*{tcolorbox}. We want a bold -title and. if given, an italic subtitle. Exercises should also have the -points after the subtitle in parentheses if given. Let's also say we want -those to be an additional exercise type in addition to the ones \xsim\ already -provides. This is shown with the following code which is also how the -problems in this manual have been defined: - -\begin{sourcecode} - \DeclareExerciseEnvironmentTemplate{tcolorbox} - {% - \tcolorbox[ - colback = red!5!white , - colframe = red!75!black , - colbacktitle = yellow!50!red , - coltitle = red!25!black , - breakable , - drop shadow , - beforeafter skip = .5\baselineskip , - title = - \textbf{\GetExerciseName~\GetExerciseProperty{counter}}% - \GetExercisePropertyT{subtitle}{ \textit{\PropertyValue}}% - \IfInsideSolutionF{% - \GetExercisePropertyT{points}{ % notice the space - (% - \printgoal{\PropertyValue} - \IfExerciseGoalSingularTF{points} - {\XSIMtranslate{point}} - {\XSIMtranslate{points}}% - )% - }% - }% - ]% - } - {\endtcolorbox} - - \DeclareExerciseType{problem}{ - exercise-env = problem , - solution-env = answer , - exercise-name = Problem , - solution-name = Answer , - exercise-template = tcolorbox , - solution-template = tcolorbox - } -\end{sourcecode} - -See it in action: -\begin{example} - \begin{problem}[subtitle=My subtitle,points=5] - This is a problem using a subtitle and points. - \end{problem} - \begin{answer} - This is the answer to problem~\GetExerciseProperty{counter}. - \end{answer} -\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 -\cs*{marginpar} but the result should look very similar. A safer definition -would use a real sectioning command for the title. - -\begin{sourcecode} - \usepackage{needspace} - \DeclareExerciseEnvironmentTemplate{runin} - {% - \par\vspace{\baselineskip} - \Needspace*{2\baselineskip} - \noindent - \textbf{\XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}}% - \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} - -\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} - \DeclareExerciseEnvironmentTemplate{margin} - {% - \trivlist - \item[\llap{% - \smash{% - \tabular[t]{@{}r@{}} - \textbf{\XSIMmixedcase{\GetExerciseName}~\GetExerciseProperty{counter}} - \IfExercisePropertySetT{points}{% - \tabularnewline - (% - \printgoal{\GetExerciseProperty{points}}% - \GetExercisePropertyT{bonus-points}{+\printgoal{#1}}% - \,\XSIMtranslate{point-abbr}% - )% - }% - \endtabular - }% - }]\relax - } - {\endtrivlist} -\end{sourcecode} - -\subsubsection{A \code{minimal} Template} -\label{sec:minimal-template} - -This shows the implementation of the \code{minimal} template: -\begin{sourcecode} - \DeclareExerciseEnvironmentTemplate{minimal} - {% - \par - \textbf{\GetExerciseProperty{counter}}% - \IfInsideSolutionF{% - \GetExercisePropertyT{points}{% - \GetExercisePropertyT{bonus-points}{+\printgoal{\PropertyValue}}% - \,\IfExerciseGoalSingularTF{points} - {\XSIMtranslate{point}} - {\XSIMtranslate{points}}% - }% - }% - } - {\par} -\end{sourcecode} - -\subsubsection{The Headings Templates}\label{sec:headings-templates} -\xsim\ defines four heading templates which only differ by which text they -output: -\begin{sourcecode} - \DeclareExerciseHeadingTemplate{default} - {\section*{\XSIMtranslate{default-heading}}} - \DeclareExerciseHeadingTemplate{collection} - {\section*{\XSIMtranslate{collection-heading}}} - \DeclareExerciseHeadingTemplate{per-section} - {\section*{\XSIMtranslate{per-section-heading}}} - \DeclareExerciseHeadingTemplate{per-chapter} - {\section*{\XSIMtranslate{per-chapter-heading}}} -\end{sourcecode} -Section~\vref{sec:exerc-transl} shows how the translations are defined. - -\subsubsection{The \code{default} Table Template}\label{sec:table-templ-default} -This template is the one used for grading tables per default. It has a -vertical layout. - -\begin{sourcecode} - \DeclareExerciseTableTemplate{default}{% - \XSIMputright\ExerciseTableCode{% - \toprule - \XSIMifblankTF{\ExerciseType} - {} - {\XSIMmixedcase{\GetExerciseParameter{exercise-name}}} - & - \XSIMmixedcase{\XSIMtranslate{points}} & - \XSIMtranslate{reached} \\ - \midrule - }% - \ForEachUsedExerciseByType{% - \XSIMifeqTF{#1}{\ExerciseTableType{#1}} - {% - \XSIMifblankTF{\ExerciseType} - {% - \XSIMputright\ExerciseTableCode{% - \XSIMmixedcase{\ExerciseParameterGet{#1}{exercise-name} }% - }% - } - {}% - \XSIMputright\ExerciseTableCode - {#3 & \XSIMifblankTF{#5}{\printgoal{0}}{\printgoal{#5}} & \\ }% - } - {}% - } - \XSIMputright\ExerciseTableCode{% - \midrule - \XSIMtranslate{total} & - \XSIMifblankTF{\ExerciseType} - {\TotalExerciseGoal{points}{}{}} - {\TotalExerciseTypeGoal{\ExerciseType}{points}{}{}} & - \\ \bottomrule - }% - \XSIMexpandcode{% - \noexpand\begin{tabular}{\XSIMifblankTF{\ExerciseType}{l}{c}cc} - \noexpand\ExerciseTableCode - \noexpand\end{tabular}% - }% - } -\end{sourcecode} - -The part -\begin{sourcecode} - \XSIMifblankTF{\ExerciseType}{ ... }{ ... } -\end{sourcecode} -repeatedly checks if an exercise type has been given for the table. This -makes it possible to design the table differently if it is for one exercise -type only (the \code{true} case) or for all exercise types (the \code{false} -case). \cs*{ExerciseTableType}\marg{code} either expands to the given -exercise type or to \meta{code}. - -\subsubsection{The \code{default*} Table Template}\label{sec:table-templ-default*} -The second of the predefined grading table templates. It has a horizontal -layout. -\begin{bewareofthedog} - If you have a lot of exercises the width of a table with this layout may - exceed the text width of the document! -\end{bewareofthedog} - -\begin{sourcecode} - \DeclareExerciseTableTemplate{default*}{% - \XSIMputright\ExerciseTableCode{% - \toprule - \XSIMifblankTF{\ExerciseType} - {} - {\XSIMmixedcase{\GetExerciseParameter{exercise-name}}} - &% - }% - \ForEachUsedExerciseByType{% - \XSIMifeqTF {#1} { \ExerciseTableType {#1} } - { - \XSIMifblankTF{\ExerciseType} - {% - \XSIMputright\ExerciseTableCode{% - \XSIMmixedcase{\ExerciseParameterGet{#1}{exercise-name} }% - }% - } - {}% - \XSIMputright\ExerciseTableCode{#3 &} - } - {}% - }% - \XSIMputright\ExerciseTableCode{% - \XSIMtranslate{total} \\ - \midrule - \XSIMmixedcase{\XSIMtranslate{points}} & - }% - \ForEachUsedExerciseByType{% - \XSIMifeqTF{#1}{\ExerciseTableType{#1}} - {% - \XSIMputright\ExerciseTableCode{% - \XSIMifblankTF{#5}{\printgoal{0}}{\printgoal{#5}} &}% - } - {}% - }% - \XSIMputright\ExerciseTableCode{% - \XSIMifblankTF{\ExerciseType} - {\TotalExerciseGoal{points}{}{}} - {\TotalExerciseTypeGoal{\ExerciseType}{points}{}{}}% - \\ \midrule - \XSIMtranslate{reached} &% - }% - \ForEachUsedExerciseByType{% - \XSIMifeqTF{#1}{\ExerciseTableType{#1}} - {\XSIMputright\ExerciseTableCode{&}} - {}% - }% - \XSIMputright\ExerciseTableCode{ \\ \bottomrule }% - \def\numberofcolumns{% - \XSIMifblankTF{\ExerciseType} - {\numberofusedexercises} - {\csname numberof \ExerciseType s\endcsname}% - }% - \XSIMifeqF{\numberofcolumns}{0} - {% - \begin{tabular}{l*{\numberofcolumns}{c}c} - \ExerciseTableCode - \end {tabular}% - }% - } -\end{sourcecode} - -The part -\begin{sourcecode} - \XSIMifblankTF{\ExerciseType}{ ... }{ ... } -\end{sourcecode} -repeatedly checks if an exercise type has been given for the table. This -makes it possible to design the table differently if it is for one exercise -type only (the \code{true} case) or for all exercise types (the \code{false} -case). \cs*{ExerciseTableType}\marg{code} either expands to the given -exercise type or to \meta{code}. - -\section{Exercise Translations}\label{sec:exerc-transl} - -\begin{commands} - \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. - See an example of the usage below. - \expandable\command{XSIMtranslate}[\marg{keyword}] - Delivers the translation of \meta{keyword} according to the current - document language (in the meaning of a \pkg{babel}~\cite{pkg:babel} or - \pkg{polyglossia}~\cite{pkg:polyglossia} language). - \command{ForEachExerciseTranslation}[\marg{code}] - Loops over all translations of all keywords known to \xsim. Inside - \meta{code} you can refer to the keyword with \code{\#1}, to the language - with \code{\#2}, and to the translation with \code{\#3}. -\end{commands} - -As an example how to use \cs{DeclareExerciseTranslations} here is how the -translations for \code{exercise} have been defined: - -\begin{sourcecode} - \DeclareExerciseTranslations{exercise}{ - Fallback = exercise , - English = exercise , - French = exercice , - German = \"Ubung - } -\end{sourcecode} - -Table~\vref{tab:translation-keys} shows all existing keywords with all -predefined translations. - -\ForEachExerciseTranslation{ - \appto\translationtable{\texttt{#1} & #2 & \texttt{\detokenize{#3}} \\} -} - -\begin{longtable}{llp{.55\linewidth}} - \caption{Translation keywords predefined by \xsim.} - \label{tab:translation-keys} \\ - \toprule - \bfseries keyword & \bfseries language & \bfseries translation \\ - \midrule - \endfirsthead - \toprule - \bfseries keyword & \bfseries language & \bfseries translation \\ - \midrule - \endhead - \bottomrule - \endlastfoot - \midrule - & & \hfill\emph{continues} \\ - \endfoot - \translationtable -\end{longtable} - -\section{Cloze Tests and Blank Lines} - -Similar to \pkg{exsheets} \xsim\ provides a command \cs{blank}: -\begin{commands} - \command{blank}[\sarg\oarg{options}\marg{text to be filled in}] - Creates a blank in normal text or in an exercise but fills the text of its - argument if inside a solution. If used at the \emph{begin of a paragraph} - \cs{blank} will do two things: it will set the linespread according to an - option explained below and will insert \cs*{par} after the lines. The - starred version doesn't do these things. -\end{commands} - -Those are the options for customization: -\begin{options} - \keyval{blank-style}{code}\Module{blank}\Default{\cs*{underline}\Marg{\#1}} - Instructions for typesetting the blank cloze. Refer to the filled in - space with \code{\#1}. - \keyval{filled-style}{code}\Module{blank}\Default{\cs*{underline}\Marg{\#1}} - Instructions for typesetting the filled cloze. Refer to the filled in text - with \code{\#1} - \keyval{style}{code} - Shortcut for setting both \option{blank-style} and \option{filled-style} - at once. - \keyval{scale}{decimal number}\Module{blank}\Default{\code{1}} -\textsc{} Scales the blank to \meta{decimal number} times its natural width. - \keyval{width}{dim}\Module{blank}\Default - Sets the blank to a width of \meta{dim}. This takes precendence over - \option{scale}. - \keyval{linespread}{decimal number}\Module{blank}\Default{\code{1}} - Set the linespread for the blank lines. This only has an effect if - \cs{blank} is used at the begin of a paragraph. - \keyval{line-increment}{dim}\Module{blank}\Default{\code{0.001\cs*{linewidth}}} - The blank line is built in multiples of this value. If the value is too - large you may end up with uneven lines. If the value is too small you may - end up with a non-ending compilation. Experiment with values to find the - suiting one for your use case. - \keyval{line-minimum-length}{dim}\Module{blank}\Default{\code{2em}} - The minimal length a line must have before it is built step by step. -\end{options} - -\begin{example} - This is a \blank{blank} outside in normal text. - \begin{exercise} - Try to fill in \blank[width=4cm]{these} blanks. All of them - \blank{are created} by using the \cs{blank} \blank{command}. - \end{exercise} - \xsimsetup{blank/filled-style=\textcolor{red}{#1}} - \begin{solution}[print] - Try to fill in \blank[width=4cm]{these} blanks. All of them - \blank{are created} by using the \cs{blank} \blank{command}. - \end{solution} -\end{example} -A number of empty lines are easily created by setting the \option{width} -option: -\begin{example} - Write up the pros and cons of \xsim\ over \pkg{exsheets}: - - \blank[width=4.8\linewidth,linespread=1.5]{} -\end{example} - -\edef\lastsection{\arabic{section}} - -\appendix - -\section{Future Plans} - -\xsim\ is complete in so far as it is perfectly usable to create exams or -exercise and solution sections in books with the most freedom in layout -already. But still there are features which would be useful additions. Below -I list all ideas that I currently plan to add to \xsim: -\begin{itemize} - \item a document class \code{xsim-exam} for creating exams; this class - should itself feature the possibility of creating different versions of an - exam, maybe already provide multiple choice questions and so on; one could - also think about automatic creation of running headers and footers, \ie, - means for changing the layout of the exam; following the spirit of \xsim\ - this should probably be done using templates as well. -\end{itemize} -I am very open to suggestions regarding features, both in general and -specifically regarding the document class. - -\section{FAQ \& How to\dots} -This section serves as a kind of gallery showing solutions to common -problems. I expect this section to grow over the years. Some examples -especially regarding other layouts are also shown in example files added to -this package. - -\subsection{\dots Know if \xsim\ Needs Another Compilation?} -If \xsim\ wants you to recompile your document it writes the following to the -logfile: -\begin{sourcecode} - ************************************************* - * xsim warning: "rerun" - * - * Exercise properties may have changed. Rerun to get them synchronized. - ************************************************* -\end{sourcecode} -So just check the logfile regularly (which you should be doing anyway) and -keep your eyes open. - -\subsection{\dots Resolve Getting Repeatedly Wrong Exercise Properties or - Wrong Exercise Lists?}\label{sec:resolve-getting} -\xsimauxfileinfo - -\subsection{\dots Resolve Strange Errors After Updating?} -\xsim\ writes a lot of stuff to the auxiliary file. An update may well change -how this is done so deleting the auxiliary file and doing a few fresh -compilations may 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 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?} -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. - -\subsection{\dots Put a Star (or Another Symbol) in Headings of Exercises That - Are Special?} - -The code below shows one possible modification of an exercise template which -allows to easily create bonus exercises: -\begin{sourcecode} - % preamble: - \usepackage{amsymb} - % declare boolean property: - \DeclareExerciseProperty*{bonus} - \DeclareExerciseEnvironmentTemplate{bonus} - {% - \subsection* - {% - % test for boolean property and insert star symbol if true: - \IfExerciseBooleanPropertyT{bonus}{\llap{$\bigstar$ }Bonus }% - \XSIMmixedcase{\GetExerciseName}\nobreakspace - \GetExerciseProperty{counter}% - \IfInsideSolutionF - {% - \IfExercisePropertySetT{subtitle} - { {\normalfont\itshape\GetExerciseProperty{subtitle}}}% - }% - } - \GetExercisePropertyT{points} - {% - \marginpar - {% - \IfInsideSolutionF{\rule{1.2cm}{1pt}\slash}% - \PropertyValue - \GetExercisePropertyT{bonus-points} - {\nobreakspace(+\PropertyValue)}% - \nobreakspace\XSIMtranslate{point-abbr}% - }% - }% - } - {} -\end{sourcecode} - -The usage is now as follows: -\begin{example} - \xsimsetup{exercise/template = bonus} - % set the boolean property to true - \begin{exercise}[bonus] - A bonus question. - \end{exercise} -\end{example} - -\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. -\begin{sourcecode} - % preamble: - % \usepackage{etoolbox} - % \newcounter{sections} - - % document: - \setcounter{sections}{1} - \whileboolexpr - { test {\ifnumless{\value{sections}}{\value{section}+1}} } - { - \printsolutions[section=\value{sections},headings-template=per-section] - \stepcounter{sections} - } -\end{sourcecode} -For this manual we then get the following list\footnote{Taking care of the - fact that we're in the appendix now which means we can't use - \cs*{value}\Marg{section}. Therefore this manual does - \cs*{edef}\cs*{lastsection}\Marg{\cs*{arabic}\Marg{section}} right before - \cs*{appendix}}. - -\newcounter{sections} -\setcounter{sections}{1} -\whileboolexpr - { test {\ifnumless{\value{sections}}{\lastsection+1}} } - { - \printsolutions[section=\value{sections},headings-template=per-section] - \stepcounter{sections} - } - -\section{The \pkg*{xsimverb} package}\label{sec:xsimverb-package} -\xsim\ comes bundled with another package called -\pkg{xsimverb}\xsimverbversion. This package loads a very small subset of -\xsim\ which allows to create environments that write their contents verbatim -to external files. It provides the following commands (which of course are -also available in \xsim, too): - -\begin{commands} - \command{XSIMfilewritestart}[\sarg\marg{file name}] - Start writing to the file named \meta{file name}. This should be the - \emph{last} command in the \emph{begin} definition of an environment. If - is is used in an environment with arguments where the \emph{last} argument - is optional you should check if the optional argument is given and use - the starred version if the test is negative. This is demonstrated in an - example below using \pkg{xparse}'s \cs{NewDocumentEnvironment}. \emph{If - you want an environment with only an optional argument you \emph{should} - use \pkg{xparse}'s commands to define it. Due to the way how - \cs*{newenvironment} scans for optional arguments you'll otherwise may - end up with leading spaces gobbled from the first line in your - environment.} - \command{XSIMfilewritestop} - Stop writing to the file. This should be the \emph{first} command in the - \emph{end} definition of an environment. - \command{XSIMsetfilebegin}[\marg{code}] - This command can be used to write something to the external file - \emph{before} the environment contents. Must be set before - \cs{XSIMfilewritestart} in the \emph{begin} definition. - \command{XSIMsetfileend}[\marg{code}] - This command can be used to write something to the external file - \emph{after} the environment contents. Must be set before - \cs{XSIMfilewritestart} in the \emph{begin} definition. - \command{XSIMgobblechars}[\marg{integer}] - Determines how many characters are cut off of the beginning of each line - of the environment body before it is written to the file. The default - value is~$0$. -\end{commands} - -The following code shows an example of how to use those commands: -\begin{sourcecode} - \documentclass{article} - \usepackage{xsimverb,listings} - - \makeatletter - \NewDocumentEnvironment{example}{o} - {% - \XSIMsetfilebegin{\@percentchar\space file `\jobname.tmp'}% - \XSIMsetfileend{\@percentchar\space bye bye}% - \IfNoValueTF{#1} - {\XSIMfilewritestart*{\jobname.tmp}} - {\XSIMfilewritestart{\jobname.tmp}}% - } - {% - \XSIMfilewritestop - \lstinputlisting[language={[LaTeX]TeX}]{\jobname.tmp}% - \input{\jobname.tmp} - } - \makeatother - - \begin{document} - - \begin{example} - bla bla \LaTeX - \end{example} - - \end{document} -\end{sourcecode} - -The \code{tmp} file produced by the above example will contain the following -three lines (if the file itself was called \code{test.tex}): -\begin{sourcecode} - % file `test.tmp' - bla bla \LaTeX - % bye bye -\end{sourcecode} - -\section{All Exercise Examples} - -\begin{bewareofthedog} - You will notice that some exercises from - section~\vref{sec:template-examples} look differently in this section. That - is because all exercises of a type use the template that's \emph{currently - active}. If you want exercises with a different look you should use - different exercises types. -\end{bewareofthedog} - -The following list is created with this code: -\begin{sourcecode} - \xsimsetup{exercise/template = bonus} - \printcollection[headings]{all exercises} -\end{sourcecode} - -\xsimsetup{exercise/template = bonus} -\printcollection[headings]{all exercises} - -\section{All Solution Examples} -\printsolutions - -\section{Example Documents Coming With This Package}\label{sec:example-files} -The repository of this package\footnote{GitHub: - \url{https://github.com/cgnieder/xsim/}, CTAN: - \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 to solve concrete problems -that have come up in different \LaTeX\ forums. - -Besides showing excerpts of the code and the resulting pdf the examples below -also link to both the \code{tex} source the resulting pdf. - -\listexamplefiles - -\printbibliography - -\end{document} -- cgit v1.2.3