sepfootnotes (19jan13)

git-svn-id: svn://tug.org/texlive/trunk@28885 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 393 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/sepfootnotes/sepfootnotes.tex b/Master/texmf-dist/doc/latex/sepfootnotes/sepfootnotes.tex
new file mode 100644
index 00000000000..27bd129a4a2
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/sepfootnotes/sepfootnotes.tex
@@ -0,0 +1,393 @@
+% Copyright (C) 2013 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.2}
+\newcommand\filedate{January 17, 2013}
+\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 for his valuable feedback on \texttt{sepfootnotes}.}\\{or a footnote to Plato}}
+\author{Eduardo C. Louren\c{c}o de Lima \\ \texttt{elourenco@phi.pro.br}}
+\date{\filedate}
+\maketitle
+
+
+        \begin{abstract}\noindent
+        The |sepfootnotes| package supports footnotes and endnotes from separate files.
+        Basically, it provides |\sepfootnotecontent| and |\sepfootnote|: the former
+        defines the content of a note; 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
+\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.\bigskip
+
+\item |\|\meta{prefix}|notetext| \marg{key}
+
+Typeset just the note identified by \meta{key} without the corresponding mark.\bigskip
+
+\item |\print|\meta{prefix}|content| \marg{key}
+
+Just print the \meta{content} identified by \meta{key}.
+\end{synopsis}
+\end{Description}
+
+\newpage
+
+\begin{Description}
+\DescribeMacro{\the<prefix>notes}
+\DescribeMacro{\addto<prefix>notes}
+\DescribeEnv{<prefix>notes}
+\DescribeMacro{\the<prefix>note}
+\DescribeMacro{\the<prefix>mark}
+\DescribeMacro{\make<prefix>mark}
+\DescribeMacro{\<prefix>notesize}
+\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\<prefix>notesize|
+
+Define the fontsize in which to typeset endnotes.
+
+Default: |\footnotesize|\bigskip
+
+\item |\renewenvironment {<prefix>notes}|
+
+Define the environment in which endnotes are typeset.
+
+Default: |\<prefix>notesize\setlength\parskip\footnotesep|\bigskip
+
+\item |\renewcommand\the<prefix>note|
+
+Define how endnote numbers are typeset.
+
+Default: |\arabic {<prefix>note}|\bigskip
+
+\item |\renewcommand\the<prefix>mark|
+
+Define how endnote marks are typeset.
+
+Default: |\the<prefix>note|\bigskip
+
+\item |\renewcommand\make<prefix>mark|
+
+Define how a particular endnote mark is typeset.
+
+Default:\footnote{Adapted from the {LaTeX2e} sources.} |\hbox {\normalfont\the<prefix>mark.\ }|\bigskip
+
+\item |\renewcommand\<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<prefix>mark}|
+\end{synopsis}
+\end{Description}
+
+
+\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}
+\begin{document}
+\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}