studenthandouts (16mar17)

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

1 files changed, 614 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/studenthandouts/studenthandouts-doc.tex b/Master/texmf-dist/doc/latex/studenthandouts/studenthandouts-doc.tex
new file mode 100644
index 00000000000..e0b1f50c824
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/studenthandouts/studenthandouts-doc.tex
@@ -0,0 +1,614 @@
+\documentclass[10pt,oneside,letterpaper]{article}
+
+%
+%	TABLE OF CONTENTS STUFF
+%
+\usepackage{tocloft}
+\tocloftpagestyle{empty}
+\renewcommand{\cftsubsecfont}{\it}
+\renewcommand{\cftsecleader}{\hspace{0.25cm}}%\textbullet\hspace{0.25cm}}
+\renewcommand{\cftsecafterpnum}{\cftparfillskip}
+\renewcommand{\cftsubsecleader}{\hspace{0.25cm}}%$\cdot$\hspace{0.25cm}}
+\renewcommand{\cftsubsecafterpnum}{\cftparfillskip}
+\renewcommand{\cftsubsubsecleader}{\hspace{0.25cm}}%$\cdot$\hspace{0.25cm}}
+\renewcommand{\cftsubsubsecafterpnum}{\cftparfillskip}
+\renewcommand{\cftpnumalign}{l}
+
+
+
+
+
+%
+%	INDEXING STUFF
+%
+\usepackage{makeidx}
+\usepackage[columns=1,initsep=20pt,totoc=true]{idxlayout}
+\makeindex
+
+\newcommand{\indexcommand}[1]{
+	\index{\texttt{#1}}%
+	\marginpar{\texttt{\textbackslash#1}}%
+}
+\renewcommand\indexname{Index of commands}
+
+
+%
+%	TIKZ
+%
+\usepackage{tikz}
+\usetikzlibrary{decorations.pathreplacing}
+
+
+%
+%	HEADER AND FOOTER STYLING
+%
+\usepackage{fancyhdr}
+\pagestyle{fancy}
+	\renewcommand{\headrulewidth}{0pt}
+\fancyfoot{}
+\fancyhead{}
+\fancyhead[R]{\it The Student Handouts Package $\cdot$ \thepage}
+\newcommand{\pdf}{\textsc{pdf} }
+\newcommand{\Latex}{La\textsc{t}e\textsc{x} }
+
+
+
+
+%
+%	FONT STUFF
+%
+\frenchspacing
+\usepackage[oldstyle]{libertine}
+\usepackage[T1]{fontenc}
+\linespread{1.1}
+\usepackage{verbatim}
+%The mono spaced font
+\usepackage{inconsolata}
+
+\title{\vspace{-2\baselineskip}The Student Handouts Package}
+\author{James Fennell\\{\normalsize jamespfennell@gmail.com}}
+
+
+\begin{document}
+
+
+\maketitle
+
+\noindent
+The Student Handouts package, \texttt{studenthandouts}, is used to generate a single master document that contains a set of individual student handouts.
+
+
+The package has two main functions.
+
+First, it provides a simple framework for organizing handout source code, and supplies a set  of
+	import management tools for selectively importing a subset of the handouts into the master document.
+Selective import is convenient when compilation of all of the handouts is unnecessary, for example when working on a new handout.
+
+As a secondary feature, the package defines a basic visual style for handouts.
+This style can be easily changed.
+
+
+
+\tableofcontents
+
+%\section{Managing handouts with the studenthandouts package}
+
+
+
+
+
+\vfill
+
+\noindent
+[\emph{Student handouts version 1.0; this documentation compiled \today.}]
+
+
+
+\section{Basic usage of the package}
+
+
+
+This package is used as an aid in managing and compiling student handouts.
+When using this package, the \Latex source for the handouts project as a whole is divided between a 
+	single master file and individual handout files, one for each handout.
+This section describes the details of this structure and the basic method for importing handouts into the master document.
+All of these features can be seen in the sample code that is distributed with the package.
+
+
+
+
+The handouts master file, into which all of the handouts are imported during compilation, is a standard \Latex file that includes this
+	package.
+Place the usual command in the preamble of this file:
+\begin{verbatim}
+    \usepackage{studenthandouts}
+\end{verbatim}
+For options that may be passed through \texttt{usepackage}, see section \ref{sec:options} below.
+
+The source for the handouts themselves is stored in a subdirectory of the directory containing the master document.
+By default, this subdirectory is \texttt{./handouts/}.
+This directory can be changed; see subsection \ref{sec:variables} below.
+
+The package imposes a one-level organizational structure on the handouts.
+Each handout is a member of a numbered \emph{unit} and within that unit has a unique handout number.
+Handout 1.1 is the first handout in unit one.
+The source for handout 1.1 is, by default, stored in
+\begin{verbatim}
+    ./handouts/handout-1-1.tex
+\end{verbatim}
+Handout 3.4 is the fourth handout in unit three and its source is stored in
+\begin{verbatim}
+    ./handouts/handout-3-4.tex
+\end{verbatim}
+The work `unit' is intentionally generic.
+When working on a specific project units may represent, for example, individual lessons, or chapters in the textbook the handouts are based on.
+
+The organizational structure is loose.
+For example, there is no requirement that handouts begin at the beginning and proceed sequentially: the first handout can be handout 10.521 if desired.
+
+
+The source file\indexcommand{sethandouttitle}%
+ for a specific handout begins with a \texttt{sethandouttitle} command and is followed by the \Latex code for the handout proper.
+Place this line at the start:
+\begin{verbatim}
+	    \sethandoutitle{<Title of the handout>}
+\end{verbatim}
+If the handout does not have a title, execute the command with an empty argument:
+\begin{verbatim}
+	    \sethandouttitle{} 
+\end{verbatim}
+%The command \texttt{handouttitle} must be executed in all cases.
+
+
+Once\indexcommand{importhandout}%
+there is a  source file for handout \emph{n.m}, it is imported into the master document through the  \texttt{importhandout} command. % in the master document.
+Place this command in the master document at the point the handout is to appear:
+\begin{verbatim}
+	    \importhandout{n}{m}
+\end{verbatim}
+Again, \emph{n} is the unit number and \emph{m} is the unique number of the handout within the unit.
+
+
+\section{Handout import management}
+
+
+After writing a number of handouts, the master document will have many handout import  commands. 
+However at a given time it may not be desirable to compile all of the handouts in the project.
+For example, if working on a new handout it is faster to only compile the new work when error checking.
+If collaborating, it may be necessary to compile just a certain subset of the handouts to share.
+
+The import management tools are designed for these situations.
+The basic mechanism is that when handout \emph{n.m} is set to be imported the package first checks, based on previous instructions, whether 
+	unit \emph{n} is to be imported, and if so whether handout \emph{n.m} specifically is to be imported.
+By default all units and handouts are imported.
+
+The instructions for which handouts are to be imported are given through the commands that follow.
+The instructions may be changed at any point in the master file, even after some of the handouts have already been imported.
+
+\begin{itemize}
+
+	\item \verb$\importall$	\indexcommand{importall}
+
+		Import all handouts.
+		This is the default behavior. 
+		The \texttt{importall} command is used to reset to the default behavior after other instructions have been given.
+
+	\item \verb$\importnone$ \indexcommand{importnone}
+	
+		Import none of the handouts.
+
+	\item \verb$\importonlyunits{$\emph{<unit numbers>}\verb$}$ \indexcommand{importonlyunits} 
+
+		Import only those units whose unit numbers appear in \emph{<unit numbers>}. The argument \emph{<unit numbers>} is a comma separated list of numbers with no spaces.
+		Example usage: 
+		\begin{verbatim}
+		  \importonlyunits{1,2,4}
+		\end{verbatim}
+
+
+	\item \verb$\importallunits$	\indexcommand{importallunits}
+
+		Reverse the last command by removing any unit importing restrictions.
+		The difference between this command and \texttt{importall} is that if any specific handout restrictions have been imposed then
+			those restrictions still stand.
+	
+
+	\item \verb$\importonlyhandouts{$\emph{<handout numbers>}\verb$}$		\indexcommand{importonlyhandouts}
+
+		Import only those handouts whose full handout number \emph{n.m} appears in \emph{<unit numbers>}. 
+		The argument \emph{<unit numbers>} is a comma separated list of handout numbers with no spaces.
+		Example usage: 
+		\begin{verbatim}
+		  \importonlyhandouts{5.2,6.5,6.6}
+		\end{verbatim}
+
+	
+	\item \verb$\importallhandouts$		\indexcommand{importallhandouts}
+
+		Reverse the last command by removing any specific handout importing restrictions.
+		The difference between this command and \texttt{importall} is that if any specific unit restrictions have been imposed then
+			those restrictions still stand.
+
+	
+\end{itemize}
+
+An important feature is that the import instructions can be changed on the fly.
+For example with the following code
+\begin{verbatim}
+    	\importnone
+    	\importhandout{1}{1}
+    	\importhandout{1}{2}
+    	\importonlyhandouts{1.3,2.1}
+    	\importhandout{1}{3}
+    	\importhandout{2}{1}
+    	\importhandout{2}{2}
+    	\importhandout{2}{3}
+    	\importall
+    	\importhandout{2}{4}
+\end{verbatim}
+handouts 1.3, 2.1 and 2.4 will be imported.
+
+In particular, in the import context the \texttt{importnone} and \texttt{importall} commands work similarly to 
+	\verb$\begin{comment}$ and \verb$\end{comment}$ respectively.
+
+
+\section{Options and variables}
+
+
+\subsection{The blanks option}
+
+\label{sec:options}
+
+
+The package has one option: \texttt{blanks} or \texttt{noblanks}, with \texttt{blanks} as default.
+
+The \texttt{blanks} option places a blank page after every handout that has an odd number of pages. 
+That way, the compiled handouts document can be printed double sided, and handouts with an odd number of pages will still be on their own sheet.
+
+To see how the \texttt{blanks} options achieves this, see Figure \ref{fig:blanks}.
+In this example there are three handouts: 1.1 with one page, 1.2 with two pages, and 1.3 with one page.
+It is required that 1.2 be distributed double-sided.
+
+
+In the first case in Figure \ref{fig:blanks}, the handouts are compiled one after another with the \texttt{noblanks} option.
+If the resulting document is printed at once double-sided,
+the back of handout 1.1 will contain the first page of handout 1.2, and the next sheet will contain the second page of handout 1.2 with handout 1.3 on the reverse.
+In order to print the handouts correctly with this \pdf file, separate print calls for each of the three handouts are required.
+
+On the other hand, with the \texttt{blanks} option, the resulting \pdf document can just be printed double sided at once.
+The first sheet will contain handout 1.1 on the front, and the blank page after 1.1 on the back.
+The next sheet will have the two pages of handout 1.2 back-to-back, and the last sheet will have handout 1.3 by itself.
+
+
+
+
+
+\newcommand{\handoutimage}[3]{
+	\draw[white] #1 -- ++(-0.05,0.15) coordinate(hib) -- ++(-0.03,1) coordinate(hia) {};
+	\draw[white] #1 -- ++(0.5,0.8) coordinate (hic) {};
+	\node[anchor=west] at (hia) {\footnotesize #2};
+	\node[anchor=west] at (hib) {\tiny p.#3};
+	%\draw (hic) rectangle ++ (0.5,0.5);
+	\draw #1 rectangle ++ (1,1.3);
+}
+
+
+\newcommand{\handoutimageb}[3]{
+	\draw[white] #1 -- ++(-0.05,0.15) coordinate(hib) -- ++(-0.03,1) coordinate(hia) {};
+	\draw[white] #1 -- ++(0.5,0.8) coordinate (hic) {};
+	%\draw (hic) rectangle ++ (0.5,0.5);
+	\draw #1 rectangle ++ (1,1.3);
+}
+
+
+\newcommand{\handoutimagedbl}[5]{
+	\draw[white] #1 -- ++(-0.05,0.15) coordinate(hib) -- ++(-0.03,1) coordinate(hia) {};
+	\draw[white] #1 -- ++(0.5,1.3) coordinate (hic) {};
+
+	\node[anchor=west] at (hia) {\footnotesize #2};
+	\node[anchor=west] at (hib) {\tiny p.#3};
+
+
+	\node[anchor=west,rotate around={65:(hic)}] at (hia) {\footnotesize #4};
+	%\node[anchor=west,rotate around={65:(hic)}] at (hib) {\tiny p.#5};
+
+	\fill[white] (hic) -- ++(0.5,-0.75) -- ++(0,0.75) -- cycle;
+
+	\draw (hic) -- ++(0.5,-0.75);
+	%\draw #1 -- ++(1,0) -- ++(0,0.1) -- ++(-0.85,0.85) -- ++(0.35,0.35) -- ++(-0.5,0) -- cycle;
+	\draw #1 -- ++(1,0) -- ++(0,0.55) -- ++(-0.725,0.30) -- ++(0.225,0.45) -- ++(-0.5,0) -- cycle;
+}
+
+\begin{figure}
+\begin{tikzpicture}[scale=0.95]
+	%\draw[blue] (0,0) grid (12,5);
+
+	\handoutimage{(0,3)}{1.1}{1}
+	\handoutimage{(1.2,3)}{1.2}{1}
+	\handoutimagedbl{(0.6,1)}{1.1}{1}{1.2}{1}
+
+
+	\handoutimage{(2.4,3)}{1.2}{2}
+	\handoutimage{(3.6,3)}{1.3}{1}
+	\handoutimagedbl{(3,1)}{1.2}{2}{1.3}{1}
+
+	\handoutimage{(5.4,3)}{1.1}{1}
+	\handoutimageb{(6.6,3)}{}{1}
+	\handoutimagedbl{(6,1)}{1.1}{1}{}{}
+
+	\handoutimage{(7.8,3)}{1.2}{1}
+	\handoutimage{(9,3)}{1.2}{2}
+	\handoutimagedbl{(8.4,1)}{1.2}{1}{1.2}{2}
+
+
+	\handoutimage{(10.2,3)}{1.3}{1}
+	\handoutimageb{(11.4,3)}{}{}
+	\handoutimagedbl{(10.8,1)}{1.3}{1}{}{}
+
+	\draw [decorate,decoration={brace,amplitude=6pt}] (2.2,2.8) -- (0,2.8) node {};
+	\draw [decorate,decoration={brace,amplitude=6pt}] (4.6,2.8) -- (2.4,2.8) node {};
+
+	\draw [decorate,decoration={brace,amplitude=6pt}] (7.6,2.8) -- (5.4,2.8) node {};
+	\draw [decorate,decoration={brace,amplitude=6pt}] (10,2.8) -- (7.8,2.8) node {};
+	\draw [decorate,decoration={brace,amplitude=6pt}] (12.4,2.8) -- (10.2,2.8) node {};
+
+	\node at (2.3,4.8){\texttt{noblanks}};
+	\node at (8.8,4.8){\texttt{blanks}};
+\end{tikzpicture}
+	\caption{Comparison of the outcome of printing the compiled handouts document double-sided. 
+		On the left is the handouts document compiled with the option \texttt{noblanks}; on the right
+		is the same document compiled with the option \texttt{blanks}.}
+	\label{fig:blanks}
+\end{figure}
+
+\subsection{Variables}
+\subsubsection{The handouts subdirectory}
+
+\label{sec:variables}
+
+By default
+\indexcommand{thehandoutsdirectory}%
+the handouts are stored in the subdirectory \texttt{handouts/} of the directory that contains the master document.
+Change this be redefining
+% the variable
+ \texttt{thehandoutsdirectory}:
+\begin{verbatim}
+    \renewcommand{\thehandoutsdirectory}{worksheets/}
+\end{verbatim}
+It is necessary to place a forward slash at the end.
+
+If the handouts files are to be stored in the same directory as the master file, set the variable \texttt{thehandoutsdirectory} to be empty:
+\begin{verbatim}
+    \renewcommand{\thehandoutsdirectory}{}
+\end{verbatim}
+
+
+\subsubsection{The handouts label}
+
+\label{sec:label}
+By default
+\indexcommand{thehandoutslabel}%
+ the package deals with `handouts', and uses that word in the handouts output itself.
+For example, the default style prints `Handout 1.1' in the header of handout 1.1.
+A different term like `Student worksheet' might be desired instead.
+To achieve this, redefine the variable \texttt{thehandoutlabel}:
+\begin{verbatim}
+	    \renewcommand{\thehandoutlabel}{Student worksheet}
+\end{verbatim}
+
+
+\subsubsection{The credit/copyright line}
+\label{sec:credit} 
+\indexcommand{thehandoutscredit}
+The default handouts style contains a space in left side of the footer where a credit or copyright line can appear.
+By default it is empty.
+Set it by redefining the variable \texttt{thehandoutcredit}:
+\begin{verbatim}
+	    \renewcommand{\thehandoutcredit}{NYU Calulus I; Summer 2015}
+\end{verbatim}
+
+
+
+
+\section{Auxiliary package features}
+
+\subsection{A table of contents for the compiled document}
+
+While each handout has its own page numbering -- the first page of a handout is always page one --
+ having a table of contents which references the page numbers of the handouts as they appear in the compiled \pdf document
+	can be convenient for determining which pages of the \pdf document need to be printed to get certain handouts. 
+
+To generate this type of table of contents in the compiled document, place usual command in the master file:
+\begin{verbatim}
+	   \tableofcontents
+\end{verbatim}
+The resulting table of contents will have some custom styling defined by the package.
+
+
+
+\subsection{Setting unit titles}
+
+When
+using this package handouts are organized under generic `units'.
+In a given project these units might represent something concrete;
+	for example, each unit might refer to a specific chapter in a book.
+In this case individual units might also have titles, like 
+	`Introduction to Differentiation',
+	and it may be useful to use these titles in the handouts.
+
+\indexcommand{setunittitle}
+Set the title of a unit with the command\texttt{setunittitle}:
+\begin{verbatim}
+	    \setunittitle{<unit number>}{<unit title>}
+\end{verbatim}
+
+When changing the handout style, or writing a specific handout, the title of the current unit may be printed with the command \verb$\theunittitle$.
+If the current unit's title is not set, \verb$\theunittitle$ will do nothing.
+
+In addition, if the title of a unit is set, the title will appear in the compiled document's table of contents.
+This will likely make the compiled \pdf easier to navigate, and for this reason alone it is worth setting unit titles if they're available.
+
+
+
+\section{Modifying the handout style}
+
+
+
+
+The package defines a basic handouts style.
+The style is implemented by changing the page margins (using the \texttt{geometry} package)
+	and editing the headers and footers of the handouts (using the \texttt{fancyhdr} package).
+
+
+\subsection{Editing the page layout}
+
+When
+\indexcommand{thehandoutsgeometry}%
+a new handout is loaded the page layout is temporarily changed using the \texttt{geometry} package.
+In general handouts do not have large paragraphs of text, so by default the margins are made smaller so that the whole page can be more efficiently used.
+
+When the package needs to change the page layout to that of the handouts it calls the command
+\begin{verbatim}
+	    \thehandoutsgeometry
+\end{verbatim}
+By default, the command \texttt{thehandoutsgeomtry} calls the command \texttt{newgeometry} \linebreak(from the \texttt{geometry} package)
+	which implements the desired changes.
+The exact command that the command \texttt{thehandoutsgeometry} executes by default is
+\begin{verbatim}
+	    \newgeometry{top=3cm,left=2cm,right=2cm,bottom=2.5cm}
+\end{verbatim}
+Any desired geometry for the handouts can thus be achieved by setting the command $\texttt{thehandoutsgeometry}$ 
+	to execute the \texttt{newgeometry} command with appropriate options.
+The possible options that can be sent to \texttt{newgeometry} are extensive and 
+ may be discovered in the documentation for the \texttt{geometry} package.
+
+For example, to have uniform margins of four centimeters, use the following:
+\begin{verbatim}
+	    \renewcommmand{\thehandoutsgeometry}{
+	        \newgeometry{margins=4cm}
+	    }
+\end{verbatim}
+
+To make no changes to the geometry -- that is, to have the handouts use the same layout as the rest of the document -- 
+	just set the command to do nothing:
+\begin{verbatim}
+	    \renewcommmand{\thehandoutsgeometry}{}
+\end{verbatim}
+
+
+
+\subsection{Editing the header and footers}
+
+
+The design of the handouts is implemented by editing the headers and footers using the \texttt{fancyhdr} package.
+All of the handouts are within the \texttt{studenthandout} fancy page style.
+This way, the headers and footers of the handouts can be styled without affecting the rest of the document.
+
+To change the default handout style, use the appropriate commands from the \texttt{fancyhdr} package.
+Make the changes to the fancy page style \texttt{studenthandout}.
+For example, the following code removes the horizontal lines of the headers and footers and removes
+	all of the handout information, except for the handout's full title which is placed in the center of the header.
+\begin{verbatim}
+	    \fancypagestyle{studenthandout}{
+	        \renewcommand{\headrulewidth}{0pt}
+	        \renewcommand{\footrulewidth}{0pt}
+	        \fancyhf{}
+	        \fancyhead[C]{\thehandoutfulltitle}
+	    }
+\end{verbatim}
+When changing the handout style the handout output commands in the next section will likely be needed.
+
+\subsection{Handout output commands}
+When editing the style there are a number of commands available that print information such as the current handout's title.
+None of these commands take an argument.
+As is commonplace in \Latex{}, using a command with no argument can result in the whitespace that follows being gobbled up.
+If this happens use the command with braces after; for example \verb$\thehandoutnumber{}$.
+
+
+\vspace{\baselineskip}
+\noindent
+The commands that print information specific to a given handout are as follows.
+\begin{itemize}
+
+	\item \verb$\thehandoutnumber$		\indexcommand{thehandoutnumber}
+
+		Print the number of the current handout.
+		This is the unique number of the handout within the unit.
+		To print the full handout number, write
+	
+		\begin{verbatim}
+			    \theunitnumber.\thehandoutnumber
+		\end{verbatim}
+
+	\item \verb$\thehandoutitle$		\indexcommand{thehandouttitle}
+
+		Print the title of the current handout.
+	\item \verb$\thehandoutfulltitle$	\indexcommand{thehandoutfulltitle}
+
+		Print the full title of the current handout.
+		This will read something like `Handout 3.4: Handout Title', or, if the handout has no title, simply `3.4'.
+
+	\item \verb$\thehandoutpage$		\indexcommand{thehandoutpage}
+
+		Print the current handout page number.
+		This is distinct from the document page number as each handout begins at Page 1.
+		To print the document page number use the usual command \verb$\thepage$.
+
+\end{itemize}
+
+\vspace{\baselineskip}
+\noindent
+The commands that print information about the current unit or the handouts as a whole are as follows.
+\begin{itemize}
+	\item	\verb$\theunitnumber$		\indexcommand{theunitnumber}
+
+		Print the number of the current unit.
+	
+	\item 	\verb$\theunittitle$		\indexcommand{theunittitle}
+
+		Print the title of the current unit, as set through the \texttt{setunittitle} command.
+		If the current unit's title has not been set, this command will do nothing.
+
+	\item 	\verb$\theunitfulltitle$		\indexcommand{theunitfulltitle}
+
+		Print the full title of the current unit.
+		This will read something like `1: Unit Title'.	
+		If the unit's title has not been set the full title will just read `1`.
+
+	\item	\verb$\thehandoutslabel$	\indexcommand{thehandoutslabel}
+
+		Print the handouts label -- that is, the word or phrase that says what the handouts are.
+		By default this is `Handout' but it can be changed;
+			see section \ref{sec:label} above.
+
+	\item 	\verb$\thehandoutscredit$	\indexcommand{thehandoutscredit}
+
+		Print the handouts credit.
+		This is by default blank but may be set to include information like the teacher's name or the institution's name; see section \ref{sec:credit} above.
+\end{itemize}
+
+\vspace{\baselineskip}
+\noindent
+Finally, the package provides a command
+\indexcommand{fullhandoutinfo}
+\begin{verbatim}
+	    \fullhandoutinfo
+\end{verbatim}
+which outputs a table containing all nine pieces of information from above, as well as the output of the command \verb$thepage$. 
+This command is intended for debugging and is not designed to be used in the final document.
+
+
+
+\newpage
+
+\printindex
+
+
+
+
+\end{document}
+
+
+
+
+