diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/enotez/enotez_en.tex |
Initial commit
Diffstat (limited to 'macros/latex/contrib/enotez/enotez_en.tex')
-rw-r--r-- | macros/latex/contrib/enotez/enotez_en.tex | 522 |
1 files changed, 522 insertions, 0 deletions
diff --git a/macros/latex/contrib/enotez/enotez_en.tex b/macros/latex/contrib/enotez/enotez_en.tex new file mode 100644 index 0000000000..85cf03b688 --- /dev/null +++ b/macros/latex/contrib/enotez/enotez_en.tex @@ -0,0 +1,522 @@ +% !arara: pdflatex +% !arara: biber +% arara: pdflatex +% arara: pdflatex +% -------------------------------------------------------------------------- +% the ENOTEZ package +% +% Endnotes for LaTeX2e +% +% -------------------------------------------------------------------------- +% Clemens Niederberger +% Web: http://www.mychemistry.eu/forums/forum/enotez/ +% E-Mail: contact@mychemistry.eu +% -------------------------------------------------------------------------- +% Copyright 2012-2017 Clemens Niederberger +% +% 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. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is Clemens Niederberger. +% -------------------------------------------------------------------------- +% The enotez package consists of the files +% - enotez.sty, enotez_en.tex, enotez_en.pdf, README +% -------------------------------------------------------------------------- +% If you have any ideas, questions, suggestions or bugs to report, please +% feel free to contact me. +% -------------------------------------------------------------------------- +\documentclass[load-preamble+]{cnltx-doc} +\usepackage[utf8]{inputenc} +\usepackage{enotez} + +\setcnltx{ + package = enotez , + info = {Endnotes for \LaTeXe} , + authors = Clemens Niederberger , + email = contact@mychemistry.eu , + url = https://bitbucket.org/cgnieder/enotez/ , + pre-output = \setfnpct{dont-mess-around} , + add-cmds = { + @endnotemark, + endnote , + endnotemark , + endnotetext , + enmark , + enmarkstyle , + enotezwritemark , + NewSplitTitleTag , + printendnotes , + setenotez , + splitendnotes , + theendnote + } , + add-silent-cmds = { + @currentlabel , + appendix , + cs , + DeclareInstance , + DeclareTemplateInterface , + DeclareTranslation , + kant + } , + index-setup = { + othercode = \footnotesize , + level = \addsec , + % noclearpage + } , + makeindex-setup = { + columns = 3 , + columnsep = 1em + } +} +\setenotez{mark-cs=\textsu,backref} +\DeclareInstance{enotez-list}{addsec}{paragraph}{heading=\addsec{#1}} + +\defbibheading{bibliography}{\addsec{References}} + +\usepackage{kantlipsum} +\usepackage{enumitem} + +\begin{document} + +\section{Licence and Requirements} +\license + +\enotez\ needs and loads the following packages: +\bnd{l3kernel}~\cite{bnd:l3kernel}, \pkg{xparse}, \pkg{xtemplate} and +\pkg{l3keys2e} from the \bnd{l3packages} bundle~\cite{bnd:l3packages}, +\pkg{xpatch}~\cite{pkg:xpatch}, \pkg{scrlfile} from the \KOMAScript\ +bundle~\cite{bnd:koma-script} and \pkg{translations}~\cite{pkg:translations}. + +\section{Motivation} +\enotez\ is a new implementation of endnotes for \LaTeXe\ since the +\pkg{endnotes} package~\cite{pkg:endnotes} has some deficiencies. Nested +endnotes, for example, are not supported, neither is +\pkg{hyperref}~\cite{pkg:hyperref}. The \pkg{sepfootnotes} +package~\cite{pkg:sepfootnotes} also provides means for endnotes but actually +has a different purpose: to separate input and usage both of footnotes and +endnotes. So it might not be the best solution in every case\footnote{You + have to write the actual notes in the preamble or a separate file and + reference them in the text.}. It also does not allow nested endnotes. + +While \enotez\ worked in tests nicely with the +\cls{memoir}~\cite{cls:memoir} class please keep in mind that +\cls{memoir} provides its own endnote mechanism. + +\enotez\ enables nested endnotes properly and has another mechanism of +customizing the list of endnotes which is easily extendable. One of the main +features of \enotez\ is a split list of endnotes in which the notes are +automatically separated by the sections or chapters they were set in, see +section~\ref{sec:split} for more information. + +As an aside: \enotez\ is nicely compatible with the \pkg{fnpct} +package~\cite{pkg:fnpct}. Version~0.2j or newer of \pkg{fnpct} automatically +detects \enotez\ and adapts the \cs{endnote} command. + + +\section{Usage} +\subsection{Placing the Notes} +The usage is simple: use \cs{endnote} in the text where you want to place the +note mark. +\begin{commands} + \command{endnote}[\oarg{mark}\marg{text}] + Add an endnote in the text. + \command{endnotemark}[\oarg{mark}] + \sinceversion{0.9}Add an endnotemark. + \command{endnotetext}[\marg{text}] + \sinceversion{0.9}Add text to an endnote placed with \cs{endnotemark}. +\end{commands} +\begin{example} + This is some text.\endnote{With an endnote.} +\end{example} +There's not really much more to it. It is possible to add a custom mark by +using the optional argument but that shouldn't be needed too often. +% \cs{endnote} works fine inside tables, minipages, floats and +% captions\footnote{This has been tested with the standard classes, +% \cls{memoir}, and the \cls{KOMA-Script} classes, with and without the +% \pkg*{caption} package. If you're using another package that redefines +% \cs*{caption} or are using another class it might not work. Before you +% place a note in a caption you should re-think the idea anyway.}. +Endnotes +can also be nested. + +% Since this functionality seemed making a pair +% \cs{endnotemark}/\cs{endnotetext} superfluous they are \emph{not} defined by +% \enotez. +\begin{example} + This is some text.\endnote{With another endnote.\endnote{This is a + nested\endnote{And another level deeper\ldots} endnote!}} + % uses package `kantlipsum' to produce dummy text: + Of course you can have several paragraphs\endnote{\kant[1-3]} in an endnote. +\end{example} + +The marks of the endnotes in the running text are printed through the command +\cs{enotezwritemark} which defaults to \cs*{textsuperscript}. Its argument +contains the current mark which is preceded by \cs{enmarkstyle}. Both of +these commands can be redefined of course to adapt to custom settings. This +can also be done using options, see section~\ref{sec:options}. The mark of +the endnote that has been set last is stored in % \cs{theendnote} and in +\verbcode+\@currentlabel+.\sinceversion{0.6} + +% This could be used to define a command which writes a mark: +% \begin{example} +% % we cannot use \newcommand -- the command starts with \end... +% \makeatletter +% \def\endnotemark{\@ifnextchar[{\@endnotemark}{\@endnotemark[\theendnote]}} +% \def\@endnotemark[#1]{\enotezwritemark{\enmarkstyle#1}} +% \makeatother +% Text\endnotemark +% \end{example} +% Please note that this definition \emph{does not} step the endnote counter but +% either refers to the last number (no optional argument) or uses the one +% provided in the optional argument. + +% \makeatletter +% \def\endnotemark{\@ifnextchar[{\@endnotemark}{\@endnotemark[\theendnote]}} +% \def\@endnotemark[#1]{\enotezwritemark{\enmarkstyle#1}} +% \makeatother + +Endnotes can also be labelled and later be referred to: +\begin{example} + The next endnote\endnote{This endnote gets a label.}\label{en:test} has + the number~\ref{en:test}. Let's now test + \cs{endnotemark}\endnotemark[\ref{en:test}]. +\end{example} + +\subsection{Printing the Notes} +The notes are printed by using the command \cs{printendnotes}. +\begin{commands} + \command{printendnotes}[\sarg\oarg{style}] + Print the list of endnotes. \meta{style} is one of the instances + explained in section~\ref{sec:customizing_the_list}. +\end{commands} +If used without argument it prints all notes set so far with +\cs{endnote}. The current list will then be cleared. All endnotes set after +it are stored again for the next usage of \cs{printendnotes}. The starred +version will print \emph{all} endnotes but shouldn't be used more than once if +you have nested endnotes. + +It may take several compilation runs until all notes are printed correctly. +In a first run they are written to the \code{aux} file. In the second run +they are available to \cs{printendnotes}. If you have nested endnotes they +will be written to the \code{aux} file the first time they're printed with +\cs{printendnotes} which means you might have to compile your file once more. +If you change any of the endnotes or add another one you again will need at +least two runs, maybe more. \enotez\ tries to warn you in these cases by +invoking the warning +\begin{flushleft} + \ttfamily + Endnotes may have changed. Rerun to get them right. +\end{flushleft} +but may not catch all cases. + +\enotez\ provides two commands that allow to set some kinds of preamble and +postamble to a list, either to every list or only to the next one: +\begin{commands} + \command{AtEveryEndnotesList}[\marg{text}] + \sinceversion{0.5}inserts \meta{text} between heading and the actual notes + every time \cs{printendnotes} is used. + \command{AtNextEndnotesList}[\marg{text}] + \sinceversion{0.5} inserts \meta{text} between heading and the actual + notes the next time \cs{printendnotes} is used. This overwrites a + possible preamble set with \cs{AtEveryEndnotesList} for this instance of + \cs{printendnotes}. + \command{AfterEveryEndnotesList}[\marg{text}] + \sinceversion{0.5} inserts \meta{text} after the notes list every time + \cs{printendnotes} is used. + \command{AfterNextEndnotesList}[\marg{text}] + \sinceversion{0.5} inserts \meta{text} after the notes list the next time + \cs{printendnotes} is used. This overwrites a possible postamble set with + \cs{AfterEveryEndnotesList} for this instance of \cs{printendnotes}. +\end{commands} +If something is inserted with one of these commands the inserted \meta{text} +will be followed by a \cs*{par} and a vertical skip for the preamble. The +postambles follow a \cs*{par} and a vertical skip. The skips can be set using +an option, see section~\ref{sec:options}. + +\section{Options}\label{sec:options} +\subsection{Package Options} +\enotez\ has a few package options which should be pretty self-explanatory. +They can be set either as package options with +\cs*{usepackage}\oarg{options}\Marg{enotez} or with the setup command. +\begin{commands} + \command{setenotez}[\marg{options}] + Setup command for setting \enotez' options. +\end{commands} +\begin{options} + \keyval{list-name}{list name}\Default{Notes} + The name of the notes list. This name is used for the heading of the + list. + \keybool{reset}\Default{false} + If set to \code{true} the notes numbers will start from 1 again after + \cs{printendnotes} has been invoked. + \keychoice{counter-format}{arabic,alph,Alph,roman,Roman,symbols}\Default{arabic} + Change the format of the endnote counter. Please be aware that there are + only 26 alphabetic counter symbols (options \code{alph} and \code{Alph} + and \emph{only 9} symbols (option \code{symbols}). + \keyval{mark-format}{code}\Default + Redefine \cs{enmarkstyle} to execute \meta{code}. This command is placed + directly before the endnote mark in the text. + \keyval{mark-cs}{command}\Default{\cs*{textsuperscript}} + Lets \cs{enotezwritemark} to be equal to \meta{command}. This command + is used to typeset the endnote marks in the text and should take one + argument. + \keybool{backref}\Default{false}\label{key:backref} + \sinceversion{0.7}If set to \code{true} and \pkg{hyperref} has been + loaded backlinks from the notes in the list to the marks in the text are + added. + \keychoice{totoc}{section,chapter,false}\Default{false}\label{key:totoc} + Add an entry to the table of contents. + \keyval{list-heading}{sectioning command including argument} + You can use this option to manually set the list heading command, \eg, + \keyis{list-heading}{\cs{chapter}\Marg{\#1}} for a numbered heading. The + default depends upon if the class you're using provides \cs*{chapter} or + not. It either uses \cs*{chapter}\sarg\ or \cs*{section}\sarg. You can + see that you have to refer to the actual heading with \code{\#1}. + \keyval{list-style}{style}\Default{plain} + Sets the default list style, see section~\ref{sec:customizing_the_list} + for details. + \keyval{list-preamble-skip}{skip}\Default{\cs*{medskipamount}} + \sinceversion{0.5}Sets the vertical skip (a rubber length) that is + inserted if a list preamble is inserted by using either + \cs{AtNextEndnotesList} or \cs{AtEveryEndnotesList}. It's default is set + equal to \cs*{medskipamount}. + \keyval{list-postamble-skip}{skip}\Default{\cs*{medskipamount}} + \sinceversion{0.5}Sets the vertical skip (a rubber length) that is + inserted if a list postamble is inserted by using either + \cs{AfterNextEndnotesList} or \cs{AfterEveryEndnotesList}. It's default + is set equal to \cs*{medskipamount}. +\end{options} + +\subsection{Customizing the List}\label{sec:customizing_the_list} +The list is typeset with \pkg{xtemplate}'s possibilities. \enotez\ declares +the object \code{enotez-list} and two templates for it, the template +\code{paragraph} and the template \code{list}. + +\subsubsection{The \code{paragraph} Template} +The \code{paragraph} template's interface is defined as follows: +\begin{sourcecode} + \DeclareTemplateInterface{enotez-list}{paragraph}{1} + { + % parameter : type = default + heading : function 1 = \section*{#1} , + format : tokenlist = \footnotesize , + number : function 1 = \enmark{#1} , + number-format : tokenlist = \normalfont , + notes-sep : length = .5\baselineskip , + } +\end{sourcecode} +The parameters functions are these: +\begin{description}[style=nextline] + \item[\code{heading}] The command with which the heading is typeset. + \item[\code{format}] The format of the whole list. + \item[\code{number}] The command that is used to typeset the numbers of the + notes. The command \cs{enmark} is explained soon. + \item[\code{numbers-format}] The format of the numbers. + \item[\code{notes-sep}] Additional space between the notes. +\end{description} + +\enotez\ uses this template to define the instance \code{plain}: +\begin{sourcecode} + \DeclareInstance{enotez-list}{plain}{paragraph}{} +\end{sourcecode} +This is the default style of the list. + +You can easily define your own instances, though: +\begin{sourcecode} + \DeclareInstance{enotez-list}{custom}{paragraph} + { + heading = \chapter*{#1} , + notes-sep = \baselineskip , + format = \normalfont , + number = \textsuperscript{#1} + } +\end{sourcecode} +This would use a chapter heading for the title, separate the notes with +\cs*{baselineskip} and typeset them with \cs*{normalfont}. The numbers would +be typeset with \cs*{textsuperscript}. You could now use it like this: +\begin{sourcecode} + \printendnotes[custom] +\end{sourcecode} + +If you wanted superscripted numbers, you could also redefine \cs{enmark}. +\begin{commands} + \command{enmark} + this command is initially defined like this: + \verbcode=\newcommand*\enmark[1]{#1.}= +\end{commands} + +\subsubsection{The \code{list} Template} +The \code{list} template's interface is defined as follows: +\begin{sourcecode} + \DeclareTemplateInterface{enotez-list}{list}{1} + { + % parameter : type = default + heading : function 1 = \section*{#1} , + format : tokenlist = \footnotesize , + number : function 1 = \enmark{#1} , + number-format : tokenlist = \normalfont , + list-type : tokenlist = description , + } +\end{sourcecode} +This template uses a list to typeset the notes. As you can see the default +list is a \code{description} list. + +\enotez\ defines two instances of this template: +\begin{sourcecode} + \DeclareInstance{enotez-list}{description}{list}{} + \DeclareInstance{enotez-list}{itemize}{list}{list-type = itemize} +\end{sourcecode} +They're available through \cs{printendnotes}\Oarg{description} and +\cs{printendnotes}\Oarg{itemize}, respectively. + +Again you can define your own instances using whatever list you want, possibly +one defined with the power of \pkg{enumitem}. + +\section{Collect Notes Section-wise and Print List Stepwise}\label{sec:split} +\emph{This feature is experimental and surely has some limitations. Please + let me know if something doesn't work as expected}. + +Not to be misunderstood: you can use \cs{printendnotes} as often as you like, +possibly after each section. That is \emph{not} what is meant here. Let's +suppose you are writing a book and have many endnotes in many chapters. It +would be nice if the list of endnotes at the end of the book could be split +into parts for each chapter. This section describes how you can achieve that +with \enotez. + +First of all \enotez\ will rely on the fact that you use \cs{printendnotes} +only \emph{once}! If you call it more times nobody knows what will +happen\ldots + +You'll need to tell \enotez\ that you want to split the notes into groups. +\begin{options} + \keychoice{split}{section,chapter,false}\Default{false} + Enable the automatic splitting. + \keyval{split-sectioning}{csname}\Default + \emph{This option is deprecated and may be dropped in future versions!} + The command that is used to display the titles between the splits. It + needs to be a command that takes one argument and should be entered + without the leading backslash. If the option is not used \enotez\ will + choose \code{subsection*} for \keyis{split}{section} and \code{section*} + for \keyis{split}{chapter}. + \keyval{split-heading}{sectioning command including argument} + \sinceversion{0.3}The command that is used to display the titles between + the splits. It is entered with argument and the actual title is referred + to with \code{\#1}, \eg, + \keyis{split-heading}{\cs*{subsection}\sarg\Marg{\#1}}. If the option is + not used \enotez\ will choose \cs*{subsection}\sarg\Marg{\#1} for + \keyis{split}{section} and \cs*{section}\sarg\Marg{\#1} for + \keyis{split}{chapter}. + \keyval{split-title}{tokenlist}\Default{Notes for <name> <ref>} + The title that will be inserted between the splits. \code{<name>} is + replaced by \code{section} for \keyis{split}{section} and \code{chapter} + for \keyis{split}{chapter}. \code{<ref>} is replaced by the corresponding + \cs*{thesection} or \cs*{thechapter}. +\end{options} +Set the \option{split} option: +\begin{sourcecode} + \setenotez{split=section} +\end{sourcecode} +Well -- that's it, basically. You'll have to be careful, though: if you're +having nested endnotes the nested ones appear first in the ``Notes'' section +(or chapter, respectively). In this case you should have a numbered section +title for the notes, presumably in the appendix. You'll need to create a new +list style: +\begin{sourcecode} + % preamble: + \usepackage{enotez} + \DeclareInstance{enotez-list}{section}{paragraph}{heading=\section{#1}} + \setenotez{list-style=section,split=section} + % document: + \appendix + \printendnotes +\end{sourcecode} + +Please beware that the option \option{reset} also impacts here: the numbering +will be reset for each section or chapter, depending on the choice you made +for \option{split}. + +There are additional commands: +\begin{commands} + \command{AtEveryListSplit}[\marg{code}] + Inserts\sinceversion{0.7} \meta{code} before each sub-heading in a + splitted list. + \command{AfterEveryListSplit}[\marg{code}] + Inserts\sinceversion{0.7} \meta{code} after each sub-heading in a splitted + list. + \command{EnotezCurrentSplitTitle} + Holds\sinceversion{0.7} the current sub-heading in a splitted list and may + be used in \cs{AtEveryListSplit} and \cs{AfterEveryListSplit}. + \command{NewSplitTitleTag}[\marg{tag}\marg{replacement}] + In\sinceversion{0.8} the sub-headings of a splitted list, the tags + \code{<ref>}, \code{<name>} and \code{<split-level-id>} can be used per + default. This command allows to define additional tags. +\end{commands} + +The tags that can be used for setting the sub-headings of a splitted list have +the following meaning: +\begin{description} + \item[\code{<ref>}] The counter representation of the current section or + chapter, \ie, either the corresponding expansion of \cs*{thesection} or + \cs*{thechapter}, depending on the split-level. + \item[\code{<name>}] The name of the split-level, \ie, either ``section'' or + ``chapter'', depending on the split-level. This is language sensitive + (see section~\ref{sec:language-support}). The corresponding translation + ids are \code{enotez-section} and \code{enotez-chapter}, respectively. + \item[\code{<split-level-id>}] The number of the current section or chapter, + \ie, either the corresponding expansion of \verbcode+\arabic{section}+ or + \verbcode+\arabic{chapter}+, depending on the split-level. +\end{description} +The command \cs{NewSplitTitleTag} let's you define your own. You can use the +three existing tags inside the replacement. Note that the \meta{tag} argument +is input without opening \code{<} and closing \code{>}! +\cs{NewSplitTitleTag}\Marg{own}\Marg{...} would define the tag \code{<own>}. + +\enotez\ comes with an example document for a split list which you should find +in the same folder as this documentation. + +\section{Language Support}\label{sec:language-support} +\enotez\ uses the \pkg{translations} package~\cite{pkg:translations} to +translate language dependent strings. The advantage of this is that language +settings with \pkg{babel}~\cite{pkg:babel} or +\pkg{polyglossia}~\cite{pkg:polyglossia} are detected automatically. However, +the available translations are somewhat limited due to my limited language +knowledge. If you find missing or wrong translations you can try to add or +correct them by adding the corresponding versions of the following lines to +your preamble: +\begin{sourcecode} + \DeclareTranslation{English}{enotez-title}{Notes} + % ``<name> <ref>'' is a placeholder for e.g. ``section 1'': + \DeclareTranslation{English}{enotez-splitted-title}{Notes for <name> <ref>} + \DeclareTranslation{English}{enotez-section}{section} + \DeclareTranslation{English}{enotez-chapter}{chapter} +\end{sourcecode} +If you like you can also drop me an email at +\href{mailto:contact@mychemistry.eu}{contact@mychemistry.eu} and I'll add the +correct translations to \enotez. + +\section{hyperref Support} +If \pkg{hyperref} is loaded and you are using the option \option{totoc} (see +page~\pageref{key:totoc}) the list title is linked via a \cs*{phantomsection}. + +If \pkg{hyperref} is used with \code{hyperfootnotes} set to \code{true} the +endnote marks are linked to the respective entries in the +list\changedversion{0.7}. If you also set \enotez' option \option{backref} +(see page~\pageref{key:backref}) the notes in the list are themselves linked +to the marks in the text. + +\AtNextEndnotesList{This is an example of a preamble to the list set with +\cs{AtNextEndnotesList}.} +\AfterEveryEndnotesList{\noindent This is an example of a postamble to the + list set with \cs{AfterEveryEndnotesList}. Note that it would have started + with a paragraph indent which was prevented here by using \cs*{noindent}.} +\printendnotes[addsec] + +\end{document} |