summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/sdaps/html/_sources/sdapsclassic.rst.txt
blob: 4e9931fb8dd6a039c76e7a93fc68cf304f5de720 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
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}