diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/postnotes/postnotes-doc.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/postnotes/postnotes-doc.tex | 1001 |
1 files changed, 1001 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/postnotes/postnotes-doc.tex b/Master/texmf-dist/doc/latex/postnotes/postnotes-doc.tex new file mode 100644 index 00000000000..3d29f76a69c --- /dev/null +++ b/Master/texmf-dist/doc/latex/postnotes/postnotes-doc.tex @@ -0,0 +1,1001 @@ +% \iffalse meta-comment +% +% File: postnotes.tex +% +% This file is part of the LaTeX package "postnotes". +% +% Copyright (C) 2022-2023 Gustavo Barros +% +% It may be distributed and/or modified under the conditions of the +% LaTeX Project Public License (LPPL), either version 1.3c of this +% license or (at your option) any later version. The latest version +% of this license is in the file: +% +% https://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 is "maintained" (as per LPPL maintenance status) by +% Gustavo Barros. +% +% This work consists of the files postnotes.dtx, +% postnotes.ins, +% postnotes-doc.tex, +% postnotes-code.tex, +% and the files generated from them. +% +% The released version of this package is available from CTAN. +% +% ----------------------------------------------------------------------- +% +% The development version of the package can be found at +% +% https://github.com/gusbrs/postnotes +% +% for those people who are interested. +% +% ----------------------------------------------------------------------- +% +% \fi + +\documentclass{l3doc} + +% The package itself *must* be loaded so that \GetFileInfo can pick up date +% and version data. +\usepackage{postnotes} +\postnotesetup{ + heading={ + \section*{\pntitle} + \markright{\pnheaderdefault} + \addcontentsline{toc}{section}{\pntitle} + } , +} + +\usepackage[T1]{fontenc} + +\usepackage[sc]{mathpazo} +\linespread{1.05} +\usepackage[scale=.88]{tgheros} % sans +\usepackage[varqu,scaled=1.03]{inconsolata} % tt +\usepackage{microtype} + +\hypersetup{hidelinks} + +\usepackage{zref-clever} +\zcsetup{ + cap, + countertype = { pnexample = example } , +} +\usepackage{zref-titleref} +\usepackage{zref-check} + +\usepackage{listings} +\lstdefinestyle{code}{ + language=[LaTeX]TeX, + alsoletter = {_:}, + moretexcs={ + \chapter , + \@mkboth , + \@textsuperscript , + \AddToHook , + \counterwithin , + \tableofcontents , + \ExplSyntaxOn , + \ExplSyntaxOff , + \NewDocumentCommand , + \tl_if_eq:NNTF , + \bool_case:nF , + \str_if_eq_p:ee , + \prg_replicate:nn , + \lipsum , + \addto , + \gappto , + \extras , + \captions , + } +} +\lstdefinestyle{postnotes}{ + style=code, + moretexcs={ + \postnote , + \postnoteref , + \postnotesection , + \printpostnotes , + \postnotesetup , + \pntitle , + \pnhdnotes , + \pnhdtopage , + \pnhdtopages , + \pnheaderdefault , + \pnthechapter , + \pnthesection , + \pnthechapternextnote , + \pnthesectionnextnote , + \pnhdpagefirst , + \pnhdpagelast , + \pnhdchapfirst , + \pnhdchaplast , + \pnhdsectfirst , + \pnhdsectlast , + \pnhdnamefirst , + \pnhdnamelast , + \mypnheader , + \demochapter , + } +} +\lstset{ + style=postnotes, + basicstyle=\ttfamily\small, + columns=fullflexible, + keepspaces, + xleftmargin=\leftmargin, + xrightmargin=.5\leftmargin, +} +% Setup inspired by https://tex.stackexchange.com/a/4068. For how to use these +% environments in a .dtx context see https://tex.stackexchange.com/a/31026. +\newcounter{pnexample} +\lstnewenvironment{pnexample}[1][]{% + \renewcommand{\lstlistingname}{Example}% + \renewcommand*\theHlstlisting{ht.\thelstlisting}% + \lstset{#1}% + \setcounter{lstlisting}{\value{pnexample}}% +}{} +\lstnewenvironment{pnsnippet}[1][]{% + \renewcommand{\lstlistingname}{Example}% + \lstset{#1}% +}{} +\ExplSyntaxOn +\makeatletter +\lst@AddToHook { PreInit } + { + \cs_if_exist:cT { c@ \lstenv@name } + { \exp_args:Nx \refstepcounter { \lstenv@name } } + } +\makeatother +\ExplSyntaxOff + +\setlength{\marginparsep}{2\labelsep} + +\NewDocumentCommand\opt{m}{\texttt{#1}} + +\NewDocumentCommand\username{m}{`\texttt{#1}'} + +\begin{document} + +\GetFileInfo{postnotes.sty} + +\title{% + The \pkg{postnotes} package% + \thanks{This file describes \fileversion, released \filedate.}% + \texorpdfstring{\\{}\medskip{}}{ - }% + User manual% + \texorpdfstring{\medskip{}}{}% +} + +\author{% + Gustavo Barros% + \thanks{\url{https://github.com/gusbrs/postnotes}}% +} + +\date{\filedate} + +\maketitle + +\begin{center} + {\bfseries \abstractname\vspace{-.5em}\vspace{0pt}} +\end{center} + +\begin{quotation} + \pkg{postnotes} is an endnotes package for \LaTeX{}. Its user interface + provides means to print multiple sections of notes along the document, and + to subdivide them either automatically -- by chapter, by section -- or at + manually specified places, thus being able to easily handle both numbered + and unnumbered headings. The package also provides infrastructure for + setting up contextual running headers for printed notes. The default is a + simple but useful one, in the form ``Notes to pages N--M'', but more + elaborate ones can be built. When \pkg{hyperref} is loaded, \pkg{postnotes} + provides hyperlinked notes, including back links. +\end{quotation} + +\clearpage{} + +\tableofcontents + +\clearpage{} + +\section{Introduction} + +\pkg{postnotes} is an endnotes package for \LaTeX{}. Its user interface +provides means to print multiple sections of notes along the document, and to +subdivide them either automatically -- by chapter, by section -- or at +manually specified places, thus being able to easily handle both numbered and +unnumbered headings. The package also provides infrastructure for setting up +contextual running headers for printed notes. The default is a simple but +useful one, in the form ``Notes to pages N--M'', but more elaborate ones can +be built. When \pkg{hyperref} is loaded, \pkg{postnotes} provides hyperlinked +notes, including back links. + +Though this feature set is mostly (albeit not completely) available in one or +another of the existing endnotes packages for \LaTeX{}, subsets of it exist in +individual packages, not necessarily compatible with each other. +\pkg{postnotes} brings these features together in one place, with no external +dependencies except an up-to-date kernel. + +On the technical side, \pkg{postnotes} is peculiar among existing \LaTeX{} +packages in this area of functionality by the fact that it does not use an +external file to store the notes. Both the notes' contents and its metadata +are stored in variables which are later retrieved at the time of printing. In +particular, the content of the note is stored and retrieved with ``no +manipulation'' (as in \texttt{expl3}'s \texttt{N}/\texttt{n} function +signatures) and only gets to be expanded at the time it is meant to be +typeset. The \file{.aux} file is leveraged to set page labels for the notes, +since that particular information has to be retrieved asynchronously but, +other than that, variables are employed to pass information around. + +This has some advantages. First, as is well known, sending arbitrary content +to a file to be read later is not a noiseless process in \LaTeX{}. Thus, not +doing so makes things smoother. Second, the external file approach is +strictly linear: the notes which were written to the file get printed as such, +in the order they were written. Having the notes available as a set of +variables allows for some more flexibility than that, through the possibility +of pre-processing the notes before printing. It also brings some extra +degrees of freedom in storing note metadata, and in restoring part of the +environment where the note is called to where the note's content is printed. + + +\section{Loading the package} + +\pkg{postnotes} can be loaded with the usual: + +\begin{pnsnippet} +\usepackage{postnotes} +\end{pnsnippet} + +The package does not accept load-time options, package options must be set +using \cs{postnotesetup} (see \zcref{sec:options}, +\zcref[ref=title,noname]{sec:package-options}). + +\section{User interface} + +\begin{function}{\postnote} + \begin{syntax} + \cs{postnote}\oarg{options}\marg{text} + \end{syntax} +\end{function} +Sets a postnote with content \meta{text}. A note ``mark'' is typeset at the +place \cs{postnote} is called, and \meta{text} is stored to be typeset later, +on the next call to \cs{printpostnotes}. The mark is usually determined by +the printed representation of the main counter, \texttt{postnote}, but can be +manually set too. \cs{postnote} can receive a number of \meta{options}, which +are presented in \zcref{sec:options}, +\zcref[ref=title,noname]{sec:note-options}. + +\begin{function}{\postnotesection} + \begin{syntax} + \cs{postnotesection}\oarg{options}\marg{text} + \end{syntax} +\end{function} +Sets a postnote section with content \meta{text}. This is the basic interface +for making notes subdivisions, and it places \meta{text} between the notes +where it occurs, at the point the notes are printed by \cs{printpostnotes}. +For more details and some examples, see \zcref{sec:notes-sections}. Its +\meta{options} are presented in \zcref{sec:options}, +\zcref[ref=title,noname]{sec:section-options}. + +\begin{function}{\printpostnotes} + \begin{syntax} + \cs{printpostnotes} + \end{syntax} +\end{function} +Prints the \cs{postnotes} set since the last call of \cs{printpostnotes}, or +since the beginning of the document. For two basic usage illustrations, see +\zcref{ex:sect:basic,ex:x:multi-print}. + +\begin{function}{\postnoteref} + \begin{syntax} + \cs{postnoteref}\meta{*}\marg{label} + \end{syntax} +\end{function} +Typesets a postnote reference to \meta{label}. Of course, \meta{label} must +have been set to a particular postnote, which can be done by the standard +\cs{label} command. The starred version of the command inhibits hyperlinking. +When the \pkg{zref-user} package is loaded, a corresponding \cs{postnotezref} +is also provided, and if \pkg{zref-hyperref} is also loaded, it is hyperlinked +as its counterpart. + + +\section{Options} +\zlabel{sec:options} + +\subsection*{Package options} +\zlabel{sec:package-options} + +\begin{function}{\postnotesetup} + \begin{syntax} + \cs{postnotesetup}\marg{options} + \end{syntax} +\end{function} +Package options can be configured by means of \cs{postnotesetup}, which +receives options and values in \texttt{key=value} fashion. + +\bigskip{} + +\DescribeOption{heading} % +\DescribeMacro{\pnheading} % +The \opt{heading} option sets the heading for the printed notes or, more +generally put, that which is printed at the beginning of \cs{printpostnotes}. +Its default value depends on the document class in use. If \cs{chapter} is +defined, the default is: +\begin{pnsnippet} +\chapter*{\pntitle} +\@mkboth{\pnheaderdefault}{\pnheaderdefault} +\end{pnsnippet} +but otherwise, it is: +\begin{pnsnippet} +\section*{\pntitle} +\@mkboth{\pnheaderdefault}{\pnheaderdefault} +\end{pnsnippet} +where \cs{pntitle} is localizable string, which by default contains ``Notes'' +(see \zcref{sec:localization}), and \cs{pnheaderdefault} is a function which +takes no arguments, but processes a number of variables, to set a contextual +running header for the printed notes (see \zcref{sec:headers}). +\cs{pnheaderdefault} produces a header in the form ``Notes to pages N--M'', +according to the notes in each page. If you prefer, you can redefine +\cs{pnheading} instead of using the \opt{heading} option, to the same effect. + +\DescribeOption{format} % +The \opt{format} option stores formatting instructions for printing the +notes. It is called at \cs{printpostnotes}, every time a block of notes is +about to start. The default value is \cs{small}. + +\DescribeOption{listenv} % +The \opt{listenv} option sets the list environment inside which the notes are +printed in \cs{printpostnotes}. This must be the name of an existing list +environment, and \pkg{postnotes} provides two suitable ones for convenience: +\env{postnoteslist}, which is the default, and \env{postnoteslisthang} which +typesets the notes with a hanging indent. You can also create your own, with +\pkg{enumitem} or otherwise, of course. \opt{listenv} can also receive the +special value \texttt{none}, in which case the notes blocks are not wrapped in +a list environment, but rather typeset as plain paragraphs. +\texttt{\opt{listenv}=none} already sets \opt{postprintnote} to \cs{par} for +that reason but, when using \texttt{none}, you'll probably also want to set +\opt{maketextmark}, \opt{pretextmark}, or \opt{posttextmark} to values +different than the defaults. + +\DescribeOption{makemark} % +\DescribeOption{maketextmark} % +\DescribeMacro{\pnthepage} % +The \opt{makemark} and \opt{maketextmark} options control how the mark is to +be typeset, at the point \cs{postnote} is called and at the point the note's +text is printed at \cs{printpostnotes}, respectively. They both can receive +three arguments: \texttt{\#1} is the mark itself, and arguments \texttt{\#2} +and \texttt{\#3} are, respectively, the start and the end of the hyperlink +(hence they must be used in this order, and always in pair). Their default +values are: +\begin{pnsnippet} +makemark = {#2\hbox{\@textsuperscript{\normalfont#1}}#3} , +maketextmark = {#2#1.#3} , +\end{pnsnippet} +At the point \opt{maketextmark} gets typeset, the \cs{pnthepage} variable +contains the value of \cs{thepage} where its corresponding note was set. + +\DescribeOption{pretextmark} % +\DescribeOption{posttextmark} % +\DescribeOption{postprintnote} % +The options \opt{pretextmark}, \opt{posttextmark}, and \opt{postprintnote} +allow to insert additional material in \cs{printpostnotes}, respectively, +right before the mark, right after the mark, and after the note's content. +All in all, when \opt{listenv} is not \texttt{none}, each note in the list is +laid out in the form: +\begin{pnsnippet}[escapeinside=`'] +\item[`\meta{pretextmark}'`\meta{mark}'`\meta{posttextmark}']`\meta{note content}'`\meta{postprintnote}' +\end{pnsnippet} +and when \opt{listenv} is \texttt{none}, each note is laid out in the form: +\begin{pnsnippet}[escapeinside=`'] +`\meta{pretextmark}'`\meta{mark}'`\meta{posttextmark}'`\meta{note content}'`\meta{postprintnote=\textbackslash{}\textbf{par}}' +\end{pnsnippet} + +\DescribeOption{style} % +\opt{style} is just a convenience ``meta'' option which sets a number of +``base'' options -- such as \opt{listenv}, \opt{format}, \opt{maketextmark}, +etc.\ -- in order to emulate known styles of printing the notes. It accepts +the values \texttt{endnotes} or \texttt{pagenote} so that \cs{printpostnotes} +works as its counterparts in each of these packages. + +\DescribeOption{hyperref} % +\DescribeOption{backlink} % +The \opt{hyperref} option controls the use of \pkg{hyperref} by +\pkg{postnotes} and takes values \opt{auto}, \opt{true} or \opt{false}. The +default value, \opt{auto}, makes \pkg{postnotes} use \pkg{hyperref} if it is +loaded. \opt{true} does the same thing, but warns if \pkg{hyperref} is not +loaded (\pkg{hyperref} is never loaded for you). \opt{false} means not to use +\pkg{hyperref} regardless of its availability. The \opt{backlink} option +controls whether only a link from the note to is respective text at +\cs{printpostnotes} is created, or if a back link from the text at +\cs{printpostnotes} back to where the note's mark is placed is also made +available. It is a boolean option, defaults to \texttt{true}, and is only +operational if \opt{hyperref} is not \texttt{false}. These are both preamble +only options. + +\DescribeOption{sort} % +The \opt{sort} option controls whether the notes queue is sorted or not at +\cs{printpostnotes}. Normally, the order the notes should be printed is the +one in which the notes were placed along the document. However, in cases +where some manual intervention was required, sorting the notes can be quite +useful, and difficult to handle in its absence. Two typical examples are: a +note inside a float which disturbed the sequence of the \texttt{postnote} +counter (see \zcref{ex:x:float} in \zcref{sec:further-examples} for an +illustration) and a manually set mark, in which case \pkg{postnotes} also +allows to manually set a sort value with the \opt{sortnum} option of +\cs{postnote}. Sorting does not cross boundaries of notes sections, as set by +\cs{postnotesection}, in other words, if notes sections exist, sorting is only +ever carried out within the boundaries of each section. This may be a +restriction for cases in which floats cross sections' boundaries, but it's the +only reasonable thing to do. \opt{sort} is a boolean option, and defaults to +\texttt{true}. + + +\subsection*{Note options} +\zlabel{sec:note-options} + +The options accepted by \cs{postnote}\oarg{options}\marg{text} are the +following: + +\bigskip{} + +\DescribeOption{mark} % +\DescribeOption{markstr} % +By default, the mark generated by \cs{postnote} is determined by the printed +representation of the \texttt{postnote} counter, \cs{thepostnote}, which is +stepped when \cs{postnote} is called. But the \opt{mark} and \opt{markstr} +options allow you to manually set it, in case you want, or need, to do so. +When either \opt{mark} or \opt{markstr} is manually set, the \texttt{postnote} +counter is not stepped. The difference between them is that \opt{mark} must +receive a number as value, and uses its value to also set the \opt{sortnum} +option, while \opt{markstr}, differently from the optional argument of +\cs{footnote}, can receive a string as value which is directly used as the +mark, but it does not set \opt{sortnum}. + +\DescribeOption{sortnum} % +Normally, the sort value used for sorting the notes queue (see the \opt{sort} +package option above) is determined by the value of the \texttt{postnote} +counter (that is, by \cs{the}\cs{c@postnote}, and not by its printed +representation, \cs{thepostnote}). But you may specify this sort value +manually with the \opt{sortnum} option, typically, when you have also manually +specified the mark. It receives a floating point number as value. So, for +example, if one needed to insert a note between notes 2 and 3, without +disturbing the numbering of other notes, one could use +\texttt{\cs{postnote}[markstr=2*,sortnum=2.5]\marg{text}}. + +\DescribeOption{nomark} % +The \opt{nomark} option makes \cs{postnote} inhibit the typesetting of the +mark. Of course, normally, we do want the visual cue of the mark, but the +intended use case for this option is for a \cs{postnote} with \opt{nomark} to +be paired with a \cs{postnoteref}, so as to be able to typeset a note in +places where doing so directly may be problematic. For a practical example +and an illustration on how to use it, see \zcref{ex:x:caption} in +\zcref{sec:further-examples}. + +\DescribeOption{label} % +The \opt{label} option sets a standard \cs{label} named with the value given +to the option. When the \pkg{zref-user} package is loaded, a corresponding +\opt{zlabel} option is also provided. See \zcref{sec:cross-references} for +details about cross-referencing. + + +\subsection*{Section options} +\zlabel{sec:section-options} + +The options accepted by \cs{postnotesection}\oarg{options}\marg{text} are the +following: + +\bigskip{} + +\DescribeOption{name} % +For the purposes of building running headers, each \cs{postnotesection} can be +identified by its \opt{name}. This is mainly intended to support unnumbered +headings, but its mechanism is general. The name of a note section is made +available for the first and last note on a given page through the variables +\cs{pnhdnamefirst} and \cs{pnhdnamelast} at the moment the header of the page +is typeset. For details on how to use these variables, see +\zcref{sec:headers}. + +\DescribeOption{exp} % +By default, \cs{postnotesection} stores its \meta{text} argument with ``no +manipulation''. The \opt{exp} option allows one to fully expand +(\texttt{x}-type expansion) \meta{text} in place before storing it. It is a +boolean option, and the option given with no value is equivalent to +\texttt{exp=true}. + + +\section{Notes sections} +\zlabel{sec:notes-sections} + +As mentioned above, \cs{postnotesection} is the basic interface for +subdividing the notes when printed. For those familiar with it, this command +is \pkg{postnotes}'s equivalent to \pkg{endnotes}' \cs{addtoendnotes}. It has +the same intended use -- to add text or commands along the notes' sequence at +the point it is called -- and the way it works is quite similar to +\cs{addtoendnotes}. But there are some differences, prominently a +\cs{postnotesection} is skipped at \cs{printpostnotes} if it contains no +notes. In other words, if two (or more) calls of \cs{postnotesection} occur +in immediate sequence, with no \cs{postnote} in between, the latter call takes +precedence over the former, instead of being accumulated in the queue. This +is intended to facilitate the automation of the subdivision of the notes. So, +one can, for example, use a hook to \cs{chapter} and not have to worry if a +chapter with no notes will generate an empty section inside +\cs{printpostnotes}, e.g., by the call to \cs{chapter*} at the table of +contents, and so on. Or, one can use the heading number for the automated +case, but be able to override it manually for an occasional unnumbered one. +For this reason, a more semantic name was chosen for it, instead of the +generic ``add to''. + +\DescribeMacro{\pnthechapter} % +\DescribeMacro{\pnthesection} % +\DescribeMacro{\pnthechapternextnote} % +\DescribeMacro{\pnthesectionnextnote} % +Just like with \cs{postnote}, the contents of \cs{postnotesection} are not +expanded in place, but rather stored with ``no manipulation'' to be typeset +later at \cs{printpostnotes}. For this reason, some contextual information is +stored at the place \cs{postnotesection} is called, and made available at the +point it's content gets expanded by means of some variables (you can use +\cs{postnotesection}\texttt{[exp]} instead, in which case these variables are +of little use). When the content of a notes section gets typeset, +\cs{pnthechapter} contains the value of \cs{thechapter} where +\cs{postnotesection} was originally called. Similarly, \cs{pnthesection} +contains the value of \cs{thesection}. \cs{pnthechapternextnote} and +\cs{pnthesectionnextnote} are meant to support the automation of the notes +subdivision by using hooks to sectioning commands, which is a quite natural +way to do this. However, since it may be problematic to hook \emph{after} +sectioning commands -- \cs{section}, for example, figures prominently in the +documentation of \pkg{ltcmdhooks} as a case of ``look ahead'' command for +which the \texttt{after} hook is not supported -- we will typically want to +hook \emph{before} them. But, at this point the values of the +\texttt{chapter} or \texttt{section} counters have not yet been stepped, +therefore \cs{thechapter} and \cs{thesection} do not correspond to what we +would like to refer to. For this reason, \cs{pnthechapternextnote} contains +the value of \cs{thechapter} at the point the ``next note'' is placed (a +\cs{postnote}, that is), the first in the chapter, and already inside it, thus +with an expected value of the \texttt{chapter} counter. Similarly, +\cs{pnthesectionnextnote} contains the value of \cs{thesection} for the ``next +note''. Of course, the ``next note'' variables are \emph{proxies}, but they +are meant to support the automation of the subdivision of the notes through +the use of \texttt{before} hooks to the document's sectioning commands, in +which case the subdivision of the notes will correspond to the document's +structure and, given empty notes sections are skipped, the values will be the +ones we are interested in. But more complex use cases may require something +different. Either way, it is up to the user to judge whether the \emph{proxy} +is a good one for their use case, the variables just do what they say, and +contain the values of interest for the ``next note''. + +This is meant to be simple. Some examples might make things more concrete. +At its most basic, \cs{postnotesection} can just be set manually: + +\begin{pnexample}[caption={Basic usage},label={ex:sect:basic}] +\documentclass{book} +\usepackage{postnotes} +\usepackage{hyperref} +\begin{document} +\chapter{First chapter} +\postnotesection{\section*{Notes to chapter \pnthechapter}} +Foo.\postnote{Foo note.} +Bar.\postnote{Bar note.} +\chapter{Second chapter} +\postnotesection{\section*{Notes to chapter \pnthechapter}} +\setcounter{postnote}{0} +Baz.\postnote{Baz note.} +Boo.\postnote{Boo note.} +\printpostnotes +\end{document} +\end{pnexample} + +The document in \zcref{ex:sect:basic} resets the \texttt{postnote} counter for each +chapter, and manually sets notes sections by chapter, which results in +\cs{printpostnotes} being correspondingly subdivided. But it is easy to make +this automatic: + +\begin{pnexample}[caption={Automating notes subdivision with a hook},label={ex:sect:auto}] +\documentclass{book} +\usepackage{postnotes} +\AddToHook{cmd/chapter/before}{% + \postnotesection{\section*{Notes to chapter \pnthechapternextnote}}} +\counterwithin*{postnote}{chapter} +\usepackage{hyperref} +\begin{document} +\tableofcontents +\chapter{First chapter} +Foo.\postnote{Foo note.} +Bar.\postnote{Bar note.} +\chapter{Second chapter} +Baz.\postnote{Baz note.} +Boo.\postnote{Boo note.} +\printpostnotes +\end{document} +\end{pnexample} + +\zcref{ex:sect:auto} uses the \texttt{cmd/chapter/before} hook, and thus +\cs{pnthechapternextnote} to retrieve the correct chapter number for +\cs{postnotesection}, as explained above. The counter is reset every chapter +by means of \cs{counterwithin*}. Note that the call to \cs{chapter*} inside +\cs{tableofcontents} does not generate a spurious notes section at +\cs{printpostnotes} (as long as you don't place a note in a sectioning command +with no short argument, which you shouldn't do anyway). But what if we have, +among mostly numbered chapters, an ocasional unnumbered one? +\cs{pnthechapternextnote} wouldn't possibly work in this case. Since +immediately successive calls to \cs{postnotesection} override the previous +ones, it is straightforward to just manually adjust the exception: + +\begin{pnexample}[caption={Fine-tuning automation},label={ex:sect:fine-auto}] +\documentclass{book} +\usepackage{postnotes} +\AddToHook{cmd/chapter/before}{% + \postnotesection{\section*{Notes to chapter \pnthechapternextnote}}} +\counterwithin*{postnote}{chapter} +\usepackage{hyperref} +\begin{document} +\tableofcontents +\chapter*{Introduction} +\postnotesection{\section*{Notes to the introduction}} +Intro.\postnote{Intro note.} +\chapter{First chapter} +Foo.\postnote{Foo note.} +Bar.\postnote{Bar note.} +\chapter{Second chapter} +Baz.\postnote{Baz note.} +Boo.\postnote{Boo note.} +\printpostnotes +\end{document} +\end{pnexample} + +\section{Headers} +\zlabel{sec:headers} + +\pkg{postnotes}' support for running headers comprises a basic header, enabled +by default, generating headers in the form ``Notes to pages N--M'', but also +some infrastructure for users to build more elaborate ones. + +The default headers are generated by the function \cs{pnheaderdefault} which, +as we saw in \zcref{sec:section-options} is used to set the headers in option +\opt{heading} (with \cs{@mkboth}). So, the default headers are enabled +through that particular setting. + +Examining the definition of \cs{pnheaderdefault} is possibly the most direct +way to explore how the feature is meant to work. + +\begin{pnsnippet} +\ExplSyntaxOn +\NewDocumentCommand \pnheaderdefault {} + { + \tl_if_eq:NNTF \pnhdpagefirst \pnhdpagelast + { \pnhdnotes{} ~ \pnhdtopage{} ~ \pnhdpagefirst } + { \pnhdnotes{} ~ \pnhdtopages{} ~ \pnhdpagefirst -- \pnhdpagelast } + } +\ExplSyntaxOff +\end{pnsnippet} + +\cs{pnhdnotes}, \cs{pnhdtopage}, and \cs{pnhdtopages} are localizable strings, +which by default respectively contain ``Notes'', ``to page'', and ``to pages'' +(see \zcref{sec:localization}). Let's replace them to examine the interesting +part of the definition: + +\begin{pnsnippet} +\ExplSyntaxOn +\NewDocumentCommand \pnheaderdefault {} + { + \tl_if_eq:NNTF \pnhdpagefirst \pnhdpagelast + { Notes~to~page~ \pnhdpagefirst } + { Notes~to~pages~ \pnhdpagefirst -- \pnhdpagelast } + } +\ExplSyntaxOff +\end{pnsnippet} + +\DescribeMacro{\pnhdpagefirst} % +\DescribeMacro{\pnhdpagelast} % +\DescribeMacro{\pnhdchapfirst} % +\DescribeMacro{\pnhdchaplast} % +\DescribeMacro{\pnhdsectfirst} % +\DescribeMacro{\pnhdsectlast} % +\DescribeMacro{\pnhdnamefirst} % +\DescribeMacro{\pnhdnamelast} % +\cs{pnhdpagefirst} and \cs{pnhdpagelast} store the value of \cs{thepage} for +the first and the last notes (where these notes were originally placed) of the +current page (at the point they are being printed). These variables are +updated every page along the span of \cs{printpostnotes} to the values +corresponding to their respective first and last note (which start on that +page), so that these values are available at the moment the headers get to be +typeset. Hence, what the definition of \cs{pnheaderdefault} does is to use +these variables to build a rule in the form: ``if the page of the first and +last notes are equal, write a singular form and just one value but, if they +are different, write a plural form and a range of both values''. +\cs{pnhdchapfirst}, \cs{pnhdchaplast}, \cs{pnhdsectfirst}, and +\cs{pnhdsectfirst} provide the same for \cs{thechapter} and \cs{thesection}. +\cs{pnhdnamefirst} and \cs{pnhdnamelast} contain the name of the notes +section, the one given with the \opt{name} option of \cs{postnotesection} (and +are empty in case no \opt{name} was provided). + +With that in hand, fancier headers can be built. For example, if we'd like +headers in the form ``Notes to chapters A--C, pages N--M'', we could define: +\begin{pnsnippet} +\ExplSyntaxOn +\NewDocumentCommand \mypnheader {} + { + \tl_if_eq:NNTF \pnhdchapfirst \pnhdchaplast + { Notes~to~chapter~\pnhdchapfirst,~ } + { Notes~to~chapters~\pnhdchapfirst -- \pnhdchaplast,~ } + \tl_if_eq:NNTF \pnhdpagefirst \pnhdpagelast + { page~\pnhdpagefirst } + { pages~\pnhdpagefirst -- \pnhdpagelast } + } +\ExplSyntaxOff +\end{pnsnippet} +and then set \opt{heading} to use \cs{mypnheader} instead of +\cs{pnheaderdefault}. This definition should work well as long as all the +chapters (containing notes) are numbered, but if unnumbered ones come into +play, again we can fine-tune the automation, adjusting for the exception. +That's the purpose of the \opt{name} option for \cs{postnotesection}, and of +\cs{pnhdnamefirst} and \cs{pnhdnamelast}. \zcref{ex:hd:fancy} illustrates +their use (of course, the use of \pkg{lipsum} is just for demonstration): + +\begin{pnexample}[caption={Fancy headers},label={ex:hd:fancy}] +\documentclass{book} +\usepackage{postnotes} +\postnotesetup{ + heading = {% + \chapter*{\pntitle} + \markboth{\mypnheader}{\mypnheader}% + } , +} +\counterwithin*{postnote}{chapter} +\AddToHook{cmd/chapter/before}{% + \postnotesection{\section*{Notes to chapter \pnthechapternextnote}}% +} +\ExplSyntaxOn +\NewDocumentCommand \mypnheader {} + { + \bool_case:nF + { + { + \str_if_eq_p:ee { \pnhdnamefirst } { intro } && + \str_if_eq_p:ee { \pnhdnamelast } { intro } + } + { Notes~to~the~introduction,~ } + { + \str_if_eq_p:ee { \pnhdnamefirst } { intro } && + ! \str_if_eq_p:ee { \pnhdnamelast } { intro } + } + { Notes~to~the~introduction~and~chapter~\pnhdchaplast{},~ } + } + { + \tl_if_eq:NNTF \pnhdchapfirst \pnhdchaplast + { Notes~to~chapter~\pnhdchapfirst{},~ } + { Notes~to~chapters~\pnhdchapfirst{} -- \pnhdchaplast{},~ } + } + \tl_if_eq:NNTF \pnhdpagefirst \pnhdpagelast + { page~\pnhdpagefirst{} } + { pages~\pnhdpagefirst{} -- \pnhdpagelast{} } + } +\ExplSyntaxOff +\usepackage{hyperref} +\usepackage{lipsum} +\ExplSyntaxOn +\NewDocumentCommand \demochapter { m } + { \prg_replicate:nn { #1 } { \lipsum[1-2]\postnote{\lipsum[3]}\par } } +\ExplSyntaxOff +\begin{document} +\tableofcontents +\chapter*{Introduction} +\postnotesection[name=intro]{\section*{Notes to the introduction}} +\demochapter{12} +\chapter{Chapter 1} +\demochapter{15} +\chapter{Chapter 2} +\demochapter{15} +\printpostnotes +\end{document} +\end{pnexample} + + +\section{Cross-references} +\zlabel{sec:cross-references} + +Cross-referencing with \pkg{postnotes} works in a pretty standard way: set a +label, make references to it. However, there are two ways to set a label to a +note. One can either set a label with the \opt{label} option of +\cs{postnote}, or one can directly set it with the standard \cs{label} as part +of the note's content. They are both valid, but they are not equivalent, they +have different meanings and, accordingly, behave differently. + +The label set with the \opt{label} option is set at the place where +\cs{postnote} is. The label set with \cs{label} in the note's content, is +just stored, and only gets expanded when this content gets to be typeset, at +\cs{printpostnotes}. In short, the \opt{label} option belongs to the +``mark'', while the \cs{label} set in the content belongs to the ``text''. + +Of course, the data stored in each label will correspond to this difference. +Even if the plain \cs{ref} to both will get the same value (the mark), a +\cs{pageref} will be different, the links to either will point to different +places, etc. + + +\section{Localization} +\zlabel{sec:localization} + +\DescribeMacro{\pntitle} % +\DescribeMacro{\pnhdnotes} % +\DescribeMacro{\pnhdtopage} % +\DescribeMacro{\pnhdtopages} % +\pkg{postnotes} uses a few localized strings, stored in the variables +\cs{pntitle}, \cs{pnhdnotes}, \cs{pnhdtopage}, and \cs{pnhdtopages}. The +first one is used in the default value of the \opt{heading} option and +defaults to ``Notes''. The remaining three are used in \cs{pnheaderdefault} +(and thus, indirectly also in the \opt{heading} option) and their respective +defaults are: ``Notes'', ``to page'', and ``to pages''. So, if you changed +the default value of \opt{heading} and is not using \cs{pnheaderdefault}, you +don't have to worry about them. + +These strings will automatically adjust to the document language, set either +by \pkg{babel} or by \pkg{polyglossia}, \emph{if} the language is supported by +\pkg{postnotes}. Currently supported are English, German, French, and +Portuguese. Either way, you can always change these variables to the values +of your preference. If you are not using either \pkg{babel} or +\pkg{polyglossia}, you can do so directly, for example, with: +\begin{pnsnippet} +\renewcommand*{\pntitle}{My title} +\end{pnsnippet} +However, with \pkg{babel} or \pkg{polyglossia}, and specially in a multi +language document, you must use the appropriate hooks of your language package +for this, otherwise, the next call to \cs{selectlanguage} will override your +settings. For \pkg{babel} you should use: +\begin{pnsnippet}[escapeinside=`'] +\addto\extras`\meta{language}'{\renewcommand*{\pntitle}{My title}} +\end{pnsnippet} +and for \pkg{polyglossia}: +\begin{pnsnippet}[escapeinside=`'] +\gappto\captions`\meta{language}'{\renewcommand*{\pntitle}{My title}} +\end{pnsnippet} + + +\section{Further examples} +\zlabel{sec:further-examples} + +This section collects some further usage examples which did not fit into the +previous sections, but might still be of interest. + +\bigskip{} + +\zcref{ex:x:multi-print} illustrates a basic procedure of how to obtain a note +section for each chapter of a book, by calling \cs{printpostnotes} at the end +of each chapter: + +\begin{pnexample}[caption={Notes for each chapter},label={ex:x:multi-print}] +\documentclass{book} +\usepackage{postnotes} +\postnotesetup{heading={\section*{\pntitle}}} +\usepackage{hyperref} +\begin{document} +\chapter{First chapter} +Foo.\postnote{Foo note.} +Bar.\postnote{Bar note.} +\printpostnotes +\chapter{Second chapter} +\setcounter{postnote}{0} +Baz.\postnote{Baz note.} +Boo.\postnote{Boo note.} +\printpostnotes +\end{document} +\end{pnexample} + +\zcref{ex:x:float} shows a case of a float which disturbs the order of the +notes. It demonstrates a (traditional) technique to deal with the situation, +by setting a manual mark and adjusting the counter where appropriate. It also +illustrates the role the sorting of notes can have, by producing not only +correctly ordered note marks (as a result of the manual adjustments), but also +correctly ordered printed notes (as a result of sorting): + +\begin{pnexample}[caption={Sorting and floats},label={ex:x:float}] +\documentclass{book} +\usepackage{postnotes} +\usepackage{hyperref} +\begin{document} +\chapter{First chapter} +\postnote{1} +\postnote{2} +\begin{table}[p] + \caption{Table} + Table.\postnote[mark=5]{3} +\end{table} +\postnote{4} +\postnote{5} +\stepcounter{postnote} +\clearpage +\postnote{6} +\printpostnotes +\end{document} +\end{pnexample} + +\zcref{ex:x:caption} illustrates a couple of techniques to handle long +captions. Captions pose a problem to \cs{postnote} because, if you set a +\cs{postnote} inside a standard caption, whose text is long enough to require +two lines, the content of the caption ends up being typeset twice: once to +check if it would have fitted in a single line, the second to typeset the two +lines since it didn't fit in one. This triggers the \texttt{postnote} counter +to be stepped twice (and any other counter that happens to be there too). One +way to handle the situation is, if you know(!) that the caption takes two +lines, you can decrement the counter just before it, and place the note +directly in the caption, this will get you a correctly numbered note. Another +way is to use the pairing between a \opt{nomark} \cs{postnote} and +\cs{postnoteref}: place a note outside the caption (but close to it, since its +position will determine the anchor for the backlink) with the \opt{nomark} +option, set a label inside it and, inside the caption make a \cs{postnoteref} +to the label. In practice: + +\begin{pnexample}[caption={Long caption},label={ex:x:caption}] +\documentclass{article} +\usepackage[textwidth=8cm]{geometry} +\usepackage{postnotes} +\usepackage{hyperref} +\begin{document} +\begin{figure} + Figure. + \addtocounter{postnote}{-1} + \caption[Caption for LOF]{A long caption, long enough to require two + lines\postnote{A note.}} +\end{figure} +\begin{figure} + Figure. + \postnote[nomark]{\label{en:1}A note.}% + \caption[Caption for LOF]{A long caption, long enough to require two + lines\postnoteref{en:1}} +\end{figure} +\printpostnotes +\end{document} +\end{pnexample} + + +\section{Acknowledgments} + +Some people have kindly contributed to \pkg{postnotes}. Suggestions, ideas, +insightful comments, solutions to problems, bug reports were generously +provided by (in chronological order): + Ulrike Fischer, + % 2022-03-22: https://chat.stackexchange.com/transcript/message/60708390#60708390 + % 2022-03-28: https://chat.stackexchange.com/transcript/message/60754383#60754383 + % 2022-03-31: https://github.com/latex3/hyperref/issues/230 + % 2022-04-09: https://github.com/latex3/hyperref/issues/229 + % 2023-02-10: https://chat.stackexchange.com/transcript/message/62955941#62955941 (and discussion) + % 2023-02-19: https://tex.stackexchange.com/q/675818#comment1678904_675818 + David Carlisle, + % 2022-03-28: https://chat.stackexchange.com/transcript/message/60754383#60754383 + % 2022-04-08: https://tex.stackexchange.com/a/640035 (comments) + % 2023-02-10: https://chat.stackexchange.com/transcript/message/62955941#62955941 (and discussion) + % 2023-02-10: https://tex.stackexchange.com/a/674846 + Moritz Wemheuer, + % 2022-04-05: https://tex.stackexchange.com/q/597359#comment1594585_597389 + and Joseph Wright. + % 2023-02-10: https://chat.stackexchange.com/transcript/message/62955941#62955941 (and discussion) + +The package's language support have been provided or improved thanks to: + \username{Pika78} (French) + % 2022-04-25: https://github.com/gusbrs/postnotes/issues/1#issuecomment-1108634938 + and Herbert Voß (German). + % 2022-11-12: https://github.com/gusbrs/postnotes/issues/2 + +If I have inadvertently left anyone off the list I apologize, and please let +me know, so that I can correct the oversight. + +Thank you all very much! + + +\section{Change history} + +A change log with relevant changes for each version, eventual upgrade +instructions, and upcoming changes, is maintained in the package's repository, +at \url{https://github.com/gusbrs/postnotes/blob/main/CHANGELOG.md}. The +change log is also distributed with the package's documentation through CTAN +upon release so, most likely, \texttt{texdoc postnotes/changelog} should +provide easy local access to it. An archive of historical versions of the +package is also kept at \url{https://github.com/gusbrs/postnotes/releases}. + +\end{document} |