\documentclass{ltxdockit}[2011/03/25]
\usepackage{btxdockit}
\usepackage{fontspec}
\usepackage[mono=false]{libertine}
\usepackage{microtype}
\usepackage[american]{babel}
\usepackage[strict]{csquotes}
\setmonofont[Scale=MatchLowercase]{DejaVu Sans Mono}
\usepackage{shortvrb}
\usepackage{pifont}
\usepackage{minted}
\usepackage{bidi}
% Meta-datas
\titlepage{%
title={Making handout},
subtitle={to support your talk},
email={maieul <at> maieul <dot> net},
author={Maïeul Rouquette},
revision={1.6.0},
date={21/04/2017},
url={https://github.com/maieul/handout}}
\begin{document}
\printtitlepage
\tableofcontents
\section{Introduction}
\subsection{Goal}
In some fields of scholarship, a beamer does not offer good support when giving a talk. For example, in classical philology, the main sources are text, and it will be better to distribute a handout to the audience with extracts of the texts about which we will talk.
The package supports preparation of such handouts when writing the talk.
\subsection{Credits}
This package was created for Maïeul Rouquette's PHD\footnote{\url{http://apocryphes.hypothese.org}.} in 2014. It is licenced under the \emph{\LaTeX\ Project Public Licence}.\footnote{\url{http://latex-project.org/lppl/lppl-1-3c.html}.}
All issues can be submitted, in French or English, on the GitHub issues page.\footnote{\url{https://github.com/maieul/handout/issues}.}
\subsection{French tutorial}
As the idea for the package behavior came from French \LaTeX\ users\footnote{\url{http://fr.comp.text.tex.narkive.com/pXMop2kE/fabrication-d-un-exemplier}.}, and as the package's author speaks French as a native language, a French tutorial is available in \url{http://geekographie.maieul.net/136}.
All files in the examples’ folder are in French, but the effect of the commands they use should still be clear. They have to be run with \XeLaTeX.
\section{Basis}
The package can be loaded very quickly with the standard command \cs{usepackage}
\begin{minted}{tex}
\usepackage{handout}
\end{minted}
+The idea of the this package is to prepare a handout during the writing of a paper. When you want to add something to your handout, just write it in an external file, and call this external file with the command \cs{handout}:
\begin{minted}{tex}
Your text
\handout{folder/example}
Your text
\end{minted}
The PDF output will contain two parts:
\begin{enumerate}
\item Your paper.
\item The handout.
\end{enumerate}
You have just to split your pdf in two parts to obtain your handout for your audience.
See example~1.
\section{Code to be run at the beginning / at the end of the handout}
You can execute any code at the beginning of the handout by defining a command \cmd{beforehandout}. For example, to suppress the extra margins of the \env{quotation} environment:
\begin{minted}{tex}
\newcommand{\beforehandout}{%
\renewenvironment{quotation}{}{}%
}
\end{minted}
See example~2.
Note that some actions are always performed before the handout:
\begin{itemize}
\item Start a new page.
\item Reset page, footnote, table and figure counters.
\item Disable \cmd{index} and \cmd{label} command.
\end{itemize}
You can also execute any code at the end of the handout by defining a command \cmd{afterhandout}.
For example, if you want to add additional remarks on your handout, but not in your main text.
\begin{minted}{tex}
\newcommand{\afterhandout}{%
Additional remarks.
}
\end{minted}
\section{Putting all your examples in a single folder}
In most cases, all your external files will be in a single folder. So you can fix this folder with the package's option \opt{dir}:
\begin{minted}{tex}
\usepackage[dir=folder]{handout}
...
Your text
\handout{example}
Your text
\end{minted}
See example~3.
\section{Recopying the sectioning commands in the handout}
If you want your handout be organized with the same sectioning commands as your main paper, you can use the option \opt{sectioning} when loading the package. See example~4.
\section{Numbering the examples}
The package option \opt{numbering} automatically numbers the examples. Each example's number is by default printed in the margin, in a frame. See example~5.
To customize number's presentation, you can redefine three commands:
\begin{enumerate}
\item \cmd{thehandoutnumber} to redefine the way the number is displayed. Standard is:
\begin{minted}{tex}
\renewcommand{\thehandoutnumber}{\fbox{\arabic{handoutnumber}}}
\end{minted}
See \LaTeX\ documentation on counter's appearance.
\item \cmd{handoutnumber} to redefine the position of the number. Standard is:
\begin{minted}{tex}
\newcommand{\handoutnumber}[1]{\marginpar{#1}}
\end{minted}
\item \cmd{handoutnumberintxt}, to redefine the position of the number in the main text. Standard is:
\begin{minted}{tex}
\newcommand{\handoutnumberintxt}[1]{\handoutnumber{#1}}
\end{minted}
\end{enumerate}
\section{Temporarily disabling the handout generation}
The package option \opt{disabled} allows you to disable the handout's generation.
\label{enablehandout}You can also disable it for only some parts of the text: use \cmd{disablehandout} to disable the handout's generation from the current point and \cmd{enablehandout} to enable it from the current point.
\label{printing} You can also use \opt{printing=false}, which makes \LaTeX\ number the examples without producing the handout.
\section{Advanced use}
\subsection{Conditional code}
The argument of a \cmd{onlyhandout} command will be printed only in the handout. Conversely, the argument of a command \cmd{nothandout} will be printed only in the main text. See example~6.
\subsection{Insert code in the handout}
\subsubsection{\cmd{forhandout} and \cmd{forhandout*}}\label{forhandout}
The argument of the \cmd{forhandout} command will be added to the handout, even if used outside any included file.
All the commands inside will be expanded, except the one which starts argument..
The \cmd{forhandout} command is quite complex to manage, but can be useful if you want to insert bibliographic references automatically into your handout. If you use \emph{biblatex} to manage your bibliography, you can define a \cmd{citehandout} command with this code:
\begin{minted}{tex}
\newcommand{\citehandout}{%
\AtNextCitekey{%
\forhandout{%
\beforehandoutref%
}%
\forhandout{%
\cite[\strfield{postnote}]{\strfield{entrykey}}%
}%
\forhandout{%
\afterhandoutref%
}%
}%
}
\newcommand{\beforehandoutref}{\par\noindent\hspace{-2\parindent}}
\newcommand{\afterhandoutref}{\par\vskip0.25\baselineskip}
\end{minted}
You can call the \cmd{citehandout} command before citation commands when you want the reference to be copied to the handout. See example~7 and the \emph{biblatex} handbook.
Note that the citation tracker is automatically reset at the beginning of the handout.
The starred version of \cmd{citehandout} command will not expand any macro inside the argument. For example, if you need to write instructions for readers:
\begin{minted}{latex}
\forhandout{Read the three following texts, looking for:
\begin{itemize}
\item Places.
\item Topics.
\item Characters.
\end{itemize}
}
\end{minted}
\subsubsection{\cmd{AtEveryHandout}}\label{forhandout}
You can also add define a \cs{AtEveryHandout} command to be executed in the handout, before each content added to the handout.
\section{Change history}
\begin{changelog}
\begin{release}{1.6.0}{2017-04-21}
\item Add starred version of \cs{forhandout} macro \see{forhandout}.
\end{release}
\begin{release}{1.5.0}{2016-11-15}
\item Reset automatically table and figure counters before typesetting handout.
\end{release}
\begin{release}{1.4.0}{2016-10-24}
\item Add possibility to add additional content before every element of an handout.
\end{release}
\begin{release}{1.3.0}{2016-10-13}
\item Add possibility to add additional content at the end of the handout.
\end{release}
\begin{release}{1.2.1}{2015-01-06}
\item Optimize performance with \opt{sectioning} option.
\end{release}
\begin{release}{1.2.0}{2015-01-06}
\item Add new option printing. \see{printing}
\item Optimize performance.
\end{release}
\begin{release}{1.1.0}{2014-12-15}
\item Add \cmd{enablehandout} and \cmd{disablehandout}. \see{enablehandout}
\end{release}
\begin{release}{1.0.1}{2014-05-23}
\item Also disable indexing in the handout when using multiple index.
\end{release}
\begin{release}{1.0.0}{2014-03-20}
\item First public release.
\end{release}
\end{changelog}
\end{document}