summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/handout/handout.tex
blob: dc483101d1475e21ef09550fe496340ae79231c3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
\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 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}
\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}