new package mathexam

git-svn-id: svn://tug.org/texlive/trunk@4759 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 453 insertions, 0 deletions

diff --git a/Master/texmf-dist/source/latex/mathexam/mathexam.dtx b/Master/texmf-dist/source/latex/mathexam/mathexam.dtx
new file mode 100644
index 00000000000..2a70cb88697
--- /dev/null
+++ b/Master/texmf-dist/source/latex/mathexam/mathexam.dtx
@@ -0,0 +1,453 @@
+% \def\EmailAddress{jhlavace@svsu.edu}
+% \iffalse meta-comment
+% 
+% Program mathexam  
+% Copyright (C) 2007 Jan Hlavacek
+%
+% This program may be distributed and/or modified under the
+% conditions of the LaTeX Project Public License, either version 1.2
+% of this license or (at your option) any later version.
+% The latest version of this license is in
+%    http://www.latex-project.org/lppl.txt
+% and version 1.2 or later is part of all distributions of LaTeX 
+% version 1999/12/01 or later.
+%
+% The Program's files are mathexam.dtx, mathexam.ins and mathexam.sty.
+%
+% Run latex with the input file mathexam.ins to generate the mathexam.sty 
+% package file. Run latex with the input file mathexam.dtx to generate the 
+% package documentation.
+%
+% \fi
+%
+% \CheckSum{179}
+%
+% \CharacterTable
+%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
+%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
+%   Digits        \0\1\2\3\4\5\6\7\8\9
+%   Exclamation   \!     Double quote  \"     Hash (number) \#
+%   Dollar        \$     Percent       \%     Ampersand     \&
+%   Acute accent  \'     Left paren    \(     Right paren   \)
+%   Asterisk      \*     Plus          \+     Comma         \,
+%   Minus         \-     Point         \.     Solidus       \/
+%   Colon         \:     Semicolon     \;     Less than     \<
+%   Equals        \=     Greater than  \>     Question mark \?
+%   Commercial at \@     Left bracket  \[     Backslash     \\
+%   Right bracket \]     Circumflex    \^     Underscore    \_
+%   Grave accent  \`     Left brace    \{     Vertical bar  \|
+%   Right brace   \}     Tilde         \~}
+%
+% \iffalse
+%<*driver>
+\ProvidesFile{mathexam.dtx}
+%</driver>
+%<package,ls>\NeedsTeXFormat{LaTeX2e}
+%<package>\ProvidesPackage{mathexam}
+%<*package>
+        [2007/07/30 v1.00 Package for typesetting exams]
+%</package>
+%<*driver>
+\documentclass{ltxdoc}
+\usepackage[nohdr]{mathexam}[2007/07/30]
+\usepackage{hyperref}
+\EnableCrossrefs         
+\CodelineIndex
+\RecordChanges
+\begin{document}
+\DocInput{mathexam.dtx}
+\PrintChanges
+\PrintIndex
+\end{document}
+%</driver>
+% \fi
+%
+% \GetFileInfo{mathexam.dtx}
+%
+% \DoNotIndex{\newcommand,\newenvironment}
+%
+% \changes{1.00}{2007/07/30}{Rewrote as a .dtx file for distribution}
+%
+% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+% \title{\bf The \textsf{mathexam} Package\thanks{This document
+%        describes the version number \fileversion, last
+%        revised \filedate.}}
+%
+% \author{Jan Hlavacek\\ 
+% \small Email: \texttt{\EmailAddress}}
+% \date{30 July 2007}
+% \maketitle
+%
+% \begin{abstract}
+% This package can help you typeset exams (mostly in mathematics and related
+% disciplines where students are required to show their calculations followed by
+% one or more short answers). It provides commands for inclusion of space for
+% calculations, as well as commands for automatic creation of ``answer spaces''.
+% In addition, the package will automatically create page headers and footers,
+% and will let you include instructions and space for students to put their
+% name.  
+% \end{abstract}
+%  \thispagestyle{empty}
+%  \tableofcontents
+%  \section{Introduction}
+%
+% There are several classes and packages for typesetting exams in \LaTeX\
+% available. However, I found out that none of them satisfy my needs.  Some of
+% the classes and packages are very sophisticated, providing commands and
+% environments for things like fill in the blank, true/false and multiple choice
+% questions. In contrast, nearly all exams in my lower level undergraduate math
+% classes (including exams I took myself as an undergraduate) have basically the
+% same format: a list of questions, each followed by a vertical space for
+% students to do their calculations, each optionally followed by one or more
+% reserved spaces for students to write their final answers. 
+%
+% Some of my colleagues use various word-processing softwares to type their
+% exams.  Because of limitations of these programs, they usually end up typing
+% each questions, followed by bunch of blank lines, followed by something like 
+% ``Answer underscore underscore underscore \ldots'', carefully inserting just
+% the right number of blank lines so that the each question will be on the same
+% page as its corresponding ``Answer:\ldots'', and the last ``Answer:\ldots'' on
+% each page will be somewhat close to the bottom of the page.  This works fine
+% as long as you don't change the questions, the font, margins, and as long as
+% you always use the same printer to print the exam.  Every time you do anything
+% that results in a change in pagination, you have to go back and insert or
+% delete blank lines in order to have everything align correctly again. 
+%
+% \TeX\, with its stretchable vertical glue, can easily solve this
+% problem.  This package provides a way for easy inclusion of vertical space
+% after questions, as well as single or multiple ``answer spaces''. 
+% It does not take care of things like numbering of questions (I prefer to use
+% standard \LaTeX\ list making environments), tracking the number of points,
+% etc.  
+%
+%  \section{Installation}
+%
+% To install this package, simply run \LaTeX\ with the input file
+% \texttt{mathexam.ins} like this:
+%  \begin{verbatim}
+% $ latex mathexam.ins
+%  \end{verbatim}
+% That will create the file \texttt{mathexam.sty}. You need to move this file to
+% a place where \LaTeX\ can find it. 
+%
+% To generate documentation for this package, run \LaTeX\ with the input file
+% \texttt{mathexam.dtx} instead, like
+%  \begin{verbatim}
+% $ latex mathexam.dtx
+%  \end{verbatim}
+% to generate the documentation in the \texttt{.dvi} format, or
+%  \begin{verbatim}
+% $ pdflatex mathexam.dtx
+%  \end{verbatim}
+% to create a \texttt{pdf} file.
+%
+%  \section{Usage} \label{usage}
+%
+% To use the package, all you have to do is include |\usepackage{mathexam}| in
+% the preamble of your document:
+%  \begin{verbatim}
+%  \documentclass[11pt]{article}
+%  \usepackage{mathexam}
+%  \end{verbatim}
+%
+% \DescribeMacro{nohdr}
+% Normally, the \texttt{mathexam} package automatically generates headers and
+% footers for each page, containing information about the exam. In order to do
+% that, the package uses several other packages, namely \texttt{fancyhdr},
+% \texttt{lastpage} and \texttt{ifthen}.  These packages have to be installed on
+% your computer if you want the \texttt{mathexam} package generate headers.  If
+% you don't have all of these packages, or if for some reason you don't want the
+% \texttt{mathexam} package to generate headers (you have your own way to
+% include headers, for example), you can call the \texttt{mathexam} package with
+% \texttt{nohdr} option:
+%  \begin{verbatim}
+%  \documentclass[11pt]{article}
+%  \usepackage[nohdr]{mathexam}
+%  \end{verbatim}
+%
+% \subsection{Main Commands}
+%
+% \DescribeMacro{\answer} 
+%  The command |\answer| inserts a stretchable vertical space followed by a
+%  generic ``answer space'':
+%  \begin{verbatim}
+%   What is $1+1$? \answer
+%  \end{verbatim}
+% produces:
+%
+% What is $1+1$? \answer
+%
+% \DescribeMacro{\addanswer} 
+%  The command |\addanswer| works just like |\answer| except that it does not
+%  insert any extra vertical space.  It can be used for example in situation where we
+%  need two ``answer spaces'' immediately following each other:
+%  \begin{verbatim}
+%   Product of two numbers equals 24, while their sum is 10.  What are the
+%   numbers? \answer\addanswer
+%  \end{verbatim}
+% produces:
+%
+%   Product of two numbers equals 24, while their sum is 10.  What are the
+%   numbers? \answer\addanswer
+%
+% \subsection{Optional Arguments}
+%
+% In the examples above, there is a stretchable vertical glue between the text
+% of each problem and the ``answer space''. You cannot really see it in this
+% document, since the problems are surrounded by other text and we let \LaTeX\
+% decide where to break the page.  Normally, you would insert |\newpage| after
+% several problems, which would make the problems nicely distributed on the
+% page. 
+% 
+% Sometimes you want to make sure that certain problem has enough space for
+% students to write down their work.  You can specify an exact amount of space between
+% the text of the problem and the ``answer space'' using an optional argument
+% with the |\answer| or |\addanswer| commands: 
+%  \begin{verbatim}
+%   What is $1+1$? \answer[1in]
+%  \end{verbatim}
+% produces:
+%
+% What is $1+1$? \answer[1in]
+%
+% Here, the space between the text of the problem and the ``answer space'' will
+% be 1 inch.  In this aspect,  |\addanswer[1in]| will work the exact same way. 
+% The argument can be any glue, for example if you want to include at least one inch,
+% which can possibly stretch further, you can do |\answer[1in plus 1fill]|
+%
+% \subsection{Changing Labels for ``Answer Spaces''}
+%
+% Often you want to use different text instead of the default ``Answer:'' label
+% for an ``answer space''.  This can easily be done with the ``stared'' version
+% of the commands.  The commands |\answer*| and |\addanswer*| take one mandatory
+% argument (in addition to the optional argument described above) with the text
+% you want to use for the label.  For example
+% \begin{verbatim}
+% Find the first two derivatives of the function $f(x) = x^2\cos(x)$.  Simplify
+% your answers as much as possible.  Show all your work.
+% \answer*[1in]{$f'(x)=$}\answer*[1in]{$f''(x)=$}
+% \end{verbatim}
+% produces
+%
+% Find the first two derivatives of the function $f(x) = x^2\cos(x)$.  Simplify
+% your answers as much as possible.  Show all your work.
+% \answer*[1in]{$f'(x)=$}\answer*[1in]{$f''(x)=$}
+%
+% Notice that here, vertical spaces before both of the ``answer spaces'' will be
+% 1 inch long.
+% In the following example, the answer spaces for $x$ and $y$ will be right
+% above each other:
+% \begin{verbatim}
+% If $x + y = 10$ and $2x - y = 8$, find $x$ and $y$.
+% \answer*[1in]{$x=$}\addanswer*{$y=$}
+% \end{verbatim}
+% produces
+%
+% If $x + y = 10$ and $2x - y = 8$, find $x$ and $y$.
+% \answer*[1in]{$x=$}\addanswer*{$y=$}
+%
+% \subsection{No ``Answer Space''}
+%
+% Sometimes you will have problems where the work is the answer, or the answer
+% is too long to fit into a short ``answer space''. For that purpose, the
+% package defines the |\noanswer| command.
+%
+% \DescribeMacro{\noanswer}
+% This command will simply include a stretchable vertical space after the
+% problem. Again, as with |\answer| and |\addanswer|, the command takes one
+% optional argument, which is an optional length of the vertical space. 
+%
+% \subsection{Other Commands}
+% 
+% The package provides several other commands for things like identifying the
+% exam, giving instructions to students, including space for student's name etc.
+%
+% \DescribeMacro{\ExamName}\DescribeMacro{\ExamClass}\DescribeMacro{\ExamHead}
+% The commands |\ExamName|, |\ExamClass| and |\ExamHead| are used for
+% identifying the exam.  They will determine how will the headers of the exam
+% pages look like.  For example, in the preamble of your document you could
+% specify
+% \begin{verbatim}
+% \ExamName{Final Exam}
+% \ExamClass{Calculus III}
+% \ExamHead{\today}
+% \end{verbatim}
+% The \texttt{mathexam} package will use the \texttt{fancyhdr} package to
+% include this information in the page headers.
+%
+% \DescribeMacro{\ExamNameLine}
+% The |\ExamNameLine| command can be used to include a line on which students
+% can write their name:
+% \begin{verbatim}
+% \ExamNameLine
+% \end{verbatim}
+% produces
+% 
+% \ExamNameLine
+% 
+% \DescribeMacro{\ExamInstrBox}
+% The command |\ExamInstrBox| lets you include some basic instructions to
+% students taking the exam.  Example:
+% \begin{verbatim}
+% \ExamInstrBox{Please show all your work! Answers without supporting work will
+% not be given credit. Write answers in spaces provided.  You have 1 hour and 50
+% minutes to complete this exam.}
+% \end{verbatim}
+% produces
+% 
+% \ExamInstrBox{Please show all your work! Answers without supporting work will
+% not be given credit. Write answers in spaces provided.  You have 1 hour and 50
+% minutes to complete this exam.}
+%
+% \section{Notes}
+% 
+% \subsection{TODO}
+% 
+% There are several things I plan to improve in the future:
+% \begin{itemize}
+%    \item Some basic internationalization (right now everything is in English)
+%    \item Add some code for printing point value of problems.
+% \end{itemize}
+% If you have any other suggestions, please contact me.
+%
+% \subsection{Bugs, Suggestions, Comments\ldots}
+% 
+% If you find any bugs, or have any suggestions, comments, patches etc.~please
+% let me know at \texttt{\EmailAddress}.
+% \StopEventually{}
+%
+% \section{Implementation}
+%
+% First we will process options:
+%    \begin{macrocode}
+\newif\ifExamHdr
+\ExamHdrtrue
+\DeclareOption{nohdr}{\ExamHdrfalse}
+\ProcessOptions
+%    \end{macrocode}
+%
+% If ExamHdr is true, we load some packages we need
+%    \begin{macrocode}
+\ifExamHdr
+\RequirePackage{fancyhdr}
+\RequirePackage{lastpage}
+\RequirePackage{ifthen}
+\fi
+%    \end{macrocode}
+%
+% \begin{macro}{\ExamName}
+% \begin{macro}{\ExamClass}
+% \begin{macro}{\ExamHead}
+% Here we will set up macros that handle exam headers and footers.  First we
+% will define the three commands that provide a user interface:
+%    \begin{macrocode}
+\newcommand{\ExamName}[1]{\def\@xamname{#1}}
+\newcommand{\ExamClass}[1]{\def\@xamclass{#1}}
+\newcommand{\ExamHead}[1]{\def\@xamrighthdr{#1}}
+%    \end{macrocode}
+% Then we will initialize the internal macros to some default values:
+%    \begin{macrocode}
+\def\@xamname{\relax}
+\def\@xamclass{\relax}
+\def\@xamrighthdr{\relax}
+%    \end{macrocode}
+% If ExamHdr is true, set up the fancy headers:
+%    \begin{macrocode}
+\ifExamHdr
+\pagestyle{fancy}
+
+\lhead{\@xamclass}
+\chead{\@xamname}
+\rhead{Page \thepage\ of \pageref{LastPage}}
+
+\rfoot{\ifthenelse{\value{page}=\pageref{LastPage}}{The End.}{Cont.}}
+\cfoot{}
+%    \end{macrocode}
+% Handle the first page differently:
+%    \begin{macrocode}
+\AtBeginDocument{
+\begin{center}
+   \large\scshape \@xamclass \hfill \@xamname \hfill \@xamrighthdr
+\end{center}}
+
+\thispagestyle{empty}
+\fi
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% \end{macro}
+% 
+% \begin{macro}{\answer}
+% \begin{macro}{\addanswer}
+% Prepare auxiliary commands for |\answer| and |\addanswer|.  First the regular
+% (non-stared) version:
+%    \begin{macrocode}
+\newcommand{\answ@r}[1][\fill]{%
+   \nopagebreak\vspace{#1}\par\nopagebreak\hfill\hbox to
+   .5\columnwidth{Answer:\hrulefill}\vspace{\baselineskip}}
+
+\newcommand{\addansw@r}[1][\baselineskip]{%
+   \nopagebreak\vspace{#1}\par\nopagebreak\hfill\hbox to
+   .5\columnwidth{Answer:\hrulefill}\vspace{\baselineskip}}
+%    \end{macrocode}
+%
+% Then the stared version:
+%    \begin{macrocode}
+\newcommand{\answ@rstar}[2][\fill]{%
+   \nopagebreak\vspace{#1}\par\nopagebreak\hfill\hbox to
+   .5\columnwidth{#2\hrulefill}\vspace{\baselineskip}}
+
+\newcommand{\addansw@rstar}[2][\baselineskip]{%
+   \nopagebreak\vspace{#1}\par\nopagebreak\hfill\hbox to
+   .5\columnwidth{#2\hrulefill}\vspace{\baselineskip}}
+%    \end{macrocode}
+%
+% Now we will pot them together.  Look ahead to see if there is a star.  If
+% there is, use the stared version: 
+%    \begin{macrocode}
+\def\answer{%
+   \def\e@t*{}%
+   \def\n@xt{\if\noexpand\myn@@xt*%
+      \expandafter\expandafter\expandafter\answ@rstar\expandafter\e@t\else%
+      \expandafter\answ@r\fi}%
+   \futurelet\myn@@xt\n@xt}
+
+\def\addanswer{%
+   \def\e@t*{}%
+   \def\n@xt{\if\noexpand\myn@@xt*%
+      \expandafter\expandafter\expandafter\addansw@rstar\expandafter\e@t\else%
+      \expandafter\addansw@r\fi}%
+   \futurelet\myn@@xt\n@xt}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+% 
+% \begin{macro}{\noanswer}
+%    \begin{macrocode}
+\newcommand{\noanswer}[1][\fill]{\nopagebreak\vspace{#1}\par}
+%    \end{macrocode}
+% \end{macro}
+%
+% Finally, couple of very simple macros.  They could probably be made more
+% interesting and flexible.
+% \begin{macro}{\ExamNameLine}
+%    \begin{macrocode}
+\newcommand{\ExamNameLine}{%
+\par
+\vspace{\baselineskip}
+Name:\hrulefill\relax
+\par}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\ExamInstrBox}
+%    \begin{macrocode}
+\newcommand{\ExamInstrBox}[1]{\begin{center}\vspace{\baselineskip}%
+   \fbox{\fbox{\parbox{.8\hsize}{#1}}}\end{center}}
+%    \end{macrocode}
+% \end{macro}
+%
+% \Finale
+
+\endinput