From cef5a237f3f64c3c51e4781e7709ce738c6afd02 Mon Sep 17 00:00:00 2001 From: Sebastian Kuhnert Date: Thu, 14 Aug 2008 13:43:44 +0000 Subject: move files in thi3 for better sorting; split exercisesheets.sty to seperate directory --- exercisesheets.tex | 425 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 425 insertions(+) create mode 100644 exercisesheets.tex (limited to 'exercisesheets.tex') 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 -- cgit v1.2.3