summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2024-11-05 20:18:59 +0000
committerKarl Berry <karl@freefriends.org>2024-11-05 20:18:59 +0000
commit0f56d930677c687334ae778f579713f33765e696 (patch)
tree5ff3d92428f670dac7584594c74f9c3696c82e42 /Master/texmf-dist/doc
parent8b20c49eb5d6de2903b9d5ba8312565c8d5956b0 (diff)
postnotes (5nov24)
git-svn-id: svn://tug.org/texlive/trunk@72770 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r--Master/texmf-dist/doc/latex/postnotes/CHANGELOG.md37
-rw-r--r--Master/texmf-dist/doc/latex/postnotes/postnotes-code.pdfbin883243 -> 897339 bytes
-rw-r--r--Master/texmf-dist/doc/latex/postnotes/postnotes-doc.pdfbin203619 -> 222149 bytes
-rw-r--r--Master/texmf-dist/doc/latex/postnotes/postnotes-doc.tex351
4 files changed, 345 insertions, 43 deletions
diff --git a/Master/texmf-dist/doc/latex/postnotes/CHANGELOG.md b/Master/texmf-dist/doc/latex/postnotes/CHANGELOG.md
index 016ab2ebbc0..26355acbff3 100644
--- a/Master/texmf-dist/doc/latex/postnotes/CHANGELOG.md
+++ b/Master/texmf-dist/doc/latex/postnotes/CHANGELOG.md
@@ -1,6 +1,39 @@
# Changelog
-## [Unreleased](https://github.com/gusbrs/postnotes/compare/v0.3.0...HEAD)
+## [Unreleased](https://github.com/gusbrs/postnotes/compare/v0.4.0...HEAD)
+
+## [v0.4.0](https://github.com/gusbrs/postnotes/compare/v0.3.0...v0.4.0) (2024-11-04)
+
+*WARNING*: You may need to clear your .aux files after this update.
+- (Internally, the macro used in the .aux file, `\post@note`, used to take two
+ arguments, but now it takes four.)
+
+### Added
+- Provide (experimental) `counteraux` option: full automation of notes
+ numbering and sequence capable of handling both multiple passes from
+ measuring operations and floats shuffling the sequence of notes.
+ `\postnote`s set inside floats may float past `\printpostnotes` and belong
+ to the section where they are actually typeset.
+- Provide options `checkduplicates` and `checkfloats`, which issue warnings in
+ case of duplicate notes from measuring passes and of notes order mismatch
+ resulting from float placement.
+- Provide `maybemulti` option, exposing to users a simple method to handle
+ cases of duplicate notes resulting from measuring passes which was already
+ used internally.
+- Warning at `enddocument` for stray `\postnote`s left after the last
+ `\printpostnotes`.
+- Support for `xltabular` package.
+
+### Fixed
+- Fixed `style=endnotes` tagging error (see issue
+ [#8](https://github.com/gusbrs/postnotes/issues/8))
+
+### Changed
+- Improved handling of nested notes, example added to the User manual.
+
+### Removed
+- Command `\postnotesectionx`, which had been deprecated since v0.2.0 from
+ 2022-12-28, has been removed.
## [v0.3.0](https://github.com/gusbrs/postnotes/compare/v0.2.8...v0.3.0) (2024-10-15)
@@ -13,7 +46,7 @@
## [v0.2.8](https://github.com/gusbrs/postnotes/compare/v0.2.7...v0.2.8) (2023-12-12)
-## Fixed
+### Fixed
- Fixed `multibool` test in `\__postnotes_verify_multipass:N`.
## [v0.2.7](https://github.com/gusbrs/postnotes/compare/v0.2.6...v0.2.7) (2023-11-14)
diff --git a/Master/texmf-dist/doc/latex/postnotes/postnotes-code.pdf b/Master/texmf-dist/doc/latex/postnotes/postnotes-code.pdf
index 5742cac6a2b..6e988f9d099 100644
--- a/Master/texmf-dist/doc/latex/postnotes/postnotes-code.pdf
+++ b/Master/texmf-dist/doc/latex/postnotes/postnotes-code.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/postnotes/postnotes-doc.pdf b/Master/texmf-dist/doc/latex/postnotes/postnotes-doc.pdf
index 952c0446d71..d5a31a5aa7f 100644
--- a/Master/texmf-dist/doc/latex/postnotes/postnotes-doc.pdf
+++ b/Master/texmf-dist/doc/latex/postnotes/postnotes-doc.pdf
Binary files differ
diff --git a/Master/texmf-dist/doc/latex/postnotes/postnotes-doc.tex b/Master/texmf-dist/doc/latex/postnotes/postnotes-doc.tex
index 30bbcc1cba6..fda2323dcf9 100644
--- a/Master/texmf-dist/doc/latex/postnotes/postnotes-doc.tex
+++ b/Master/texmf-dist/doc/latex/postnotes/postnotes-doc.tex
@@ -130,6 +130,7 @@
\pnhdnamefirst ,
\pnhdnamelast ,
\mypnheader ,
+ \thepostnote ,
\demochapter ,
\origlatexchapter ,
\l_postnotes_note_id_tl ,
@@ -154,7 +155,7 @@
\zcsetup{countertype={lstlisting=example}}%
\lstset{#1}%
\stepcounter{pnexample}%
- \setcounter{lstlisting}{\value{pnexample}}%
+ \setcounter{lstlisting}{\value{pnexample}-1}%
}{}
\lstnewenvironment{pnsnippet}[1][]{%
\renewcommand{\lstlistingname}{Example}%
@@ -311,10 +312,10 @@ as its counterpart.
\section{Options}
-\zlabel{sec:options}
+\label{sec:options}
\subsection*{Package options}
-\zlabel{sec:package-options}
+\label{sec:package-options}
\begin{function}{\postnotesetup}
\begin{syntax}
@@ -385,16 +386,6 @@ maketextmark = {#2#1.#3} ,
At the point \opt{maketextmark} gets typeset, the \cs{pnthepage} variable
contains the value of \cs{thepage} where its corresponding note was set.
-\DescribeMacro{multiple} %
-\DescribeMacro{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{pretextmark} %
\DescribeOption{posttextmark} %
\DescribeOption{postprintnote} %
@@ -418,6 +409,16 @@ 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
@@ -450,9 +451,58 @@ 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}
-\zlabel{sec:note-options}
+\label{sec:note-options}
The options accepted by \cs{postnote}\oarg{options}\marg{text} are the
following:
@@ -498,9 +548,13 @@ 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}
-\zlabel{sec:section-options}
+\label{sec:section-options}
The options accepted by \cs{postnotesection}\oarg{options}\marg{text} are the
following:
@@ -525,11 +579,11 @@ boolean option, and the option given with no value is equivalent to
\section{Notes sections}
-\zlabel{sec: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}'s equivalent to \pkg{endnotes}' \cs{addtoendnotes}. It has
+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
@@ -772,7 +826,7 @@ Things could easily get fancier, of course. But that's the basic structure.
\section{Headers}
-\zlabel{sec: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 also
@@ -920,7 +974,7 @@ their use (of course, the use of \pkg{lipsum} is just for demonstration):
\section{Cross-references}
-\zlabel{sec: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
@@ -942,7 +996,7 @@ places, etc.
\section{Localization}
-\zlabel{sec:localization}
+\label{sec:localization}
\DescribeMacro{\pntitle} %
\DescribeMacro{\pnhdnotes} %
@@ -980,7 +1034,7 @@ and for \pkg{polyglossia}:
\section{Further examples}
-\zlabel{sec: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.
@@ -1039,19 +1093,21 @@ correctly ordered printed notes (as a result of sorting):
\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
+\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:
+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}
@@ -1060,21 +1116,224 @@ to the label. In practice:
\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.}}
+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.
- \postnote[nomark]{\label{en:1}A note.}%
- \caption[Caption for LOF]{A long caption, long enough to require two
- lines\postnoteref{en:1}}
+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}
@@ -1093,6 +1352,10 @@ provided by (in chronological order):
% 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)
David Carlisle,
% 2022-03-28: https://chat.stackexchange.com/transcript/message/60754383#60754383
% 2022-04-08: https://tex.stackexchange.com/a/640035 (comments)
@@ -1110,8 +1373,14 @@ provided by (in chronological order):
\username{SwitWu},
% 2023-11-29: https://github.com/gusbrs/postnotes/pull/4
% 2023-11-30: https://github.com/gusbrs/postnotes/pull/5
- and Jonathan P. Spratte (\username{Skillmon}).
+ 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)