path: root/Master/texmf-dist/source/latex/sepfootnotes/sepfootnotes.dtx

% \iffalse meta-comment
%
% Copyright (C) 2012 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.
%
% \fi
% \iffalse
%
%<package>\NeedsTeXFormat{LaTeX2e}[1996/06/01]
%<package>\ProvidesPackage{sepfootnotes}[2012/03/06 v0.1 Footnotes in separate file]
%<*driver>
\documentclass{ltxdoc}
\usepackage{sepfootnotes}
\newenvironment{Description}
 {\par\medskip\noindent\ignorespaces}{}
\newenvironment{synopsis}
 {\begin{list}{}
  {\setlength\parsep{0pt}
   \setlength\itemsep{0pt}}}
 {\end{list}}
\newenvironment{Example}[1]
 {\if#1\else\paragraph{Example.}#1\fi}
 {}
\newenvironment{page}
 {\begin{center}\begin{minipage}[t]{0.5\linewidth}}
 {\end{minipage}\end{center}}
\newcommand\TODO{\texttt{Todo:}}
\begin{document}
 \DocInput{sepfootnotes.dtx}
\end{document}
%</driver>
% \fi
% \changes{0.1}{2012/03/06}{Initial version}
% \GetFileInfo{sepfootnotes.sty}
% \CheckSum{185}
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
% \DoNotIndex{\,,\@addtoreset,\begin,\closeout,\csname,\end,\endcsname}
% \DoNotIndex{\expandafter,\fnsymbol,\@footnotemark,\footnotesep,\footnotesize}
% \DoNotIndex{\@footnotetext,\@ifundefined,\immediate,\input,\jobname,\label}
% \DoNotIndex{\@makebox,\makebox,\mbox,\MessageBreak,\@namedef,\@nameuse}
% \DoNotIndex{\newcommand,\newcounter,\newenvironment,\newwrite,\noindent}
% \DoNotIndex{\normalfont,\openout,\PackageError, \par,\parskip,\ref}
% \DoNotIndex{\refstepcounter,\relax,\renewcommand,\setlength,\string}
% \DoNotIndex{\@thefnmark\write}
% \title{The \textsf{sepfootnotes} package,\thanks{This document
%        corresponds to \textsf{sepfootnotes}~\fileversion,
%        dated~\filedate.}\\{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 allows the content of footnotes
%         to be defined before their marks are inserted in a document.
%         Footnotes and endnotes can, thus, be easily grouped together
%         in a separate file, so that the main body is less
%         cluttered.\end{abstract}
%
%
%                            \section*{Introduction}
%
% Footnotes and endnotes can be a problem when reading {\LaTeX} code. If there
% are many notes to a document, or if some of them are too long, as is often
% the case with philosophers and people from the humanities in general, reading
% and editing the main body may be quite difficult.
%
% They can be a problem for the simple reason that standard |\footnote| and
% |\endnote| both take the text of a note as a mandatory argument.  For one
% thing, a verb and its complement may be\footnote{Notice that this footnote
% does precisely that to the main body of this document. There are ten or more
% lines of code between `may be' and `severed' in such an otherwise short
% paragraph. 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}.  Some people circumvent that issue by
% other artful maneuvering, such as indenting or folding footnote code lines.}
% severed by a dozen lines of code.
%
% This package aims to get around this inconvenience by means of
% macros that take as arguments mere \emph{identifiers,} instead of text, thus
% allowing the content of footnotes and endnotes to be defined \emph{before}
% their marks are inserted in a document.  Notes can, thus, be easily grouped
% together in a \emph{separate file,} so that the main body is less
% cluttered.
%
% The point is not to prevent writers from indulging in footnotes. Quite the
% contrary.
%
%
%                             \section*{Synopsis}
%
% \begin{synopsis}
% \item |\newfootnotes| \marg{prefix}
% \item |\newendnotes| \marg{prefix}
% \item |\newsymbolfootnotes| \oarg{master counter} \marg{prefix}\medskip
% \item |\|\meta{prefix}|note| \marg{id}
% \item |\|\meta{prefix}|notemark| \marg{id}
% \item |\|\meta{prefix}|notetext| \marg{id}
% \item |\|\meta{prefix}|notecontent| \marg{id} \marg{text}\medskip
% \item |\|\meta{prefix}|notes| \marg{id}
% \end{synopsis}
%
% \setcounter{tocdepth}{2}
% \tableofcontents
% \newpage
%                            \section{Basic Usage}
%
%                            \subsection{Footnotes}
%
% \begin{Description}
% \DescribeMacro{\newfootnotes}
% The first step is to create a new footnote apparatus.
% \begin{synopsis}
% \item |\newfootnotes| \marg{prefix}
% \end{synopsis}
% The
% argument \meta{prefix} can be any sequence of letters, such as `a'
% or `dog', except `foot' and other names that have already been taken.
% For example, executing |\newfootnotes{a}| creates a number of new commands, the
% names of which all begin with~`a-': |\anotemark|,  |\anotetext|, |\anote|,  and  |\anotecontent|.
% \end{Description}
% \begin{Description}
% \DescribeMacro{\<prefix>notemark}
% \DescribeMacro{\<prefix>notetext}
% The first two correspond to {\LaTeX}
% |\footnotemark|, and |\footnotetext|.
% They also produce a footnote, or rather, a mark without a footnote, and a footnote without a mark. But the important difference
% to their analogues is that they do not have the text of the footnote as
% arguments. They take a \emph{identifier} instead.
% \begin{synopsis}
% \item |\|\meta{prefix}|notemark| \marg{id}
% \item |\|\meta{prefix}|notetext| \marg{id}
% \end{synopsis}
% \end{Description}
% \begin{Description}
% \DescribeMacro{\<prefix>notecontent}
% The identifier \meta{id} identifies the text of a footnote.
% It can be any arbitrary sequence of letters, numbers, space and punctuation marks.
% But it is not
% itself the text
% of the footnote; it is more like a tag, or a name. This naming is brought
% about by:
% \begin{synopsis}
% \item |\|\meta{prefix}|notecontent| \marg{id} \marg{text}
% \end{synopsis}
% \end{Description}
% \begin{Description}
% \DescribeMacro{\<prefix>note}
% And once \meta{text} bears a name it can be identified
% by |\|\meta{prefix}|note| to produce a footnote.
% \begin{synopsis}
% \item |\|\meta{prefix}|note| \marg{id}
% \end{synopsis}
% \end{Description}
% \begin{Example}
% {How to typeset `Aristotle's master' as a footnote.}
% \iffalse
%<*example>
% \fi
\begin{verbatim}
\newfootnotes{a}
\anotecontent{Plato}{Aristotle's master.}

This was first brought up by
the great Plato\anote{Plato}
in the \textit{Sophist}.
\end{verbatim}
% \iffalse
%</example>
% \fi
% \begin{page}
% \newfootnotes{a}
% \anotecontent{PlatoFoot}{Aristotle's master.}
% This was first brought up by
% the great Plato\anote{PlatoFoot}
% in the \textit{Sophist}.
% \end{page}
%
% \medskip\noindent That sentence will take three lines of code however long the footnote to
% Plato is. No pun intended.
% \end{Example}
%
%
%                            \subsection{Endnotes}
%
% \begin{Description}
% \DescribeMacro{\newendnotes}
% \DescribeMacro{\<prefix>notes}
% Endnote and footnote commands are essentially the same but for two
% differences. To use endnotes first substitute |\newendnotes|
% for |\newfootnotes|, and then insert |\|\meta{prefix}|notes|,
% plural, at the end of the document.
% \begin{synopsis}
% \item |\newendnotes| \marg{prefix}
% \item |\|\meta{prefix}|notes|
% \end{synopsis}
% \end{Description}
% \begin{Example}
% {How to effortlessly convert all footnotes into endnotes.}
% \iffalse
%<*example>
% \fi
% \begin{verbatim}\newendnotes{a}
\anotecontent{Plato}{Aristotle's master.}

This was first brought up by
the great Plato\anote{Plato}
in the \textit{Sophist}.

\section*{Notes}
\anotes
\end{verbatim}
% \iffalse
%</example>
% \fi
% \end{Example}
%
%                        \subsection{Symbol footnotes}
%
% \begin{Description}
% \DescribeMacro{\newsymbolfootnotes}
% To get footnotes with symbols, such as *, $\dag$, and $\ddag$, instead of
% numbers, just declare |\newsymbolfootnotes| instead of |\newfootnotes|.
% (See section~\ref{Roman} for notes with Roman numerals or letters.)
% \begin{synopsis}
% \item |\newsymbolfootnotes| \oarg{master counter} \marg{prefix}
% \end{synopsis}
% \end{Description}
% 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.
% \begin{Example}{}
% \iffalse
%<*example>
% \fi
%\begin{verbatim}\newsymbolfootnotes[page]{a}
\anotecontent{Plato}{Aristotle's master.}

This was first brought up by
the great Plato\anote{Plato}
in the \textit{Sophist}.
\end{verbatim}
% \iffalse
%</example>
% \fi
% No need to modify the main body. Symbol footnotes are just footnotes using
% the same commands as before.
% \end{Example}
% \newpage
%
%                   \subsection{Footnotes in separate file}
%
% It is now easy to see how footnotes can be stored in a separate file. It is
% just a matter of moving all |\|\meta{prefix}|notecontent| declarations to a
% new file, say, |notes.tex|, and then loading it in the preamble with |\input|.
%
% \begin{Example}{How to move all footnotes to a separate file.}
%
% \bigskip This is |notes.tex|
% \iffalse
%<*example>
% \fi
% \begin{verbatim}
\anotecontent{Homer}{Everybody's master.}
\anotecontent{Plato}{Aristotle's master.}
\end{verbatim}
%
% And here is |document.tex|
%\begin{verbatim}\documentclass{article}
\usepackage{sepfootnotes}
\newfootnotes{a}
\input{notes.tex}
\begin{document}
 This was first brought up by
 the great Plato\anote{Plato}
 in the \textit{Sophist}. But
 nobody could suppose that an
 antecedent is to be found in
 Homer.\anote{Homer}
\end{document}
\end{verbatim}
% \iffalse
%</example>
% \fi
% Notice that |Homer| is the first entry in |notes.tex| though it will be
% typeset as note~\ref{homer}, whereas |Plato| is the first footnote here but
% the second entry there.
%\begin{page}\makeatletter\let\c@a\undefined\makeatother
%\newfootnotes{a}
%\anotecontent{HomerSep}{Everybody's master.}
%\anotecontent{PlatoSep}{Aristotle's master.}
%This was first brought up by
%the great Plato\anote{PlatoSep}
%in the \textit{Sophist}. But
%nobody could suppose that an
%antecedent is to be found in
%Homer.\anote{HomerSep}\label{homer}
% \end{page}
% \end{Example}
%
% \medskip\noindent Fortunately, the order in which content declarations
% appear in |notes.tex| is \textbf{not} particularly important when it comes to
% numbering footnotes. Numbering depends solely upon the order in which
% |\|\meta{prefix}|note| commands appear in the document.
%
% Content declarations can be either randomly inserted into
% |notes.tex|, or more interestingly perhaps, grouped together by similarity of
% subject or size.
%
% \newpage
%                         \section{Advanced Usage}
%
%                 \subsection{Footnotes and endnotes together}
%
% If a writer wants to insert footnotes and endnotes in the same document, all
% he has to do is declare |\newfootnotes| \marg{prefix$_1$} and
% |\newendnotes| \marg{prefix$_2$} in the preamble. Each |\new...notes| creates
% an independent note apparatus with its own counter, |\|\meta{prefix}|note|,
% |\|\meta{prefix}|notecontent|, etc.
%
% The trick though is to give each apparatus a different prefix, say, `a' and
% `b':
% \begin{Example}{}
% \iffalse
%<*example>
% \fi
\begin{verbatim}\newfootnotes{a}
\newendnotes{b}
\end{verbatim}
% \iffalse
%</example>
% \fi
% and then substitute prefix~`b' for `a' whenever a note is to be identified by
% the |b| apparatus. In our example if |Plato| is a footnote, but |Homer| is to be made into an endnote,
% just replace |\anotecontent{Homer}| with |\bnotecontent{Homer}| in
% |notes.tex|
% \iffalse
%<*example>
% \fi
% \begin{verbatim}
\bnotecontent{Homer}{Everybody's master.}
\anotecontent{Plato}{Aristotle's master.}
\end{verbatim}
% \iffalse
%</example>
% \fi
% And do the same to |\anote{Homer}| and |\bnote{Homer}| in |document.tex|.
% But don't forget the |\bnotes|, plural, at the end.
% \iffalse
%<*example>
% \fi
%\begin{verbatim}\newfootnotes{a}
\newendnotes{b}
\input{notes.tex}
\begin{document}
 This was first brought up by
 the great Plato\anote{Plato}
 in the \textit{Sophist}. But
 nobody could suppose that an
 antecedent is to be found in
 Homer.\bnote{Homer}
\section*{Notes}
\bnotes
\end{document}
\end{verbatim}
% \iffalse
%</example>
% \fi
% Here |Plato| will be typeset as a footnote, whereas |Homer| as an endnote.
% \end{Example}
%
% Now imagine that, for whatever reason, a writer or editor needs
% footnotes, endnotes, and symbol footnotes all together in the
% same document. He just has to declare three independent note apparatus taking
% three distinct prefixes:
% \begin{Example}{}
% \iffalse
%<*example>
% \fi
\begin{verbatim}\newfootnotes{a}
\newendnotes{b}
\newsymbolfootnotes{c}
\end{verbatim}
% \iffalse
%</example>
% \fi
% and then use |\anote| and |\anotecontent| for footnotes, but reserve |\bnote|
% and |\bnotecontent| for endnotes, as well as |\cnote| and |\cnotecontent| for
% symbol footnotes.
% \end{Example}
%
%
%                        \subsection{Cross-references}
%
% \begin{Description}
% \DescribeMacro{\<prefix>noteref}
% Footnotes and endnotes can be referenced to with |\|\meta{prefix}|noteref|.
% \begin{synopsis}
% \item |\|\meta{prefix}|noteref| \marg{id}.
% \end{synopsis}
% \end{Description}
% \begin{Example}
% {How to produce the number of that footnote to Plato.}
% \iffalse
%<*example>
% \fi
% \begin{verbatim}
 This was first brought up by
 the great Plato\anote{Plato}
 in the \textit{Sophist}.

 See note~\anoteref{Plato}.
\end{verbatim}
% \iffalse
%</example>
% \fi
% \end{Example}
% It is okay to use {\LaTeX} |\label| and |\ref| to refer the reader to notes
% created by |sepfootnotes|.  However, because both |\label|, and |\|\meta{prefix}|note|,
% assign a unique identifier---or label, tag, marker, or name---to a particular
% note number, it may in most cases be just superfluous to label it twice. Compare:
% \begin{Example}{}
% \iffalse
%<*example>
% \fi
% \begin{verbatim}
 This was first brought up by
 the great Plato\anote{Plato}\label{Plato}
 in the \textit{Sophist}.

 See note~\ref{Plato}.
\end{verbatim}
% \iffalse
%</example>
% \fi
% \end{Example}
% But imagine our writer would rather stick to |\ref|. Since the labels |sepfootnotes|
% internally assigns to note numbers all have names like
% |Notes@refs@|\meta{prefix}|@|\meta{id}, the footnote number to |Plato| in our example
% may also be typeset, though somewhat clumsily, by
% |\ref{Notes@refs@a@Plato}|.
%
%
%                   \subsection{Roman numerals and letters}
%                                \label{Roman}
%
% \begin{Description}
% \DescribeMacro{\the<prefix>}
% To change the style of footnote or endnote marks, simply redefine
% |\the|\meta{prefix} to use another style: |roman|, |Roman|, |alph|, |Alph|, or
% |fnsymbol|.
% \begin{synopsis}
% \item |\renewcommand\the|\meta{prefix} |{\|\meta{style}| {|\meta{prefix}|}}|
% \end{synopsis}
% \end{Description}
% \begin{Example}
% {How to typeset lowercase Roman numerals in footnotes.}
% \iffalse
%<*example>
% \fi
\begin{verbatim}
\renewcommand\thea{\roman{a}}

This was first brought up by
the great Plato\anote{Plato}
in the \textit{Sophist}.
\end{verbatim}
% \iffalse
%</example>
% \fi
%\begin{page}\makeatletter\let\c@a\undefined\makeatother
%\newfootnotes{a}
%\renewcommand\thea{\roman{a}}
%\anotecontent{PlatoRoman}{Aristotle's master.}
%This was first brought up by
%the great Plato\anote{PlatoRoman}
%in the \textit{Sophist}.
%\end{page}
% \end{Example}
%
%
%                     \subsection{Endnotes customization}
%
% To customize how the text of endnotes is typeset at the end of the document,
% you may redefine |\|\meta{prefix}|endnotemark| and the
% \meta{prefix}|endnotes| environment.
% \begin{Description}
% \DescribeMacro{\<prefix>endnotemark} Numbers right before the text of
% endnotes are typeset by |\|\meta{prefix}|endnotemark|, which is not to be
% confused with |\the|\meta{prefix}. See section~\ref{Roman}.
% \begin{synopsis}
% \item |\|\meta{prefix}|endnotemark| \marg{number}
% \end{synopsis}
% \end{Description}
% \begin{Description}
% \DescribeEnv{<prefix>endnotes}
% The text of all endnotes is typeset within the \meta{prefix}|endnotes|
% environment.
% \end{Description}
% \iffalse
%<*example>
% \fi
% \begin{Example}{How to typeset endnotes as a list of numbers, instead of numbered paragraphs, and in boldface.}
%\begin{verbatim}
\newendnotes{a}
\anotecontent{Homer}{Everybody's master.}
\anotecontent{Plato}{Aristotle's master.}

\renewcommand     \aendnotemark [1] {\item[\textbf{#1.}]}
\renewenvironment {aendnotes}       {\begin{list}{}{}}
                                    {\end{list}}
This was first brought up by
the great Plato\anote{Plato}
in the \textit{Sophist}. But
nobody could suppose that an
antecedent is to be found in
Homer.\anote{Homer}
\section*{Notes}
\anotes
\end{verbatim}
% \begin{page}\makeatletter\let\c@a\undefined\makeatother
% \newendnotes{a}
% \anotecontent{HomerCustom}{Everybody's master.}
% \anotecontent{PlatoCustom}{Aristotle's master.}
% \renewcommand     \aendnotemark [1] {\item[\textbf{#1.}]}
% \renewenvironment {aendnotes}
% {\begin{list}{}
%  {\setlength\topsep {0pt}
%   \setlength\parsep {0pt}
%   \setlength\itemsep{0pt}}}
% {\end{list}}
% This was first brought up by
% the great Plato\anote{PlatoCustom}
% in the \textit{Sophist}. But
% nobody could suppose that an
% antecedent is to be found in
% Homer.\anote{HomerCustom}
% \par\smallskip\noindent\textbf{Notes}
% \anotes
% \end{page}
% \end{Example}
% \iffalse
%</example>
% \fi
%
%\begin{thebibliography}{1}
%
%  \bibitem{Nicholas Cole}
%  At \texttt{http://tug.org/mailman/htdig/texhax/2010-April/014558.html}
%
%  \bibitem{Luecking}
%  At \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}
%
%
% \StopEventually
%
%                           \section{Implementation}
%
%                            \subsection*{Namespace}
%
% First we define a namespace for labels and identifiers.
%    \begin{macrocode}
\newcommand\@SFnNamespace{Notes@}
%    \end{macrocode}
%
% \subsection{Public macros}
%
% This section comments on public macros dynamically named, and defined, using a user provided prefix.
% They fall into four categories: footnote macros, endnote macros, symbol footnote macros, and
% macros that are common to all of them.
%
% \subsubsection{Common macros}
%
%    \begin{macro}{\@SFnNew}
% The public |\newfootnotes|, |\newsymbolfootnotes|, and |\newendnotes|
% commented upon in the next sections first call
% the private |\@SFnNew| \marg{prefix}, which dynamically defines a counter and
% three public macros common to both footnotes and endnotes.  They are all named with \meta{prefix}: if
% `bar' is provided as the prefix then |\barnotecontent|, |\barnoteref|, |\barnmark|,
% and the counter |bar| are defined.
%    \begin{macrocode}
\newcommand\@SFnNew [1]{%
%    \end{macrocode}
% The counter \meta{prefix} will only track notes typeset by macros named with \meta{prefix}.
%    \begin{macrocode}
 \newcounter{#1}%
%    \end{macrocode}
%    \begin{macro}{\<prefix>notecontent}
% The macro |\|\meta{prefix}|notecontent| \marg{id} \marg{text} stores
% \meta{text} as \meta{id}, which is in the \meta{prefix} namespace itself.
%    \begin{macrocode}
 \expandafter
 \newcommand\csname #1notecontent\endcsname [2]
 {\@SFnStoreText {#1} {##1} {##2}}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\<prefix>noteref}
% The macro |\|\meta{prefix}|noteref| \marg{id} typesets the reference to the label
% associated with \meta{id}. See |\|\meta{prefix}|notemark| in \ref{footnotes} below.
%    \begin{macrocode}
 \expandafter
 \newcommand\csname #1noteref\endcsname [1]
 {\@SFnGetReference {#1} {##1}}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\<prefix>nmark}
% Finally |\|\meta{prefix}|nmark| typesets the default note mark.
%    \begin{macrocode}
 \expandafter
 \newcommand\csname #1nmark\endcsname
 {\csname the#1\endcsname}}%
%    \end{macrocode}
%    \end{macro}
%    \end{macro}
%
%                          \subsubsection{Footnotes}
%                              \label{footnotes}
%
%    \begin{macro}{\newfootnotes}
% The macro |\newfootnotes| \marg{prefix} dynamically defines three public
% macros. They also are all named with \meta{prefix}.
%    \begin{macrocode}
\newcommand\newfootnotes [1]
 {\@SFnNew{#1}%
%    \end{macrocode}
%    \begin{macro}{\<prefix>notemark}
% The macro |\|\meta{prefix}|notemark| \marg{id} steps the counter, assigns it a
% label, links that label up with \meta{id}, and typesets a footnote mark. See
% |\@SFnInsertMark|.
%    \begin{macrocode}
 \expandafter
 \newcommand\csname #1notemark\endcsname [1]
 {\@SFnInsertMark   {#1} {##1}}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\<prefix>notetext}
% The macro |\|\meta{prefix}|notetext| \meta{id} typesets the text that was
% previously associated with \meta{id} by |\|\meta{prefix}|notecontent|.
%    \begin{macrocode}
 \expandafter
 \newcommand\csname #1notetext\endcsname [1]
 {\@SFnSetMark     {#1}%
  \@SFnTypesetText {#1} {##1}}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\<prefix>note}
% The macro |\|\meta{prefix}|note| \meta{id} typesets the mark and text of a
% footnote.
%    \begin{macrocode}
 \expandafter
 \newcommand\csname #1note\endcsname [1]
 {\csname #1notemark\endcsname{##1}%
  \csname #1notetext\endcsname{##1}}}
%    \end{macrocode}
%    \end{macro}
%
% \subsubsection{Symbol footnotes}
%
%    \begin{macro}{\newsymbolfootnotes}
% The macro |\newsymbolfootnotes| \oarg{master counter} \marg{prefix} dynamically
% define all of the footnote macros commented upon in \ref{footnotes}, but it also
% redefines |\|\meta{prefix}|nmark| so as to render symbols instead of numbers. Further,
% it creates a counter to be reset when \meta{master counter} is stepped.
% The default master counter is |page|.
%    \begin{macrocode}
\newcommand\newsymbolfootnotes [2][page]
 {\newfootnotes {#2}%
  \@addtoreset  {#2} {#1}%
  \expandafter
  \renewcommand\csname #2nmark\endcsname
  {\fnsymbol {#2}}}
%    \end{macrocode}
%    \end{macro}
%
%                           \subsubsection{Endnotes}
%                               \label{endnotes}
%
% Endnote identifiers, but not endnote number and text, need to be stored in a file
% for later processing.  The list of endnote identifiers may then be converted into
% endnotes at the end of the document within a suitable environment.
%
% The following is similar to \ref{footnotes} on footnotes but for
% the fact that now we have to deal with files, and delayed typesetting of
% endnote text. Another difference to the footnote set is that
% |\|\meta{prefix}|notemark| and |\|\meta{prefix}|note| are the same here.
%
%    \begin{macro}{\newendnotes}
% The macro |\newendnotes| \marg{prefix} dynamically defines a corresponding
% environment \meta{prefix}|endnotes|, as well as five public macros
% available to endnotes only. They also are
% all named with \meta{prefix}.
%    \begin{macrocode}
\newcommand\newendnotes [1]
 {\@SFnNew         {#1}%
  \@SFnOpenFileOut {#1}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\<prefix>note}
%    \begin{macro}{\<prefix>notemark}
% Both |\|\meta{prefix}|note| \marg{id} and |\|\meta{prefix}|notemark| \marg{id}
% typeset an endnote mark, and write down its \meta{id} for later
% processing.
%    \begin{macrocode}
 \expandafter
 \newcommand\csname #1notemark\endcsname [1]
 {\@SFnInsertMark    {#1} {##1}%
  \@SFnWriteToFile   {#1} {##1}}%
 \expandafter
 \newcommand\csname #1note\endcsname [1]
 {\csname #1notemark\endcsname {##1}}%
%    \end{macrocode}
%    \end{macro}
%    \end{macro}
%    \begin{macro}{\<prefix>notetext}
% Though public, |\|\meta{prefix}|notetext| \marg{id} is not meant to be directly used
% when applied to endnotes. It typesets a single
% endnote mark and text, preferably within the \meta{prefix}|endnotes|
% environment.
%    \begin{macrocode}
 \expandafter
 \newcommand\csname #1notetext\endcsname [1]
 {\csname #1endnotemark\endcsname
  {\@SFnGetReference {#1} {##1}}%
  \@SFnRetrieveText  {#1} {##1}\par}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\<prefix>notes}
% The |\|\meta{prefix}|notes| immediately closes the auxiliary file, and typesets all endnotes
% within a \meta{prefix}|endnotes| environment.
%    \begin{macrocode}
 \expandafter
 \newcommand\csname #1notes\endcsname
 {\@SFnCloseFile {#1}%
  \begin{#1endnotes}
  \input\@SFnFileName{#1}%
  \end{#1endnotes}}%
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\<prefix>endnotemark}
% Now, the macro |\|\meta{prefix}|endnotemark| \marg{number}
% typesets marks preferably within the \meta{prefix}|endnotes|
% environment.\footnote{From \cite[p.114]{Companion}.}
%    \begin{macrocode}
 \expandafter
 \newcommand\csname #1endnotemark\endcsname [1]
 {\noindent\makebox[0pt][r]{\mbox{{\normalfont ##1.\,}}}}
%    \end{macrocode}
%    \end{macro}
%    \begin{environment}{<prefix>endnotes}
% And here is the environment where to typeset all endnotes.
%    \begin{macrocode}
 \newenvironment{#1endnotes}
  {\footnotesize\setlength\parskip\footnotesep}
  {}}%
%    \end{macrocode}
%    \end{environment}
%
% \newpage
%                         \subsection{Private macros}
%
% This section comments on private macros.
%
%                            \subsubsection{Files}
%
% The following apply to endnotes only. See~\ref{endnotes}.
%
%    \begin{macro}{\@SFnFileName}
% The macro |\@SFnFileName| \marg{prefix} returns a filename based on,
% surprise, \meta{prefix}. \TODO{} 3 letter extension: |sep|.
%    \begin{macrocode}
\newcommand\@SFnFileName [1]
 {\jobname.notes-#1}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\@SFnOpenFileOut}
%    \begin{macro}{\@SFnWriteToFile}
%    \begin{macro}{\@SFnCloseFile}
% Here are three macros that operate on file descriptors:
%
% The first,
% |\@SFnOpenFileOut| \marg{prefix}, opens for writing a dynamically named
% file |\@SFnFileOut|\meta{prefix}.
%    \begin{macrocode}
\newcommand\@SFnOpenFileOut [1]
 {\expandafter\newwrite\csname @SFnFileOut#1\endcsname
  \immediate\expandafter\openout
  \csname @SFnFileOut#1\endcsname=\@SFnFileName#1\relax}
%    \end{macrocode}
% The macro |\@SFnWriteToFile| \marg{prefix} \marg{id} writes down a
% note identifier, \meta{id}, for later processing. See
% |\|\meta{prefix}|notes| in section~\ref{endnotes}.
%    \begin{macrocode}
\newcommand\@SFnWriteToFile [2]
 {\immediate\write\csname @SFnFileOut#1\endcsname
  {\expandafter\string\csname #1notetext\endcsname
  {#2}}}%
%    \end{macrocode}
% And |\@SFnCloseFile| \marg{prefix} closes the file containing note
% identifiers related to \meta{prefix}.
%    \begin{macrocode}
\newcommand\@SFnCloseFile [1]
 {\immediate\expandafter
  \closeout\csname @SFnFileOut#1\endcsname\relax}
%    \end{macrocode}
%    \end{macro}
%    \end{macro}
%    \end{macro}
%
%                             \subsubsection{Text}
%
% These are private macros to store, retrieve, and typeset the text of notes.
% They apply to both footnotes and endnotes.
%
%    \begin{macro}{\@SFnStoreText}
% First |\@SFnStoreText| \marg{prefix} \marg{id} \marg{text} stores the
% text of a note as \meta{id} in the \meta{prefix} |text| namespace. The
% package aborts if \meta{id} is already in use in that namespace.
%    \begin{macrocode}
\newcommand\@SFnStoreText [3]
 {\@ifundefined{\@SFnNamespace text@#1@#2}
  {\@SFnNameDef {#1} {#2} {#3}}
  {\PackageError
   {\@SFnPackageName}
   {`#1' is already in use.}
   {The note identifier `#1' already identifies a piece of
    text.\MessageBreak Solution: Use another identifier.}}}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\@SFnRetrieveText}
% And |\@SFnRetrieveText| \marg{prefix} \marg{id} retrieves a previously
% stored piece of text identified by \meta{id} in the \meta{prefix} |text|
% namespace.  It silently ignores undefined content.
%    \begin{macrocode}
\newcommand\@SFnRetrieveText [2]
 {\@ifundefined{\@SFnNamespace text@#1@#2}
  {}
  {\@SFnNameUse {#1} {#2}}}
%    \end{macrocode}
% ^^A {\PackageWarningNoLine
% ^^A  {\@SFnPackageName}
% ^^A  {Empty note `#2' on page \thepage}}
% ^^A%  {Note `#2' has no content assigned to it.\MessageBreak
% ^^A%   Solution: Insert \expandafter\protect\csname #1notetext\endcsname{#2}{...}
% ^^A%   before it.}
%    \end{macro}
%    \begin{macro}{\@SFnTypesetText}
% Finally, |\@SFnTypesetText| \marg{prefix} \marg{id} not only retrieves
% but also typesets a note text identified by \meta{id} in the \meta{prefix}
% |text| namespace.
%    \begin{macrocode}
\newcommand\@SFnTypesetText [2]
 {\@footnotetext{\@SFnRetrieveText {#1} {#2}}}
%    \end{macrocode}
%    \end{macro}
%
%                            \subsubsection{Marks}
%
% These are private macros to typeset note marks.
% They apply to both footnotes and endnotes.
%
%    \begin{macro}{\@SFnInsertMark}
% The macro |\@SFnInsertMark| \marg{prefix} \marg{id} steps the counter,
% assigns it a label, links that label up with \meta{id}, and then typesets a note
% mark. It does the real work behind |\|\meta{prefix}|notemark| in sections \ref{footnotes} and~\ref{endnotes}.
%    \begin{macrocode}
\newcommand\@SFnInsertMark [2]
 {\@SFnStepCounter  {#1}%
  \@SFnSetReference {#1} {#2}%
  \@SFnSetMark      {#1}%
  \@SFnTypesetMark}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\@SFnSetMark}
% Now, |\@SFnSetMark| \marg{prefix} sets\footnote{From {\LaTeX} Kernel (Floats),
% 2002/10/01 v1.1v.: |base/ltfloat.dtx|.} \LaTeX{} internal note engine to typeset a mark as
% publicly defined by |\|\meta{prefix}|nmark|.
%    \begin{macrocode}
\newcommand\@SFnSetMark [1]
 {\protected@xdef\@thefnmark{\csname #1nmark\endcsname}}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\@SFnTypesetMark}
% And |\@SFnTypesetMark| is just a more descriptive wrapper to the
% internal macro that typesets the note mark.
%    \begin{macrocode}
\newcommand\@SFnTypesetMark
 {\@footnotemark}
%    \end{macrocode}
%    \end{macro}
%
%                 \subsubsection{Labels and cross-references}
%
% This package relies heavily on labels and cross-references to keep track of endnote
% numbers. But every note number, be it footnote or endnote, is assigned a
% label in the \meta{prefix} |label| namespace. Thus note numbers can be
% directly referenced to with |\ref{Notes@refs@|\meta{prefix}|@|\meta{id}|}|, or
% indirectly, but more simply, with |\|\meta{prefix}|noteref| \meta{id}.
%
% On the one hand, labels require running |latex| at least twice to get
% cross-references right. But on the other they allow us not to bother
% with note numbers. As long as note text and labels are implicitly connected by a unique
% identifier \meta{id} in \meta{prefix} namespace, the explicit connection between note
% content and number does not need to be hard coded into the endnote auxiliary
% file, as it is in the |endnotes| package.
%
% But the motivation for the identifier approach---notes defined before notes
% inserted---is quite independent of such a feature, if it is a feature.
%
% \TODO{} However it be, the identifier approach might prove itself useful in solving
% \LaTeX{} misnumbering footnotes when two or more |\footnotemark| precedes two
% or more |\footnotetext|. Since the |sepfootnotes| package requires note text to
% be defined before note marks are inserted, even in a separate file, it no
% longer matters how many times |\|\meta{prefix}|notemark| \meta{id} is invoked before
% |\|\meta{prefix}|notetext| \meta{id}. That is precisely what goes on with endnotes.
%    \begin{macro}{\@SFnSetReference}
% The macro |\@SFnSetReference| \marg{prefix} \marg{id} assigns a note
% number a label in the \meta{prefix} |refs| namespace.
%    \begin{macrocode}
\newcommand\@SFnSetReference [2]
 {\label{\@SFnNamespace refs@#1@#2}}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\@SFnGetReference}
% And |\@SFnGetReference| \marg{prefix} \marg{id} simply returns that
% number.
%    \begin{macrocode}
\newcommand\@SFnGetReference [2]
 {\ref{\@SFnNamespace   refs@#1@#2}}
%    \end{macrocode}
%    \end{macro}
%
%                          \subsubsection{Counters}
%
%    \begin{macro}{\@SFnStepCounter}
% The macro |\@SFnStepCounter| \marg{prefix} steps the counter |prefix|,
% and makes sure it can be properly labeled afterwards.
%    \begin{macrocode}
\newcommand\@SFnStepCounter [1]
 {\refstepcounter{#1}}
%    \end{macrocode}
%    \end{macro}
%
%                            \subsubsection{Names}
%                                \label{names}
%
%    \begin{macro}{\@SFnNameDef}
% The macro |\@SFnNameDef| \marg{prefix} \marg{id} \marg{text} stores
% \meta{text} as \meta{id} in the \meta{prefix} |text|
% namespace.\footnote{I owe Dan Luecking the idea of using \LaTeX{} internal
% table to store note text.~\cite{Luecking}}
%    \begin{macrocode}
\newcommand\@SFnNameDef [3]
 {\@namedef{\@SFnNamespace text@#1@#2}{#3}}
%    \end{macrocode}
%    \end{macro}
%    \begin{macro}{\@SFnNameUse}
% And |\@SFnNameUse| \marg{prefix} \marg{id} retrieves a previously stored
% piece of text identified by \meta{id} in the \meta{prefix} |text| namespace.
% Undefined content is silently ignored.
%    \begin{macrocode}
\newcommand\@SFnNameUse [2]
 {\@nameuse{\@SFnNamespace text@#1@#2}}
%    \end{macrocode}
%    \end{macro}
%    \end{macro}
%\Finale