path: root/Master/texmf-dist/doc/latex/parnotes/parnotes.tex

%!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}