summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/sepfootnotes/sepfootnotes.tex
blob: 4000f00fad0e9c8c4de61a7817563abb1a4d6870 (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
% Copyright (C) 2013-2016 Eduardo C. Lourenço de Lima
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
% version 1.3 of this license or (at your option) any later
% version.  The latest version of this license is in
%
%   http://www.latex-project.org/lppl.txt
%
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
\documentclass{ltxdoc}
\usepackage{sepfootnotes}
\usepackage{color}
\definecolor{myblue}{rgb}{0,0.2,0.6}

\newenvironment{Description}
 {\par\medskip\noindent\ignorespaces}{}

\newenvironment{synopsis}
 {\begin{list}{}
  {\setlength\parsep{0pt}
   \setlength\itemsep{0pt}}}
 {\end{list}}

\newenvironment{syntax}
 {\par\noindent \textbf{Syntax:}\begin{list}{}
  {\setlength\parsep{0pt}
   \setlength\itemsep{0pt}}}
 {\end{list}}

\newenvironment{example}
 {\par\noindent \textbf{Example:}\begin{list}{}
  {\setlength\parsep{0pt}
   \setlength\itemsep{0pt}}}
 {\end{list}}

\newcounter{example}
\newenvironment{Example}[1]
 {\stepcounter{example}\subsection*{Example \theexample}#1}
 {}

\newenvironment{page}
 {\begin{center}\begin{minipage}[t]{0.5\linewidth}}
 {\end{minipage}\end{center}}
\newcommand\TODO{\texttt{Todo:}}
\newcommand\fileversion{0.3c}
\newcommand\filedate{July 18, 2016}
\begin{document}
\title{The \textsf{\color{myblue} sepfootnotes} package,\thanks{This document corresponds to \textsf{sepfootnotes}~\fileversion, dated~\filedate.
I am grateful to Michael Sellhoff, Sam Foster, Mats, and David Carlisle for their valuable feedback on \texttt{sepfootnotes} and to Dan Luecking for the basic idea implemented in this package.}\\{or a footnote to Plato}}
\author{Eduardo C. Louren\c{c}o de Lima \\ \texttt{elourenco@phi.pro.br}}
\maketitle


        \begin{abstract}\noindent This package supports footnotes and endnotes from separate files.  This is achieved with commands |\sepfootnotecontent| and |\sepfootnote|; the former defines the content of a note, while the latter typesets that note.\end{abstract}

                           \section*{Introduction}

        Standard |\footnote| and |\endnote| both take a note as a mandatory argument.  Because notes have to be embedded in the paragraph to which they refer, sentences are often split up into two\footnote {This is precisely what this footnote does to the first paragraph of this document. There are more than thirty words between `two' and `or more' in the code of an otherwise short paragraph.} or more parts.  Consequently, footnotes and endnotes may disrupt the flow of reading and editing {\LaTeX} prose.\footnote {In a posting to \texttt{texhax.tug.org} in April 2010, someone complained that using footnotes ``tends to disrupt the flow of the document on the screen and makes editing the text itself harder'', and asked about the possibility of ``putting all of the footnotes in a separate file''~\cite{Nicholas Cole}.  Another user, back in 2004, remarked that the ``only thing I missed about word processors was the ability to keep footnote text at the bottom of the page, or in a separate window. I often have extensive footnotes, and don't want them cluttering up my main body text when I'm composing''~\cite{Luecking}.} This can be an issue for those who make extensive use of notes, such as philosophers and people from the humanities in general.

        The |sepfootnotes| package gets around this inconvenience by separating note input from usage.  That is, it provides a command to define what a particular note says, and another command to insert that note later on in the document.

        Note definitions may be grouped together---in no particular order---in the preamble, at the beginning of chapters or sections, right before a paragraph, or even in a \emph{separate file}. In that way, the main body is less cluttered.

        You may use |sepfootnotes| and standard |\footnote| simultaneously; the same goes for |\footcite| from |biblatex|.


\newpage

                               \section{Synopsis}


                    \subsection*{Default footnote apparatus}

\begin{synopsis}
\item |\sepfootnotecontent| \marg{key} \marg{content}
\item |\sepfootnote| \marg{key}
\end{synopsis}


            \subsection*{User-defined footnote or endnote apparatus}

\begin{synopsis}
\item |\newfootnotes | \marg{prefix}
\item |\newfootnotes*| \marg{prefix}\medskip
\item |\newsymbolfootnotes| \oarg{master counter} \marg{prefix}\medskip
\item |\newendnotes| \marg{prefix}\bigskip
\item |\|\meta{prefix}|notecontent| \marg{key} \marg{content}
\item |\|\meta{prefix}|note| \marg{key}
\item |\|\meta{prefix}|notemark| \marg{key}
\item |\|\meta{prefix}|notetext| \marg{key}
\item |\print|\meta{prefix}|note| \marg{key}\medskip
\item |\|\meta{prefix}|quicknote| \marg{content}
\end{synopsis}

                         \subsection*{Endnote-specific}

\begin{synopsis}
\item |\the|\meta{prefix}|notes|
\item |\addto|\meta{prefix}|notes| \marg{text}
\end{synopsis}

                            \subsection*{Formatting}

\begin{synopsis}
\item |\renewcommand\the|\meta{prefix}|note|
\item |\renewcommand\the|\meta{prefix}|mark|
\item |\renewcommand\make|\meta{prefix}|mark|
\item |\renewcommand\|\meta{prefix}|notesize|
\item |\renewcommand\|\meta{prefix}|noteformat|\medskip
\item |\renewenvironment {|\meta{prefix}|notes}|
\end{synopsis}


                           \section{Basic usage}


\begin{Description}
\DescribeMacro{\sepfootnotecontent}
First define the \meta{content} of a footnote by
assigning it a \meta{key} that uniquely identifies it:
\begin{synopsis}
\item |\sepfootnotecontent| \marg{key} \marg{content}
\end{synopsis}
\end{Description}


\begin{Description}
\DescribeMacro{\sepfootnote}
Then insert that footnote anywhere in the main body by means of the
same \meta{key} as used before:
\begin{synopsis}
\item |\sepfootnote| \marg{key}
\end{synopsis}
\end{Description}


% ------------------------------ Intermediate ---------------------------------

                           \section{Advanced usage}

\begin{Description}
\DescribeMacro{\newfootnotes}
\DescribeMacro{\newfootnotes*}
\DescribeMacro{\newsymbolfootnotes}
\DescribeMacro{\newendnotes}
The |sepfootnotes| apparatus described above is available by default.
But you may create as many distinct and independent footnote or endnote apparatus as needed:
\begin{synopsis}
\item |\newfootnotes  |\marg{prefix}

Create an apparatus of footnote commands named after \meta{prefix} using the standard |footnote| counter.\bigskip

\item |\newfootnotes* |\marg{prefix}

Create an apparatus of footnote commands named after \meta{prefix} using its own counter.\bigskip

\item |\newsymbolfootnotes| \oarg{master counter} \marg{prefix}

Create an apparatus of symbol-footnote commands named after \meta{prefix} using its own counter. The optional argument \meta{master counter} can be anything like |page|, |section|, |chapter|, etc.  The default master counter is |page|. The series of symbols is reset each new page, so that * marks the first symbol-footnote on any page, whereas $\dag$ marks the second, $\ddag$ the third, and so on.\bigskip

\item |\newendnotes |\marg{prefix}

Create an apparatus of endnote commands named after \meta{prefix} using its own counter.
\end{synopsis}
\end{Description}

\begin{Description}
\DescribeMacro{\<prefix>notecontent}
This is how to typeset notes: once a note apparatus of any kind is created, you need to assign a \meta{key} to a \meta{content}:
\begin{synopsis}
\item |\|\meta{prefix}|notecontent| \marg{key} \marg{content}
\end{synopsis}
\end{Description}

\begin{Description}
\DescribeMacro{\<prefix>note}
\DescribeMacro{\<prefix>notemark}
\DescribeMacro{\<prefix>notetext}
\DescribeMacro{\print<prefix>content}
And then use the \meta{key} to typeset that content using any of the following:
\begin{synopsis}
\item |\|\meta{prefix}|note| \marg{key}

Typeset a note identified by \meta{key}.\bigskip

\item |\|\meta{prefix}|notemark| \marg{key}

Typeset just the mark identified by \meta{key} without the corresponding note.\medskip

\item |\|\meta{prefix}|notetext| \marg{key}

Typeset just the note identified by \meta{key} without the corresponding mark.\medskip

\item |\print|\meta{prefix}|note| \marg{key}

Just print the \meta{content} identified by \meta{key}.\medskip

\item |\|\meta{prefix}|quicknote| \marg{content}

Typeset a note with \meta{content} without a key.
This is similar to standard |\footnote| \marg{content},
and may be useful for short notes, such as ``Idem.''
\end{synopsis}
\end{Description}

\newpage

\begin{Description}
\DescribeMacro{\the<prefix>notes}
\DescribeMacro{\addto<prefix>notes}
\DescribeMacro{\<prefix>notesize}
\DescribeEnv{<prefix>notes}
\DescribeMacro{\the<prefix>note}
\DescribeMacro{\the<prefix>mark}
\DescribeMacro{\make<prefix>mark}
\DescribeMacro{\<prefix>noteformat}
These are endnote-specific:
\begin{synopsis}
\item |\the|\meta{prefix}|notes|

Typeset the actual endnotes at the end of a chapter or section.\bigskip

\item |\addto|\meta{prefix}|notes| \marg{text}

Add \meta{text} to endnotes.

Suggestion: |\subsection*|\bigskip

\item |\renewcommand\|\meta{prefix}|notesize|

Define the fontsize in which to typeset endnotes.

Default: |\footnotesize|\bigskip

\item |\renewenvironment {|\meta{prefix}|notes}|

Define the environment in which endnotes are typeset.

Default: |\|\meta{prefix}|notesize\setlength\parskip\footnotesep|\bigskip

\item |\renewcommand\the|\meta{prefix}|note|

Define how endnote numbers are typeset.

Default: |\arabic {|\meta{prefix}|note}|\bigskip

\item |\renewcommand\the|\meta{prefix}|mark|

Define how endnote marks are typeset.

Default: |\the|\meta{prefix}|note|\bigskip

\item |\renewcommand\make|\meta{prefix}|mark|

Define how a particular endnote mark is typeset.

Default:\footnote{Adapted from the {\LaTeX2e} sources.} |\hbox {\normalfont\the|\meta{prefix}|mark.\ }|\bigskip

\item |\renewcommand\|\meta{prefix}|noteformat|

Define how a particular endnote is typeset.

Default:\footnote{Adapted from the \texttt{endnotes} package.}

|\noindent\rightskip\z@ \leftskip\z@|\newline
|\leavevmode\llap{\make|\meta{prefix}|mark}|
\end{synopsis}
\end{Description}


\section {Package options}

\begin{list}{}{}
\item[|warn|]  Print warning messages. (Default.)
\item[|error|] Print warning messages, halt, and wait for user input.
\item[|quiet|] Suppress warning and error messages.
\item[|global|] Notes defined within environments and groups take global scope and become available throughout, as if they were defined in the preamble.
\end{list}

\section{Examples}

% -------------------------------- Examples -----------------------------------
\begin{Example}
{How to typeset `Socrates's pupil' as a footnote to Plato using the default |sepfootnotes| apparatus:}
\begin{verbatim}
\documentclass{article}
\usepackage{sepfootnotes}
\sepfootnotecontent{Plato}{Socrates's pupil.}
\begin{document}
This was first brought up by the great Plato.\sepfootnote{Plato}
\end{document}
\end{verbatim}
\end{Example}

\begin{Example}
{How to typeset `Socrates's pupil' as a footnote to Plato using a \emph{user-defined} footnote apparatus with prefix |a-|}
\begin{verbatim}
\documentclass{article}
\usepackage{sepfootnotes}
\newfootnotes{a}
\anotecontent{Plato}{Socrates's pupil.}
\begin{document}
This was first brought up by the great Plato.\anote{Plato}
\end{document}
\end{verbatim}
\end{Example}

\begin{Example}
{How to typeset a footnote \emph{from a separate file} using a user-defined apparatus with prefix |b-|}
\begin{itemize}\item mynotes.tex:
\begin{verbatim}
\bnotecontent{Plato}{Socrates's pupil.}
\end{verbatim}
\item document.tex:
\begin{verbatim}
\documentclass{article}
\usepackage{sepfootnotes}
\newfootnotes{b}
\input{mynotes}
\begin{document}
This was first brought up by the great Plato.\bnote{Plato}
\end{document}
\end{verbatim}
\end{itemize}
\end{Example}

\begin{Example}
{How to typeset `Socrates's pupil' as a \emph{symbol-footnote} to Plato using a user-defined footnote apparatus with prefix |symbol-|}
\begin{verbatim}
\documentclass{article}
\usepackage{sepfootnotes}
\newsymbolfootnotes{symbol}
\symbolnotecontent{Plato}{Socrates's pupil.}
\begin{document}
This was first brought up by the great Plato.\symbolnote{Plato}
\end{document}
\end{verbatim}
\end{Example}

\begin{Example}
{How to typeset `Socrates's pupil' as an \emph{endnote} to Plato using a user-defined endnote apparatus with prefix |x-|}
\begin{verbatim}
\documentclass{article}
\usepackage{sepfootnotes}
\newendnotes{x}
\xnotecontent{Plato}{Socrates's pupil.}
\begin{document}
This was first brought up by the great Plato.\xnote{Plato}
\section*{Notes}
\thexnotes
\end{document}
\end{verbatim}
\end{Example}

\begin{Example}
{How to typeset a footnote to Plato \emph{and} an endnote to Homer from a separate file \emph{in no particular order}:}

\begin{itemize}
\item mynotes.tex:
\begin{verbatim}
\xnotecontent{Homer}{The greatest of ancient poets.}
\anotecontent{Plato}{Socrates's pupil.}
\end{verbatim}

\item document.tex:
\begin{verbatim}
\documentclass{article}
\usepackage{sepfootnotes}
\newfootnotes{a}
\newendnotes{x}
\input{mynotes}
\begin{document}
 This was first brought up by the great Plato.\anote{Plato}
 But an antecedent is to be found in Homer.\xnote{Homer}
\section*{Notes}
\thexnotes
\end{document}
\end{verbatim}
\end{itemize}

\end{Example}



\begin{thebibliography}{1}

  \bibitem{Nicholas Cole}
  \texttt{http://tug.org/mailman/htdig/texhax/2010-April/014558.html}

  \bibitem{Luecking}
  \texttt{http://www.44342.com/tex-f809-t9440-p1.htm}.

%  \bibitem{Companion}
%  Frank Mittelbach, and Michel Goossens, with Johannes Braams, David Carlisle,
%  and Chris Rowley.
%  \newblock \emph{The {\LaTeX} Companion}. 2nd
%  \newblock Addison~Wesley, 2004.
%  \newblock ISBN~\mbox{0-201-36299-6}.

\end{thebibliography}

\end{document}