summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/sdaps/html/_sources
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/sdaps/html/_sources')
-rw-r--r--macros/latex/contrib/sdaps/html/_sources/FAQ.rst.txt99
-rw-r--r--macros/latex/contrib/sdaps/html/_sources/customlayout.rst.txt288
-rw-r--r--macros/latex/contrib/sdaps/html/_sources/index.rst.txt37
-rw-r--r--macros/latex/contrib/sdaps/html/_sources/sdapsarray.rst.txt209
-rw-r--r--macros/latex/contrib/sdaps/html/_sources/sdapsbase.rst.txt405
-rw-r--r--macros/latex/contrib/sdaps/html/_sources/sdapsclassic.rst.txt607
-rw-r--r--macros/latex/contrib/sdaps/html/_sources/sdapslayout.rst.txt81
-rw-r--r--macros/latex/contrib/sdaps/html/_sources/sdapspdf.rst.txt71
8 files changed, 1797 insertions, 0 deletions
diff --git a/macros/latex/contrib/sdaps/html/_sources/FAQ.rst.txt b/macros/latex/contrib/sdaps/html/_sources/FAQ.rst.txt
new file mode 100644
index 0000000000..97fd155e35
--- /dev/null
+++ b/macros/latex/contrib/sdaps/html/_sources/FAQ.rst.txt
@@ -0,0 +1,99 @@
+Frequently Asked Questions
+==========================
+
+Numeric field input
+-------------------
+
+Sometimes the input of longer numbers is required. Freeform text cannot be used
+so that other methods are necessary. The method presented here is a field of
+checkboxes, but further options may exist depending on the solution:
+
+* Use of a unique questionnaire ID and be careful when handing out the questionnaire
+* :ref:`Codeboxes`, i.e. text fields where a barcode sticker is placed
+
+In this example, each digit of an 8 digit number is asked for using an
+:environ:`optiongroup` environment.
+
+.. sdaps:: Using optiongroup to input longer numbers
+ :sdapsclassic:
+
+ \begin{optiongroup}[vertical]{Please enter the 8 digit number}
+ % Set the value as it would be 1 based otherwise, so we can just
+ % use it directly from the data export
+ \choice[val=0]{0}
+ \choice[val=1]{1}
+ \choice[val=2]{2}
+ \choice[val=3]{3}
+ \choice[val=4]{4}
+ \choice[val=5]{5}
+ \choice[val=6]{6}
+ \choice[val=7]{7}
+ \choice[val=8]{8}
+ \choice[val=9]{9}
+ \question[text=d1]{$\bigsqcup$}
+ \question[text=d2]{$\bigsqcup$}
+ \question[text=d3]{$\bigsqcup$}
+ \question[text=d4]{$\bigsqcup$}
+ \question[text=d5]{$\bigsqcup$}
+ \question[text=d6]{$\bigsqcup$}
+ \question[text=d7]{$\bigsqcup$}
+ \question[text=d8]{$\bigsqcup$}
+ \end{optiongroup}
+
+
+How can one use images?
+-----------------------
+
+The normal LaTeX commands will work as usual. As the image needs to be
+available during and after the `setup` step of SDAPS extra steps will be
+required though. The basic problem is that the given LaTeX file is copied
+into a new directory and the images may not be available then. The following
+ways exist to deal with this:
+
+ 1. Copy all images by passing `--add` for each image
+ 2. Place all images into a directory and use `--add` on the directory
+
+The second option is a good strategy if you have more images. In the example
+below a directory called `images` is used which has one file called `sdaps.png`.
+The `\\graphicspath` command is used so that the image can be refered to by its
+filename rather than the full relative path.
+
+.. sdaps:: Using `graphicx` together with `\\graphicspath` to place images into a subdirectory
+ :sdapsclassic:
+ :preamble:
+ \usepackage{graphicx}
+ % Do not add a leading ./ as that will cause issues under some conditions!
+ \graphicspath{{images/}}
+
+ The SDAPS logo for the website is \raisebox{-0.8cm}{\includegraphics[width=2cm]{sdaps.png}}.
+
+With that done, you need to run the following to setup the project
+
+.. code-block:: shell
+
+ $ sdaps setup tex PROJECT_DIR questionnaire.tex --add images
+
+Adjusting corner mark positions
+-------------------------------
+
+It is possible to adjust the positions of the corner marks. Currently this
+needs to be done manually. You can override the positions and also update
+the default page margins using code like the following in the preamble.
+
+This requires SDAPS version 1.9.10 or later.
+
+.. code-block:: tex
+
+ % Re-define the default margins (10mm -> 12mm, 12mm -> 15mm)
+ \ExplSyntaxOn
+ \dim_gset:Nn \g_sdaps_edge_left_margin_dim { 12mm }
+ \dim_gset:Nn \g_sdaps_edge_right_margin_dim { 12mm }
+ \dim_gset:Nn \g_sdaps_edge_top_margin_dim { 15mm }
+ \dim_gset:Nn \g_sdaps_edge_bottom_margin_dim { 15mm }
+ \ExplSyntaxOff
+
+ % Modify the top, bottom and left/right margins, these should be 2mm larger
+ \geometry{top=15mm}
+ \geometry{bottom=17mm}
+ \geometry{hmargin=14mm}
+
diff --git a/macros/latex/contrib/sdaps/html/_sources/customlayout.rst.txt b/macros/latex/contrib/sdaps/html/_sources/customlayout.rst.txt
new file mode 100644
index 0000000000..87c553ce05
--- /dev/null
+++ b/macros/latex/contrib/sdaps/html/_sources/customlayout.rst.txt
@@ -0,0 +1,288 @@
+Creating custom layouts using base commands
+===========================================
+
+Usually the pre-defined layouts that SDAPS provides are sufficent. However,
+there may be special cases that need more customization. Such customization is
+possible, but it does require a more in depth understanding of LaTeX and
+the SDAPS packages.
+
+If you do this, please make sure to properly test the output. The easiest way
+of such testing is to use the ``annotate`` command that SDAPS provides, as it
+visualises the view that SDAPS has of the questionnaire. Doing this testing is
+essential as small errors and even side effects of how LaTeX executes code may
+render the information about the questionnaire useless!
+
+Even seemingly "simple" environments like ``tabularx`` may not be usable
+together with SDAPS!
+
+
+General question structure
+--------------------------
+
+To define a question, you need to define
+1. the start of the question and its type,
+2. the possible answers to the question
+3. the checkboxes and textboxes, and finally
+4. the end of the question.
+
+A very simple example might look like the following.
+
+.. sdaps:: Question with one checkbox
+ :sdapsclassic:
+ :metadata:
+
+ % Prepare some stuff so that we can access the specialized commands more easily.
+ \ExplSyntaxOn
+ \let\myquestionbegin\sdaps_qobject_begin:nnn
+ \let\mycheckbox\sdaps_checkbox:nn
+ \let\myanswer\sdaps_answer:n
+ \let\myquestionend\sdaps_qobject_end:n
+ \ExplSyntaxOff
+
+ \myquestionbegin{name}{Choice}{Exported question text}
+ Please check after reading this text: \mycheckbox{}{}
+ \myanswer{check}
+ \myquestionend{name}
+
+Please have a look at the resulting document and the generated metadata. In particular,
+please note:
+
+* The export shows "``QObject-Choice``" this is from the ``Choice`` specified and denotes the question type
+* The ``name`` argument does not show up. It only needs to match the one at the end and primarily serves error detection purposes.
+* SDAPS will see the question as "Exported question text" with one answer "check"
+* The checkbox is automatically exported including its coordinates
+
+.. warning::
+ Be careful! The below example shows the effect that ``tabularx`` has. This environment
+ expands its content multiple times, and the result is that the automatic numbering
+ breaks; making this the 3rd question rather than the first! Other subtle errors like
+ this can occur with certain environments, so make sure to double check everything is OK!
+
+ .. sdaps:: Question inside tabularx
+ :preamble: \usepackage{tabularx}
+ :sdapsclassic:
+ :metadata:
+
+ % Prepare some stuff so that we can access the specialized commands more easily.
+ \ExplSyntaxOn
+ \let\myquestionbegin\sdaps_qobject_begin:nnn
+ \let\mycheckbox\sdaps_checkbox:nn
+ \let\myanswer\sdaps_answer:n
+ \let\myquestionend\sdaps_qobject_end:n
+ \ExplSyntaxOff
+
+ \begin{tabularx}{\textwidth}{|X|}
+ \myquestionbegin{name}{Choice}{The tabularx environment breaks everything ...}
+ Please check after reading this text: \mycheckbox{}{}
+ \myanswer{check}
+ \myquestionend{name}
+ \end{tabularx}
+
+
+The different question types
+============================
+
+Headings
+--------
+
+This is the easiest case, and it can be used for structuring the document.
+
+For example, the ``\section`` command simply calls
+``\sdaps_qobject_begin:nnn { section }{ Head }{ #1 }``
+and ``\sdaps_qobject_end:n { section }`` for you. Something similar happens for
+the ``choicegroup`` and other grouping environments where a heading is defined
+for all questions.
+
+.. sdaps:: Grouping questions
+ :sdapsclassic:
+ :metadata:
+
+ % Prepare some stuff so that we can access the specialized commands more easily.
+ \ExplSyntaxOn
+ \let\myquestionbegin\sdaps_qobject_begin:nnn
+ \let\myquestionend\sdaps_qobject_end:n
+ \ExplSyntaxOff
+
+ \myquestionbegin{heading}{Head}{Heading}
+ Something inside the section.
+ \myquestionend{heading}
+
+
+Multiple choice
+---------------
+
+The simple multiple choice question is of type ``Choice``. We already saw the
+first example earlier. Simply add more checkboxes and answers as needed. SDAPS
+will match each checkbox to one answer in the order that it finds the defintions.
+
+.. sdaps:: Multiple choice question using itemize
+ :sdapsclassic:
+ :metadata:
+
+ % Prepare some stuff so that we can access the specialized commands more easily.
+ \ExplSyntaxOn
+ \let\myquestionbegin\sdaps_qobject_begin:nnn
+ \let\mycheckbox\sdaps_checkbox:nn
+ \let\myanswer\sdaps_answer:n
+ \let\myquestionend\sdaps_qobject_end:n
+ \ExplSyntaxOff
+
+ \myquestionbegin{name}{Choice}{Attended events}
+ Which of the following events did you attend?
+ \begin{itemize}
+ \item[\mycheckbox{}{}] \myanswer{Keynote} The Keynote
+ \item[\mycheckbox{}{}] \myanswer{Workshop} A workshop
+ \item[\mycheckbox{}{}] \myanswer{Party} Our glorious party
+ \item Something else entirely \myanswer{other}
+ \ExplSyntaxOn
+ \sdaps_textbox_hstretch:nnnnn{}{2mm}{5mm}{40mm}{1}
+ \ExplSyntaxOff
+ \end{itemize}
+ \myquestionend{name}
+
+Note that we placed a textbox rather than a checkbox as one of the possible
+answers.
+
+
+Single choice
+-------------
+
+We can also define a single choice question. For this, we need to make two
+small adjustments. The first is to use the ``Option`` question type. The second
+is to tell SDAPS that we would like to use the ``singlechoice`` style for
+checkboxes.
+
+The checkbox style change will be in effect for the scope of the question.
+
+.. sdaps:: Single choice question using itemize
+ :sdapsclassic:
+ :metadata:
+
+ % Prepare some stuff so that we can access the specialized commands more easily.
+ \ExplSyntaxOn
+ \let\myquestionbegin\sdaps_qobject_begin:nnn
+ \let\mycheckbox\sdaps_checkbox:nn
+ \let\myanswer\sdaps_answer:n
+ \let\myquestionend\sdaps_qobject_end:n
+ \let\mysetcheckboxtype\sdaps_checkbox_set_type:n
+ \ExplSyntaxOff
+
+ \myquestionbegin{name}{Option}{Attended events}
+ \mysetcheckboxtype{singlechoice}
+ Which one of the following events did you attend?
+ \begin{itemize}
+ \item[\mycheckbox{}{}] \myanswer{Talk room A} Talk in room A
+ \item[\mycheckbox{}{}] \myanswer{Talk room B} Talk in room B
+ \item Something else entirely \myanswer{other}
+ \ExplSyntaxOn
+ \sdaps_textbox_hstretch:nnnnn{}{2mm}{5mm}{40mm}{1}
+ \ExplSyntaxOff
+ \end{itemize}
+ \myquestionend{name}
+
+Note that we placed a textbox rather than a checkbox as one of the possible
+answers.
+
+
+Ranges
+------
+
+Quite often one has single choice question which represent a value on a range.
+One could create these using the ``Option`` type question, but with ``Range``
+it becomes more convenient.
+
+Range questions can contain a single range and further answers like
+"Not applicable".
+
+The range is specified with a separate command. For the purpose of this command,
+the first and last box that is part of the range needs to be specified. This is
+done with a zero based index (i.e. the first checkbox is 0, the second 1, …).
+
+.. sdaps:: Range question
+ :sdapsclassic:
+ :metadata:
+
+ % Prepare some stuff so that we can access the specialized commands more easily.
+ \ExplSyntaxOn
+ \let\myquestionbegin\sdaps_qobject_begin:nnn
+ \let\mycheckbox\sdaps_checkbox:nn
+ \let\myanswer\sdaps_answer:n
+ \let\myrange\sdaps_range:nnn
+ \let\myquestionend\sdaps_qobject_end:n
+ \let\mysetcheckboxtype\sdaps_checkbox_set_type:n
+ \ExplSyntaxOff
+
+ \myquestionbegin{name}{Option}{Attended events}
+ \mysetcheckboxtype{singlechoice}
+ Did you like the keynote?
+ \begin{itemize}
+ \item
+ it was bad
+ \mycheckbox{}{} ~
+ \mycheckbox{}{} ~
+ \mycheckbox{}{} ~
+ \mycheckbox{}{} ~
+ \mycheckbox{}{} ~
+ it was great
+ \item[\mycheckbox{}{}] I did not attend the keynote
+ \end{itemize}
+ \myrange{lower}{0}{bad}
+ \myrange{upper}{4}{great}
+ \myanswer{did not attend}
+ \myquestionend{name}
+
+Note that ``lower`` must always be the earlier checkbox. You can however assign
+different values to each checkbox using the second parameter to the checkbox
+command, thereby redefining the numeric value. The main different to the
+``Option`` question is simply how the question will be represented in the
+report.
+
+.. _codeboxes:
+
+Codeboxes
+---------
+
+There is experimental support for code boxes, that is not yet available using a
+nice wrapper. This can be used to create QR code read fields.
+
+.. sdaps:: Codebox question and field
+ :sdapsclassic:
+ :metadata:
+ :preamble:
+ % Prepare some stuff so that we can access the specialized commands more easily.
+ \ExplSyntaxOn
+ \let\myquestionbegin\sdaps_qobject_begin:nnn
+ \let\mytexthbox\sdaps_textbox_hbox:nnn
+ \let\myquestionend\sdaps_qobject_end:n
+ \let\mysettextboxtype\sdaps_textbox_set_type:n
+ % Set a global overlay with a nice icon (quite likely, you will just want
+ % to place text into the hbox below rather than just placing spacing).
+ \sdaps_context_set:n {
+ codebox = {
+ centered_text = {
+ \begin{tikzpicture}[yscale=-0.1, xscale=0.1]
+ \path[draw=black,fill=black,stroke=] (-1,0)
+ -- (-1,5) -- (4,5) -- (4,0) -- cycle(7,0) -- (7,5) -- (12,5) -- (12,0) -- cycle(0,1) -- (3,1) -- (3,4)
+ -- (0,4) -- cycle(8,1) -- (11,1) -- (11,4) -- (8,4) -- cycle(1,2) -- (1,3) -- (2,3) -- (2,2) -- cycle(5,2) --
+ (5,3) -- (6,3) -- (6,2) -- cycle(9,2) -- (9,3) -- (10,3) -- (10,2) -- cycle(5,4) -- (5,6) -- (2,6) -- (2,7)
+ -- (6,7) -- (6,4) -- cycle(0,6) -- (0,7) -- (1,7) -- (1,6) -- cycle(7,6) -- (7,7) -- (8,7) -- (8,6) --
+ cycle(-1,8) -- (-1,13) -- (4,13) -- (4,8) -- cycle(5,8) -- (5,13) -- (6,13) -- (6,8) -- cycle(7,8) -- (7,9)
+ -- (8,9) -- (8,10) -- (7,10) -- (7,13) -- (8,13) -- (8,11) -- (9,11) -- (9,10) -- (10,10) -- (10,9) -- (9,9)
+ -- (9,8) -- cycle(10,9) -- (12,9) -- (12,8) -- (10,8) -- cycle(0,9) -- (3,9) -- (3,12) -- (0,12) --
+ cycle(1,10) -- (1,11) -- (2,11) -- (2,10) -- cycle(11,10) -- (11,11) -- (12,11) -- (12,10) -- cycle(11,11) --
+ (10,11) -- (10,12) -- (9,12) -- (9,13) -- (12,13) -- (12,12) -- (11,12) -- cycle;
+ \end{tikzpicture}
+ },
+ }
+ }
+ \ExplSyntaxOff
+
+ \myquestionbegin{name}{Text}{This is a QR code question}
+ \mysettextboxtype{codebox}
+
+ Place barcode sticker into the box:
+ % Note that we use hspace + vrule for sizing here, that is a bit weird but
+ % a reasonable method of setting a size
+ \mytexthbox{}{3bp}{ \hspace{8cm} \vrule width 0pt height 3cm depth 2cm }
+ \myquestionend{name}
+
diff --git a/macros/latex/contrib/sdaps/html/_sources/index.rst.txt b/macros/latex/contrib/sdaps/html/_sources/index.rst.txt
new file mode 100644
index 0000000000..d6cb8a28e7
--- /dev/null
+++ b/macros/latex/contrib/sdaps/html/_sources/index.rst.txt
@@ -0,0 +1,37 @@
+.. sdaps-class documentation master file, created by
+ sphinx-quickstart on Tue Oct 25 19:43:42 2016.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Welcome to sdaps-class's documentation!
+=======================================
+
+Contents:
+
+Usage Guides
+------------
+.. toctree::
+ :maxdepth: 2
+
+ FAQ
+ customlayout
+
+Reference documentation
+-----------------------
+.. toctree::
+ :maxdepth: 2
+
+ sdapsclassic
+ sdapslayout
+ sdapspdf
+ sdapsarray
+ sdapsbase
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
diff --git a/macros/latex/contrib/sdaps/html/_sources/sdapsarray.rst.txt b/macros/latex/contrib/sdaps/html/_sources/sdapsarray.rst.txt
new file mode 100644
index 0000000000..73df087b87
--- /dev/null
+++ b/macros/latex/contrib/sdaps/html/_sources/sdapsarray.rst.txt
@@ -0,0 +1,209 @@
+sdapsarray package
+==================
+
+This is a base package for "array" like environments. It really is similar to a
+tabularx environment to some extend. Its purpose is much more specialized compared
+to tabularx. It is less flexible in the types of layouts that can be realized but
+a lot more powerful otherwise. The `sdapsarray` environment has the following
+features:
+
+* All :environ:`sdapsarray` environments in the document can be aligned to each other
+* The environment can span multiple pages
+* Headers will be repeated when page splits are encountered
+* The rows/columns can be swapped on the fly
+* Different ``layouter`` can be plugged in to modify the rendering
+* Fragile content can be used without further preparation
+* Contained content is executed exactly once (important for metadata generation)
+
+Things that are *not* possible currently:
+
+* Row or column backgrounds
+* Grid lines
+
+.. warning::
+ The :environ:`sdapsarray` is **not** a ``tabular`` like environment. It behaves
+ in similar ways, but there are fundamental differences, causing some issues:
+
+ * You **must not** add a trailing ``\\`` to the last row.
+
+.. sdaps:: Example of a sdapsarray environment
+
+ The following two \texttt{sdapsarray} environments are almost identical. They
+ are both aligned to each other because the \texttt{align} option is set to
+ the same value. In the second environment the rows and columnes are swapped
+ by setting the \texttt{flip} option.
+
+ \begin{sdapsarray}[align=testing]
+ row header & colum header & colum header \\
+ row header & cell 1 & cell 2 \\
+ row header & cell 3 & cell 4
+ \end{sdapsarray}
+
+ \hrule
+
+ \begin{sdapsarray}[flip,align=testing]
+ row header & colum header & colum header \\
+ row header & cell 1 & cell 2 \\
+ row header & cell 3 & cell 4
+ \end{sdapsarray}
+
+.. sdaps:: Example of a sdapsarray environment split over two columns using multicols
+ :preamble: \usepackage{multicol}
+
+ \begin{multicols}{2}
+ \begin{sdapsarray}[align=testing,layouter=rotated]
+ colum header 0 & colum header 1 & colum header 2 \\
+ row header 1 & cell 1 & cell 2 \\
+ row header 2 & cell 3 & cell 4 \\
+ row header 3 & cell 5 & cell 6 \\
+ row header 4 & cell 7 & cell 8 \\
+ row header 5 & cell 9 & cell 10 \\
+ row header 6 & cell 11 & cell 12
+ \end{sdapsarray}
+ \end{multicols}
+
+
+Layout and formatting considerations
+------------------------------------
+
+The following hold true inside the environment:
+
+* The row headers are set into a :macro:`\\vtop` with the left over width from
+ the cells. This vertical box is later re-set into a :macro:`\\vbox`. The
+ effect is that the interrow skip is calculated between the last element of
+ the previous row and the first element of the next row. this means you must
+ be careful to not insert invisible content at the start of the vertical box.
+ (e.g. by adding a :macro:`\\leavevmode`).
+* The exception to the above rule is the start of the environment (i.e. the
+ header row) for which the top baseline information is (currently) discarded!
+* Each cell is set into an :macro:`\\hbox` with the last skip in the box removed
+ again (i.e. trailing space). You can use :macro:`\\hfill` to align the box to
+ the left/right but need to prevent the :macro:`\\hfill` to be removed again
+ for left alignment (e.g. by adding a ``\kern 0pt``).
+* Column headers behave like cells but a special layouter can be assigned to
+ them.
+* Row headers and column headers will usually be set on a common baseline. The
+ exception to this is if the column header contains multiple boxes/lines. In
+ that case the cells will be centered ignoring the baselines of both cells
+ and row header.
+* A penalty of 10 is inserted between rows.
+
+
+sdapsarray environment
+----------------------
+
+.. environ::
+ \begin{sdapsarray}[kwargs]
+ content with cells delimitted with & and \\
+ \end{sdapsarray}
+
+ :kwarg flip: Transpose array making rows to columns (default: ``false``)
+ :kwarg layouter: The layouter to use. New layouters can be defined, the following
+ exists by default:
+
+ * ``default``: Simple layout centering cells and giving all leftover space to the row
+ header which will line break automatically (this is the default)
+ * ``rotated``: Similar to default but rotates the column headers
+
+ :kwarg angle: The angle of the header when in ``rotated`` mode
+ :kwarg align: An arbitrary string to align multiple :environ:`sdapsarray` environments
+ to each other. All environments with the same string will be
+ aligned. (default: no alignment)
+ :kwarg keepenv: Do not modify the parser to consume ``&`` and ``\\`` for alignment.
+ Instead, the user must use :macro:`\\sdaps_array_alignment:` and :macro:`\\sdaps_array_newline:`.
+ This is only useful for writing custom environments which use :environ:`sdapsarray` internally.
+ Normal users should simply put any nested `array` environment into :macro:`\\sdapsnested`
+ to prevent issues (see below).
+ :kwarg no_header: Disable column header handling and repeating. Note that this
+ setting is independent of whether the ``flip`` option is set. As such, one may
+ need to take its value into account when setting it. (default: ``false``)
+ :kwarg colsep: Spacing added on the left/right of every cell. This defaults to `6pt`.
+ :kwarg rowsep: Extra spacing added between rows. This defaults to `0pt`.
+
+ The ``keepenv`` option should usually not be used by an end user writing a document, it is very useful
+ when writing environments which use :environ:`sdapsarray` internally (like :environ:`choicearray`).
+
+ .. macro:: \sdapsnested{content}
+
+ Reverts the ``&`` and ``\\`` to their original meaning. Content in an
+ :environ:`sdapsarray` environment can be wrapped with this if it requires
+ these characters to be active (i.e. you can use the ``array`` environment
+ this way for example).
+
+ .. macro:: \sdaps_array_alignment:
+
+ Alternative to using the ``&`` delimiter between cells. This is useful together
+ with the ``keepenv`` kwarg argument. In particular when creating custom environments
+ which use sdapsarray internally.
+
+ .. macro:: \sdaps_array_newline:
+
+ Alternative to using the ``\\`` delimiter between cells. This is useful together
+ with the ``keepenv`` kwarg argument. In particular when creating custom environments
+ which use sdapsarray internally.
+
+ .. sdaps:: Two sdapsarray environments each with a nested array, in one case using the keepenv option.
+ :preamble:
+ \usepackage{multicol}
+ % Wrap the commands with _ as we cannot use them directly. This needs to
+ % be a \def and not a \let because they are redefined dynamically internally.
+ \ExplSyntaxOn
+ \def\sdapsalignment{\sdaps_array_alignment:}
+ \def\sdapsnewline{\sdaps_array_newline:}
+ \ExplSyntaxOff
+
+ \begin{multicols}{2}
+ \begin{sdapsarray}
+ & col 1 & col 2 \\
+ row header 1 & \sdapsnested{$ \begin{array}{cc} a & b \\ c & d \end{array}$} & cell 2 \\
+ \verb^row_header^ & cell 3 & cell 4
+ \end{sdapsarray}
+
+ \begin{sdapsarray}[keepenv]
+ \sdapsalignment col 1 \sdapsalignment col 2 \sdapsnewline
+ row header 1 \sdapsalignment $ \begin{array}{cc} a & b \\ c & d \end{array}$ \sdapsalignment cell 2 \sdapsnewline
+ \verb^row_header^ \sdapsalignment cell 3 \sdapsalignment cell 4
+ \end{sdapsarray}
+ \end{multicols}
+
+
+Defining a custom layouter
+--------------------------
+
+.. warning:: This is an advanced feature and its use a good or even in depth knowledge of how TeX processes boxes and input!
+
+It is possible to register further ``layouter``
+which can subsequently used throughout the document. These layouters need to
+adhere to a number of rules which will not be explained in detail here.
+
+The following code is a copy of the two predefined layouter not showing the
+implementation of the different macros. Visible here is that they only differ
+in the method to render the column header ``colhead``, all other methods are
+identical.
+
+.. code::
+
+ \prop_gput:Nnn \g__sdaps_array_layouter_prop { default } {
+ begin = { \_sdaps_array_begin_default: },
+ row_start = { \_sdaps_array_row_start_default: },
+ rowhead = { \_sdaps_array_rowhead_default:Nw },
+ colhead = { \_sdaps_array_cell_default:Nw },
+ cell = { \_sdaps_array_cell_default:Nw },
+ row = { \_sdaps_array_row_ltr:NNNN },
+ end = { \_sdaps_array_end_default: },
+ }
+
+ \prop_gput:Nnn \g__sdaps_array_layouter_prop { rotated } {
+ begin = { \_sdaps_array_begin_default: },
+ row_start = { \_sdaps_array_row_start_default: },
+ rowhead = { \_sdaps_array_rowhead_default:Nw },
+ colhead = { \_sdaps_array_cell_rotated:Nw },
+ cell = { \_sdaps_array_cell_default:Nw },
+ row = { \_sdaps_array_row_ltr:NNNN },
+ end = { \_sdaps_array_end_default: },
+ }
+
+If you consider modifying the layouter, then please have a look at the relevant
+parts of ``sdapsarray.dtx``. Also, please consider submitting modifications for
+upstream inclusion so that other people can benefit from new features.
+
diff --git a/macros/latex/contrib/sdaps/html/_sources/sdapsbase.rst.txt b/macros/latex/contrib/sdaps/html/_sources/sdapsbase.rst.txt
new file mode 100644
index 0000000000..218f5d0970
--- /dev/null
+++ b/macros/latex/contrib/sdaps/html/_sources/sdapsbase.rst.txt
@@ -0,0 +1,405 @@
+.. _sdapsbase:
+
+sdapsbase package
+=================
+
+This base package handles many of the core functionalities to make the SDAPS
+class work (together with :environ:`sdapsarray`). It implements a number of features
+which should however not be relevant for many end users. It should not be
+neccessary to dive into the :ref:`sdapsbase <sdapsbase>` implementation unless you want to use
+some of the more advanced features or even create completely custom layouts.
+
+
+
+The context subsystem
+----------------------
+
+SDAPS has a system to handle context for the questions. This context is managed
+in the global TeX scope. This means that modifications done for example inside
+a `multicols` environment will still be seen in the rest of the document. The
+context system itself is also hirarchical, so that it is possible to define
+different defaults for sections of the document. The most obvious use case for
+this might be prefixing all variables within parts of the document with a
+certain string. But one could also imagine changing the size of checkboxes
+for parts of the document.
+
+Handling context nesting
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following commands can be used to handle context nesting. Note that SDAPS
+makes a best effort to detect errors where begin/end was not used in a balanced
+fashion.
+
+.. macro:: \sdaps_context_begin:n { context name }
+
+ Begins a context with the given name
+
+.. macro:: \sdaps_context_end:n { context name }
+
+ Ends the context again, ensuring the name is correct
+
+.. macro:: \sdaps_context_begin:
+
+ Begins a context with an empty name
+
+.. macro:: \sdaps_context_end:
+
+ Ends a context started with :macro:`\\sdaps_context_begin:`
+
+.. macro:: \sdaps_context_begin_local:
+
+ Begins a context which automatically ends together with the current TeX group.
+
+.. macro:: \sdaps_context_enable_writing:
+
+ Enable metadata writing for the remainder of the current context. Note that
+ this package disables writing at start and you need to enable it before
+ calling :macro:`\\sdaps_begin:` (and :macro:`\\sdaps_end:`). Classes such as
+ the :ref:`sdapsclassic` will enable metadata writing for you.
+
+.. macro:: \sdaps_context_disable_writing:
+
+ Disable metadata writing for the remainder of the current context. Note that
+ disabling metadata writing may have some side effects with regard to
+ variables and automatic numbering of questions and answers. The exact
+ behaviour is currently *not* well defined.
+
+.. macro:: \sdaps_context_hook_end:n
+
+ Register a token list which will be executed at the end of the current
+ context. This is primarily useful as a context might be ended implicitly
+ in some circumstances.
+
+.. macro:: \sdaps_context_hook_post_end:n
+
+ Register a token list which will be executed *after* the end of the current
+ context has ended (i.e. in the parent context). This is primarily useful
+ as a context might be ended implicitly in some circumstances.
+
+Managing context variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. macro:: \sdaps_context_put:n { key }
+
+ Set the given variable (or key) to ``\\undefined``.
+
+.. macro:: \sdaps_context_put:nn { key } { value }
+
+ Set the given variable to the given value (Variants: ``nV``)
+
+.. macro:: \sdaps_context_remove:n { key }
+
+ Remove the given variable from the context.
+
+.. macro:: \sdaps_context_set:n { key=value, key={a=b, c=d} }
+
+ Set context variables from the given ``key=value`` parameters
+
+.. macro:: \sdaps_context_append:nn { key } { value }
+
+ The first argument being a variable to modify, append the given value to the
+ existing value. This can for example be used to change only one aspect of
+ checkbox drawing (e.g. ``form``) without affecting resetting another one
+ that was defined earlier (e.g. ``width`` or ``height``).
+
+ Generally it is a good idea to use this macro as nested options are common.
+
+ Identical to :macro:`\\sdaps_context_append:nnn` with "``,``" as the separator.
+
+.. macro:: \sdaps_context_append:nnn { key } { value } { separator }
+
+ Append the value to the given ``key`` in the context. If ``key`` is set,
+ inserts ``separator`` between them. If key is not set, simply sets the
+ ``key`` to the given value.
+
+ :Variants: ``nVn``
+
+
+Defining questions and headings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. macro:: \sdaps_qobject_begin:nnn { name } { type } { title }
+
+ Start a new qobject, giving the following arguments:
+
+ * The name of the context group to start
+ * The type of the qobject (to be consumed by the SDAPS main program)
+ * The title for the metadata
+
+.. macro:: \sdaps_qobject_end:n { name }
+
+ Finish a qobject again, must pass the correct name to verify correct nesting.
+
+.. macro:: \sdaps_qobject_begin:nn { type } { title }
+
+ Same as :macro:`\sdaps_qobject_begin:nnn` but without giving a context name.
+
+.. macro:: \sdaps_qobject_begin_local:nn { type } { title }
+
+ Same as :macro:`\sdaps_qobject_begin:nnn` but will automatically end with
+ the current TeX group (using :macro:`\sdaps_context_begin_local:`).
+
+.. macro:: \sdaps_qobject_end:
+
+ End a question which did not have a defined context name
+
+You can write further metadata using the following macros:
+
+.. macro:: \sdaps_qobject_append_var:n { var }
+
+ Appends the given string to the variable name of the question. An ``_``
+ will be used to separate the new variable name with any piece that was
+ defined earlier (either on the same question or on a surrounding question
+ object).
+
+ If ``var`` starts with an underscore (``_``) then an implicit variable name
+ for all surrounding question object (i.e. headings/sections) will be
+ generated based on their automatic numbering. This is similar to the
+ mechanism used by :environ:`choicearray` to ensure that the different questions
+ can always be told appart, even if the user did not specify a variable name
+ for all of them.
+
+.. macro:: \sdaps_answer:n { answer text }
+
+ Write metadata for an answer which belongs to the current question (context)
+
+.. macro:: \sdaps_range:nnn { lower|upper } { ID } { answer text }
+
+ Writes metadata for a range.
+
+ :arg lower|upper: Give either ``lower`` or ``upper`` for each end of the range.
+ :arg ID: The ID of the checkbox which corresponds to the first/lower or
+ last/upper box in the range. Other boxes are considered outside and need a
+ separate answer. Boxes are counted zero based and the given range is inclusive.
+ :arg answer text: The string for the metadata.
+
+ :Variants: ``nno``, ``nnf``, ``nnV``
+
+Generic commands are also provided to write to
+
+.. macro:: \sdaps_info_write:n { text }
+
+ Write given text to metadatafile at shipout. Some output may be reordered due
+ to this, but all SDAPS classes ensure that the metadata can still be decoded
+ correctly. As this macro leaves elements in the output stream it can affect
+ layouting in a few cases (e.g. row headers of :environ:`sdapsarray`).
+
+ The tokens **will not be expanded** again before writing. This implies that coordinates
+ cannot be written using this macro.
+
+ :arg text: Text to write to the metadata file.
+
+ :Variants: ``x``
+
+.. macro:: \sdaps_info_write_x:n
+
+ Write given text to metadatafile at shipout. Some output may be reordered due
+ to this, but all SDAPS classes ensure that the metadata can still be decoded
+ correctly. As this macro leaves elements in the output stream it can affect
+ layouting in a few cases (e.g. row headers of :environ:`sdapsarray`).
+
+ The tokens **will be expanded** again before writing. This implies that coordinates
+ can be written using this macro if one takes care not to protect them from
+ being expanded at macro execution time.
+
+ :arg text: Text to write to the metadata file.
+
+ :Variants: ``x``
+
+Overrides
+---------
+
+Overrides allow setting defaults based on the questionnaire ID or based on the
+variable name and value of items. Using this feature it would for example be
+possible to fill in names into text fields for printing.
+
+.. note::
+ Overrides are independent of the context itself.
+
+Commands which adhere to overrides are currently:
+
+* all ``multichoice`` or ``singlechoice`` checkboxes
+* all ``textboxes``
+
+There is only one command to set the overrides string:
+
+.. macro:: \sdaps_set_questionnaire_id:n { ID }
+
+ Set the current questionnaire ID. This should generally not change unless
+ some sort of concatenation is done. It is only relevant for writing new
+ environments.
+
+.. macro:: \sdaps_overrides_init:n { overrides }
+
+ :arg overrides: A key=value argument with all the override definitions.
+
+ Each of the override definitions will be appened to the items keys if it is
+ matching. Matching happens first based on the questionnaire ID with ``*``
+ being allowed as a wildcard, and then based on variable name and value. The
+ second level (name and value) is either just the variable name or the variable
+ name and value separated by an ``&`` character.
+
+ This gives six matches with increasing priority:
+
+ * wildcard questionnaire ID, wildcard target
+ * wildcard questionnaire ID, matching variable
+ * wildcard questionnaire ID, matching variable, matching value
+ * matching questionnaire ID, wildcard target
+ * matching questionnaire ID, matching variable
+ * matching questionnaire ID, matching variable, matching value
+
+ .. sdaps:: Overriding checkbox color and pre-filled value based on
+ questionnaire ID and variables.
+ :sdapsclassic:
+ :metadata:
+ :preamble:
+ \ExplSyntaxOn
+ \sdaps_overrides_init:n{
+ % For all questoinnaires independent of their ID
+ *={
+ % For all elements which use the overrides
+ *={fill=green},
+ % Specific element with that variable name
+ flower_bob_alice={draw_check=true},
+ % Specific element with variable "var" and value 1
+ var&1={draw_check=true},
+ },
+ % Specific questionnaire ID
+ testid={
+ % We need to explicitly unset it again!
+ flower_bob_alice={draw_check=false},
+ flower_adam_alice={draw_check=true},
+ },
+ }
+ \ExplSyntaxOff
+
+ \begin{choicegroup}[var=flower]{A group of questions with variable "flower"}
+ \groupaddchoice[var=alice]{Choice "alice"}
+ \groupaddchoice[var=eve]{Choice "eve"}
+ \choiceline[var=adam]{Question "adam"}
+ \choiceline[var=bob]{Question "bob"}
+ \end{choicegroup}
+
+ % Force a different questionnaire ID (never do this in a real document!)
+ \ExplSyntaxOn
+ \sdaps_set_questionnaire_id:n { testid }
+ \ExplSyntaxOff
+ \begin{choicegroup}[var=flower]{A group of questions with variable "flower"}
+ \groupaddchoice[var=alice]{Choice "alice"}
+ \groupaddchoice[var=eve]{Choice "eve"}
+ \choiceline[var=adam]{Question "adam"}
+ \choiceline[var=bob]{Question "bob"}
+ \end{choicegroup}
+
+
+The rendering subsystem
+-----------------------
+
+Checkbox
+^^^^^^^^
+
+=================== ===================================================================
+Option Description
+=================== ===================================================================
+linewidth The width of the outline (default: 1bp)
+width The width of the checkbox (default 3.5mm)
+height The height of the checkbox (default: 3.5mm)
+form The form, either `box` or `ellipse` (default: `box` for `multichoice` and `ellipse` for `singlechoice`)
+value The value of the checkbox (for internal use)
+fill The colour to fill the checkbox with (default: `white`)
+draw The colour to draw the checkbox frame with (default: `.`, i.e. current text colour)
+draw\_check Whether to draw a checkmark on top of the box (default: `false`)
+centered\_text Text to overlay over the checkmark (default: `none`)
+text Text to overlay over the checkmark using a minipage (default: `none`)
+text\_align The minipage alignment of the overlay (default: `c`, valid are `c`, `t`, `b`, `s` for center, top, bottom or spread)
+text\_padding The minipages padding from the outside border of the box (default: `2bp`)
+ellipse Pass as a short form for `form=ellipse`
+box Pass as a short form for `form=box`
+=================== ===================================================================
+
+There is only one user facing command to render a checkbox:
+
+* `\\sdaps_checkbox:nn`
+ The following arguments can be given:
+
+ * Variable name
+ * Value
+
+The behaviour of the checkbox should be changed through the context. On a first
+level this works by using `\\sdaps_checkbox_set_type:n` and setting either
+`singlechoice` or `multichoice`. Other than that you can also change the style
+for `singlechoice` and `multichoice` through the context and overrides. The
+following example demonstrates the use of context modification.
+
+.. sdaps:: Example showing modification of the context for checkbox rendering
+
+ \noindent
+ \ExplSyntaxOn
+ \sdaps_checkbox:nn {} {}
+
+ \hspace{1em}
+ \sdaps_context_append:nn { * } { linewidth=2bp }
+ \sdaps_checkbox:nn {} {}
+
+ \hspace{1em}
+ \sdaps_context_append:nn { multichoice } { fill=red }
+ \sdaps_checkbox:nn {} {}
+
+ \hspace{1em}
+ \sdaps_context_set:n { * = {} }
+ \sdaps_checkbox:nn {} {}
+
+
+ \hspace{1em}
+ \sdaps_context_set:n { multichoice={ellipse} }
+ \sdaps_checkbox:nn {} {}
+
+ \hspace{1em}
+ \sdaps_context_append:nn { * } { linewidth=2bp }
+ \sdaps_checkbox:nn {} {}
+
+ \hspace{1em}
+ \sdaps_context_append:nn { multichoice } { fill=red }
+ \sdaps_checkbox:nn {} {}
+
+ \hspace{1em}
+ \sdaps_context_set:n { * = {} }
+ \sdaps_checkbox:nn {} {}
+
+ \newline
+
+ \sdaps_context_set:n { * = { centered_text = X }, multichoice = { width=5mm, height=5mm} }
+ \sdaps_checkbox:nn {} {}
+
+ \hspace{1em}
+ \sdaps_context_append:nn { * } { linewidth=2bp }
+ \sdaps_checkbox:nn {} {}
+
+ \hspace{1em}
+ \sdaps_context_append:nn { checkbox } { fill=red }
+ \sdaps_checkbox:nn {} {}
+
+ \hspace{1em}
+ \sdaps_context_set:n { * = {} }
+ \sdaps_checkbox:nn {} {}
+
+ \hspace{1em}
+ \sdaps_context_set:n { multichoice={draw_check} }
+ \sdaps_checkbox:nn {} {}
+
+ \hspace{1em}
+ \sdaps_context_append:nn { * } { linewidth=2bp }
+ \sdaps_checkbox:nn {} {}
+
+ \hspace{1em}
+ \sdaps_context_append:nn { multichoice } { fill=red }
+ \sdaps_checkbox:nn {} {}
+
+ \hspace{1em}
+ \sdaps_context_set:n { * = {} }
+ \sdaps_checkbox:nn {} {}
+
+ \ExplSyntaxOff
+
+.. todo:: It appears the text is not centered correctly.
+
diff --git a/macros/latex/contrib/sdaps/html/_sources/sdapsclassic.rst.txt b/macros/latex/contrib/sdaps/html/_sources/sdapsclassic.rst.txt
new file mode 100644
index 0000000000..4e9931fb8d
--- /dev/null
+++ b/macros/latex/contrib/sdaps/html/_sources/sdapsclassic.rst.txt
@@ -0,0 +1,607 @@
+.. _sdapsclassic:
+
+sdapsclassic class
+==================
+
+This is the main class which currently should be used to create questionnaires.
+It builds on top of the other packages and adds new macros and environments
+which are similar to the ones from the original SDAPS LaTeX class.
+
+Please note that the environments from the sdapslayout package cannot be used
+directly as using these environments will cause conflicting macro definitions.
+Instead one can simply use the aliases provided in this class.
+
+The entire document should be wrapped using the :environ:`questionnaire` environment.
+
+The following macros and environments exist:
+
+ * :environ:`questionnaire`: Main environment wrapping everything
+ * :environ:`info`: Style definition for information block
+ * :macro:`\\addinfo`: Add metadata to the project
+ * :macro:`\\sdapsinfo`: Print the standard instructions for filling out
+
+The following question types exists for your use:
+
+* :macro:`\\singlemark`: A single range or mark question
+* :macro:`\\singlemarkother`: A single range or makr question with an alternative answer in case it isn't applicable
+* :macro:`\\textbox`: A large and optionally scalable textbox for freeform content
+* :environ:`choicequestion`: A multiple choice question with a number of answers
+* :environ:`choicegroup`: A list of multiple choice questions layed out in rows (or columns)
+* :environ:`optionquestion`: A single choice question with a number of answers
+* :environ:`optiongroup`: A list of single choice questions layed out in rows (or columns)
+* :environ:`markgroup`: A list of range or mark questions layed out in rows (or columns)
+
+You should only use ``\section{}`` for structuring the document.
+
+Class Options
+-------------
+
+=========================== =========================
+Argument Description
+=========================== =========================
+sdaps_style The markings style to use. Either "code128", "qr" (default: code128)
+checkmode The mode for checkbox recognition can be any of:
+ * **checkcorrect**: check to mark, fill to correct (unmark) (default)
+ * **check**: check or fill to mark
+ * **fill**: fill to mark
+disable_recognition Disable all recognition related page markings. This must not be used
+ when intending to ues the SDAPS program for optical mark recognition.
+ An example use case would be creating a PDF form using the SDAPS
+ LaTeX classes. (default: not set)
+twoside_barcode Where to draw barcodes if in twoside/duplex mode:
+ * **both**: draw on front and back (default)
+ * **front**: only draw on the front of the page
+ * **back**: only draw on the back of the page
+globalid A global identifier to be printed on the document (as barcode)
+globalidlabel The label for the barcode (only code128)
+no_print_questionnaire_id Disable printing of questionnaire IDs
+print_questionnaire_id Enable printing of questionnaire IDs
+=========================== =========================
+
+General macros and environments
+-------------------------------
+
+.. environ::
+ \begin{questionnaire}[kwargs]
+ content
+ \end{questionnaire}
+
+ :kwarg noinfo: Suppress the generation of the standard information text
+
+ This is the main environment. You should have exactly one of these
+ environments containing the entire document.
+
+.. environ::
+ \begin{info}
+ content
+ \end{info}
+
+ A simple environment which places a line on top and below the content.
+
+.. macro:: \addinfo{key}{value}
+
+ Attach further metadata to the SDAPS project. This may be used for any
+ purpose and the information will also appear on the cover page when
+ generating a report using the main SDAPS program.
+
+.. macro:: \sdapsinfo
+
+ Print the instruction text that is printed at the top of the page
+ unless the `noinfo` keyword argument is given to :environ:`questionnaire`.
+
+ Place into a :environ:`info` block to get the same visual appearance as the
+ default information text.
+
+.. macro:: \sdapspagemark
+
+ This macro must be executed once for every page. By default it is placed
+ into the center footer and as such should not be executed unless the footer
+ is modified.
+
+ While this command is provided, use it at your own risk. No guarantees are
+ made on how the class uses this macro internally. If you use it, you need
+ to verify the behaviour whenever the class is updated and ensure that
+ everything is functioning appropriately. In particular, this macro must not
+ be executed twice per page.
+
+Question related macros
+-----------------------
+
+.. macro:: \checkbox*
+
+ :arg *: If given, a single choice checkbox is shown instead of a multi choice.
+
+ Shows an unchecked checkbox for demonstration purposes.
+
+.. macro:: \checkedbox*
+
+ :arg *: If given, a single choice checkbox is shown instead of a multi choice.
+
+ Shows a checked checkbox for demonstration purposes.
+
+.. macro:: \filledbox*
+
+ :arg *: If given, a single choice checkbox is shown instead of a multi choice.
+
+ Shows a filled checkbox for demonstration purposes.
+
+.. macro:: \correctedbox*
+
+ :arg *: If given, a single choice checkbox is shown instead of a multi choice.
+
+ Shows a filled and checked checkbox for demonstration purposes.
+
+.. macro:: \singlemark[kwargs]{question}{lower}{upper}
+
+ A simple "mark" question, i.e. a range. The command does not currently allow adding
+ an alternate answer in a way similar to the markgroup or rangearray environments.
+
+ :arg question: The question text
+ :arg lower: The text for the lower label
+ :arg upper: The text for the upper label
+
+ :kwarg var: The variable for the question (to be appended to context).
+ :kwarg count: The number of checkboxes (default: ``markcheckboxcount``).
+
+ .. sdaps:: Simplest form of a range question
+ :sdapsclassic:
+
+ \singlemark{A range question}{lower}{upper}
+ \singlemark[count=6]{A range question with 6 answers}{lower}{upper}
+ \setcounter{markcheckboxcount}{7}
+ \singlemark{A range question with 7 answers}{lower}{upper}
+
+.. macro:: \singlemarkother[kwargs]{question}{lower}{upper}{other}
+
+ Similar to :macro:`\\singlemark` but also takes an alternative answer.
+
+ :arg question: The question text
+ :arg lower: The text for the lower label
+ :arg upper: The text for the upper label
+ :arg other: The text for the other label
+
+ :kwarg var: The variable for the question (to be appended to context).
+ :kwarg count: The number of checkboxes (default: ``markcheckboxcount``).
+
+ .. sdaps:: A range question with an alternative answer
+ :sdapsclassic:
+
+ \singlemarkother{A range question}{lower}{upper}{other}
+ \singlemarkother[count=6]{A range question with 6 answers}{lower}{upper}{other}
+ \setcounter{markcheckboxcount}{7}
+ \singlemarkother{A range question with 7 answers}{lower}{upper}{other}
+
+
+.. macro:: \textbox*[kwargs]{height}{question}
+
+ :arg *: If given, the textbox is scalable in height
+ :arg height: The height of the text including a unit. If the `*` parameter is given, then this is the minimal height only
+ :arg question: The question text, may not contain fragile content
+
+ :kwarg text: The question text for the metadata. Fragile content is currently *not* supported.
+ :kwarg var: The variable name for this textbox (to be appended to context)
+
+ .. todo:: :macro:`\\textbox` should be able to handle an optional keyword
+ argument and then allow the question text to include fragile content.
+
+ .. sdaps:: A textbox
+ :sdapsclassic:
+
+ \textbox*{2cm}{A textbox which is 2cm high, not scaling up to the page size}
+ \textbox{2cm}{A textbox which is at least 2cm high and can scale up to the page size}
+ \textbox{10cm}{A textbox which is at least 10cm high sharing the rest of the page with the previous one}
+
+Note that the SDAPS class supports rather fancy textbox handling including textboxes around
+other content!
+
+ .. warning:: The following examples are missing code for proper use! They mostly exist to show off the features but are not quite ready for easy consumption.
+
+ .. sdaps:: Fancy textboxes, for real use additional metadata writing is required!
+ :sdapsclassic:
+ :metadata:
+
+ % Prepare some stuff so that we can access the specialized commands more easily.
+ \ExplSyntaxOn
+ \let\sdapshbox\sdaps_textbox_hbox:nnn
+ \let\sdapshstretch\sdaps_textbox_hstretch:nnnnn
+ \let\sdapsvbox\sdaps_textbox_vbox:nnnn
+ \ExplSyntaxOff
+
+ \sdapshbox {} {3bp} { This hbox } should have the same baseline. And one can see that a hbox on the left edge
+ is \sdapshbox{}{3bp}{ nicely aligned } with the edge. And some in a formula: $ f(x) = \frac{1}{c\,\sdapshbox{}{3bp}{box}} \sdapshstretch{}{2mm}{5mm}{40mm}{1} $
+
+ See how even the horizontally stretching box in math mode works fine and fills up to the whole width!
+
+ Some complex inline content:
+ \sdapsvbox {} {0.6\linewidth} {3bp} {
+ \begin{tabularx}{\linewidth}{l|l|X}
+ adsf lkasjd lksj flkjsfd & blub & gah \\
+ \hline
+ asdf & & \\
+ \end{tabularx}
+
+ This is a paragraph with more text. This is a paragraph with more text. This is a paragraph with more text.
+ This is a paragraph with more text. This is a paragraph with more text. This is a paragraph with more text.
+ }
+
+
+.. macro:: \addinfo{key}{value}
+
+ Adds a bit of metadata. This metadata will for example appear on the cover page of the report.
+
+ :arg key: The key to set
+ :arg value: The value to set the key to
+
+ .. sdaps:: An example showing the generated metadata
+ :sdapsclassic:
+ :metadata:
+
+ \addinfo{Key 1}{Value 1}
+ \addinfo{Key 2}{Value 2}
+ \addinfo{Key 3}{Value 3}
+ \addinfo{Key 4}{Value 4}
+
+ Almost empty document, look at the metadata to see what this is about.
+
+
+Question Environments
+---------------------
+
+.. environ::
+ \begin{choicequestion}[kwargs]{text}
+ content
+ \end{choicequestion}
+
+ :param text: Text of the choice question. Fragile content is currently *not* supported.
+ :kwarg cols: Number of columns
+ :kwarg colsep: Spacing added on the left/right of every cell. This defaults to `6pt`.
+ :kwarg rowsep: Extra distance between rows. This defaults to `0pt`.
+ :kwarg var: Variable name for this question (to be appended to context).
+ :kwarg text: Replacement text for metadata
+ :kwarg type: the question type "multichoice" or "singlechoice"
+ :kwarg multichoice: switch to multichoice "Choice" question mode
+ :kwarg singlechoice: switch to singlechoice "Option" question mode
+
+ The content should only contain :macro:`\\choiceitem`, :macro:`\\choicemulticolitem` and :macro:`\\choiceitemtext`.
+
+ .. sdaps:: A choicequestion
+ :sdapsclassic:
+
+ \begin{choicequestion}[cols=3]{This is a choice question}
+ \choiceitem{First choice}
+ \choicemulticolitem{2}{Second choice with a lot of text}
+ \choiceitemtext{1.2cm}{3}{Other:}
+ \end{choicequestion}
+
+ .. macro:: \choiceitem[kwargs]{text}
+
+ A possible choice in a :environ:`choicequestion`. Will span exactly one column.
+
+ :param text: The text for the choice. Fragile content is currently *not* supported.
+ :kwarg var: Variable name for this answer for multichoice (to be appended to context).
+ :kwarg val: Value for this answer for singlechoice.
+ :kwarg text: Replacement text for metadata.
+
+ .. macro:: \choicemulticolitem[kwargs]{cols}{text}
+
+ A possible choice in a :environ:`choicequestion`. Will span exactly `cols` columns.
+
+ :param cols: The number of columns to span.
+ :param text: The text for the choice. Fragile content is currently *not* supported.
+ :kwarg var: Variable name for this answer for multichoice (to be appended to context).
+ :kwarg val: Value for this answer for singlechoice.
+ :kwarg text: Replacement text for metadata.
+
+ .. macro:: \choiceitemtext[kwargs]{height}{cols}{text}
+
+ A possible freeform choice in a :environ:`choicequestion`. The text field
+ will be of height `height` and it will span exactly `cols` columns.
+
+ The text item can currently only be used in multichoice environments.
+
+ :param cols: The number of columns to span.
+ :param text: The text for the choice. Fragile content is currently *not* supported.
+ :kwarg var: Variable name for this question (to be appended to context).
+ :kwarg text: Replacement text for metadata.
+
+.. environ::
+ \begin{optionquestion}[kwargs]{text}
+ content
+ \end{optionquestion}
+
+ Alias for :environ:`choicequestion` which simply sets it into ``singlechoice`` mode by default.
+
+ .. sdaps:: A choicequestion
+ :sdapsclassic:
+
+ \begin{optionquestion}[cols=3,singlechoice]{This is a single choice question}
+ \choiceitem{First choice}
+ \choicemulticolitem{2}{Second choice with a lot of text}
+ \end{optionquestion}
+
+.. environ::
+ \begin{info}
+ content
+ \end{info}
+
+ A simple block to typeset important information differently.
+
+ .. sdaps:: An info block
+ :sdapsclassic:
+
+ \begin{info}
+ Just a block to write some information in, will have a line above and below.
+ \end{info}
+
+
+.. environ::
+ \begin{markgroup}[kwargs]{text}
+ content
+ \end{markgroup}
+
+ :param text: Common question for all subquestions. Fragile content is currently *not* supported
+ :param kwags: Same as :environ:`rangearray`
+
+ .. sdaps:: A group of range questions (used to be called mark)
+ :sdapsclassic:
+
+ \begin{markgroup}[align=mygroupalignment]{A set of mark questions}
+ \markline{First question}{lower}{upper}
+ \markline{Second question}{lower 2}{upper 2}
+ \end{markgroup}
+
+ \begin{markgroup}[align=mygroupalignment]{Another set of mark questions which is aligned to the first}
+ \markline{First question}{a}{c}
+ \markline{Second question}{b}{d}
+ \end{markgroup}
+
+ \begin{markgroup}[other]{Another further set of questions with an alternative answer}
+ \markline{First question}{lower}{upper}{other}
+ \markline{Second question}{a}{b}{c}
+ \end{markgroup}
+
+.. todo::
+ The spacing in the "other" case is not sane, we need a larger default spacing in general.
+
+
+
+.. environ::
+ \begin{choicegroup}[kwargs]{text}
+ content
+ \end{choicegroup}
+
+ :param text: Common question for all subquestions. Fragile content is currently *not* supported
+ :param kwags: Same as :environ:`choicearray`
+
+ .. note:: The choicegroup environment is an alias for the :environ:`choicearray` environment. At this
+ point the only difference is that the choicegroup environment correctly prints the
+ header and that it creates the :macro:`\\groupaddchoice` and :macro:`\\choiceline` aliases.
+
+ .. macro:: \choice[kwargs]{text}
+
+ A possible choice inside inside the group.
+
+ :param text: The choices (header) text.
+ :kwarg text: A replacement text for the metadata, if set fragile content is
+ permitted inside the `text` argument.
+ :kwarg var: Variable name for this answer for multichoice (to be appended to context).
+ :kwarg val: Value for this answer for singlechoice.
+
+ .. macro:: \groupaddchoice[kwargs]{text}
+
+ Alias for :macro:`\\choice` for compatibility.
+
+ .. macro:: \question[kwargs]{text}
+
+ A single question inside the group. All choices need to be defined earlier using :macro:`\\choice`.
+
+ :param text: Question text.
+ :kwarg text: A replacement text for the metadata, if set fragile content is
+ permitted inside the `text` argument.
+ :kwarg var: Variable name for this question (to be appended to context).
+ :kwarg range: Specify which chekcboxes to show. Needs ot be given an **in order list** of variables (multichoice) or values (singlechoice) also allowing specifying `...` for any amount of items.
+
+ .. macro:: \choiceline[kwargs]{text}
+
+ Alias for :macro:`\\question` for compatibility.
+
+ .. sdaps:: Example of a choicegroup environment
+ :sdapsclassic:
+
+ \begin{choicegroup}{A group of questions}
+ \choice{Choice 1}
+ \choice{Choice 2}
+ \question{Question one}
+ \question{Question two}
+ \end{choicegroup}
+
+ \begin{choicegroup}[align=something]{Another question}
+ \choice{Some choice 1}
+ \choice{Some choice 2}
+ \question{Question one}
+ \question{Question two}
+ \end{choicegroup}
+
+ \begin{choicegroup}[align=something]{Another group of questions which is automatically aligned to the previous}
+ \groupaddchoice{1}
+ \groupaddchoice{2}
+ \choiceline{Question one}
+ \choiceline{Question two}
+ \end{choicegroup}
+
+ .. sdaps:: Example of a vertical choicegroup environment also showing the "rotated" header layouter
+ :sdapsclassic:
+
+ \begin{choicegroup}[layouter=rotated,vertical]{A group of questions}
+ \groupaddchoice{Choice 1}
+ \groupaddchoice{Choice 2}
+ \choiceline{Question one}
+ \choiceline{Question two}
+ \end{choicegroup}
+
+ \begin{choicegroup}[layouter=rotated,angle=45,vertical]{A group of questions with a smaller angle}
+ \groupaddchoice{Choice 1}
+ \groupaddchoice{Choice 2}
+ \choiceline{Question one}
+ \choiceline{Question two}
+ \end{choicegroup}
+
+ .. sdaps:: Example of choice filtering
+ :sdapsclassic:
+
+ \begin{choicegroup}[colsep=2pt,singlechoice]{Please select a date}
+ \groupaddchoice{1}
+ \groupaddchoice{2}
+ \groupaddchoice{3}
+ \groupaddchoice{4}
+ \groupaddchoice{5}
+ \groupaddchoice{6}
+ \groupaddchoice{7}
+ \groupaddchoice{8}
+ \groupaddchoice{9}
+ \groupaddchoice{10}
+ \groupaddchoice{11}
+ \groupaddchoice{12}
+ \groupaddchoice{13}
+ \groupaddchoice{14}
+ \groupaddchoice{15}
+ \groupaddchoice{16}
+ \groupaddchoice{17}
+ \groupaddchoice{18}
+ \groupaddchoice{19}
+ \groupaddchoice{20}
+ \groupaddchoice{21}
+ \groupaddchoice{22}
+ \groupaddchoice{23}
+ \groupaddchoice{24}
+ \groupaddchoice{25}
+ \groupaddchoice{26}
+ \groupaddchoice{27}
+ \groupaddchoice{28}
+ \groupaddchoice{29}
+ \groupaddchoice{30}
+ \groupaddchoice{31}
+ % Note that the automatically assigned values match the choices.
+ \question{Day}
+ \question[range={...,12}]{Month}
+ \question[range={2,5,...,9,28,...}]{Range}
+ \end{choicegroup}
+
+.. environ::
+ \begin{optiongroup}[kwargs]{text}
+ content
+ \end{optiongroup}
+
+ Alias for :environ:`choicegroup` which simply sets it into ``singlechoice`` mode by default.
+
+ .. sdaps:: Example of a choicegroup environment
+ :sdapsclassic:
+
+ \begin{optiongroup}{A group of questions}
+ \choice{Choice 1}
+ \choice{Choice 2}
+ \question{Question one}
+ \question{Question two}
+ \end{optiongroup}
+
+ \begin{optiongroup}[align=something]{Another question}
+ \choice{Some choice 1}
+ \choice{Some choice 2}
+ \question{Question one}
+ \question{Question two}
+ \end{optiongroup}
+
+ \begin{choicegroup}[align=something,singlechoice]{Another group of questions which is automatically aligned to the previous}
+ \groupaddchoice{1}
+ \groupaddchoice{2}
+ \choiceline{Question one}
+ \choiceline{Question two}
+ \end{choicegroup}
+
+
+
+Complex typesetting and images
+------------------------------
+
+SDAPS allows replacing the text which is exported for the metadata (i.e. what will show
+up in the report). This can make sense for convenience reasons, if shortened answers
+are sufficient for e.g. the report, but it also allows inserting complicated LaTeX
+expressions into the document without having to fear any issues.
+
+Apart from the advantage of having a better string in the report or similar you
+also get the advantage that more TeX commands can be used in the document. Usually
+environments like `verbatim` or `array` would not work inside an SDAPS environment,
+but they will work if a replacement text is specified.
+
+.. sdaps:: Example of using fragile content together with metadata text replacement
+ :sdapsclassic:
+ :metadata:
+
+ \begin{choicegroup}[layouter=rotated]{A group of questions}
+ \groupaddchoice[text=choice 1]{$\left( \begin{array}{cc} a & b \\ c & d \end{array} \right) + \log{\alpha}$}
+ \groupaddchoice[text=choice 2]{Choice 2 -- \LaTeX}
+ \choiceline[text=question 1]{\verb^Inline verbatim^}
+ \choiceline[text=question 2]{
+ \begin{tabularx}{0.5\linewidth}{llX}
+ cell 1 & cell 2 & tabularx over half the page width fit used as the question text. This cell is the X column filling the rest of the half page.
+ \end{tabularx}%
+ }
+ \choiceline[text=question 3]{
+ \begin{verbatim}Even such things as verbatim environments work.
+ However, verbatim does have some weird spacing issues (which can be partially
+ solved by wrapping it into a vbox or similar).
+ \end{verbatim}
+ }
+ \choiceline{Question 4 ends up unmodified in the metadata}
+ \end{choicegroup}
+
+
+
+Variables
+---------
+
+.. sdaps:: A choicegroup example using variables. Notice that the boxes in the metadata
+ have variables named e.g. "flower_adam_alice". The first group of questions does
+ not have a common prefix. The second group of questions has the common "flowerd" prefix.
+ :sdapsclassic:
+ :metadata:
+
+ \begin{choicegroup}{A group of questions}
+ \groupaddchoice[var=alice]{Choice "alice"}
+ \groupaddchoice[var=eve]{Choice "eve"}
+ \groupaddchoice{Unnamed choice}
+ \choiceline[var=adam]{Question "adam"}
+ \choiceline[var=bob]{Question "bob"}
+ \choiceline{Unnamed question}
+ \end{choicegroup}
+
+ \begin{choicegroup}[var=flower]{A group of questions with variable "flower"}
+ \groupaddchoice[var=alice]{Choice "alice"}
+ \groupaddchoice[var=eve]{Choice "eve"}
+ \groupaddchoice{Unnamed choice}
+ \choiceline[var=adam]{Question "adam"}
+ \choiceline[var=bob]{Question "bob"}
+ \choiceline{Unnamed question}
+ \end{choicegroup}
+
+
+.. sdaps:: A markgroup example using variables. The variable is e.g. "car_alice"
+ and the boxes have a value assigned to them. Grouping is handled as in the
+ previous case, adding the prefix when given.
+ :sdapsclassic:
+ :metadata:
+
+ \begin{markgroup}{A group of questions}
+ \markline[var=alice]{Question "alice"}{lower}{upper}
+ \markline[var=bob]{Question "bob"}{lower}{upper}
+ \markline{Unnamed question}{lower}{upper}
+ \end{markgroup}
+
+ \begin{markgroup}[var=car]{A group of questions with variable "car"}
+ \markline[var=alice]{Question "alice"}{lower}{upper}
+ \markline[var=bob]{Question "bob"}{lower}{upper}
+ \markline{Unnamed question}{lower}{upper}
+ \end{markgroup}
+
+
+
diff --git a/macros/latex/contrib/sdaps/html/_sources/sdapslayout.rst.txt b/macros/latex/contrib/sdaps/html/_sources/sdapslayout.rst.txt
new file mode 100644
index 0000000000..a7e77e0fde
--- /dev/null
+++ b/macros/latex/contrib/sdaps/html/_sources/sdapslayout.rst.txt
@@ -0,0 +1,81 @@
+sdapslayout package
+===================
+
+This package provides a set of more complex layouting options on top of the
+sdapsarray package. The following environments are provided:
+
+* :environ:`choicearray`
+* :environ:`rangearray`
+
+The rangearray is not quite as powerful, as it does not expose some of the
+sdapsarray options to the user. Note that much more complex custom layouts can
+be created directly with sdapsarray.
+
+.. warning:: The documentation here is currently incomplete! Pleases refer to the sdapsclassic :environ:`choicegroup` and :environ:`markgroup` documentation!
+
+.. environ::
+ \begin{choicearray}[kwargs]
+ \end{choicearray}
+
+ The following optional keyword parameters can be passed to the
+ environment. These keyword parameters default to the values provided in the
+ SDAPS context and can for example be modified globally for the document.
+
+ :kwarg align: named alignment group, set to a common name to align multiple environments to each other
+ :kwarg noalign: disable alignment (same as setting ``align`` to an empty value)
+ :kwarg horizontal: set horizontal mode where each question is one row (default)
+ :kwarg layouter: set the sdapsarray layouter (e.g. rotated for rotated column headers)
+ :kwarg angle: set the angle of the column headers when in rotated mode
+ :kwarg vertical: set vertical mode where each question is one column
+ :kwarg type: the question type "multichoice" or "singlechoice"
+ :kwarg multichoice: switch to multichoice "Choice" question mode
+ :kwarg singlechoice: switch to singlechoice "Option" question mode
+
+
+ The choicearray environment represents a tabular layout for a set of multiple
+ choice questions which have the same possible answers. A new header is created
+ in the metadata to group the questions.
+
+ .. warning:: The header is currently *not shown* in the PDF and it cannot
+ contain fragile content due to implementation constraints! This is an issue
+ with the class which will be fixed. The exact final behaviour is not yet
+ specified.
+
+ .. sdaps:: Example of a choicearray environment
+
+ \begin{choicearray}[layouter=rotated]
+ \choice{Choice 1}
+ \choice{Choice 2}
+ \question{Question one}
+ \question{Question two}
+ \end{choicearray}
+
+ .. sdaps:: Example of a vertical choicearray environment
+
+ \begin{choicearray}[layouter=rotated,vertical]
+ \choice{Choice 1}
+ \choice{Choice 2}
+ \question{Question one}
+ \question{Question two}
+ \end{choicearray}
+
+ .. todo::
+ Right now all arguments can be overriden, this should not be the case. It
+ would be correct if the variable name is loaded from the kwargs, and then
+ the defaults for align and horizontal/vertical should be applied
+
+
+ Inside the environment you need to first define all possible answers with
+ choice macro and each question using the question macro.
+
+.. environ::
+ \begin{optionarray}[]
+ \end{optionarray}
+
+ .. todo:: Uh, document this.
+
+.. environ::
+ \begin{rangearray}[]
+ \end{rangearray}
+
+ .. todo:: Uh, document this.
diff --git a/macros/latex/contrib/sdaps/html/_sources/sdapspdf.rst.txt b/macros/latex/contrib/sdaps/html/_sources/sdapspdf.rst.txt
new file mode 100644
index 0000000000..75555f6a6e
--- /dev/null
+++ b/macros/latex/contrib/sdaps/html/_sources/sdapspdf.rst.txt
@@ -0,0 +1,71 @@
+sdapspdf package
+================
+
+You can use this package to make PDF forms using the SDAPS packages. SDAPS
+itself does not give you a way to submit these though.
+
+To use this feature simply use the sdapspdf package. You need to wrap everything
+containing PDF form elements inside a :environ:`Form` environment. After this
+enable form generation by simply setting the ``pdf_form`` option for checkboxes
+and freeform textboxes.
+
+.. note::
+ The sdapspdf package imports hyperref internally. So some care might need to
+ be taken to import it after hyperref itself.
+
+The following extra options are added to boxes and checkboxes:
+
+=================== =====================
+Option Purpose
+=================== =====================
+pdf_form Turn on PDF form generation (default: `false`)
+default Allows enabling a checkbox by default (default: `false`, set to `true` to use)
+checkboxsymbol The symbol to use for the checkmark (integer, see PDF specification, default: 8)
+=================== =====================
+
+.. warning::
+ The default for pdf_form might still change to be `true`.
+
+.. note::
+ The SDAPS base package will likely add further macros to make setting these options more convenient.
+
+
+.. sdaps:: Using PDF forms
+ :preamble:
+ \usepackage{sdapspdf}
+ % Define aliases for the commands we need to use, context_append
+ % expands settings, context_set sets them (for the current scope),
+ % possibly removing old settings.
+ \ExplSyntaxOn
+ \let\mycontextappend\sdaps_context_append:nn
+ \let\mycontextset\sdaps_context_set:nn
+ \let\mycheckbox\sdaps_checkbox:nn
+ \let\mytextboxvhstretch\sdaps_textbox_vhstretch:nnn
+ \ExplSyntaxOff
+
+ \begin{Form}
+ % The \my* commands are aliases that are defined in the praemble
+
+ % Set the pdf_form option for all boxes (*)
+ \mycontextappend{*}{pdf_form=true}
+
+ % Or for checkboxes and textboxes separately
+ %\mycontextappend{singlechoice}{pdf_form=true}
+ %\mycontextappend{multichoice}{pdf_form=true}
+ %\mycontextappend{textbox}{pdf_form=true}
+
+ \noindent A checkbox: \mycheckbox{}{} \newline
+ \mycontextappend{multichoice}{default=true}
+ A checked checkbox: \mycheckbox{}{} \newline
+ \mycontextappend{multichoice}{default=true,checkboxsymbol=5}
+ A checked checkbox with different symbol: \mycheckbox{}{}
+
+ Please note that the above rendering is slightly broken as the poppler
+ PDF renderer maps the checkboxsymbol incorrectly. Acrobat will show the
+ other symbol.
+
+ \noindent A non stretching textbox:
+ \mytextboxvhstretch{text}{4cm}{0}
+ \end{Form}
+
+