From 05d9e348e9ce7fb895782424da35d989a0396a44 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 3 Aug 2020 12:15:38 +0900 Subject: thorshammer (new) --- texmf-dist/doc/latex/thorshammer/thmclass.tex | 970 ++++++++++++++++++++++++++ 1 file changed, 970 insertions(+) create mode 100644 texmf-dist/doc/latex/thorshammer/thmclass.tex (limited to 'texmf-dist/doc/latex/thorshammer/thmclass.tex') diff --git a/texmf-dist/doc/latex/thorshammer/thmclass.tex b/texmf-dist/doc/latex/thorshammer/thmclass.tex new file mode 100644 index 00000000..1603ce6c --- /dev/null +++ b/texmf-dist/doc/latex/thorshammer/thmclass.tex @@ -0,0 +1,970 @@ +\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} -- cgit v1.2.3