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