move files in thi3 for better sorting; split exercisesheets.sty to seperate directory

1 files changed, 425 insertions, 0 deletions

diff --git a/exercisesheets.tex b/exercisesheets.tex
new file mode 100644
index 0000000..fb74d6b
--- /dev/null
+++ b/exercisesheets.tex
@@ -0,0 +1,425 @@
+\documentclass[DIV12,BCOR0mm]{scrartcl}
+
+\usepackage{arev}
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+\usepackage{csquotes}
+\usepackage{xspace}
+\usepackage{xcolor}
+\usepackage{calc}
+\usepackage{listings}
+\lstloadlanguages{TeX}
+\lstset{%
+  language=[LaTeX]TeX,
+  basicstyle=\ttfamily\color{blue!50!black},
+  keywordstyle=\bfseries,
+  morekeywords={subject},
+  identifierstyle=,
+  texcl,
+  commentstyle=\itshape,
+  showstringspaces=false,
+  breaklines,
+  breakatwhitespace,
+  columns=flexible,
+  escapeinside={(*}{*)},
+  mathescape,
+}
+
+\usepackage[pdfusetitle,colorlinks]{hyperref}
+
+\newcommand{\exsh}{\texttt{exercisesheets}\xspace}
+
+\newcommand{\param}[1]{$\langle${\normalfont\itshape #1}$\rangle$}
+\newcommand{\opt}[1]{\textcolor{green!50!black}{#1}}
+\newcommand{\option}[1]{{\normalfont\texttt{\color{blue!50!black}#1}}}
+
+\title{The \exsh Package}
+\author{Sebastian Kuhnert}
+\date{July 31th, 2008}
+
+\begin{document}
+\maketitle
+
+The \exsh package provides a way to typeset exercise sheets as used in
+university courses. It evolved from a set of macros an environments that were
+finally combined into this package.
+
+\section{Related Classes and Packages}
+
+\subsection{Packages with Similar Functionality}
+\begin{itemize}
+ \item The \texttt{exercise} package offers similar functionality, though the
+  concept is a bit different: That package provides explicit commands for
+  sub-exercises while \exsh relies on other means like the \texttt{enumerate}
+  environment for this. An advantage of the \texttt{exercise} package is that
+  answers can be delayed. On the other hand \exsh's environment based user
+  interface is a bit cleaner and you have to care less about package internals.
+\end{itemize}
+
+\subsection{Recommended Additional Packages}
+\begin{itemize}
+ \item The use of \texttt{hyperref} is encouraged. Please use the options
+  \texttt{pdfusetitle}, \texttt{plainpages=false} and \texttt{pdfpagelabels} for
+  optimal results.
+ \item If the \texttt{babel} package is loaded, the appropriate
+  \option{language=\param{lang}}-option is automatically derived and can be
+  omitted.
+ \item The use of \texttt{paralist} is recommended. Top level enumerating lists
+  are then modified to have the form (a), (b), \dots{}, which is useful in
+  exercise definitions.
+ \item If the \texttt{varioref} package is used, appropriate label formats are
+  installed for exercises and sub-exercises.
+ \item If the \texttt{xcolor} package is loaded, to-do markers generated with
+  \verb|\TODO| are printed in red.
+\end{itemize}
+
+\subsection{Packages Loaded by \exsh}
+\begin{itemize}
+ \item \texttt{etoolbox} (at least version
+  1.7)
+ \item \texttt{scrlfile} (part of \KOMAScript{})
+ \item \texttt{pgfkeys} (part of PGF 2.0)
+ \item \texttt{ifthen}
+ \item \texttt{amsmath} (for \verb|\numberwithin|)
+\end{itemize}
+
+
+\section{Basic Usage}
+
+\subsection{Package Loading}
+\begin{lstlisting}
+\usepackage(*\opt{[\param{options}]}*){exercisesheets}
+\end{lstlisting}
+
+The following options are available:
+\begin{description}
+ \item[\option{only=\param{list of ranges}}] When given, only the mentioned
+  sheets will be included in the output. This is useful to speed up compilation
+  times for big documents. Some efforts are made that sheet and exercise
+  numbering remain consistent and references to exercises on skipped sheets
+  still work as expected. References to other objects are broken though (they
+  currently point to the exercise containing them). The \param{list of ranges}
+  is a comma separated list of sheet numbers and sheet ranges. If a comma is
+  included in the range, it has to be protected with a pair of braces. The
+  special sheet \enquote{number} \texttt{last} stands for the last sheet in the
+  document (this may require an additional \LaTeX{} run). Examples:
+  \begin{description}
+   \item[\option{only=3}] Only include the 3rd sheet of the document.
+   \item[\option{only=\{1,3,5,7\}}] Only include the sheets 1, 3, 5 and 7.
+   \item[\option{only=last}] Only include the last sheet of the document.
+   \item[\option{only=\{3-5,8-last\}}] Exclude the sheets 1, 2, 6 and 7.
+   \item[\option{only=\{-2,5-\}}] Exclude the sheets 3 and 4.
+  \end{description}
+ \item[\option{all}] Typeset all sheets (equivalent to \option{only=-}). This is
+  the default.
+ \item[\option{solutions\opt{=\param{true/false}}}] By default, solutions
+  (provided in the \texttt{solution} environment) are not included in the
+  output. By providing the option \option{solutions=true} (or just
+  \option{solutions}) this can be changed.
+ \item[\option{solutionsby=\param{name/names}}] Use this to give the authors of the
+  solutions. They are credited at the beginning of each sheet, if the solutions
+  are included in the output.
+ \item[\option{language=\param{lang}}] Set the language of the sheet and
+  exercise heads to \param{lang}. If the \texttt{babel} package is loaded this
+  is not necessary, as the main document language will be automatically
+  detected. Currently \option{english}, \option{german} and \option{ngerman} are
+  supported. Other translations are welcome: Please contact the author.
+\end{description}
+
+\subsection{Supplying Meta-Data}
+
+The following commands are enhanced (or provided) to set the options controlling
+the sheet headers (see Section \ref{sec:sheet}):
+\begin{lstlisting}
+\subject{(*\param{subject}*)}
+\author{(*\param{author}*)}
+\date{(*\param{semester}*)}
+\end{lstlisting}
+
+If one of these commands is omitted (and the corresponding option is not used
+either), a warning is issued.
+
+Please do not include a \verb|\title| in your document, as \exsh will
+automatically generate an appropriate one.
+
+All this information is included in the PDF meta-data if the \texttt{hyperref}
+package is loaded with the option \texttt{pdfusetitle}.
+
+\subsection{Defining Exercise Sheets}
+\label{sec:sheet}
+\begin{lstlisting}
+\begin{sheet}(*\opt{[\param{options}]}*)
+  (*\param{sheet contents}*)
+\end{sheet}
+\end{lstlisting}
+
+Insert a sheet into the document. This environment can be repeated to combine
+several sheets in a single \LaTeX{} file. For each sheet, a new page is started
+and an appropriate header is generated. The \param{sheet contents} can be
+anything but will usually consist of several \texttt{exercise} environments (see
+\ref{sec:exercises-solutions}).
+
+The following \param{options} are supported:
+\begin{description}
+ \item[\option{date=\param{date}}] Set the date the sheet was/will be issued. This
+  information is included in the sheet header. By default, this information is
+  omitted. See also the \option{semester} option.
+ \item[\option{note=\param{note}}] Include \param{note} in the sheet header.
+  Useful to inform students when the sheet is due.
+ \item[\option{title=\param{title}}] Deviate from the usual numbering theme and
+  directly set the sheet title. When this option is used, exercise numbers are
+  reset and different page numbering conventions are used. This is useful to
+  typeset exams.
+ \item[\option{author=\param{author}}] Set the author included in the sheet
+  head. By default, the value passed to \verb|\author| is used.
+ \item[\option{subject=\param{subject}}] Set the subject included in the sheet
+  head. By default, the value passed to \verb|\subject| is used.
+ \item[\option{semester=\param{semester}}] Set the semester included in the
+  sheet head. By default, the value passed to \verb|\date| is used.
+\end{description}
+
+
+\subsection{Defining Exercises and Solutions}
+\label{sec:exercises-solutions}
+\begin{lstlisting}
+\begin{exercise}(*\opt{[\param{options}]}*)
+  (*\param{exercise text}*)
+  \begin{solution}(*\opt{[\param{solution options}]}*)
+    (*\param{solution text}*)
+  \end{solution}
+\end{exercise}
+\end{lstlisting}
+
+This inserts an exercise into the current document. The following options are
+supported:
+\begin{description}
+ \item[\option{points=\param{number}}] Assign this exercise \param{number}
+  points. By default, exercises are unlabelled.
+ \item[\option{oral}] Label this exercise as \emph{oral}. This supersedes and is
+  superseded by the option \option{points}.
+ \item[\option{firstline=\param{text}}] Save some space by putting \param{text}
+  behind the exercise number.
+ \item[\option{solutions\opt{=\param{true/false}}}] Use this to override the
+  document (or sheet) default.
+\end{description}
+
+Solutions are only typeset, if the \option{solutions} option is in effect. There
+can be multiple solution environments within a single exercise environment; this
+is useful if the exercise consists of several sub-exercises. Sub-exercises can
+simply be defined with an \texttt{enumerate} or \texttt{compactenum}
+environment.
+
+\section{Utilities}
+
+\subsection{Including Hints}
+
+\begin{lstlisting}
+\begin{hint}(*\opt{[\param{options}]}*)
+  (*\param{hint text}*)
+\end{hint}
+\end{lstlisting}
+
+\begin{lstlisting}
+\begin{hint*}(*\opt{[\param{options}]}*)
+  (*\param{hint text}*)
+\end{hint*}
+\end{lstlisting}
+
+These environments include hints in the exercise definition. The first form
+starts a new paragraph, the second one puts the hint in parenthesis.
+
+\subsection{TODO Markers}
+
+You can use the following to include a red TODO marker in your document. This is
+useful to mark places where work is still in progress. If no solutions are
+included, an error is issued, otherwise it is just a warning.
+
+\begin{lstlisting}
+\TODO
+\end{lstlisting}
+
+\subsection{Annotating Points for Sub-Exercises}
+\begin{lstlisting}
+\begin{exercise}[points=10]
+  \begin{enumerate}
+   \item Part 1 \pun[5]
+   \item Part 2 \pun[5]
+  \end{enumerate}
+\end{exercise}
+\end{lstlisting}
+
+
+\section{Advanced Usage}
+
+\subsection{Setting Options}
+
+Options can be given at different places. 
+\begin{enumerate}
+ \item As local options to one of the environments.
+ \item As package options: This is convenient for global options but suffers
+  from shortcomings in way \LaTeX{} processes options: Macros are expanded and
+  spaces are stripped.
+ \item By the independent \verb|\exshset| command. This is especially useful in
+  the preamble to set options that would be garbled by the \LaTeX{} option
+  handling routine. It also allows to change an option for the rest of the
+  current scope.
+\end{enumerate}
+
+Example: Change the solution authors of the following sheets:
+\begin{lstlisting}
+(*\param{some sheets}*)
+\exshset{solutionsby=(*\param{other authors}*)}
+(*\param{more sheets}*)
+\end{lstlisting}
+
+\subsection{Changing Strings}
+
+For some languages, predefined sets of strings are provided and automatically
+activated. If your language is not supported or if you want to change (some of)
+the used strings, you can do so with the following options:
+\begin{description}
+ \item[\option{strings/sheet=\param{string}}]
+ \item[\option{strings/sheets=\param{string}}]
+ \item[\option{strings/solutions=\param{string}}]
+ \item[\option{strings/solutionsby=\param{string}}]
+ \item[\option{strings/exercise=\param{string}}]
+ \item[\option{strings/solution=\param{string}}]
+ \item[\option{strings/hint=\param{string}}]
+ \item[\option{strings/oral=\param{string}}]
+ \item[\option{strings/point=\param{string}}]
+ \item[\option{strings/points=\param{string}}]
+\end{description}
+
+Example: Give an introduction that should only be included in the version with
+solutions:
+
+\begin{lstlisting}
+\begin{solution}[strings/solution=Introduction]
+  (*\param{introduction text}*)
+\end{solution}
+\end{lstlisting}
+
+
+\subsection{Changing Fonts}
+
+The package \exsh comes with its own way to change the used fonts. Each font can
+be changed in the following way:
+\begin{lstlisting}
+\exshset{(*\param{font element}=\param{font specification}*)}
+\end{lstlisting}
+The available \param{font element}s are listed below together with their default
+values:
+\begin{description}
+ \item[\option{sheet header font}] The basic font for subject, author, semester,
+  date, note and solution authors in the sheet headers.\\
+  Default: \verb|\normalfont\normalsize|
+ \item[\option{subject font}] The font for the subject in the sheet header.\\
+  Default: \verb|\scshape|
+ \item[\option{author font}] The font for the author in the sheet header.\\
+  Default: \verb|\scshape|
+ \item[\option{semester font}] The font for the semester in the sheet header.\\
+  Default: empty, i.\,e.\ no change.
+ \item[\option{date font}] The font for the date in the sheet header.\\
+  Default: empty, i.\,e.\ no change.
+ \item[\option{solutionsby font}] The font for the information who has produced
+  the solutions provided below the sheet title.\\
+  Default: \verb|\itshape|
+ \item[\option{sheet note font}] The font for the note provided below the sheet
+  title.\\
+  Default: \verb|\itshape\bfseries|
+ \item[\option{sheet title font}] The font for the sheet title itself.\\
+  Default: \verb|\Large\bfseries|
+ \item[\option{exercise title font}] The font for the exercise title.\\
+  Default: \verb|\bfseries|
+ \item[\option{points font}] The font for the number of points in the exercise
+  head (relative to the exercise title) and for \verb|\pun|.\\
+  Default: \verb|\itshape|
+ \item[\option{hint font}] The font for hints. \\
+  Default: empty, i.\,e.\ no change.
+ \item[\option{hint title font}] The font for the string \enquote{Hint:}.\\
+  Default: \verb|\itshape|
+ \item[\option{solution font}] The font for solutions.\\
+  Default: empty, i.\,e.\ no change.
+ \item[\option{solution title font}] The font for the string
+  \enquote{Solution:}\\
+  Default: \verb|\bfseries|
+ \item[\option{todo marker font}] The font for the string \enquote{TODO}.\\
+  Default: \verb|\ifdef{\color}{\color{red}}{}\bfseries|
+\end{description}
+
+\subsection{Controlling the Spacing}
+
+The following options allow fine-tuning of the spacing:
+\begin{description}
+ \item[\option{above sheet title skip=\param{dimen}}] The distance between
+  author/date and sheet title.\\
+  Default: \texttt{4ex}
+ \item[\option{above sheet note skip=\param{dimen}}] The distance above the
+  sheet note.\\
+  Default: \texttt{.7ex}
+ \item[\option{above solutionsby skip=\param{dimen}}] The distance above the
+  solution author.\\
+  Default: \texttt{1ex}
+ \item[\option{below sheet header skip=\param{dimen}}] The distance below the
+  sheet header.\\
+  Default: \texttt{4ex plus 1ex minus .5ex}
+ \item[\option{above exercise skip=\param{dimen}}] The distance above
+  exercises.\\
+  Default: \texttt{3ex plus 1ex minus .5ex}
+ \item[\option{below exercise title skip=\param{dimen}}] The distance below
+  exercise titles.\\
+  Default: \texttt{0ex}
+ \item[\option{above solution skip=\param{dimen}}] The distance above
+  solutions.\\
+  Default: \texttt{1ex}
+ \item[\option{above hint skip=\param{dimen}}] The distance above hints.\\
+  Default: \texttt{1ex}
+\end{description}
+
+\subsection{Special Code for Solutions}
+\begin{lstlisting}
+\ifsolutions{(*\param{if true}*)}{(*\param{if false}*)}
+\end{lstlisting}
+
+Example: Only include points for sub-exercises when solutions are typeset:
+\begin{lstlisting}
+\ifsolutions{}{\renewcommand{\pun}[1][]{}}
+\end{lstlisting}
+
+\subsection{Using Hooks}
+There are several hooks used by \exsh:
+\begin{description}
+ \item[\option{every sheet}] This is used at the beginning of every sheet.
+ \item[\option{every exercise}] This is used at the beginning of every exercise.
+ \item[\option{every solution}] This is used at the beginning of every solution.
+ \item[\option{every hint}] This is used at the beginning of every hint.
+\end{description}
+
+Hooks can be used to influence the behaviour of the respective environments.
+Users of \texttt{tikz} should be familiar with the concept.
+
+\section{Usage Tips}
+\label{sec:usage-tips}
+
+\subsection{Seperate Solution File}
+\label{sec:seper-solut-file}
+
+If you do not want to temporarily comment out the \option{solutions} option in
+your main file, say \texttt{exercises.tex}, you can create an additional file
+\texttt{solutions.tex} with the following contents:
+\begin{lstlisting}
+\PassOptionsToPackage{solutions}{exercisesheets}
+\input{exercises.tex}
+\end{lstlisting}
+If you leave out the \option{solutions} option in you main file, running
+\texttt{pdflatex exercises.tex} will create \texttt{exercises.pdf} without
+solutions and \texttt{pdflatex solutions.tex} will create \texttt{solutions.pdf}
+with solutions.
+\end{document}
+
+%%% Local Variables: 
+%%% mode: latex
+%%% TeX-master: t
+%%% End: 
+
+%%% Local IspellDict: british