Command-line-only options

• --file : File to compile, this is the only mandatory option. (Using the examrandomizer.engine does it for you)

All these options are defaulted to false unless they are given.

• --homework: If this option is given, It only applies the personalization on the preamble, it doesn’t try to randomize the document order.
• -c/--compile: If this option is given, it compiles the documents to pdfs in the output folder using latexmk.
• --xelatex: Should the engine used be xelatex. Otherwise, it will use the pdflatex engine
• --debug: If this option is true, it doesnt remove auxiliary files

General options

• "layernames"/"layercmd" :

  Default ->

  {"layernames":["questions", "choices"], "layercmd": ["question", "(choice|CorrectChoice)"]}

  A character vector with the names of the nested layer environments. It recognizes simple regular expressions. For example, the default value of layercmd, (choice|CorrectChoice), can be read as the command being either \choice or \CorrectChoice.

  The default values follows the standard exam class defaults. Therefore, it would detect appropriately the following structure.

    \begin{questions}
        \question
        \begin{choices}
            \choice
            \choice
            \choice
            \CorrectChoice
        \end{choices}
        ...
    \end{questions}
    \begin{questions}
        ...
    \end{questions}
    ...

• "reordersections", "reorderitems": Default value ->

  {"reordersections": [true, ..., true], "reorderitems": [true, ..., true]}

  Given the layernames and layercmd, the values of reordersections and reorderitems should be the same length.

  • Every entry refers to a layer, from outer-most layer to inner-most layer
  • Notice that the values on the arrays must be “true” or “false”.
  • By reordering “items”, it means reordering each item within one environment and reordering them.
  • By reordering “sections”, it means to reorder the order of the environments, from \begin{} to \end{}.

    • It should be clear that everything before the first section will be kept fixed.

      This is done to prevent the main explanation from getting dragged with the first section. If you really want to avoid some text from getting left behind, for some specific use you might have just place it on the same line as the \begin{} environment is on.

• "correcttag": Default -> ["CorrectChoice"]

  The ‘LaTeX’ command name (\correcttag) that will mark a choice as being correct if it is found somewhere within the text of that choice.

• "wrongtag": Default -> ["choice"]

  The ‘LaTeX’ command name (\wrongtag) that will mark a choice as being incorrect if found somewhere within the text of that choice.

  If \wrongtag can’t be found on a question, that question will be ignored when generating the answer sheet. Only the correct ones will be found on the answer sheet.

• --table/"table" : Default -> NULL

  Table file from which to extract info to personalize the document. If this parameter is not given it requires to give the “noutput”.

  Look at Options to personalize documents for more information in how documents can be personalized with a table.

  IMPORTANT: The table file must be specified relative to the location of the tex document being compiled, not relative to the executable location

• -n/--noutput/"noutput":

  Number of output versions. If this paramenter is not given, it requires the “table” parameter to be given. In that case, it will understand the number of output versions to be the same as the number of rows in the table.

• -q/--nquestions/"nquestions": Default -> "max"

  Number of “items” in the outer most layer of the exam structure (Usually it will be the number of questions).

  3. If the value is a number, it will remove questions from the output versions making all exams have that number of questions.
     • All sections must have at least one question, therefore, if you have 5 sections, you can’t specify the nquestions to be 4 in the output.
  4. If the value is a vector, for example "nquestions":[3, 4, 5, 6], the vector must then:
     • Have the same length as the number of sections
     • Have all values be non-zero values
  5. If the value can’t be coherced to numeric (For example, “max”), it keeps all the questions form the exam.

• -s/--seed/"seed" : Default -> NULL

  Seed to intialize the randomization. - If no value of seed is found it looks for compileInfo.txt in the output folder where it is going to dump the tex files. If it doesn’t find that file, it uses Sys.time() to create a seed. This prevents changing the seed between runs of the same file.

How the personalization is done

We rely in using ‘LaTeX’ macros to personalize documents. We search within the preamble for newcommand tags,

 \newcommand{\commandname}{commandvalue}

And once found, we change the command value to the new personalized value. A common use would be, for example, personalizing the document with a name by writing the following macro

\newcommand\Name{TestName}

An once personalization occurs, each version will replace the \Name command value for the value required for each version.

Note that if you don’t want the engine to modify the macro you are using, you can instead of using \newcommand, you could use \newcommand* or \def . The asterisk * has a special meaning in ‘LaTeX’, but with the simple use that we are giving this commands, that can’t have options, that is irrelevant..

Reserved command names

The following commands names are reserved names, that you can overwrite, but I would recommend you not to.

Instead, simply add always the next two lines in your document

\newcommand\rseed{0}
\newcommand\myversion{0}

• The command \rseed after running the randomization will store the seed that R used to seed all random numbers.

• The command \myversion will hold the version number, that can be used in the document to display the version of each exam.

  (When using the option --homework, this last command is not replaced)

Document options

So, how do you add your own commands to be personalized you might ask?

There are two types of information that you might want to add to personalize each individual document.

• Random information, that would be assigned individually at randomly.
• Or extra information, that would be taken from the table itself and incorporated into the document.

!% TexExamRandomizer = {"randominfo": {"<commandname>": <integer>, "<commandname2>" : <integer> ...}}

"<commandname>" : ["value1", "value2", "value3"]

!% TexExamRandomizer = {"extrainfo": {"<cmdName>":"<columnName>", "<cmdName>":"<columnName>", ...}}

\newcommand\cmdName{Testname}

\newcommand\cmdName{<vale row i of column columnName>}

Three layers document with table info

%! TexExamRandomizer = {"noutput": 5}
%! TexExamRandomizer = {"table":"TestClass.csv"}
%! TexExamRandomizer = {"extrainfo":{"Class":"class", "Roll Number":"rollnumber","Nickname":"nickname"}}

%! TexExamRandomizer = {"layercmd":["section", "question", "(choice|CorrectChoice)"]}
%! TexExamRandomizer = {"layernames":["document", "questions", "choices"]}
%! TexExamRandomizer = {"reordersections":[true, true, false]}
%! TexExamRandomizer = {"reorderitems":[false, true, true]}

Exam class with 6 sections, choosing a few questions for each section.

%! TexExamRandomizer = {"noutput":2, "nquestions": [2,3,3,3,1,1]}
%! TexExamRandomizer = {"randominfo": {"randomnumber":100, "switchnumber":["even", "odd"]}}

Fixing position of sections and questions. Randomizing only the choices for each question.

%! TexExamRandomizer = {"noutput":2}
%! TexExamRandomizer = {"randominfo": {"randomnumber":100000000, "switchnumber":["even", "odd", "stop"]}}
%! TexExamRandomizer = {"reordersections":[false, false], "reorderitems":[false, true]}
%! TexExamRandomizer = {"table":"TestClass.csv"}
%! TexExamRandomizer = {"extrainfo":{"Class":"class", "Roll Number":"rollnumber","Nickname":"nickname"}}