\RequirePackage[use=publish]{spdef}
\documentclass{article}
\usepackage[fleqn]{amsmath}
\usepackage[designi,forcolorpaper,latextoc,extended]{web}
\usepackage{eforms}
\usepackage{dirtree}
\usepackage{fancyvrb}

\usepackage{xbmks}
\xbmksetup{colors={int=red},styles={intbf}}
%\DeclareInitView{layoutmag={navitab:UseOutlines}}
\hypersetup{pdfpagemode=UseOutlines}


\ifpublish % developer packages
\def\useThese{\usepackage[altbullet]{lucidbry}
\usepackage[active]{srcltx}}
\expandafter\useThese\fi

\newcommand\newtopic{\par\ifdim\lastskip>0pt\relax\vskip-\lastskip\fi
\vskip\medskipamount}

\tocPartTitle{\tops{\protect\makebox[0pt][r]{\thepart\hspace{1em}}}{\thepart\space}#1}
\let\partSave\part
\def\part#1{\par\addvspace{4ex}\bgroup\let\newpage\relax\partSave{#1}\egroup\addvspace{2ex}}

\let\tops\texorpdfstring

\DeclareDocInfo
{
    university={Acro\negthinspace\TeX.Net},
%    title={The \textsf{thorshammer} package\tops{\\[1ex]}{: }%
%      Documentation for \tops{\textsf}{}{thmclass.ps1}},
    title={The \textsf{thorshammer} package\tops{\\[1ex]}{: }%
      Documentation for the system scripts},
    author={D. P. Story \& Thorsten Grothe},
    email={dpstory@acrotex.net},
    subject=Documentation for thmclass.ps1,
    talksite={\url{www.acrotex.net}},
    version={1.5.7, 2020/01/13},
    Keywords={LaTeX, AcroTeX, Powershell, thorshammer},
    copyrightStatus=True,
    copyrightNotice={Copyright (C) \the\year, D. P. Story},
    copyrightInfoURL={http://www.acrotex.net}
}


\useFullWidthForPaper

\def\dps{$\mbox{$\mathfrak D$\kern-.3em\mbox{$\mathfrak P$}%
   \kern-.6em \hbox{$\mathcal S$}}$}
\let\pkg\textsf
\def\cs#1{\texttt{\char`\\#1}}
\let\opt\textsf
\let\app\textsf
\let\uif\textsf
\def\thescript{\texttt{thmclass.ps1}}
\def\thebatch{\texttt{runps1.bat}}
\def\dtt#1{\texttt{\$#1}}
\def\ameta#1{\ensuremath{\langle\textit{\texttt{#1}}\rangle}}
\def\meta#1{\textsl{\texttt{#1}}}
\def\darg#1{\texttt{\char123\relax#1\char125\relax}}
\newenvironment{lquote}
   {\list{}{}%
    \item\relax}
   {\endlist}

\makeatletter
%\setlength{\DT@offset}{(\linewidth-1.4in)/2}
\renewcommand{\paragraph}
    {\@startsection{paragraph}{4}{0pt}{6pt}{-3pt}{\bfseries}}
\renewcommand{\subparagraph}
    {\@startsection{subparagraph}{5}{\parindent}{6pt}{-3pt}%
    {\normalfont\normalsize\bfseries}}
\def\chnglabelname#1{\edef\@currentlabelname{#1}}
\makeatother

\begin{document}

\maketitle

\pdfbookmarkx[1]{Title Page}[action={\Named{FirstPage}}]{TitlePage}
\pdfbookmarkx[1]{The thorshammer package}[action={\GoToR/F(thors-the-man.pdf)/D[0 /Fit]},color=blue,style={bf}]{thorhammer}
\pdfbookmarkx[1]{Links to AcroTeX.Net}[action={/S/GoTo/D(undefined)},%
  color=magenta,style={bf}]{acrotex}
\belowpdfbookmarkx{http://www.acrotex.net}[action={\URI{http://www.acrotex.net}},%
  color=magenta,style={bf}]{home}
\belowpdfbookmarkx{http://blog.acrotex.net}[action={\URI{http://blog.acrotex.net}},%
  color=magenta,style={bf}]{blog}


\selectColors{linkColor=black}
\tableofcontents
\selectColors{linkColor=webgreen}

\section{Introduction}

\textbf{\hyperref[PartI]{Part I}} describes how to execute {\thescript} and
documents all the subordinate files and folders it generates.
The \thescript\space file is a \app{Powershell} script file
written, for the most part, \emph{by the great Thor himself} to
meet the needs of his classes. It can be used ``as is'' or
modified to conform it to your requirements. The script is
designed to be used with the \pkg{thorshammer} package, but this
is not a requirement.

The file structure of Thor may not be for everyone, \textbf{\hyperref[PartII]{Part II}} describes a set
of ``standalone'' scripts, which were derived from the scripts in \textbf{Part I}.

\paragraph*{From the Acro\negthinspace\TeX{} Legal Department.}
We offer no guarantees and accept no liabilities. Test the
scripts extensively to be sure they are working for you. Modify the script
as you will, but don't bother us with your changes, unless they are improvements. %\verb|:-{)|


\paragraph*{Platforms.} The script has been tested on
\textsf{Windows OS} and \app{Linux}. It is our understanding
that \app{Powershell} can be installed and executed on
\textsf{MacOS}, so this script \emph{may} have use on that
platform as well.

\part{Using the Thor system}\label{PartI}

\noindent Thor has developed his own file structure for his class, this
structure may be useful to your own classroom. Here, we describe the system
that has been developed. Carefully read this part of the documentation to
determine if Thor's scheme can work for you. \medskip

\section{Deploying {\thescript} \textsl{et al}}

Locate the three files \thescript, \thebatch, and \texttt{sample-vars.txt}
from the \texttt{system-scripts} folder of the
\pkg{thorshammer} distribution.

\paragraph*{The first things first.} (1) \emph{Copy}
\thescript, \thebatch, and \texttt{sample-vars.txt} to a
working folder.  (2) Open the \app{Powershell} file \thescript{}
in a text editor and edit the value of the variable appropriate to your platform
\texttt{\$pathThorshammerWin} or \texttt{\$pathThorshammerLin},
being sure the default path points to your \pkg{thorshammer}
folder, and if not, modify the path to point to the folder
of the \pkg{thorshammer} distribution on your computer.\footnote{The purpose of this is to
grab the two support files \texttt{container.pdf} and
\texttt{terminate-batch.pdf}. If your {\TeX} installation has
installed these two files elsewhere, find them, and modify the
path to point to the folder containing these two files.}

\section{Executing \thescript}

On \app{Windows}, the easiest way to execute \thescript\space is
through the BAT file \thebatch.\footnote{The authors have little
knowledge of how to do this on \app{Mac OS}. An interested user
on \app{Mac OS} would need to advise us.} Running the script
requires the input of eight (8) values for variables, these are
listed below and described in the order they are expected to be
input.

\paragraph*{Eight basic variables}\label{para:eight}
\begin{enumerate}
  \item \dtt{class}: The name of the class, could be name as
      listed in the college catalog (MAT101, STA221, HH21B,
      A21A, WF23, \dots) or something more understandable (calc1,
      alg1, euhist, \dots)\footnote{The value of this variable is used in the file name
      of the TEX template file; consequently, this value should be kept short, yet meaningful.}

  \item \dtt{number}: The quiz or exam number. The value of
      this variable is not required to be a number.\footnotemark[\thefootnote]

  \item \dtt{subject}: Field of study, such as Math, German,
      History, and so on.\footnotemark[\thefootnote]

  \item \dtt{theme}: The topic of this exam: factoring, grammar, 20thcentury, etc.\footnotemark[\thefootnote]


  \item \dtt{instrName}: Instructor's name. The name should be
      a single word that identifies the instructor (Thor,
      Newton, Banach, and so on).\footnotemark[\thefootnote]


  \item \dtt{date}: The date of the exam.


  \item \dtt{time}: The length of the exam; this is, the time
      the students have to work on the exam.

  \item \dtt{classPath}: The full path to the folder that
      contains the quizzes of the class.

\end{enumerate}

\begin{comment}
\goodbreak
\section{Execution modes: interactive and automatic}

There are two execution modes: (1) interactive and (2)
automatic.

\subparagraph*{(1) Interactive:} If you execute \thebatch\space on the
    \uif{Command Prompt}, you are offered three options:\footnote{Instructions are in German or English}\par\medskip
    \begin{minipage}{\linewidth-\parindent}
      \begin{enumerate}
        \item[(1)] interactive query of individual variables (class,
            teacher abbreviation, \dots)

            Here, you are asked in enter the values for each of the
            above listed eight variables.
        \item[(2)] No query: test with default values

            Used for testing purposes; automatically sets the values
            of the eight variables.
        \item[(q)] Exit the script
      \end{enumerate}
    \end{minipage}
\subparagraph*{(2) Automatic:} For the automatic, the script gets
    the values for the eight variables from a TXT file. It is
    this option that is the main approach to building your file
    structure, and is the topic of the rest of the discussion in
    the documentation.
\end{comment}

\subsection{On running \thescript}\label{Focus}

Now that you have read a brief description of the eight variables, rename the
file \texttt{sample-vars.txt} in your working folder to something short yet
appropriate to your work (perhaps rename it to just \texttt{class.txt}). In
this document, we shall refer to the renamed TXT file as
\texttt{\ameta{varlist}.txt}. Open \texttt{\ameta{varlist}.txt} in a text
editor and modify the left column to values appropriate to your class. The
contents of \ameta{varlist}\texttt{.txt} has the following form (shown with
default values which need to be changed):
\begin{Verbatim}[xleftmargin=\parindent]
alg1              # class
1                 # number
maths             # subject
factoring         # theme or topic
THOR              # instrName
01.01.2019        # date
60 Min.           # time
C:/temp           # classPath
\end{Verbatim}
Now execute \thebatch\space with arguments \texttt{thmclass} and
\texttt{\ameta{varlist}.txt} from the \uif{Command Prompt}:\footnote{The \uif{Command Prompt} needs
to be located in the folder that contains  \thescript, \thebatch, and \texttt{sample-vars.txt}}
\begin{equation}
  \fbox{\ttfamily runps1 thmclass \ameta{varlist}\texttt{.txt}}\label{dis:thmclass}
\end{equation}
\thescript\space reads the data contained in
\ameta{varlist}\texttt{.txt}. Using a batch file is the easiest way of executing the
\thescript\space with argument \texttt{\ameta{varlist}.txt}.

\subsubsection{The results of running \tops{\thebatch}{runps1.bat}}

Executing `\texttt{runps1 thmclass \ameta{varlist}.txt}', as
just described (see display~(\ref{dis:thmclass})), creates a
series of folders and files within the same folder in which
{\thebatch}, {\thescript}, and \texttt{\ameta{varlist}.txt}
reside.\medskip

Suppose \texttt{\ameta{varlist}.txt} has the following symbolic
values:
\begin{quote}\ttfamily\obeyspaces\catcode`\#=12
\ameta{class}     # class\\
\ameta{number}    # number\\
\ameta{subject}   # subject\\
\ameta{theme}     # theme or topic\\
\ameta{instrName} # instrName\\
\ameta{date}      # date\\
\ameta{time}      # time\\
\ameta{classPath} # classPath
\end{quote}


\subsubsection{Structure displayed} Figure~\ref{fig:struct} represents the structure created by \thescript.

\begin{figure}[htb]
\bgroup
\hfuzz120pt
%\makeatletter
%\hspace*{1.4in}
\fboxsep0pt\let\BOX\relax
\begin{center}\BOX{\begin{minipage}{3.5in}
\dirtree{%
.1 \ameta{working folder}.
.2 {runps1.bat}.
.2 {sample-vars.txt}\DTcomment{rename and edit\footnote{Generically referred to as \texttt{\ameta{varlist}.txt}}}.
.2 {thmclass.ps1}.
.2 \ameta{class}.
.3 \ameta{instrName}.
.4 backup.
.4 anSUS (toStudents).
.4 vonSUS (fromStudents).
.4 {runps1.bat}.
%.4 {classFolders.bat}.
.4 {csvTOcfg.ps1}.
.4 {classFolders.ps1}.
%.4 {csvTOcfg.bat}.
.4 {copyka.ps1}.
.4 {delka.ps1}.
.4 {moveka.ps1}.
.4 {sample-list.csv}\DTcomment{rename and edit\footnote{Generically referred to as \texttt{\ameta{list}.csv}}}.
.4 {container.pdf}.
.4 {terminate-batch.pdf}.
.3 {00-\ameta{class}.cfg}.
.3 {genquiz.ps1}.
.3 {runps1.bat}.
.3 {tex-template.tex}.
.3 {web.cfg}.
}
\end{minipage}}\hfill
\end{center}
\egroup
\caption{Structure created by \thescript}\label{fig:struct}
\end{figure}

\subsubsection{Structure explained}

We now attempt the Herculean task of explaining each of these.
\begin{description}
  \item[\normalfont\ameta{class}] (folder) The folder created by the \ameta{class} variable. This folder
  contains all the working files and folders of the class you are teaching.
  \item[\normalfont\ameta{instrName}] (folder) This is a short name for the instructor.  This folder contains
  a number of other folders and files.
  \begin{description}
    \item[\normalfont\texttt{backup}] A folder that will contain the
        instructor's copies of the quizzes generated. When
        you open the file \texttt{00-\ameta{class}.cfg}, you
        will find:
        \verb|\instrPath*{|\ameta{instrName}\texttt{/backup}\verb|}|.
    \item[\normalfont\texttt{anSUS} (\texttt{toStudents})] A folder to
        drop the graded quizzes into. This folder name is
        \texttt{anSUS} when the local language is German and
        \texttt{toStudents} otherwise.
    \item[\normalfont\texttt{vonSUS} (\texttt{fromStudents})] The
        target destination of the script file
        \texttt{copyka.ps1}. This folder name is
        \texttt{vonSUS} when the local language is German
        and \texttt{fromStudents} otherwise.

%    \item[\texttt{classFolders.bat}] This batch file that
%        takes the contents of its argument and creates the
%        class folder structure within the \ameta{classPath}
%        folder. See the section on \texttt{classFolders}
%        below for more details.
    \item[\normalfont\texttt{csvTocfg.ps1}] A \app{Powershell} script
        that reads the contents of the configuration file \texttt{\ameta{list}.csv} and modifies
        \texttt{00-\ameta{class}.cfg} by appending appropriate \cs{classMember}
        statements.
    \item[\normalfont\texttt{classFolders.ps1}] A \app{Powershell}
        script file that creates class folders based on the
        contents of the \texttt{00-\ameta{class}.cfg}
        file.\footnote{The sysadmin may now allow creation
        of folders on the system drive; this script may be
        used for testing on the instructor's own drive.}
    \item[\normalfont\texttt{copyka.ps1}] A \app{Powershell} script that
        copies the completed student quizzes from their
        student folders to the folder \texttt{vonSUS}
        (\texttt{fromStudents}) where the instructor can
        operate on them.
%    \item [\texttt{csvTocfg.bat}] A batch file that takes
%        the contents of its argument and modifies
%        \texttt{00-\ameta{class}.cfg}, one level up. It
%        appends the \cs{classMember} data lines.
%  See the section on \texttt{classFolders} below for more
%  details.
    \item[\normalfont\texttt{delka.ps1}] A \app{Powershell} script
        that deletes the student quizzes from their personal
        student folders. (This is done after they are copied
        using \texttt{copyka.ps1}.)
    \item[\normalfont\texttt{moveka.ps1}] The \app{Powershell} script
        that copies and deletes the student quizzes from
        their personal student folders. \textbf{Not
        recommended!} I prefer to copy them and verify that
        they are all successfully copied before deleted them
        from the personal student folders.
    \item[\normalfont\texttt{sample-list.csv}] A comma (or semi-colon) delimited file. Each line
    of the file consists of three entries and has two formulations:
    \begin{quote}\ttfamily
      \ameta{first},\ameta{last},\ameta{rel-path}\\[3pt]
      \ameta{first},\ameta{last},*\ameta{full-path}
    \end{quote}
    In the first case, \ameta{rel-path} is the path, relative to the argument of the \cs{classPath},
    to the student folder; in the second case, \ameta{full-path} is the full path to the student
    folder.

    You should rename this file and modify its contents to
    reflect the class names and folder names of your class.

    \item[\normalfont\texttt{container.pdf}] A PDF file used by
        \textsf{Thor's way} action script. See the manual
        for the \pkg{thorshammer} package for details.
    \item[\normalfont\texttt{terminate-batch.pdf}] A PDF file used by
        \textsf{Thor's way} action script. See the manual
        for the \pkg{thorshammer} package for details.
  \end{description}
\end{description}
At the top most level of this folder structure are four files.
\begin{description}
  \item[\normalfont\texttt{genquiz.ps1}]\label{item:genquiz} A \app{Powershell} script
      that works in concert with \texttt{tex-template.tex}. When executed,
      it reads the \ameta{varlist}\texttt{.txt} file (one level up), the
      variable list file used to create the folders and files, it then
      creates a TEX file named
      \texttt{\ameta{number}-\ameta{class}-\ameta{subject}.tex}, which is a
      copy of \texttt{tex-template.tex}, with certain tagged variables in
      \texttt{tex-template.tex} replaced with their values based on
      \ameta{varlist}\texttt{.txt}; for example, the tagged variable
      \texttt{\#class} in \texttt{tex-template.tex} is replaced by the
      value of the class variable declared in \ameta{varlist}\texttt{.txt}
      (perhaps it is replaced by ``alg1'').

      \textbf{Steps to change the default name.} You can
      change the default name of the generated TEX file by
      following these steps: (1) open \texttt{genquiz.ps1} in
      your favorite text editor; (2) find the line,
\begin{quote}\ttfamily\catcode`\$=12
  $templateName="$number-$class-$subject.tex"
\end{quote}
and, finally, (3) change the assignment, perhaps to a function
of one or more of the above above variables.

  \item[\normalfont\texttt{tex-template.tex}] There are two renditions (or versions) for the TEX
      template: (1) a German language version, and (2) an English language
      version. The \app{Powershell} script \texttt{thmclass.ps1} detects
      the language as set by your operating system and writes the proper
      TEX template. The TEX template, which is \texttt{tex-template.tex}
      by name, contains tagged variables {\def\AND{{\normalfont and
      }}\catcode`\,=\active\def,{{\normalfont\string,
      }\ignorespaces}\ttfamily\catcode`\#=12\relax #class,
      #number,#subject,#theme,#instrName,#date, \AND #time}, which are
      replaced by their counterparts {\def\AND{{\normalfont and
      }}\catcode`\,=\active\def,{{\normalfont\string,
      }\ignorespaces}\ttfamily\catcode`\$=12\relax $class,
      $number,$subject,$theme,$instrName,$date, \AND $time}, as declared in
      \ameta{varlist}\texttt{.txt}.

      \textbf{German.} This \texttt{tex-template.tex} file is
      Thor's visualization of what his quizzes should look
      like. When \texttt{genquiz.ps1} is executed, it reads
      this file and saves it again under a different name, as
      discussed above.

      \textbf{English.} This form of the TEX template is more
      basic, without Thor's specialized features.

      The contents of \texttt{tex-template.tex} can be
      modified to suite your own understanding of what your
      quiz should look like. Use the tagged variables as you
      wish in your personal template file.

  \item[\normalfont\texttt{00-\ameta{class}.cfg}] The configuration file
      for building a quiz for the class. Initially, it has the
      following form:
\begin{Verbatim}[fontsize=\small,commandchars={^~@}]
% Reset the paths for \instrPath and \classPath for your system
% Use relative paths here for instructor according to dir, where tex file is located
\classPath{^ameta~classPath@}
\instrPath*{^ameta~instrName@/backup}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Syntax:
% \classMember{firstname}{lastname}{rel-path}
% \classMember{firstname}{lastname}*{full-path}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\end{Verbatim}
Running \texttt{csvTocfg.ps1} appends \cs{classMember} to the file. On running, it might now read,
\begin{Verbatim}[fontsize=\small,commandchars={^~@}]
% Reset the paths for \instrPath and \classPath for your system
% Use relative paths here for instructor according to dir, where tex file is located
\classPath{^ameta~classPath@}
\instrPath*{^ameta~instrName@/backup}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Syntax:
% \classMember{firstname}{lastname}{rel-path}
% \classMember{firstname}{lastname}*{full-path}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\classMember{Muehle}{Waeter}{MW634B/^ameta~instrName@}
\classMember{Anton}{Mueller}{AM256M/^ameta~instrName@}
\classMember{Laura}{Voegt}{LM356B/^ameta~instrName}@
\end{Verbatim}


%  \item[\ameta{number}-\ameta{class}-\ameta{subject}-\ameta{theme}\texttt{.tex}]
%      This is the TEX template file. This awkward, extremely
%      long and painful file name is a result of German
%      education. The file itself is a quiz template that uses
%      the \pkg{web}, \pkg{exerquiz} packages, in addition to
%      the \pkg{thorshammer} package. Bring this file into your
%      favorite {\LaTeX} editor and modify as desired, or write
%      your own from scratch. Of course, a change of name might
%      be in order as well.

\item[\normalfont\texttt{web.cfg}] The TEX template file uses the
    \pkg{web} package, and as such, uses many
    \pkg{web}-defined commands. These commands can be
    redefined through the \texttt{web.cfg}. The file
    \thescript{} creates its own \texttt{web.cfg}, for local
    use. If you open this created file, its contents are,
\begin{Verbatim}
%
% AeB Web Configuration file
%
\ExecuteOptions{dvips}
\bWebCustomize
% Insert redefinitions between these two marks
\eWebCustomize
\end{Verbatim}
To illustrate the use of the \texttt{web.cfg}, modify the file to now read,
\begin{Verbatim}
%
% AeB Web Configuration file
%
\ExecuteOptions{dvips}
\bWebCustomize
\author{Herr Dr. Thor}
\university{AcroTeX.edu}
\eWebCustomize
\end{Verbatim}
Above, we have declared \verb|\author{Herr Dr. Thor}| and
\verb|\university{AcroTeX.edu}|. (The \cs{author} and \cs{university}
commands are defined in the \pkg{web} package.) There are no restrictions, other
redefinitions of commands defined by other packages are permitted. Freely
use the special character `\texttt{@}' without having to type
\cs{makeatletter}/\allowbreak\cs{makeatother} combination.

      The \pkg{thorshammer} package defines a new command,
      that will be picked by \pkg{web} itself; the command is
      \cs{inputWebCfg}. This command has been embedded in the
      preamble of the TEX template.
\end{description}

\paragraph*{Additional comments on the eight variables.} We
document how the eight variables are used throughout the files generated by
\thescript.
\begin{description}
  \item[\normalfont\ameta{class}] is used to construct a top-level folder
      containing all the files generated by \thescript. This
      variable is the base name of the CFG file
      (\texttt{00-\ameta{class}.cfg}).
      \texttt{00-\ameta{class}.cfg} is input by the template
      file using the \cs{InputClassData} macro. It also
      appears as the argument of the \cs{thQzHeaderL} and
      \cs{title} commands in the template file.

  \item[\normalfont\ameta{number}] This variable appears in the TEX template file as
      the argument of the \cs{DeclareQuiz} and of the \cs{version} commands.

  \item[\normalfont\ameta{subject}] This variable appears as an argument
      of \cs{thQzHeaderCQ} and \cs{subject} in the TEX
      template file.

  \item[\normalfont\ameta{theme}] This variable appears as the argument of \cs{thQzName}.

  \item[\normalfont\ameta{instrName}]  This variable appears in several
      \uif{Powershell} script files: \app{copyka.ps1}, \app{moveka.ps1},
      \app{delka.ps1}, \app{csvTOcfg.ps1}, and \app{classFolders.ps1}. In
      the TEX template file, it appears as the argument of \cs{author}.
      Within \texttt{00-\ameta{class}.cfg}, \ameta{instrName} appears as an
      argument of \cs{instrPath}.

  \item[\normalfont\ameta{date}] This variable is an argument of
      \cs{copyrightyears} in the TEX template file.

  \item[\normalfont\ameta{time}] This variable appears in the argument of \cs{keywords}

  \item[\normalfont\ameta{classPath}] This variable is used in various
      places: \app{copyka.ps1}, \app{moveka.ps1},
      \app{delka.ps1}, and \app{classFolders.ps1}. It also
      appears as the argument of \cs{classPath} within
      \texttt{00-\ameta{class}.cfg}.

\end{description}

\section{Procedures after running \texttt{thmclass.ps1}}

After the folders and files of
\hyperref[fig:struct]{Figure~\ref*{fig:struct}} are created, go
into the \ameta{class} folder, you will see \ameta{instrName} (a
folder) and the two files \texttt{00-\ameta{class}.cfg} and
\texttt{tex-template.tex}. Now, change directories by moving
into the \ameta{instrName} folder. Now perform the following
tasks.
\begin{enumerate}
  \item \textbf{Edit \texttt{sample-list.csv}.}\label{item:Editlist} Change the
      name, if desired, of the file \texttt{sample-list.csv}
      and open the renamed file in your text editor. For the
      purpose of this documentation, we shall refer to the
      renamed file \texttt{sample-list.csv} as
      \texttt{\ameta{list}.csv}. The format of each line is
      exemplified by the three sample lines provided. More
      symbolically, each line consists of a comma (or
      semi-colon) delimited list:
\begin{quote}
  \ameta{first},\ameta{last},\ameta{rel-path} or\\
  \ameta{first};\ameta{last};\ameta{rel-path}
\end{quote}
One or more lines in this file may have an alternate syntax:
\begin{quote}
  \ameta{first},\ameta{last},*\ameta{full-path}
\end{quote}
where the first character of the third entry is an \texttt*,
the rest of the entry is a full-path to the student's
folder.\footnote{This is done when the student's does not lie
in the path pointed to by the argument of \cs{classPath}.}

To continue, enter the first and last names of each student in
the class, followed by the relative path (relative to \cs{classPath})
to that student's folder. The sample file reads,
\begin{equation}
\begin{minipage}{.5\linewidth}
\begin{Verbatim}[commandchars=!()]
M!"(u)hle;W!"(a)ter;MW634B
Anton,M!"(u)ller,AM256M
Laura,V!"(o)gt,LM356B
\end{Verbatim}
\end{minipage}\label{disp:list}
\end{equation}
These sample entries are to be deleted and replaced by the
names and folders of the class members. If there are any
student exception---one whose student folder is outside
\cs{classPath}---, then a typical entry is has the following
form,
\begin{equation*}
\begin{minipage}{.5\linewidth}
\begin{Verbatim}[commandchars=!()]
Laura,V!"(o)gt,*C:/Users/dpstory/Desktop/TestFolder/myOtherClass/LM356B
\end{Verbatim}
\end{minipage}
\end{equation*}
For the last entry, the third element begins with an \texttt*, which signals that
what follows is full path to this student's folder.

  \item \textbf{Run \texttt{csvTOcfg.ps1}:} Now, execute
      \texttt{csvTocfg.ps1} using the general purpose batch
      file \texttt{run1.bat} with a command line arguments of
      \texttt{csvTocfg} and \ameta{list} (a CSV file); for example,
      on the \app{Command Prompt}, type,
\begin{equation}
    \fbox{\ttfamily runps1 csvTocfg \ameta{list}}\label{dis:csvTocfg}
\end{equation}

%  \item \textbf{Run \texttt{csvTOcfg}.} Now, run the batch
%      file \texttt{csvTOcfg.bat} with a command line argument
%      of the CVS file; for example, on the \app{Command
%      Prompt}, type.
%\begin{quote}\ttfamily
%    csvTocfg sample-list
%\end{quote}
and execute by pressing the \uif{Enter} key. \emph{Do not
include the extension in the command line argument}. This will
append the student information to the end of the
\texttt{00-\ameta{class}.cfg} one level up. Each student has
an entry in \texttt{00-\ameta{class}.cfg} of
\cs{classMember\darg{\ameta{first}}\relax
\darg{\ameta{last}}\darg{\ameta{folder-name}}}.
\texttt{csvTocfg} also replaces all German umlauts with
non-problematic characters like so: \"{u} \texttt{->} ue,
\"{o} \texttt{->} oe, etc.

  \item \textbf{Run \texttt{classFolders.ps1}:} The next step,
      if needed, creates the personal student
      folders.\footnote{The sysadmin may not allow creation of
      folders on the system system drive; this script may be
      used for testing on the instructor's own drive.} This
      step may not be needed if the folders already exist. Run
      the \texttt{runps1.bat} with a command line arguments of
      \texttt{classFolders} and the CVS file; for example, on
      the \app{Command Prompt}, type,
\begin{equation}
    \fbox{\ttfamily runps1 classFolders \ameta{list}}\label{dis:classFolders}
\end{equation}
and execute by pressing the \uif{Enter} key. \emph{Do not
include the extension in the command line argument}.  If the
folders already exist, the script does not destroy them and
create them again. No harm done, I hope.
\item \textbf{Run \texttt{genquiz.ps1}:} (Optional) If you
    want to use the \texttt{tex-template.tex} file to create a
    TEX file for your quiz, run \texttt{genquiz.ps1} with
    the following \uif{Command prompt}:
\begin{equation}
    \fbox{\ttfamily runps1 genquiz}\label{dis:genquiz}
\end{equation}
Executing this line produces a TEX template file named
`\texttt{\ameta{number}-\ameta{class}-\ameta{subject}.tex}'. The file
\texttt{genquiz.ps1}, when executed, reads the
\texttt{\ameta{varlist}.txt}, located one directory up, to get the current
values of \ameta{number}, \ameta{class}, and \ameta{subject}.

\end{enumerate}

\paragraph*{Preliminaries are done! Have fun!} You are ready to
compose your quiz/exam! Open the TEX template file and modify
its contents to suite your needs, removing easy questions and
adding difficult ones, or copy one of the demo files from the
\texttt{examples} folder and modify it. For this part of the
process you must be knowledgable of \pkg{exerquiz} and the
documentation of the \pkg{thorshammer} package. The sample files
of \pkg{thorshammer} will help to compose the quiz using the
approach you want.


\paragraph*{Repeat.} There is no need to run `\texttt{runps1 thmclass \ameta{varlist}.txt}'
more than once a semester. As you work through the semester, you can copy an
old quiz with a new file with a new name and modify for the new material
studied or run \texttt{genquiz.ps1} to obtain a new clean template file:
\[
    \fbox{\ttfamily runps1 genquiz}
\]
The file \texttt{genquiz.ps1} reads the
\texttt{\ameta{varlist}.txt} one level up; you might want to
first edit this file and change the value of \ameta{number}.

The contents of \texttt{00-\ameta{class}.cfg} remains unchanged; if students
drop out of the course simply delete that student's line from
\texttt{00-\ameta{class}.cfg} or if students add the course simply append a
line to \texttt{00-\ameta{class}.cfg} using the template
\cs{classMember\darg{\ameta{first}}\relax
\darg{\ameta{last}}\darg{\ameta{folder-name}}}. Read the discussion on how to
handle \nameref{para:exceptions} to these general rules.

\section{Deploying the quizzes}

The quizzes may be deployed to the student folders in two ways:
\begin{enumerate}
    \item When a quiz is compiled with the \opt{usebatch} option, the
        \cs{sadQuizzes} command executes JavaScript lines when first opened
        in \app{Acrobat}, which builds and distributes the quizzes to the
        designated instructor folder and deploys individualized quizzes to
        the correct student folder.
    \item When the \opt{batchdistr} option is specified,
        \cs{sadQuizzes} does its thing, but does not send the
        quizzes to the individualized student folders. To
        deploy them, either use the action sequence
        \textsf{Thor protects and distributes} or just
        \textsf{Thor distributes}. The end result of these two
        is to deploy the quizzes to their designated student
        folders.
\end{enumerate}

\section{Retrieving the quizzes}

After the exam period is over the quizzes need to be retrieved
from the student folders and placed in a folder where the
instructor can grade them. The mechanics of doing this are
explained next:
\begin{itemize}
  \item \texttt{copyka.ps1} copies the quizzes from their respective student folders
    in the class folder declared by the \cs{classPath} command to the folder designated
    by the \cs{instrPath}. These two declarations can be found in \texttt{00-\ameta{class}.cfg}.
  \item \texttt{delka.ps1} delete the quizzes from their
      respective student folders in the class folder declared
      by the \cs{classPath} command.
      \textcolor{red}{\textbf{Important:}} Do not run this
      script until you've first run \texttt{copyka.ps1}
      \emph{and} you've \emph{verified} all files have indeed been
      transferred.
  \item \texttt{moveka.ps1} copies and then deletes the
      quizzes. \textbf{Not recommended}, use a \texttt{copyka.ps1} $\rightarrow$ verify
      $\rightarrow$ \texttt{delka.ps1} workflow.
\end{itemize}
\paragraph*{\color{red}Danger Will Robinson!} These scripts dig
down deep into the folder structure (pointed to by \cs{classPath}
or any exception paths (refer to \nameref{para:exceptions}) looking for PDFs in the student's folder, in
the subfolder named \ameta{instr}. If there are more than one
PDF in this folder, the scripts will copy, delete, and move all
PDFs found in the \ameta{instr} subfolder.

\paragraph*{Running these scripts:}  In the \uif{Command Prompt} and with the cursor in the same folder
as the scripts you are to execute, type,
\begin{align*}
    &\fbox{\ttfamily runps1 copyka}\\[1ex]
    &\fbox{\ttfamily runps1 delka}\\[1ex]
    &\fbox{\ttfamily runps1 moveka}
\end{align*}
\paragraph*{Exceptions:}\chnglabelname{Exceptions}\label{para:exceptions} In an ideal semester, each of the students
takes the class for the first time and no additional information
is needed by the above three scripts; however, for students who
are taking the class again, their class folder may not be
located on the \cs{classPath}. The three scripts make a
provision for this. The above PS1 files look for a file named
\texttt{altclasspaths.txt} in the current directory. The
contents of this file is a list of \emph{alternate class paths}. For example, suppose
we declare
\begin{quote}
\verb|\classPath{/C/Users/dpstory/Desktop/myClass}|
\end{quote}
but there are students whose class folder is located on the path
\begin{quote}
\verb|/C/Users/dpstory/Desktop/TestFolder/myOtherClass|
\end{quote}
To service these `exceptional' students, create a file named
\texttt{altclasspaths.txt} and add the following line to that TXT file
\begin{quote}
\verb|/C/Users/dpstory/Desktop/TestFolder/myOtherClass|
\end{quote}
BTW, on \app{Windows}, you can use standard \app{Windows} notation (with forward slashes) as well:
\begin{quote}
\verb|C:/Users/dpstory/Desktop/TestFolder/myOtherClass|
\end{quote}
When any of the above three scripts is run, it will first perform its task for the main
\cs{classPath}, then it will perform the same task for the paths listed in
\texttt{altclasspaths.txt}.

\section{Redeploying the quizzes}

After the quizzes are marked and saved in a folder of the instructor's
choice, you can (optionally) return the graded quizzes to the students. To do
this, use the  \textsf{Thor distributes} action sequence.

\section{How to execute a PS1 file without a BAT file} There are two methods.
\begin{description}
    \item [\normalfont Using the \texttt{\app{Powershell} App}:] From
        \uif{File Explorer}, open a window and navigate to the
        folder containing the PS1 file. Now select \uif{File}
        \texttt{>} \uif{Open Windows Powershell} (or perhaps
        the administrator version). In the \app{Powershell} command prompt, type
\begin{quote}\ttfamily
Powershell -ExecutionPolicy Bypass -Command .\cs{\ameta{basename}.ps1}
\end{quote}
The \texttt{-ExecutionPolicy Bypass} allows the script to run
without security warnings.

To run a PS1 file with argument,
\begin{quote}\ttfamily
Powershell -ExecutionPolicy Bypass -Command .\cs{thmclass.ps1} myVars.txt
\end{quote}

\item [\normalfont Using the \texttt{\app{Powershell} ISE App}:] This
    application has a built-in editor. Start \app{Powershell}
    ISE. Here you can load in your PS1 file by simply dragging
    and dropping it into the window. Be sure the command
    prompt is showing the folder where the script file is
    located. Change directories using the \uif{cd} command, as
    needed. For a PS1 file that does not  have an argument,
    simple press on the \uif{Run Script} icon on the toolbar,
    or choose the \uif{Run} menu item from the \uif{File}
    menu.

    To run a PS1 file with argument, type, for example,
\begin{quote}\ttfamily
Powershell -ExecutionPolicy Bypass -Command .\cs{thmclass.ps1} myVars.txt
\end{quote}
into the command prompt window and press the \uif{Enter} key to execute that line.
\end{description}

\part{Using a standalone system}\label{PartII}

\noindent
Using the Thor system of class structure (see \hyperref[fig:struct]{Figure~\ref*{fig:struct}}) may not be for
everyone. For this reason, some standalone scripts are provided
in the \texttt{standalone} folder of the \texttt{system-scripts}
folder.

\newtopic\noindent
\textbf{Important:} The contents of the \texttt{standalone} folder should be
copied to your working folder, the one that contains the source files for
your quizzes you are developing.

\newtopic\noindent
Within the \texttt{system-scripts/standalone} folder, the following files are provided:\medskip
\begin{description}
\item[\normalfont\texttt{cpquizzes.ps1}] A renamed and modified version of \texttt{copyka.ps1}. To use this script,
first open it in your editor and modify the following lines:
\end{description}
\begin{quote}\ttfamily
\$baseName="\ameta{baseName}"\\
\$classPath="\ameta{classPath}"\\
\$destPath="\ameta{destPath}"
\end{quote}
\begin{itemize}
\item[]
The value of \texttt{\$baseName} is usually one word that
represents the instructor (eg, THOR), but it does not have to be
the instructor's name. \texttt{\$classPath} is the path to the
class folders. The script searches \texttt{\$classPath} and
copies all PDFs within \emph{any} subfolder with
\texttt{\$baseName} as its name. It copies the PDFs to
\texttt{\$destPath}. The quizzes all must be uniquely named
because they are all copied to the same destination folder
(\texttt{\$destPath}). Any older PDFs (perhaps from earlier
quizzes, or actually any latent PDFs) are also copied, so you
must set up your protocols appropriately. Execute this script
from the \uif{Command Prompt}:
\begin{flushleft}
    \fbox{\ttfamily runps1 cpquizzes}
\end{flushleft}
\end{itemize}
\begin{description}
\item[\normalfont\texttt{rmquizzes.ps1}] After you've run \texttt{cpquizzes.ps1} and verified that all required
files have been copied, you can safely delete (or remove) the quizzes from the student quiz folders.
Open \texttt{rmquizzes.ps1} in your editor, and modify the values of this variables:
\end{description}
\begin{quote}\ttfamily
\$baseName="\ameta{baseName}"\\
\$classPath="\ameta{classPath}"
\end{quote}
\begin{itemize}
\item[] The meanings of the variables \texttt{\$baseName} and \texttt{\$classPath} are the same as above in the
description of \texttt{cpquizzes.ps1}. Run the script as follows:
\begin{flushleft}
    \fbox{\ttfamily runps1 rmquizzes}
\end{flushleft}
\item[] These first two scripts are basic and the class can be conducted using only \texttt{cpquizzes.ps1}
and \texttt{rmquizzes.ps1}. The next two scripts can be considered optional.
\end{itemize}
\begin{description}
\item[\normalfont\texttt{mkcfg.ps1}] This is a modified and renamed
    version of \texttt{csvTOcfg.ps1}, refer to the description of \texttt{csvTOcfg.ps1}. Prior to using this
    script, delete the file \texttt{00-web.cfg} in the current
    folder (this file is created by \texttt{mkcfg.ps1}). Open
    your editor and modify the values of the following
    variables:
\end{description}
\begin{quote}\ttfamily
\$classPath="\ameta{classPath}"\\
\$instrPath="\ameta{instrPath}"
\end{quote}
\begin{itemize}
\item[] The values of these variables correspond to \cs{classPath} and
\cs{instrPath}, respectively. The script is executed from the
\uif{Command Prompt} as follows:
\begin{equation*}
    \fbox{\ttfamily runps1 mkcfg \ameta{list}}
\end{equation*}
\item[] where the argument \ameta{list} is a list of class members and
    folder locations data, as described in `Edit \texttt{sample-list.csv}'
    on page~\pageref{item:Editlist}.

The purpose of this script is to create the \texttt{00-web.cfg}
file. Once created, move this file to the same file as your
quizzes; input this file using \cs{InputClassData\darg{00-web}}. Examples of the use
of \cs{InputClassData} are found in the \texttt{examples/cfgs} folder.
As described earlier, the format of this file is,
\begin{Verbatim}[commandchars=!()]
\classPath{!ameta(classPath)}
\instrPath{!ameta(instrPath)}
\classMember{Muehle}{Waeter}{MW634B/_Thor}
\classMember{Anton}{Mueller}{AM256M/_Thor}
\classMember{Laura}{Voegt}{LM356B/_Thor}
\end{Verbatim}
\item[] Here, the sample class members of \texttt{sample-list.csv} are
shown. For the \cs{classPath} and \cs{instrPath}, \emph{use only full
paths}. Refer to `\textbf{Edit \texttt{sample-list.csv}}' on
page~\pageref{item:Editlist} for more information.
\end{itemize}
\begin{description}
\item[\normalfont\texttt{mkfolders.ps1}] This is a modified and renamed
    version of \texttt{classFolders.ps1}. This script is used for testing
    purposes; it can also be used to set up class folders provided you have
    the necessary permissions. Run this script from the \uif{Command prompt}:
\end{description}
\begin{itemize}
\item[] Open the file and edit the variable
\begin{quote}\ttfamily
\$classPath="\ameta{classPath}"
\end{quote}
where \ameta{classPath} is the full path to the root of the class folders. Run this script
from the \uif{Command prompt}:
\begin{equation*}
    \fbox{\ttfamily runps1 mkfolders \ameta{list}}
\end{equation*}
where the argument \ameta{list} is a list of class members and
    folder locations data, as described in `Edit \texttt{sample-list.csv}'
    on page~\pageref{item:Editlist}.
\end{itemize}
%\end{description}

\part{My retirement}

Now, I simply must get back to it. \dps

\end{document}
