% \iffalse meta-comment
%
% File: postnotes.tex
%
% This file is part of the LaTeX package "postnotes".
%
% Copyright (C) 2022-2023  gusbrs
%
% 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 gusbrs.
%
% 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}
\usepackage{zref-titleref}
\usepackage{zref-check}

\usepackage{listings}
\lstdefinestyle{code}{
  language=[LaTeX]TeX,
  alsoletter = {_:},
  moretexcs={
    \chapter ,
    \@mkboth ,
    \@textsuperscript ,
    \thechapter ,
    \AddToHook ,
    \AddToHookNext ,
    \counterwithin ,
    \tableofcontents ,
    \ExplSyntaxOn ,
    \ExplSyntaxOff ,
    \NewDocumentCommand ,
    \RenewDocumentCommand ,
    \NewCommandCopy ,
    \IfBooleanTF ,
    \IfNoValueTF ,
    \tl_if_eq:NNTF ,
    \tl_if_eq:eeTF ,
    \tl_new:N ,
    \tl_gset:Nv ,
    \prop_new:N ,
    \prop_gput:NeV ,
    \prop_item:NV ,
    \bool_case:nF ,
    \str_if_eq_p:ee ,
    \prg_replicate:nn ,
    \lipsum ,
    \addto ,
    \gappto ,
    \extras ,
    \captions ,
    \FirstMark ,
    \LastMark ,
  }
}
\lstdefinestyle{postnotes}{
  style=code,
  moretexcs={
    \postnote ,
    \postnoteref ,
    \postnotesection ,
    \printpostnotes ,
    \postnotesetup ,
    \pntitle ,
    \pnhdnotes ,
    \pnhdtopage ,
    \pnhdtopages ,
    \pnheaderdefault ,
    \pnthechapter ,
    \pnthesection ,
    \pnthechapternextnote ,
    \pnthesectionnextnote ,
    \pnidnextnote ,
    \mypnheader ,
    \thepostnote ,
    \demochapter ,
    \origlatexchapter ,
    \l_postnotes_note_id_tl ,
    \g_my_currentname_tl ,
    \g_my_names_prop ,
  }
}
\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}%
  \zcsetup{countertype={lstlisting=example}}%
  \lstset{#1}%
  \stepcounter{pnexample}%
  \setcounter{lstlisting}{\value{pnexample}-1}%
}{}
\lstnewenvironment{pnsnippet}[1][]{%
  \renewcommand{\lstlistingname}{Example}%
  \lstset{#1}%
}{}

\setlength{\marginparsep}{2\labelsep}

\NewDocumentCommand\opt{m}{\texttt{#1}}

\NewDocumentCommand\username{m}{`\texttt{#1}'}

\begin{document}

\GetFileInfo{postnotes.sty}

\title{%
  The \pkg{postnotes} package%
  \texorpdfstring{\\{}\medskip{}}{ - }%
  User manual%
  \texorpdfstring{\medskip{}}{}%
}

\author{%
  \texorpdfstring{\texttt{gusbrs}\\[0.8em]
  \url{https://github.com/gusbrs/postnotes}\\
  \url{https://www.ctan.org/pkg/postnotes}}{gusbrs}}

\date{Version \fileversion\ -- \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{postnote}s 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}
\label{sec:options}

\subsection*{Package options}
\label{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{multiple} %
\DescribeOption{multisep} %
Just as for footnotes, when two or more \cs{postnote}s are called in imediate
sequence, the marks typeset in superscript give impression of being one large
number, instead of the sequence of smaller ones they were supposed to convey.
Enabling the \opt{multiple} option makes \pkg{postnotes} typeset a separator
between marks occurring in sequence.  The separator can be configured with the
\opt{multisep} option, which has a comma as initial value.  \opt{multiple} is
a boolean option, and has \texttt{false} as initial value.

\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's mark to its 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}.

\DescribeOption{checkduplicates} %
\DescribeOption{checkfloats} %
Issue warnings in case of duplicate notes resulting from measuring/trial
passes and from mismatches in the sequence of notes resulting from floats,
respectively.  These checks are only expected to be meaningful in a document
for which the compilation has stabilized: with labels and floats already in
place.  See \zcref{sec:thorns} for discussion.  Note that the
\opt{checkfloats} option does not test ``if my notes are in numeric order''
(that's the job of \opt{sort}), but rather whether the order the marks are
typeset along the document and the order the notes are printed in
\cs{printposnotes} are the same.  These options are booleans.
\opt{checkduplicates} is initially enabled, since whether a place performs
measuring passes does not really change, and it is easy to deal with a note in
this situation with the \opt{maybemulti} option. \opt{checkfloats}, on the
other hand, is initially disabled.  Float placement (and its implications for
\pkg{postnotes}) is something one should not worry about until the very last
stages of the document.  At that time, I expect it to be useful, but during
the writing phase, such a warning would only be distracting.  Think of if as
something to use like you would use the \pkg{widows-and-orphans} package, for
example.

\DescribeOption{maybemulti} %
A \cs{postnote} set while \opt{maybemulti} is true is checked at
\cs{printposnotes} and only kept in the printing queue if its corresponding
(internal) page label exists.  See \zcref{sec:thorns} for discussion.  The
drawback is that, since it requires the label for the check, a new note set
with \opt{maybemulti} will need one more compilation run than otherwise.  This
is a boolean option, and the initial value is false.

\DescribeOption{counteraux} %
\DescribeMacro{\pnsetcounteraux\marg{int}} %
\DescribeMacro{\pnaddtocounteraux\marg{int}} %
(Experimental) Build the printing queue based on the (internal) page labels
set in the \file{.aux} file, and also handle the counter stepping at the same
time.  This should provide us with a fully automated sequence of notes which
is both exempt from duplicates resulting from measuring passes and from notes
order issues caused by floats.  See \zcref{sec:thorns} for discussion.  Since
the counter sequence is determined during the input of the \file{.aux} file,
the regular counter commands will not work as intended.  \cs{pnsetcounteraux}
and \cs{pnaddtocounteraux} take an integer number as argument, and do what
their names imply, but at the time they can actually affect the sequence used
by \opt{counteraux}.  The option is a boolean, is initially disabled, and is
preamble only.  Enabling \opt{counteraux} also disables \opt{sort} at
\texttt{begindocument/before}.\footnote{The truth is, I have not yet thought
  it through how these options may interact.  So, this is done out of caution.
  I don't expect them to clash but, in principle, with \opt{counteraux},
  \opt{sort} is not needed.  You are not blocked from re-enabling it later
  but, if you do, be mindful of possible interactions.}


\subsection*{Note options}
\label{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.

\DescribeOption{maybemulti} %
Does the same thing as the corresponding package option, but is applied for a
particular \cs{postnote}.


\subsection*{Section options}
\label{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 through the (lt)mark class \opt{postnotes/sectname}, for details on
how to use it, see \zcref{sec:headers} and, in particular,
\zcref{ex:hd:fancy}.

\DescribeOption{exp} %
By default, \cs{postnotesection} stores its \meta{text} argument with ``no
manipulation''.  The \opt{exp} option allows one to fully expand
(\cs{protected@edef} 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}
\label{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}' 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} %
\DescribeMacro{\pnidnextnote} %
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''.  \cs{pnidnextnote}, in turn, stores the Id number of 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?\footnote{The
  example here counts on the lucky circumstance of having only a single
  initial unnumbered section.  But, in general, if that's not the case,
  \cs{counterwithin*} is insufficient and the resetting of the
  \texttt{postnote} counter at unnumbered sections must be handled somehow
  else.}  \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}

If one wants to use section names/titles, the technique above (of using
something similar to \cs{pnthechapternextnote}) is less useful, since if the
first note in the section occurs within a subsection we would lose the
information of interest.  So we have a little more work to do in this case.
\zcref{ex:sect:names} uses the \texttt{cmd/chapter/before} hook to store the
value of \cs{@currentlabelname} in a dedicated variable after the next call to
\cs{NR@gettitle} (presuming the use of \pkg{nameref}, through \pkg{hyperref}).
We then store the value of this variable for each note using the
\texttt{postnotes/note/store} hook and the note's Id number
\cs{l_postnotes_note_id_tl}.  Finally we can retrieve this stored value using
\cs{pnidnextnote} inside \cs{postnotesection}.  Indeed, this example is also
meant to illustrate the general technique for storing/restoring variables of
interest for this purpose.

\begin{pnexample}[caption={Section names},label={ex:sect:names}]
\documentclass{book}
\usepackage{postnotes}
\ExplSyntaxOn
\tl_new:N \g_my_currentname_tl
\prop_new:N \g_my_names_prop
\AddToHook{cmd/chapter/before}{
  \AddToHookNext{cmd/NR@gettitle/after}{
    \tl_gset:Nv \g_my_currentname_tl { @currentlabelname } } }
\AddToHook{postnotes/note/store}{
  \prop_gput:NeV \g_my_names_prop
    { \l_postnotes_note_id_tl } \g_my_currentname_tl }
\AddToHook{cmd/chapter/before}{
  \postnotesection{
    \section*{Notes~to~\prop_item:NV \g_my_names_prop \pnidnextnote}}}
\ExplSyntaxOff
\counterwithin*{postnote}{chapter}
\usepackage{hyperref}
\begin{document}
\chapter*{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}

While \pkg{postnotes} goes through great lengths to avoid tampering with
sectioning commands, the fact that in general we cannot use \texttt{cmd} hooks
after \cs{chapter} or \cs{section} does complicate things.  And
\zcref{ex:sect:names} is indeed a good illustration of how a supposedly simple
task can become quite convoluted if we are not allowed to observe the
variables of interest \emph{after} the sectioning commands.  However, things
are quite different from the perspective of a user, considering the problem at
the document level.  In this case, the definition of the sectioning commands
is known, and unique, so that it may make sense to use of the traditional
technique of storing the definition of the sectioning command, and then
redefining it to do what it used to, plus something
else.\footnote{\username{egreg} commonly applies the technique for the same
  purpose in answers using \pkg{endnotes} at TeX.SX.  For example:
  \url{https://tex.stackexchange.com/a/62425},
\url{https://tex.stackexchange.com/a/109566}, and
\url{https://tex.stackexchange.com/a/85001}.  But things are somewhat simpler
with \pkg{postnotes}, since there's no need to handle the case of sections
with no notes, given that empty \cs{postnotesection}s are already skipped.}
In which case, we can set \cs{postnotesection}s with full generality and
flexibility.

\begin{pnexample}[caption={Redefining sections},label={ex:sect:redefined}]
\documentclass{book}
\usepackage{postnotes}
\counterwithin*{postnote}{chapter}
\NewCommandCopy\origlatexchapter\chapter
\RenewDocumentCommand{\chapter}{som}{%
  \IfBooleanTF{#1}{%
    \origlatexchapter*{#3}%
    \setcounter{postnote}{0}%
    \postnotesection{\section*{Notes to ``#3''}}%
  }{%
    \IfNoValueTF{#2}{%
      \origlatexchapter{#3}%
    }{%
      \origlatexchapter[#2]{#3}%
    }%
    \postnotesection{\section*{Notes to chapter \pnthechapter}}%
  }%
}
\usepackage{hyperref}
\begin{document}
\chapter*{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}

Things could easily get fancier, of course.  But that's the basic structure.


\section{Headers}
\label{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 it is
actually focused on generating mark data, using the \pkg{ltmarks} kernel
module,\footnote{Note that ``mark'' in the context of \pkg{ltmarks} is a
  completely different thing than what is usually meant in the context of an
  end notes package.  I won't try to invent terminology here, and hopefully
  context is sufficient for the difference to be clear.  But beware.} so that
users can build their own headers, possibly 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, depending on the page style in use.

Examining a slightly simplified version of the definition of
\cs{pnheaderdefault} is possibly the most direct way to explore how to use the
mark data generated by the package.\footnote{The ``slight simplification'' is,
  namely, that I'm using here a L3 \texttt{e}-type expansion for comparing the
  equality between the marks, instead of expanding them with
  \cs{protected@edef} before comparing them.  The contents of the marks set by
  \pkg{postnotes} are typically ``safe'' in the context of an \texttt{e}-type
  expansion, but not necessarily so.  You know them: \cs{thepage},
  \cs{thechapter}, \cs{thesection}, etc.  So I won't overburden the User
  manual with this technical aspect.  But if your marks may contain fragile
  content, you'd need to expand them with \cs{protected@edef} before comparing
  with \cs{tl_if_eq:NNTF} or equivalent, as \cs{pnheaderdefault} actually
  does.}

\begin{pnsnippet}
\ExplSyntaxOn
\NewDocumentCommand \pnheaderdefault {}
  {
    \tl_if_eq:eeTF
      { \FirstMark{postnotes/page} }
      { \LastMark{postnotes/page}  }
      { \pnhdnotes{}~\pnhdtopage{}~ \FirstMark{postnotes/page} }
      {
        \pnhdnotes{}~\pnhdtopages{}~
        \FirstMark{postnotes/page}--\LastMark{postnotes/page}
      }
  }
\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:eeTF
      { \FirstMark{postnotes/page} }
      { \LastMark{postnotes/page}  }
      { Notes~to~page~\FirstMark{postnotes/page} }
      { Notes~to~pages~\FirstMark{postnotes/page}--\LastMark{postnotes/page} }
  }
\ExplSyntaxOff
\end{pnsnippet}

What the definition of \cs{pnheaderdefault} does is 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''.  The data used for this purpose, retrieved there by
the \cs{FirstMark}/\cs{LastMark} calls, is provided by some \pkg{ltmarks} mark
classes set by \pkg{postnotes}.

\DescribeOption{\normalfont\emph{Mark classes}} %
\DescribeOption{postnotes/page} %
\DescribeOption{postnotes/chapter} %
\DescribeOption{postnotes/section} %
\DescribeOption{postnotes/sectname} %
These mark classes class keep track of the information of interest, and can be
accessed through \pkg{ltmarks}' user interface: particularly, but not only,
\cs{TopMark}, \cs{FirstMark}, and \cs{LastMark}.  Now, \pkg{postnotes} inserts
the marks when the notes are being printed, but the values being tracked are
those from where the respective note marks were originally placed, since
that's what interests us for a purpose of building running headers for
\cs{printpostnotes}.  As their names suggest, the \opt{postnotes/page},
\opt{postnotes/chapter}, and \opt{postnotes/section} classes keep track of
\cs{thepage}, \cs{thechapter}, and \cs{thesection}, respectively.  The
\opt{postnotes/sectname} class, in turn, tracks the name of the notes section,
the one given with the \opt{name} option of \cs{postnotesection} (and is 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:eeTF
      { \FirstMark{postnotes/chapter} }
      { \LastMark{postnotes/chapter}  }
      { Notes~to~chapter~\FirstMark{postnotes/chapter},~ }
      {
        Notes~to~chapters~
        \FirstMark{postnotes/chapter}--\LastMark{postnotes/chapter},~
      }
    \tl_if_eq:eeTF
      { \FirstMark{postnotes/page} }
      { \LastMark{postnotes/page}  }
      { page~\FirstMark{postnotes/page} }
      { pages~\FirstMark{postnotes/page}--\LastMark{postnotes/page} }
  }
\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
the \opt{postnotes/sectname} mark class.  \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 { \FirstMark{postnotes/sectname} } { intro } &&
          \str_if_eq_p:ee { \LastMark{postnotes/sectname} } { intro }
        }
        { Notes~to~the~introduction,~ }
        {
          \str_if_eq_p:ee { \FirstMark{postnotes/sectname} } { intro } &&
          ! \str_if_eq_p:ee { \LastMark{postnotes/sectname} } { intro }
        }
        { Notes~to~the~introduction~and~chapter~\LastMark{postnotes/chapter},~ }
      }
      {
        \tl_if_eq:eeTF
          { \FirstMark{postnotes/chapter} }
          { \LastMark{postnotes/chapter}  }
          { Notes~to~chapter~\FirstMark{postnotes/chapter},~ }
          {
            Notes~to~chapters~
            \FirstMark{postnotes/chapter}--\LastMark{postnotes/chapter},~
          }
      }
    \tl_if_eq:eeTF
      { \FirstMark{postnotes/page} }
      { \LastMark{postnotes/page}  }
      { page~\FirstMark{postnotes/page} }
      { pages~\FirstMark{postnotes/page}--\LastMark{postnotes/page} }
  }
\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}

Note that there's absolutely no ``prescriptive'' aspect in this particular way
of setting the headers used in the examples above, by means of these functions
then used as content for \cs{markboth} or similar.  This is just a way to do
things which is mostly independent of the document class in use and of the
presence of other related packages.  Indeed, if you just set the \opt{heading}
option removing call to \cs{@mkboth}, or simply use a page style which
disables it, \pkg{postnotes} is completely ``hands-off'' in this area.  The
main effort of the package is to generate the data, by setting appropriate
\texttt{ltmarks}, so that it is available.  How to use this data is the
business of the user.  The facilities of your favorite document class, or
\pkg{fancyhdr}, may well be be better options than this simple minded setup.


\section{Cross-references}
\label{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}
\label{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}
\label{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.\footnote{This is the case for the
  \cs{caption} command provided by the kernel, but it may be different
  depending on the document class, packages and options in use.}  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 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.
Another method is to call \cs{stepcounter}\texttt{\{postnote\}} before the
caption, then place a \cs{postnote} setting the \opt{mark} option with
\cs{arabic}\texttt{\{postnote\}}.  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.
\postnote[nomark]{\label{en:1}A note.}%
\caption[Short caption]{A long caption, long enough to require two
lines\postnoteref{en:1}}
\end{figure}
\begin{figure}
Figure.
\stepcounter{postnote}
\caption[Short caption]{A long caption, long enough to require two
lines\postnote[mark=\arabic{postnote}]{A note.}}
\end{figure}
\printpostnotes
\end{document}
\end{pnexample}

Arguably, the second method is more interesting for normal cases, since it
does not offset the note's anchor.  The first one would work for multiple
notes as well, and it is also more robust to multiple passes of the content.
\pkg{postnotes} controls for this in a number of known cases to avoid notes in
duplicity, but obviously cannot cover every possibility, in which case
\opt{nomark} with \cs{postnoteref} has you covered.  Caveat, these techniques
assume the floats do not disturb the order of the notes, otherwise we are back
to the case discussed in \zcref{ex:x:float}.

The (experimental) \opt{counteraux} option, shown in \zcref{ex:x:counteraux},
is an attempt to fully ``automate away'' the issues illustrated in
\zcref{ex:x:float,ex:x:caption}, so that there's no need to manipulate either
the counter or the mark.  See \zcref{sec:thorns} for discussion.

\begin{pnexample}[caption={\opt{counteraux} option},label={ex:x:counteraux}]
\documentclass{book}
\usepackage[textwidth=8cm]{geometry}
\usepackage{postnotes}
\postnotesetup{counteraux}
\usepackage{hyperref}
\begin{document}
\chapter{First chapter}
\postnote{one}
\postnote{two}
\begin{figure}[p]
Figure.%
\caption[Short caption]{A long caption, long enough to require two
lines\postnote{three}}
\end{figure}
\postnote{four}
\postnote{five}
\clearpage
\postnote{six}
\printpostnotes
\end{document}
\end{pnexample}

Nested notes.  To be honest, the design of the package was not made with this
use case in mind.  However, since \pkg{postnotes} does not use the method of
writing the notes' contents to an external file and printing the notes by
inputting it, the technical restriction of the traditional method does not
apply.  Hence, it mostly works.  However, nested notes are not included in the
ongoing \cs{printpostnotes}, but are left for the next call.  So, if nesting,
call \cs{printpostnotes} again to print the nested ones.  Which is actually
convenient, since different settings may be applied to each set.  Also, expect
limitations, particularly with regard to the context variables stored by the
package: the context of a nested note is the notes section, not the one to
which the parent note belongs to.  Finally, be watchful of results, because
what works does so more by luck than by design.  Still, it is not too bad that
\pkg{postnotes} can handle not only nesting but even split sections of nested
notes as shown in \zcref{ex:x:nesting}.

\begin{pnexample}[caption={Nested notes},label={ex:x:nesting}]
\documentclass{book}
\usepackage{postnotes}
\usepackage{hyperref}
\counterwithin*{postnote}{chapter}
\begin{document}
\chapter{First chapter}
\postnotesection{\section*{Notes to chapter 1}%
  \setcounter{postnote}{0}%
  \postnotesection{\section*{Editor's notes to chapter 1}}}
Foo.\postnote{Foo note.}\par
Bar.\postnote{Bar note.\postnote{Editor's note bar.}}\par
Baz.\postnote{A note.\postnote{Editor's note baz.}}
\chapter{Second chapter}
\postnotesection{\section*{Notes to chapter 2}%
  \setcounter{postnote}{0}%
  \postnotesection{\section*{Editor's notes to chapter 2}}}
Foo.\postnote{Foo note.}\par
Bar.\postnote{Bar note.\postnote{Editor's note bar.}}\par
Baz.\postnote{A note.\postnote{Editor's note baz.}}
\begingroup
\renewcommand*{\thepostnote}{\roman{postnote}}
\printpostnotes
\renewcommand*{\pntitle}{Editor's notes}
\printpostnotes
\endgroup
\end{document}
\end{pnexample}


\section{Thorny cases}
\label{sec:thorns}

Depending on where one places a \cs{postnote}, some undesirable side-effects
may ensue.  A note set somewhere which is subject to measuring/trial passes
may be stored multiple times, thus appearing in duplicity at
\cs{printpostnotes}.\footnote{That would normally be the case, but
  \pkg{postnotes} already handles some known instances of this, avoiding the
  duplicates.  It doesn't mean there are not places unknown to the package
  which do the same.}  Also, a note placed within a float may result in the
sequence of notes being disturbed, depending on where the float ends up being
typeset.  These problems are usually not too frequent, but they come up
occasionally and, when they do, they can be a pain.

\pkg{postnotes} offers some ways to deal with these issues.  Sorting falls
into this category.  The traditional ``counter juggling'' around a float which
disrupted the sequence of the notes could always be used to fix the sequence
the marks got typeset (see \zcref{ex:x:float}), and the \opt{sort} option
handles the sequence at \cs{printpostnotes}.

Besides sorting, what the package does offer is, ultimately, based on the page
labels each \cs{postnote} sets internally, the \cs{post@note}s in the
\file{.aux} file.  These labels are non-immediate writes (whatsits, in the
jargon), as they must be, since we are interested in the page number.  As a
result, measuring passes don't get written, and they are also written in the
order the document elements get shipped out.  Hence, the labels set in the
\file{.aux} file are free of duplicates resulting from measuring passes, and
are also ordered the same as the typeset order of the document, floats
considered.  Based on the information gathered from these labels, we have a
number of options.

For known cases of measuring/trial passes where it's possible to distinguish
the measuring from the final pass, \pkg{postnotes} uses that information to
inhibit the note and also handles the counter appropriately so that the
measuring pass has the correct value to measure.  Currently, such support is
provided for \pkg{amsmath} display math environments, \pkg{csquotes}'
\cs{blockcquote}s, \pkg{tabularx}, \pkg{tabularray}, and \pkg{xltabular}.  For
cases where it is not possible to distinguish the trial from the final pass,
\pkg{postnotes} uses the page labels mentioned above, and for \cs{postnote}s
flagged as potential duplicates, it checks whether the page label exists, and
drops the (duplicate) note if it doesn't.  Prominent example here is the
kernel's \cs{caption}.  This mechanism is exposed to users through the
\opt{maybemulti} option.  Important distinction here between this method and
the more controlled inhibition above is that there's little we can do about
the counter.  The counter itself can be adjusted manually if need be, to
restore the sequence.  But the value the measuring pass receives is out of our
hands, hence it may be off.  Of course, the expected difference should
normally be small.  But if the measuring is presumed to be exact, some
mysterious slightly overfull \cs{hbox}es may occur.

\pkg{postnotes} also offers some checks, to issue warnings for cases of
duplicates or sequence problems: the \opt{checkduplicates} and
\opt{checkfloats} options.  They use the information generated by the page
labels to perform some consistency checks, and report problems.  I expect them
to be useful, since this is the kind of issue that may trick even a competent
proofreader.

Finally, \pkg{postnotes} also provides the (experimental) \opt{counteraux}
option, which is an attempt to fully ``automate away'' these issues.  The
basic idea is that, since we are already using the data generated by the page
labels to handle some of the issues and perform some checks, why not use that
information directly?  The page labels are already net of duplicates and in
the order the document elements are typeset.  Indeed, why not use them?
That's what \opt{counteraux} does: the queue which feeds \cs{printpostnotes}
is built from the calls of \cs{post@note} in the \file{.aux} file and the
counter is also stepped, as appropriate, at the same time.  Technically, I
should say ``a counter'', which is then used to locally set the value of the
user facing counter, \texttt{postnote}, at the moment \cs{postnote} is called,
with a cross-reference of sorts.

Some differences.  In the standard behavior, a \cs{postnote} inside a float
belongs where the float environment was set, because that's where the
numbering of the note is defined.  With \opt{counteraux}, a \cs{postnote}
inside a float belongs where the float ends up being typeset, and for the same
reason.  This means a note inside a float may float past a subsequent call of
\cs{printpostnotes}, and will belong to the next call.  That's actually neat,
and I'd call it a feature.  But you should be mindful of the warning for
``stray notes'' issued at \texttt{enddocument} by the package, and make sure
to extinguish your floats before a final \cs{printpostnotes}.  A limitation of
the package's design is that the opposite cannot occur, if a note inside a
float goes to the top of the page and happens to be typeset before a
\cs{printpostnotes} which actually precedes it, the information to print the
note is not available, so it's still left for the next call, but the numbering
will be off.

Some inconveniences.  You cannot set the counter directly, as you normally
would.  Also \cs{counterwithin} will not affect the counter being stepped in
the \file{.aux} file.  \pkg{postnotes} offers \cs{pnsetcounteraux} and
\cs{pnaddtocounteraux} for the purpose.  But, normally, all you should ever
need is a \texttt{\textbackslash{}pnsetcounteraux\{0\}} when splitting
sections for your notes.  Also, the heavy reliance on labels will normally
require one additional compilation run, and some possible transitory content
swings.

Some caveats.  I mentioned above that, in the case of multiple passes handled
with the \opt{maybemulti} method, it is hard to ensure the value of the
counter is correct for the measuring pass(es).  \opt{counteraux} makes this
issue worse, because even in the cases where we can identify the measuring
pass, we can't ensure the correct value, since the sequence of the passes is
lost in the \file{.aux} file.  Indeed, the measuring passes do not even exist
there, and we cannot, in general, reestablish the connection the original
sequence offered.  Fortunately, there is a reasonable way around it.  If a
\cs{postnote} sets a label (through the \opt{label} option of the note, not
inside the content), the connection can be reestablished.  ``Connection'' is
perhaps too much of a word for this, it's simpler.  With the label, a
cross-reference to the mark is available, which can then be fed to the
measuring pass.  And we know that value to be correct, because the label
belongs to the pass which is actually typeset.  In sum, if some measuring
problems do occur, set a label for the note, even if you do not refer to it,
\pkg{postnotes} will use it.  Alas, if you are unlucky enough, you may even
find yourself stuck in an infinite loop.\footnote{In a situation similar to
  \pkg{varioref}, but in the choice of which pass is the measuring and which
  is the final, instead of the reference crossing page boundaries.  However,
  given the typical width of a mark, and the even smaller variations of those
  widths which may result from floating, I expect the likelihood of meeting
  such case in practice to be narrow.  There is no attempt to warn about this
  here though, as \pkg{varioref} does, and probably no way to do it either.}
In this case, setting the label is no relief, and the alternatives I can think
of are either using a manual mark with \cs{pnaddtocounteraux} or a
\opt{nomark} \cs{postnote} with \cs{postnoteref}.


\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
  % 2023-12-12: https://chat.stackexchange.com/transcript/message/64848034#64848034 (and discussion)
  % 2024-01-28: https://chat.stackexchange.com/transcript/message/65071091#65071091 (discussion)
  % 2024-10-09: https://chat.stackexchange.com/transcript/message/66415504#66415504 (discussion)
  % 2024-10-10: https://chat.stackexchange.com/transcript/message/66421777#66421777 (discussion)
  % 2024-10-15: https://chat.stackexchange.com/transcript/message/66444011#66444011 (discussion)
  % 2024-10-17: https://chat.stackexchange.com/transcript/message/66456022#66456022
  % 2024-10-22: https://github.com/gusbrs/postnotes/issues/8#issuecomment-2429501962
  % 2024-10-25: https://chat.stackexchange.com/transcript/message/66510334#66510334 (discussion)
  % 2024-11-03: https://chat.stackexchange.com/transcript/message/66554870#66554870 (discussion)
  % 2024-11-27: https://chat.stackexchange.com/transcript/message/66696438#66696438 (discussion)
  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
  % 2023-12-12: https://chat.stackexchange.com/transcript/message/64848034#64848034 (and discussion)
  % 2024-01-28: https://chat.stackexchange.com/transcript/message/65071091#65071091 (discussion)
  % 2024-10-15: https://chat.stackexchange.com/transcript/message/66444011#66444011 (discussion)
  % 2024-11-27: https://chat.stackexchange.com/transcript/message/66696438#66696438 (discussion)
  Moritz Wemheuer,
  % 2022-04-05: https://tex.stackexchange.com/q/597359#comment1594585_597389
  Joseph Wright,
  % 2023-02-10: https://chat.stackexchange.com/transcript/message/62955941#62955941 (and discussion)
  % 2023-12-12: https://chat.stackexchange.com/transcript/message/64848034#64848034 (and discussion)
  % 2024-10-15: https://chat.stackexchange.com/transcript/message/66444011#66444011 (discussion)
  \username{SwitWu},
  % 2023-11-29: https://github.com/gusbrs/postnotes/pull/4
  % 2023-11-30: https://github.com/gusbrs/postnotes/pull/5
  Jonathan P. Spratte, % @Skillmon
  % 2023-12-12: https://chat.stackexchange.com/transcript/message/64848034#64848034 (and discussion)
  Clea F. Rees, % @cfr
  % 2024-10-24: https://chat.stackexchange.com/transcript/message/66493234#66493234 (discussion)
  Romano Giannetti, % @Rmano
  % 2024-10-24: https://chat.stackexchange.com/transcript/message/66493234#66493234 (discussion)
  and Frank Mittelbach.
  % 2024-10-29: https://github.com/latex3/latex2e/issues/1514#issuecomment-2444889179

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}