diff options
Diffstat (limited to 'macros/latex/contrib/sdaps/html/_sources')
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} + + |