path: root/Master/texmf-dist/source/latex/stex/assignment/assignment.dtx

% \iffalse meta-comment
% An Infrastructure for marking up Assignments
% $URL: https://svn.kwarc.info/repos/stex-content/sty/assignment/assignment.dtx $ 
% $Rev: 2871 $; last modified by $Author: kohlhase $ 
% $Date: 2010-05-29 07:43:20 +0200 (Sat, 29 May 2010) $
% Copyright (c) 2007 Michael Kohlhase, all rights reserved
%               this file is released under the
%               LaTeX Project Public License (LPPL)
% \fi
% 
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{assignment}[2010/06/25 v0.9a assignment documents]
%
%<*driver>
\documentclass{ltxdoc}
\usepackage{url,array,float}
\usepackage[show]{ed}
\usepackage{hyperref}
\usepackage{assignment}
\makeindex
\floatstyle{boxed}
\newfloat{exfig}{thp}{lop}
\floatname{exfig}{Example}
\begin{document}\DocInput{assignment.dtx}\end{document}
%</driver>
% \fi
%\CheckSum{323}
% 
% \changes{v0.9}{2006/09/18}{First Version with Documentation}
% 
% \GetFileInfo{assignment.sty}
% 
% \MakeShortVerb{\|}
%\def\scsys#1{{{\sc #1}}\index{#1@{\sc #1}}}
% \def\latexml{\scsys{LaTeXML}}
%
% \title{An Infrastructure for formatting Assignments\thanks{Version {\fileversion} (last revised
%        {\filedate})}}
%    \author{Michael Kohlhase\\
%            Jacobs University, Bremen\\
%            \url{http://kwarc.info/kohlhase}}
% \maketitle
%
% \begin{abstract}
%   The |assignment| packge allows individual course assignment sheets and compond
%   assignment documents using problem files marked up with the |problem| package. 
% \end{abstract}
% \setcounter{tocdepth}{2}\tableofcontents\newpage
%
%\section{Introduction}\label{sec:intro}
%
% The |assignment| package supplies an infrastructure that allows to format nice-looking
% assignment sheets by simply including problems from problem files marked up with the
% |problem| package.  It is designed to be compatible with |problems.sty|, and inherits
% some of the functionality.
% 
% \section{The User Interface}
% 
% \subsection{Assignments}
% \DescribeEnv{assignment} This package supplies the |assignment| environment that groups
% problems into assignment sheets. It takes an optional KeyVal argument with the keys
% \DescribeMacro{number}|number| (for the assignment number; if none is given, 1 is
% assumed as the default or --- in multi-assignment documents --- the ordinal of the
% |assignment| environment), \DescribeMacro{title}|title| (for the assignment title; this
% is referenced in the title of the assignment sheet), \DescribeMacro{type}|type| (for the
% assignment type; e.g. ``quiz'', or ``homework''), \DescribeMacro{given}|given| (for the
% date the assignment was given), and \DescribeMacro{due}|due| (for the date the
% assignment is due).
% 
% \DescribeMacro{\CourseTitle} |\Coursetitle{|\meta{title}|}| can be used to specify the
% title of the course. It is usually specified in the driver file.
% 
% \DescribeMacro{\AssignmentType} Similarly, |\AssignmentType{|\meta{type}|}| can be used
% to specify the default assignment type.
% 
% The |assignment| package takes the options \DescribeMacro{solutions}|solutions|,
% \DescribeMacro{notes}|notes|, \DescribeMacro{hints}|hints|, \DescribeMacro{pts}|pts|,
% \DescribeMacro{min}|min|, and \DescribeMacro{boxed}|boxed| that are just passed on to
% the |problems| package (cf. its documentation for a description of the intended
% behavior).
% 
% \subsection{Typesetting Exams}
%
% Furthermore, the |assignment| package takes the option
% \DescribeMacro{multiple}|multiple| that allows to combine multiple assigment sheets into
% a compound document (the assignment sheets are treated as section, there is a table of
% contents, etc.). 
% 
% Finally, there is the option \DescribeMacro{test}|test| that modifies the behavior to
% facilitate formatting tests. Only in |test| mode, the macros |\testspace|,
% |\testnewpage|, and |\testemptypage| have an effect: they generate space for the
% students to solve the given problems. Thus they can be left in the {\LaTeX} source. 
%
% \DescribeMacro{\testspace}|\testspace| takes an argument that expands to a dimension,
% and leaves vertical space accordingly. \DescribeMacro{\testnewpage}|\testnewpage| makes
% a new page in |test| mode, and \DescribeMacro{\testemptypage}|\testemptypage| generates
% an empty page with the cautionary message that this page was intentionally left empty.
%
% Finally, the \DescribeMacro{\testheading}|\testheading| takes a keyword argument where
% the keys |duation| specifies a string that specifies the duration of the test, |min|
% specifies the equivalent in number of minutes, and |reqpts| the points that are required
% for a perfect grade.
% \begin{exfig}[ht]
% \makeatletter
% \@problem{1.1}{4}{10}
% \@problem{2.1}{4}{8}
% \@problem{2.2}{6}{10}
% \@problem{2.3}{6}{10}
% \@problem{3.1}{4}{8}
% \@problem{3.2}{4}{8}
% \@problem{3.3}{2}{4}
% \makeatother
% \begin{verbatim}
%   \testheading{duration=one hour,min=60,reqpts=27}
% \end{verbatim}
% \vspace*{-3ex}\hrule\vspace*{.5ex}  formats to\vspace*{1ex} \hrule\par\noindent\vspace*{2ex}
%   \testheading{duration=one hour,min=60,reqpts=27}
%   \caption{A generated test heading.}\label{fig:testheading}
% \end{exfig}
% 
% \subsection{Including Assignments}
%
% The \DescribeMacro{\includeassignment}|\includeassignment| macro can be used to include
% an assignment from another file. It takes an optional KeyVal argument and a second
% argument which is a path to the file containing the problem (the macro assumes that
% there is only one |assignment| environment in the included file).  The keys
% \DescribeMacro{number}|number|, \DescribeMacro{title}|title|,
% \DescribeMacro{type}|type|,\DescribeMacro{given}|given|, and \DescribeMacro{due}|due|
% are just as for the |assignment| environment and (if given) overwrite the ones specified
% in the |assignment| environment in the included file.
% 
% \StopEventually{\newpage\PrintChanges}
% \newpage
%
% \section{The Implementation} 
%
% \subsection{Package Options}
%
% The first step is to declare (a few) package options that handle whether certain
% information is printed or not. Some come with their own conditionals that are set by the
% options, the rest is just passed on to the |problems| package.
%
%    \begin{macrocode}
%<*package>
\newif\iftest\testfalse
\newif\ifsolutions\solutionsfalse
\DeclareOption{test}{\testtrue\solutionsfalse}
\newif\ifmultiple\multiplefalse
\DeclareOption{multiple}{\multipletrue}
\DeclareOption*{\PassOptionsToPackage{\CurrentOption}{problem}}
\ProcessOptions
%</package>
%    \end{macrocode}
% Then we make sure that the necessary packages are loaded (in the right versions).
%    \begin{macrocode}
%<*package>
\RequirePackage{keyval}[1997/11/10]
\RequirePackage{problem}
%</package>
%    \end{macrocode}
%
% Here comes the equivalent header information for {\latexml}, we also initialize the
% package inclusions. Since {\latexml} does not handle options yet, we have nothing to
% do. 
%    \begin{macrocode}
%<*ltxml>
# -*- CPERL -*-
package LaTeXML::Package::Pool;
use strict;
use LaTeXML::Package;
RequirePackage('problem');
%</ltxml>
%    \end{macrocode}
%
% Then we register the namespace of the requirements ontology
%    \begin{macrocode}
%<*ltxml>
RegisterNamespace('assig'=>"http://omdoc.org/ontology/assignments#");
RegisterDocumentNamespace('assig'=>"http://omdoc.org/ontology/assignments#");
%</ltxml>
%    \end{macrocode}
%
% \subsection{Assignments}
%
% We will prepare the keyval support for the |assignment| environment.
%
%    \begin{macrocode}
%<*package>
\omdaddkey{assig}{number}
\omdaddkey{assig}{title}
\omdaddkey{assig}{type}
\omdaddkey{assig}{given}
\omdaddkey{assig}{due}
%</package>
%    \end{macrocode}
%
% The next macro just sets the internal token register to the intended string.
% 
%    \begin{macrocode}
%<*package>
\def\AssignmentType#1{\gdef\assig@default@type{#1}}
\def\assig@default@type{Assignment}
%</package>
%<*ltxml>
%</ltxml>
%    \end{macrocode}
%
% The next three macros are intermediate functions that handle the case gracefully, where
% the respective token registers are undefined.
% 
%    \begin{macrocode}
%<*package>
\def\Assig@Type{\ifx\assig@type\@empty\assig@default@type\else\assig@type\fi}
\def\Assig@Title{\ifx\assig@title\@empty\else\assig@title~\fi}
%    \end{macrocode}
% 
% The |\given@due| macro prints information about the given and due status of the
% assignment. Its arguments specify the brackets. 
% 
%    \begin{macrocode}
\def\given@due#1#2{%
\ifx\assig@given\@empty\else\ifx\assig@due\@empty\else{#1}\fi\fi%
\ifx\assig@given\@empty\else{Given {\assig@given}}\fi%
\ifx\assig@given\@empty\else\ifx\assig@due\@empty\else{, }\fi\fi%
\ifx\assig@due\@empty\else{Due {\assig@due}}\fi%
\ifx\assig@given\@empty\else{\ifx\assig@due\@empty\else{#2}\fi}\fi}
%</package>
%    \end{macrocode}
% 
% With them, we can define the central |assignment| environment. This has two forms
% (separated by |\ifmultiple|) in one we make a title block for an assignment sheet, and
% in the other we make a section heading and add it to the table of
% contents.
% 
% \begin{environment}{assignment}
%    \begin{macrocode}
%<*package>
\newenvironment{assignment}[1][]% keyval args
{\omdsetkeys{assig}{#1}% collect the keys and correct them from the outside
\@ifundefined{incl@assig@title}{}{\def\assig@title{\incl@assig@title}}
\@ifundefined{incl@assig@type}{}{\def\assig@type{\incl@assig@type}}
\@ifundefined{incl@assig@num}{}{\def\assig@num{\incl@assig@num}}
\@ifundefined{incl@assig@due}{}{\def\assig@due{\incl@assig@due}}
\@ifundefined{incl@assig@given}{}{\def\assig@given{\incl@assig@given}}
\@ifundefined{assig@num}{\stepcounter{section}}%
{\setcounter{section}{\assig@num}\setcounter{problem}{0}}
\ifmultiple%
\section*{\Assig@Type~\arabic{section}:~\Assig@Title\given@due{\\(})}
  \addcontentsline{toc}{section}{\Assig@Type~{\arabic{section}}:~\Assig@Title}
\else
\begin{center}
\Large\Course@Title\\
{\bf{\Assig@Type}~{\arabic{section}}:~\Assig@Title\strut\\\large{\given@due()}}
\end{center}
\fi%ifmultiple
}{}
%</package>
%    \end{macrocode}
% 
%    \begin{macrocode}
%<*ltxml>
DefEnvironment('{assignment} OptionalKeyVals:assig',
  "<omdoc:omgroup ?&KeyVal(#1,'id')(xml:id='&KeyVal(#1,'id')')() "
  .  "assig:dummy='for the namespace'"
  . "?#locator(stex:srcref='#locator')()>"
  .  "<omdoc:metadata ?#locator(stex:srcref='#locator')()>"
  .    "<dc:title ?#locator(stex:srcref='#locator')()>"
  .       "Assignment ?&KeyVal(#1,'num')(&KeyVal(#1,'num').)()"
  .       "?&KeyVal(#1,'title')((&KeyVal(#1,'title')))"
  .    "</dc:title>"
  .    "?&KeyVal(#1,'given')(<omdoc:meta property='assig:given'>&KeyVal(#1,'given')</omdoc:meta>)()"
  .    "?&KeyVal(#1,'due')(<omdoc:meta property='assig:due'>&KeyVal(#1,'due')</omdoc:meta>)()"
  .    "?&KeyVal(#1,'pts')(<omdoc:meta property='assig:pts'>&KeyVal(#1,'pts')</omdoc:meta>)()"
  .  "</omdoc:metadata>"
  .  "#body"
  ."</omdoc:omgroup>\n");
%</ltxml>
%    \end{macrocode}
% \end{environment}
% 
% \subsection{Including Assignments}
%
% The next command is essentially a glorified |\include| statement, it just sets some
% internal macros first that overwrite the local points, 
% 
%    \begin{macrocode}
%<*package>
\define@key{incl@assig}{number}{\def\incl@assig@num{#1}}
\define@key{incl@assig}{title}{\def\incl@assig@title{#1}}
\define@key{incl@assig}{type}{\def\incl@assig@type{#1}}
\define@key{incl@assig}{given}{\def\incl@assig@given{#1}}
\define@key{incl@assig}{due}{\def\incl@assig@due{#1}}
\newcommand{\includeassignment}[2][]{\bgroup\setkeys{incl@assig}{#1}\include{#2}\egroup}
%</package>
%<*ltxml>
DefMacro('\includeassignment [] {}','\input{#2}');
%</ltxml>
%    \end{macrocode}
%
%    \begin{macrocode}
%<*package>
\def\CourseTitle#1{\gdef\Course@Title{#1}}
%</package>
%<*ltxml>
DefConstructor('\CourseTitle{}','');
%</ltxml>
%    \end{macrocode}
%
% \subsection{Typesetting Exams}
%
%    \begin{macrocode}
%<*package>
\omdaddkey{testheading}{min}
\omdaddkey{testheading}{duration}
\omdaddkey{testheading}{reqpts}
\def\testheading#1{\omdsetkeys{testheading}{#1}
{\noindent\large NAME: \\[1ex] MATRICULATION NUMBER:\\[2ex]
 {\textbf{You have 
\ifx\test@heading@duration\@empty\testheading@min minutes\else\testheading@duration\fi 
(sharp) for the test}};\\ Write the solutions to the sheet.}\par\noindent

\newcount\check@time\check@time=\testheading@min
\advance\check@time by -\theassignment@totalmin
The scheduled time for solving this exam is {\theassignment@totalmin} minutes, 
leaving you {\the\check@time} minutes for revising your exam. 

\newcount\bonus@pts\bonus@pts=\theassignment@totalpts
\advance\bonus@pts by -\testheading@reqpts
You can reach {\theassignment@totalpts} points if you solve all problems. You will only need
{\testheading@reqpts} points for a perfect score, i.e.\ {\the\bonus@pts} points are
bonus points. \vfill
\begin{center}
  {\Large\em
%  You have ample time, so take it slow and avoid rushing to mistakes!\\[2ex]
  Different problems test different skills and knowledge, so do not get stuck on
  one problem.}\vfill\par\correction@table
\end{center}\newpage}
%</package>
%<*ltxml>
DefConstructor('\testheading{}','');
%</ltxml>
%    \end{macrocode}
%
%    \begin{macrocode}
%<*package>
\def\testspace#1{\iftest\vspace*{#1}\fi}
\def\testnewpage{\iftest\newpage\fi}
\def\testemptypage{\iftest\begin{center}This page was intentionally left
    blank for extra space\end{center}\vfill\eject\else\fi}
%</package>
%<*ltxml>
DefConstructor('\testspace{}','');
DefConstructor('\testnewpage','');
DefConstructor('\testemptypage','');
%</ltxml>
%    \end{macrocode}
%
% \begin{macro}{\@problem}
%   This macro acts on a problem's record in the |*.aux| file. Here we redefine it to
%   generate the correction table. 
%    \begin{macrocode}
%<*package>
\def\@problem#1#2#3{\stepcounter{assignment@probs}
\def\@test{#2}\ifx\@test\@empty\else\addtocounter{assignment@totalpts}{#2}\fi
\def\@test{#3}\ifx\@test\@empty\else\addtocounter{assignment@totalmin}{#3}\fi
\xdef\correction@probs{\correction@probs & #1}%
\xdef\correction@pts{\correction@pts & #2}
\xdef\correction@reached{\correction@reached &}}
%</package>
%    \end{macrocode}
% \end{macro}
% 
% \begin{macro}{\correction@table}
%   This macro generates the correction table
%    \begin{macrocode}
%<*package>
\newcounter{assignment@probs}
\newcounter{assignment@totalpts}
\newcounter{assignment@totalmin}
\def\correction@probs{prob.}%
\def\correction@pts{total}%
\def\correction@reached{reached}%
\stepcounter{assignment@probs}
\def\correction@table{\begin{tabular}{|l|*{\theassignment@probs}{c|}|p{3cm}|}\hline%
&\multicolumn{\theassignment@probs}{c||}%
{\footnotesize To be used for grading, do not write here} &\\\hline
\correction@probs & Sum & grade\\\hline
\correction@pts &\theassignment@totalpts & \strut\hspace{3cm}\strut\\\hline
\correction@reached & & \\[.7cm]\hline
\end{tabular}}
%</package>
%    \end{macrocode}
% \end{macro}
% 
% \subsection{Leftovers}
%
% at some point, we may want to reactivate the logos font, then we use
% \begin{verbatim}
% here we define the logos that characterize the assignment
% \font\bierfont=../assignments/bierglas
% \font\denkerfont=../assignments/denker
% \font\uhrfont=../assignments/uhr
% \font\warnschildfont=../assignments/achtung
%
% \def\bierglas{{\bierfont\char65}}
% \def\denker{{\denkerfont\char65}}
% \def\uhr{{\uhrfont\char65}}
% \def\warnschild{{\warnschildfont\char 65}}
% \def\hardA{\warnschild}
% \def\longA{\uhr}
% \def\thinkA{\denker}
% \def\discussA{\bierglas}
% \end{verbatim}
%
% Finally, we need to terminate the file with a success mark for perl.
%    \begin{macrocode}
%<ltxml>1;
%    \end{macrocode}
% \Finale
\endinput
% \iffalse
% LocalWords:  GPL structuresharing STR
%%% Local Variables: 
%%% mode: doctex
%%% TeX-master: t
%%% End: 
% \fi