summaryrefslogtreecommitdiff
path: root/texmf-dist/doc/latex/thorshammer/thmclass.tex
blob: 1603ce6c937cf98d5520584be30593a607cf27c9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
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}