diff options
Diffstat (limited to 'macros/latex/contrib/sdaps/html/_sources/sdapsclassic.rst.txt')
-rw-r--r-- | macros/latex/contrib/sdaps/html/_sources/sdapsclassic.rst.txt | 607 |
1 files changed, 607 insertions, 0 deletions
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} + + + |