summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/parnotes/parnotes.tex
blob: 662dc1aa628bf8b6d753bcd4574e442c3a53d1b2 (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

%!TEX program = lualatex

\documentclass[10pt]{article}
%\usepackage[USenglish,english]{babel}
\usepackage[USenglish]{babel}
%\selectlanguage{USenglish}
%\usepackage[no-math]{fontspec}
\usepackage[oldstyle]{Alegreya}
\usepackage[]{AlegreyaSans}
\setmonofont[Scale=MatchLowercase]{IBM Plex Mono}

%\defaultfontfeatures{Ligatures=TeX}
%\def\MinionDefaults{%
%	SizeFeatures = {
%		{Size =     -8.41, OpticalSize = 8, Numbers = Lining},
%		{Size = 8.41-13.1, OpticalSize = 11},
%		{Size = 13.1-20.0, OpticalSize = 19},
%		{Size = 20.0-,     OpticalSize = 72}},
%	Numbers = {OldStyle,Monospaced}}
%\setmainfont[\MinionDefaults,
%	BoldFont = {Minion Pro Semibold}]{Minion Pro}
%\setsansfont[Scale=MatchLowercase, BoldFont = {Myriad Pro Semibold}]{Myriad Pro}
%\setmonofont[Scale=MatchLowercase]{Consolas}

\usepackage{amsmath}
\usepackage{parnotes}
\usepackage{xcolor}
\usepackage[colorlinks]{hyperref}
\hypersetup{allcolors=blue}
\usepackage{varwidth}
\usepackage{accsupp}

%\DeclareRobustCommand\squelch[1]{%
%    \BeginAccSupp{method=plain,ActualText={}}#1\EndAccSupp{}}
%\def\squelchstyle{%
%    \BeginAccSupp{method=plain,ActualText={}}%
%    \aftergroup\aftersquelchstyle}
%\def\aftersquelchstyle{\EndAccSupp{}}

\usepackage{fancyhdr}
\fancypagestyle{plain}{%
    \fancyhf{}%
%    \fancyfoot[C]{\squelch{\thepage}}%
    \fancyfoot[C]{\thepage}%
    \renewcommand{\headrulewidth}{0pt}%
    \renewcommand{\footrulewidth}{0pt}%
}
\pagestyle{plain}
\usepackage{listings}
%\lstset{numbers=left,basicstyle={\small\ttfamily},numberstyle={\squelchstyle\color{gray}}}
\lstset{numbers=left,basicstyle={\scriptsize\ttfamily},numberstyle={\color{gray}}}
\usepackage{booktabs}
\usepackage{microtype}

\title{The \textsf{parnotes} package\parnote{This is rev.~3b, last modified 2019/07/23.}}
\author{Chelsea Hughes\parnote{See \texttt{parnotes.sty} for copyright details. The package has currently no maintainer.}}
\date{July 23, 2019}

\renewcommand{\parnotefmt}[1]{\centerline{\colorbox{black!10}{\parbox{0.82\textwidth}{\footnotesize\sffamily\noindent #1}}}}

\begin{document}
\maketitle
\parnotes
The \textsf{parnotes} package adds a new note type, \verb+\parnote+. Parnotes are set as normal, running paragraphs and may be placed two ways:
\begin{itemize}
\item Automatically, at the end of the paragraph
\item Manually, using the \verb+\parnotes+ command
\end{itemize}
This package was inspired by a question on the \TeX\ Stack Exchange\parnote{``Placing footnotes or endnotes at the end of the current paragraph'' at
\url{http://tex.stackexchange.com/questions/34746}} that asked for notes
which are placeable immediately after the paragraph in which they are mentioned, to avoid
the interruption posed by footnotes.

\parnotes
\bigskip
\section{Usage}
Load parnotes normally:

\medskip\fbox{\texttt{\textbackslash{}usepackage[}$\langle$\textit{options}$\rangle$\texttt{]\{parnotes\}}}

\medskip\noindent The package options are described in section 2.1.

\medskip\fbox{\texttt{\textbackslash{}parnote\{}$\langle$\textit{text}$\rangle$\texttt{\}}}

\medskip\noindent Place a parnote mark and assign it note $\langle$\textit{text}$\rangle$. This mark is placeable within headings but will not appear in the table of contents.

\medskip\fbox{\texttt{\textbackslash{}parnote[}$\langle$\textit{mark}$\rangle$\texttt{]\{}$\langle$\textit{text}$\rangle$\texttt{\}}}

\medskip\noindent As above, but use $\langle$\textit{mark}$\rangle$ instead of the standard auto-incrementing parnote mark.

\medskip\fbox{\begin{varwidth}{\textwidth}\texttt{\textbackslash{}begin\{autopn\}\\\textbackslash{}end\{autopn\}}\end{varwidth}}

\medskip\noindent Parnotes within an \texttt{autopn} environment are set automatically at the end of every paragraph. This behavior does not carry into nested environments. To set parnotes inside another environment, nest \texttt{autopn} within it or use \verb+\parnotes+.

\medskip\fbox{\texttt{\textbackslash{}parnotes}}

\medskip\noindent Place all parnotes immediately. Use it after every paragraph for \texttt{autopn}-like behavior outside \texttt{autopn} (or where \texttt{autopn} doesn’t apply).

\medskip\fbox{\texttt{\textbackslash{}parnotereset}}

\medskip\noindent Reset the parnote number. This maps to \verb+\setcounter{parnotemark}{1}+.

\medskip\fbox{\texttt{\textbackslash{}parnoteclear}}

\medskip\noindent Reset the parnote number and also delete any pending parnotes.

\medskip\fbox{\texttt{\textbackslash{}parnoteref\{$\langle$\textrm{\textit{label}}$\rangle$\}}}

\medskip\noindent Refer to previous parnote mark $\langle$\textit{label}$\rangle$. Use the standard \LaTeX\ macro \verb+\label+ within a parnote to assign it a label. You may also use the standard \LaTeX\ reference macros \verb+\ref+ and \verb+\pageref+.

\section{Configuration}
Configure \textsf{parnotes} using package options, or manually using format macros.

\subsection{Package options}
The following options are provided:

\noindent\begin{tabbing}
\texttt{restart}\hspace{0.75in}\=Reset the parnote number each time parnotes are placed.\\
\texttt{reset}\>Alias name for \texttt{restart} to match what other packages use.\\
\texttt{roman}\>Use lowercase Roman numerals instead of Arabic numerals for\\
\>parnote marks. Specify this if you mix parnotes with footnotes.\\
\texttt{alph}\>Use lowercase alphabet characters instead.\\
\texttt{symbol}\>Use footnote symbols instead instead.\\
\texttt{breakwithin}\>Place a line break after every parnote.\\
\texttt{indentafter}\>Allow indentation in the paragraph following a parnote.\\
\texttt{narrower}\>Give parnotes an increased margin, like block quotes.\\
\texttt{nomultiple}\>Disable special behavior for multiple consecutive parnotes.\\[1ex]
The following options change the font used within parnotes:\\[1ex]
\texttt{notesrm}\>Roman. Default.\\
\texttt{notesit}\>Italic.\\
\texttt{notessf}\>Sans-serif.
\end{tabbing}

\subsection{Format macros}
Five internal macros control formatting for parnotes and parnote marks:

\medskip\fbox{\begin{varwidth}{\textwidth}\texttt{\textbackslash{}parnotefmt\{}$\langle$\textit{text}$\rangle$\texttt{\}\\
\textbackslash{}theparnotemark\\
\textbackslash{}parnotevskip\\
\textbackslash{}parnoteintercmd\\
\textbackslash{}parnotecusmarkfmt\{}$\langle$\textit{mark}$\rangle$\texttt{\}}\end{varwidth}}

\medskip\noindent Parnote text is set using \verb+\parnotefmt+, and parnote marks using \verb+\parnotecusmarkfmt+.
When the optional argument of \verb+\parnote+ is \emph{not} used, \verb+\theparnotemark+ is used to get
the parnote mark for formatting.
At least \verb+\parnotevskip+ vertical space appears before and after the parnote text. The macro
\verb+\parnoteintercmd+ is executed between all consecutive parnotes.

\textsf{parnotes} rev.~1 had a different macro, \verb+\parnotemarkfmt+, to control parnote marks.
Unfortunately, the definition of this macro is incompatible with the new feature in rev.~2 allowing for manually-specified parnote marks,
so it had to be split into two macros \verb+\parnotecusmarkfmt+ and \verb+\theparnotemark+. This is a breaking change.

Table~1 shows these macros' default values. Note that the package options \texttt{narrower},
\texttt{notesrm}, \texttt{notesit}, and \texttt{notessf} modify \verb+\parnotefmt+.
The option \texttt{roman} modifies \verb+\theparnotemark+.
The option \texttt{breakwithin} changes \verb+\parnoteintercmd+ into a line break.

\begin{table}[t]
\centering
\caption{Default values for format macros.}
\smallskip
\begin{tabular}{ll}
\toprule
Macro & Default value \\
\midrule
\verb+\parnotefmt+ & \verb+\footnotesize\rmfamily\noindent #1+ \\
\verb+\theparnotemark+ & \verb+\arabic{parnotemark}+ \\
\verb+\parnotevskip+ & \verb+\medskipamount+ \\
\verb+\parnoteintercmd+ & \verb+\hspace{1em plus 0.3em minus 0.2em}+ \\
\verb+\parnotecusmarkfmt+ & \verb+\textsuperscript{#1}+ \\
\bottomrule
\end{tabular}
\end{table}

Redefine these macros using \verb+\renewcommand+ to fine-tune \textsf{parnotes}'s formatting. For
example, to set parnotes in a sans-serif font, load \textsf{parnotes} as follows:
\begin{lstlisting}
\usepackage{parnotes}
\renewcommand{\parnotefmt}[1]{\footnotesize\sffamily\noindent #1}
\end{lstlisting}
This is the same as specifying the \texttt{notessf} package option.

To have parnotes set as \textit{completely normal text}, but one size smaller than their surroundings (using \verb+\smaller+ from \textsf{relsize}):
\begin{lstlisting}
\usepackage{relsize}
\usepackage[indentafter]{parnotes}
\renewcommand{\parnotefmt}[1]{\smaller #1}
\renewcommand{\parnotevskip}{0pt}
\end{lstlisting}
Or to set parnotes in a block set off by rules, with each parnote separated by a bullet:
\begin{lstlisting}
\usepackage{parnotes}
\renewcommand{\parnotevskip}{0pt}
\renewcommand{\parnotefmt}[1]{\footnotesize\rmfamily
    \noindent\rule{\linewidth}{1pt}\\
    \noindent #1\par
    \noindent\rule{\linewidth}{1pt}
}
\renewcommand{\parnoteintercmd}{\;$\bullet$\;}
\end{lstlisting}

Note that since \verb+\parnotefmt+ is redefined, adding the package option \texttt{narrower} to this example will not work;
instead, \verb+\narrower+ must be placed manually within the new definition for \verb+\parnotefmt+.

\section{Changelog}
{\raggedright
\noindent\textbf{Revision 3b, released on July 23, 2019 (Frank Mittelbach)}
\begin{itemize}
\item Added options \texttt{reset}, \texttt{alph} and \texttt{symbol}.
\item Changed documentation to use feely available fonts only.
\end{itemize}
\noindent\textbf{Revision 3, released on Aug 15, 2016}
\begin{itemize}
\item Bug fix: Use \verb+\protected@edef+ to expand the parnote counter (fixes incompatibility with \textsf{BiocStyle})
\end{itemize}
\noindent\textbf{Revision 2, released on Jul 26, 2016}
\begin{itemize}
\item \textbf{Breaking change:} You can no longer redefine \verb+\parnotemarkfmt+. Use \verb+\theparnotemark+ and \verb+\parnotecusmarkfmt+ instead. See section~2.2 for details.
\item Bug fix: \verb+\parnotefmt+ no longer changes the font to \verb+\rmfamily+ by default.
\item \verb+\parnote+ now behaves more like \verb+\footnote+:
	\begin{itemize}
	\item It respects \verb+\spacefactor+
	\item It no longer inserts \verb+\unskip+
	\end{itemize}
\item The parnote mark counter may be reset using standard LaTeX macros, e.g., \verb+\setcounter{parnotemark}{5}+
\item \verb+\label+ now works within parnote text; \verb+\ref+ returns the parnote label, \verb+\pageref+ returns the page where the note \emph{text} is set, and \verb+\parnoteref+ returns the parnote label formatted as a mark.
\item Implemented the system for separators between multiple footnotes from \textsf{footmisc} and \textsf{manyfoot} and added package option \texttt{nomultiple} to disable.
\item Internal: The package now uses a single counter (\verb+\c@parnotemark+) for marks.
\end{itemize}
\noindent\textbf{Revision 1, released on Jan 3, 2012}
\begin{itemize}
\item Initial release.
\end{itemize}}

\section{Example}
The following pages show a typeset example using \textsf{parnotes}, including interactions with lists,
headings, and environments (here, multicolumn text from the \textsf{multicol} package).
\begin{lstlisting}
\documentclass{article}
\usepackage{multicol} % for demonstration
\usepackage{lipsum} % for demonstration
\usepackage[narrower,notessf]{parnotes}

\begin{document}
\begin{autopn}
\begin{abstract}
\begin{autopn}
Since this is in an environment, \texttt{autopn} must be nested within
it.\parnote{If \texttt{autopn} \emph{weren't} nested, I could've used
\texttt{\textbackslash parnotes} here to set parnotes manually.}
\end{autopn}
\end{abstract}
\tableofcontents
\section{On parnotes\parnote{Parnote marks will display in a heading,
but not within the table of contents. In \texttt{autopn}, parnotes will
display right after the heading.}}

This is a paragraph with a parnote\parnote{See? And it's long enough
to push the \emph{next} parnote nearer the end of the line.}. Actually,
it has two.\parnote{By default, parnotes are set in a continuous
paragraph with 1~em of space between each note.} This sentence ends
the paragraph, but it doesn't have a parnote.

This is a normal paragraph. Note that it isn't indented since the
parnotes make it obvious where the paragraph boundaries are. To change
this behavior, use the \texttt{indentafter} option.

This paragraph's indentation isn't changed.

Here's an environment with a nested \texttt{autopn}:
\begin{multicols}{2}
\begin{autopn}
Since parnotes are set within the normal paragraph flow, they interact
well with environments\parnote{Like this multicolumn environment from
\textsf{multicols} -- it will break columns and pages along with
the normal text within the environment.}.

This is just filler text without any parnotes.
\end{autopn}
\end{multicols}
Here's an environment without a nested \texttt{autopn}:
\begin{multicols}{2}
Without a nested \texttt{autopn}, any parnotes\parnote{Like this one.}
will be set after the end of the next paragraph \emph{outside} this
environment. If \texttt{\textbackslash parnotes} is called just before
the environment ends, then the parnotes will be set within that
environment. This is useful for, say, multi-paragraph quotes.

This environment always specifies that it ends a paragraph, so
parnotes will always be set after it if needed. In some other
circumstances, \texttt{autopn} may not ``see'' that there's a
paragraph break after the environment, so
\texttt{\textbackslash parnotes} will have to be called after the
environment ends.
\end{multicols}

Here's an extra-long parnote\parnote{\lipsum[1]}, to show that parnotes
can break pages. In fact, \TeX\ should prefer to break the page within
the parnotes rather than between this text and the start of the
parnotes.
\end{autopn}

In some circumstances, it's best to forego \texttt{autopn} altogether
-- for example, if parnotes\parnote{Like this one.} should only be
set after several paragraphs. Then just call
\texttt{\textbackslash parnotes} wherever the parnotes should be set.

The same applies if parnotes are to be placed only at the end of a
section, or at a ``scene break.''
\parnotes

The only limiting factor is that \texttt{\textbackslash parnotes} must
be executed after the parnotes it refers to. Here's a table with notes
in an adjacent minipage:\\[0.5in]
\hspace*{\fill}
\begin{tabular}{|c|c|}
\hline a & b\parnote{Note 1} \\ \hline c\parnote{Note 2} & d \\ \hline
\end{tabular}
\hspace{1in}
\begin{minipage}{3in}
% locally redefining format macros so the notes are on separate
% lines, with no vertical space
\renewcommand{\parnoteintercmd}{\\}
\renewcommand{\parnotevskip}{0pt}
\textbf{Notes:}
\parnotes
\end{minipage}\\[0.5in]
Now for a list:
\begin{enumerate}
\begin{autopn}
\item This item has no parnote.
\item This one does\parnote{See? But notice that
\texttt{\textbackslash narrower} doesn't work in lists, so
this is set flush with the list's margin}.
\item This one has a parnote\parnote{Would I ever lie to you?} in its
first paragraph\dots

But not in its second.
\end{autopn}
\end{enumerate}
New features in \textsf{parnotes} rev.~2: Multiple parnote marks%
\parnote{Parnote 1}\parnote{Parnote 2}.
Manually-specified marks\parnote[aaa]{Parnote with special mark%
\label{pn:special}} and references (see~\ref{pn:special},
p.~\pageref{pn:special}), allowing you to re-use parnote marks%
\parnotemark{\ref{pn:special}}.
\parnotes
\end{document}
\end{lstlisting}
\end{document}