diff options
author | Norbert Preining <norbert@preining.info> | 2023-06-13 03:01:24 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2023-06-13 03:01:24 +0000 |
commit | af047c6e9cda7dd92590260e413522353215bf2d (patch) | |
tree | 41d7a73410e22152d46ea1c37e5c3425c38e4789 /macros/latex/contrib/postnotes/postnotes.tex | |
parent | c17d6d7111c3e6e6d92d99ba3b5bf8caf4d5b911 (diff) |
CTAN sync 202306130301
Diffstat (limited to 'macros/latex/contrib/postnotes/postnotes.tex')
-rw-r--r-- | macros/latex/contrib/postnotes/postnotes.tex | 1001 |
1 files changed, 0 insertions, 1001 deletions
diff --git a/macros/latex/contrib/postnotes/postnotes.tex b/macros/latex/contrib/postnotes/postnotes.tex deleted file mode 100644 index 0be7d50573..0000000000 --- a/macros/latex/contrib/postnotes/postnotes.tex +++ /dev/null @@ -1,1001 +0,0 @@ -% \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.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_true: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_true: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} |