summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/beamer-contrib/hackthefootline/doc/hackthefootline-doc.tex
blob: 437d5308f133db30bc607a8f2069d8a97c25e0ce (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
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
%%	This is file 'hackthefootline-doc.tex', Version 2018-01-29
%%	Copyright 2017-18 Sebastian Friedl <sfr682k@t-online.de>
%% 
%%	This work may be distributed and/or modified under the conditions of the LaTeX Project
%%	Public License, either version 1.3c of this license or (at your option) any later version.
%%	The latest version of this license is available at
%%		http://www.latex-project.org/lppl.txt
%%	and version 1.3c or later is part of all distributions of LaTeX version 2008-05-04 or later
%%
%%	This work has the LPPL maintenace status 'maintained'.
%%	The current maintainer of this work is Sebastian Friedl.
%%
%%	This work consists of the files hackthefootline.sty, hackthefootline-examples.tex and
%%	hackthefootline-doc.tex
%%
%%	-------------------------------------------------------------------------------------------
%%
%%	The hackthefootline package is a tool providing arbitrary footline selection and
%%	configuration for LaTeX beamer's standard themes (it may work with other themes as well)
%%
%%	-------------------------------------------------------------------------------------------
%%
%%	Please report bugs and other problems as well as suggestions for improvements
%%	to my email address (sfr682k@t-online.de).
%%
%%	-------------------------------------------------------------------------------------------
%%
%%	Acknowledgement:
%%	The basic layout of the two- and three-column footline is based on the original LaTeX
%%	beamer split and infolines outer themes written by Till Tantau.
%%
%%	-------------------------------------------------------------------------------------------

% !TeX spellcheck = en_GB

% !TeX document-id = {681db40e-7a84-4428-b4f4-84e230e3ba79}
% !TeX program=lualatex
% !TeX TXS-program:compile=txs:///lualatex/[--shell-escape]


\documentclass[11pt]{ltxdoc}

\usepackage[erewhon]{newtxmath}
\usepackage[no-math]{fontspec}
\usepackage{polyglossia}
\setdefaultlanguage{english}

\usepackage{csquotes}
\usepackage{hologo}
\usepackage[pdfborder={0 0 0}, unicode]{hyperref}
\usepackage[english]{selnolig}
\usepackage{tikz}

\newcommand{\DescribeOption}[3]{
  \DescribeMacro{#1}
  \begin{minipage}[t]{\textwidth}
    \textit{\textbf{#2}}\dotfill~\par
    \begingroup
    \vspace{0.5em}#3\par
    \endgroup
  \end{minipage}%
  \bigskip\medskip%
}


\parindent 0pt

\setmainfont{erewhon}
\setsansfont[Scale=MatchLowercase]{Source Sans Pro}
\setmonofont[Scale=MatchLowercase]{Hack}

\usepackage[left=4.50cm,right=2.75cm,top=3.25cm,bottom=2.75cm,nohead]{geometry}

\hyphenation{coun-ted}
\MakeShortVerb{"}


\title{The \texttt{\bfseries hackthefootline} package \\ {\large\url{https://github.com/SFr682k/hackthefootline}}}
\author{Sebastian Friedl \\ \href{mailto:sfr682k@t-online.de}{\ttfamily sfr682k@t-online.de}}
\date{2018/01/29}

\hypersetup{pdftitle={The hackthefootline package},pdfauthor={Sebastian Friedl}}

\begin{document}
	\maketitle
	\thispagestyle{empty}
	
	\begin{center} \itshape
		Dedicated to all the \LaTeX\ beamer users \dots
		
		\medskip
		\dots who load two different themes in the same presentation \\ or redefine commands to obtain the desired footline \dots
		
		\medskip
		\dots and the other guys just using "\setbeamertemplate"
	\end{center}
	
	\medskip
	\begin{abstract}
		\parindent0pt\noindent%
		\textbf{Arbitrary footline selection and configuration for \LaTeX\ \texttt{beamer}'s standard themes.} \\
		"hackthefootline" is a package taking over, defining and redefining different footlines, so they can be configured using key-value syntax.
		
		\medskip
		The basic layout of the two- and three-column footline is based on the original \LaTeX\ beamer split and infolines outer themes written by Till Tantau.
	\end{abstract}
	
	
	\tableofcontents
	
	\clearpage
	
	
	
	\subsection*{Dependencies and other requirements}
	\addcontentsline{toc}{subsection}{Dependencies and other requirements}
	%
	\DescribeMacro{beamer}
	Since "hackthefootline" is designed to modify "beamer"'s footlines, it is incompatible to any other document class. Therefore, load this package only in "beamer" documents!
	
	\medskip
	\DescribeMacro{ifthen}
	This package is required to compare the length of some boxes.
	
	\medskip
	\DescribeMacro{pgfkeys}
	"hackthefootline" heavily depends on the "pgfkeys" package for handling the whole key-value stuff.
	
	\bigskip
	Also, additional sophisticated features require the following packages:
	
	\medskip
	\DescribeMacro{appendixnumber-}\DescribeMacro{beamer}
	\textit{\bfseries Only required when using \texttt{beamer} version 3.48 and older.}
	This package is only required when using "beamer" version 3.48 or older. If you are using "beamer" version 3.49 or later\footnote{i. e. \TeX{}Live 2018 and later}, "hackthefootline" will rely on "beamer"'s internal appendix frame numbering mechanisms.
	
	\medskip
	\DescribeMacro{etoolbox}
	Provides access on \hologo{eTeX} primitives
	
	\medskip
	\DescribeMacro{calc}
	Required for basic calculations

	\medskip
	\DescribeMacro{numprint}
	Prints out numbers, counters and lengths
	
	\bigskip
	However, the four latter dependencies can be removed by using some package options. See section \ref{behavioropts} for further details.
	
	
	\subsection*{Notice: Behavior inside the presentation's appendix}
	\addcontentsline{toc}{subsection}{Notice: Behavior inside the presentation's appendix}
	By default, appendix frames are \emph{not} counted into the total number of frames when using "hackthefootline". Appendix frame numbers will be counted from 1 when using fraction frame numbers. \\
	Also, frame numbers won't be displayed on footlines inside the appendix until this is changed using the means of the "\htfconfig" command.
	
	\medskip
	This behavior can be suppressed by passing the "countappendixframes" option.
	
	
	\subsection*{License}
	\addcontentsline{toc}{subsection}{License}
	\textcopyright\ 2017-18 Sebastian Friedl
	
	\smallskip
	This work may be distributed and/or modified under the conditions of the \LaTeX\ Project Public License, either version 1.3c of this license or (at your option) any later version.
	
	\smallskip
	The latest version of this license is available at \url{http://www.latex-project.org/lppl.txt} and version 1.3c or later is part of all distributions of \LaTeX\ version 2008-05-04 or later.
	
	\smallskip
	This work has the LPPL maintenace status \enquote*{maintained}. The current maintainer of this work is Sebastian Friedl. \\
	This work consists of the following files:
	\begin{itemize} \itemsep 0pt
		\item "hackthefootline.sty"
		\item "hackthefootline-examples.tex" and
		\item "hackthefootline-doc.tex"
	\end{itemize}
	
	
	
	\clearpage



	% DOCUMENTATION PART ------------------------------------------------------------------------------------------------------------------------

	\section{Using the package}
	The "\usepackage[<Options>]{hackthefootline}" command loads the package\footnote{To do so, the package has to be installed in a location where \LaTeX\ is able to find it}. A list of all available options can be found in section \ref{packageoptions}.
	
	\medskip
	\textbf{Important note:} You \emph{have} to pass the \emph{footline's number of columns} as an option to the package (available: "onecol", "twocols" or "threecols"). If you don't do so, the footline gets removed completely. \\
	See section \ref{examples-setup} for some examples.
	
	
	
	\section{Package options} \label{packageoptions}
	\subsection{Options influencing the footline's configuration}
	These options determine the number of columns being used for the footline. \\
	You \emph{have} to pass one of these options when loading "hackthefootline"; otherwise the footline will be removed completely.
	
	\medskip
	\DescribeMacro{onecol}
	The \enquote{initial footline hack} produces a one--column footline
	
	\medskip
	\DescribeMacro{twocols}
	The \enquote{initial footline hack} produces a two--column footline
	
	\medskip
	\DescribeMacro{threecols}
	The \enquote{initial footline hack} produces a three--column footline
	
	\subsection{Options influencing the package's behavior} \label{behavioropts}
	These options can be passed to disable additional features and remove dependencies on other packages.
	
	\medskip
	\DescribeMacro{countappendix-}\DescribeMacro{frames}
	If the "countappendixframes" option is passed to the package, appendix frames are counted into the total number of frames. \\
	\textit{Removes the following dependencies:} "appendixnumberbeamer", "etoolbox"
	
	\medskip
	\DescribeMacro{nofun}
	Doesn't support frame numbers being shown as \enquote{percent of presentation} \\
	\textit{Removes the following dependencies:} "calc", "numprint"



	\section{Configuring the footline}
	The internal mechanisms of "hackthefootline" are using templates for displaying the provided information.
	Each template is available in different styles, which can be switched using the provided key value syntax:
	
	\medskip
	\DescribeMacro{\htfconfig}
	Use "\htfconfig{key1=value1, key2=value2, …}" to modify the current configuration of the footline. Changes apply instantly. \\
	See section \ref{examples-switchtemplates} for examples.
	
	\bigskip
	All available keys and values are listed below being depicted as follows:
	
	\medskip
	\DescribeOption{key}{possible values}{Description of the values' effects}
	
	\medskip
	\textbf{Annotations:}
	\begin{itemize}
		\item
			The default values of the keys depend on the number of columns chosen when loading the package. See section \ref{defaultconfig} for further details.
		\item
			\textit{Templates not visible} in the default configuration have been hidden by setting the value of the according key to "none". Apply another value to this key and the template will show up. \\
			\textit{Templates visible} in the default configuration can be hidden by setting the value of the according key to "none" (there's only one exception: "atsep"). \\
			See section \ref{examples-switchtemplates} for examples.
	\end{itemize}
	
	\bigskip
	\DescribeOption{cols}{one, two, three, none}{%
		The number of colums used for the footline:
		\begin{description}\itemsep0pt
			\item[one]
				Use a footline consisting of a single column
			\item[two]
				Use a footline consisting of two columns
			\item[three]
				Use a footline consisting of three columns
			\item[none]
				Remove the footline completely
		\end{description}
		
		Although the "cols" key's value changes, the other keys' values stay the same. \textbf{If you change the number of columns of a footline, the other keys should be adjusted as well.}
		
		\medskip
		\emph{Warning:} Changing this key's value too often might distract your audience.
	}
	
	\DescribeOption{title}{short, long, none}{%
		Sets the title type displayed in the footline:
		\begin{description}\itemsep0pt
			\item[short]
				Show the short title given in the square braces of the \texttt{\textbackslash title} command. \\
				When no short title is given, the long title will be used.
			\item[long]
				Show the long title given in the curly braces of the \texttt{\textbackslash title} command.
			\item[none]
				Don't show any title inside the footline
		\end{description}}
	
	\DescribeOption{authinst}{onlyauthor, onlyinst, instpths, authpths, both, none}{%
		Influences the way author and institute are displayed:
		\begin{description}\itemsep0pt
			\item[onlyauthor]
				Show only the author's name
			\item[onlyinst]
				Show only the institute's name
			\item[instpths]
				Show both, author and institute, but put the institute into parentheses
			\item[authpths]
				Show both, author and institute, but put the author into parentheses
			\item[both]
				Show both and separate them using a comma
			\item[none]
				Show neither author, nor institute
		\end{description}
		All templates use the values specified for short author / short institute.
	}
	
	\DescribeOption{date}{short, long, none}{%
		The date displayed in the footline:
		\begin{description}\itemsep0pt
			\item[short]
				Show the short date
			\item[long]
				Show the long date
			\item[none]
				Do not show any date
		\end{description}}
	
	\DescribeOption{framenrs}{counter, fraction, percent, none}{%
		Controls the type of frame number shown in the footline:
		\begin{description}\itemsep0pt
			\item[counter]
				Only show the number of the current frame
			\item[fraction]
				Show the number of the current frame as well as the total number of frames
			\item[percent]
				Display the current progress of the presentation displayed as a percent value \\
				When setting this value, make sure that you didn't pass the "nofun" option when loading the package, otherwise an error message will be thrown.
			\item[none]
				Do not show frame numbers
		\end{description}}
	
	\DescribeOption{atsep}{colon, comma, space}{%
		Sets the character used to separate author and title when using the "onecol" footline:
		\begin{description}\itemsep0pt
			\item[colon]
				Use a colon as separator
			\item[comma]
				Use a comma as separator
			\item[space]
				Use a space as separator
		\end{description}}
	
	
	
	\section{Default configurations} \label{defaultconfig}
	Depending on the selected number of columns, the default configuration of the footlines is as follows:
	
	\subsection*{One--column footline}
	"\htfconfig{%" \\
	"    title=short, authinst=both," \\
	"    date=none, framenrs=fraction, atsep=colon}" \\[\smallskipamount]
	\includegraphics[page=1,width=\textwidth, trim=0 0 0 15, clip]{hackthefootline-examples}
	
	\subsection*{Two--column footline}
	"\htfconfig{%" \\
	"    title=short, authinst=onlyauthor," \\
	"    date=none, framenrs=none}" \\[\smallskipamount]
	\includegraphics[page=2,width=\textwidth, trim=0 0 0 15, clip]{hackthefootline-examples}
	
	\subsection*{Three-column footline}
	"\htfconfig{%" \\
	"    title=short, authinst=instpths," \\
	"    date=short, framenrs=fraction}" \\[\smallskipamount]
	\includegraphics[page=3,width=\textwidth, trim=0 0 0 15, clip]{hackthefootline-examples}



	\section{Examples}
	\subsection{Setting up \texttt{hackthefootline}}\label{examples-setup}
	\paragraph{Example 1:}
	"\usepackage[onecol]{hackthefootline}" \\
	\textit{Effect:} A one-column footline \\
	\includegraphics[page=1, width=\textwidth, trim=0 0 0 15, clip]{hackthefootline-examples}
	
	
	\paragraph{Example 2:}
	"\usepackage[twocols]{hackthefootline}" \\
	\textit{Effect:} A two-column footline \\
	\includegraphics[page=2, width=\textwidth, trim=0 0 0 15, clip]{hackthefootline-examples}
	
	\paragraph{Example 3:}
	"\usepackage[threecols]{hackthefootline}" \\
	\textit{Effect:} A three-column footline \\
	\includegraphics[page=3, width=\textwidth, trim=0 0 0 15, clip]{hackthefootline-examples}
	
	\paragraph{Example 4:}
	"\usepackage{hackthefootline}" \\
	\textit{Effect:} The footline gets removed
	
	
	\subsection{Switching templates}\label{examples-switchtemplates}
	This section assumes, that the "\usepackage[twocols]{hackthefootline}" command was used to load the "hackthefootline" package. \\[\medskipamount]
	The preamble contains the following commands for setting the information about title, author, institute and date: \\[\smallskipamount]
	"\title[Short Introduction]{%" \\
	"    A short introduction on \texttt{hackthefootline}'s facilities}" \\
	"\author[S. Friedl]{Sebastian Friedl}" \\
	"\institute[Some Institute]{Some Institute far, far away}" \\
	"\date[2018/01/15]{January 15, 2018}"
	
	\medskip
	We will start with step 1 and continue further on, each step is changing the result of the last one.
	
	\paragraph{Initial style:}~ \\
	\includegraphics[page=4, width=\textwidth, trim=0 0 0 15, clip]{hackthefootline-examples}
	
	\paragraph{Step 1:} Show fraction frame numbers \\
	\textit{Command:} "\htfconfig{framenrs=fraction}" \\
	\textit{Effect:} \\
	\includegraphics[page=5, width=\textwidth, trim=0 0 0 15, clip]{hackthefootline-examples}
	
	\paragraph{Step 2:} Show the short version of the date \\
	\textit{Command:} "\htfconfig{date=short}" \\
	\textit{Effect:} \\
	\includegraphics[page=6, width=\textwidth, trim=0 0 0 15, clip]{hackthefootline-examples}
	
	\paragraph{Step 3:} In addition to the author, show the insitute in parentheses \\
	\textit{Command:} "\htfconfig{authinst=instpths}" \\
	\textit{Effect:} \\
	\includegraphics[page=7, width=\textwidth, trim=0 0 0 15, clip]{hackthefootline-examples}
	
	\paragraph{Step 4:} Show the long, full title \\
	\textit{Command:} "\htfconfig{title=long}" \\
	\textit{Effect:} \\
	\includegraphics[page=8, width=\textwidth, trim=0 0 0 15, clip]{hackthefootline-examples}
	
	\paragraph{Step 5:} The right column is too full now. Remove the frame numbers \\
	\textit{Command:} "\htfconfig{framenrs=none}" \\
	\textit{Effect:} \\
	\includegraphics[page=9, width=\textwidth, trim=0 0 0 15, clip]{hackthefootline-examples}
	
	\paragraph{Step 6:} Switch to a one-column footline and remove the date \\
	\textit{Command:} "\htfconfig{cols=one, date=none}" \\
	\textit{Effect:} \\
	\includegraphics[page=10, width=\textwidth, trim=0 0 0 15, clip]{hackthefootline-examples}
	
	\paragraph{Step 7:} Remove the footline \\
	\textit{Command:} "\htfconfig{cols=none}" \\
	\textit{Effect:} No footline will be shown (but a space above the frame's bottom …)
\end{document}