\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.5.0},
  date={15/11/2016},
  url={https://github.com/maieul/handout}}


\begin{document}

\printtitlepage
\tableofcontents

\section{Introduction}
\subsection{Goal}

In some fields of schol­ar­ship, a beamer does not of­fer good sup­port when giv­ing a talk. For ex­am­ple, in clas­si­cal philol­ogy, the main sources are text, and it will be bet­ter to dis­tribute a hand­out to the au­di­ence with ex­tracts of the texts about which we will talk.

The pack­age sup­ports prepa­ra­tion of such hand­outs when writ­ing 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}

The argument of the  \cmd{forhandout} command will be added to the handout, even if used outside any included file.

\emph{Be careful}: if the content of the argument starts with a command, this command won't be run before the handout.

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.

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.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}