Include a third method to deal with long captions in the manual

postnotes-doc.tex

@@ -1051,7 +1051,16 @@ \chapter{First chapter}
 \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:
+to the label.  Yet a third method is to call \cs{refstepcounter} on
+\texttt{postnote} and set an auxiliary label right before the caption, then
+set a \cs{postnote} setting the \opt{mark} option to a reference to that
+label.  In this case, it must be an expandable reference command, since
+\opt{mark} also sets \opt{sortnum}, which must be a number.  Here we use
+\cs{getrefnumber} from \pkg{refcount} (loaded by \pkg{hyperref}), but we could
+just as well replace that with equivalent ones from \pkg{ltproperties}.
+Arguably, this third method is the more robust, since it does not require that
+we know the length of the caption, and results in no offset in the note's
+anchor.  In practice:
 
 \begin{pnexample}[caption={Long caption},label={ex:x:caption}]
 \documentclass{article}
@@ -1071,10 +1080,33 @@ \chapter{First chapter}
   \caption[Caption for LOF]{A long caption, long enough to require two
     lines\postnoteref{en:1}}
 \end{figure}
+\begin{figure}
+Figure.
+\refstepcounter{postnote}\label{aux}
+\caption[Caption for LOF]{A long caption, long enough to require two
+lines\postnote[mark=\getrefnumber{aux}]{A note.}}
+\end{figure}
+\clearpage
 \printpostnotes
 \end{document}
 \end{pnexample}
 
+These techniques demonstrated in \zcref{ex:x:caption} assume the floats do not
+disturb the order of the notes, otherwise we are back to the case discussed in
+\zcref{ex:x:float}.\footnote{The third technique in \zcref{ex:x:caption} might
+  be applied to improve \zcref{ex:x:float} a little.  Indeed, instead of
+  calling \cs{stepcounter}\texttt{\{postnote\}} after note 5, we could call
+  \cs{refstepcounter}\texttt{\{postnote\}}\cs{label}\texttt{\{aux\}} and use
+  \cs{getrefnumber}\texttt{\{aux\}} to set the \opt{mark} of the note on the
+  table.  However, for that situation, this does not change things that
+  significantly, because you still have to know were to call
+  \cs{refstepcounter}, depending on the place the float actually ends up, and
+  that requires being in the ``finishing touches'' fase of your document
+  anyway.  In which case, you \emph{know} the number is ``5''.}  Still,
+floating behavior aside, they show some alternatives to deal with the general
+problem of setting \cs{postnote}s in places which perform multiple passes of
+the content, and for which \pkg{postnotes} does not, or cannot, account for.
+
 
 \section{Acknowledgments}
 

testfiles-3runs/pn-examples-caption01.lvt

@@ -49,6 +49,18 @@
 \end{figure}
 \ENDTEST
 
+\BEGINTEST{caption 3}
+\begin{figure}
+  Figure.
+  \refstepcounter{postnote}\label{aux}
+  \caption[Caption for LOF]{A long caption, long enough to require two
+    lines%
+\setbox0=\hbox{\postnote[mark=\getrefnumber{aux}]{A note.}}%
+\showbox0%
+\box0}
+\end{figure}
+\ENDTEST
+
 \OMIT
 
 \cleardoublepage{}

testfiles-3runs/pn-examples-caption01.tlg

@@ -89,7 +89,51 @@ l. ...\box0}
 l. ...\box0}
 ============================================================
 ============================================================
-TEST 3: Print caption
+TEST 3: caption 3
+============================================================
+> \box...=
+\hbox(8.14003+0.0)x4.48613
+.\penalty 10000
+.\hbox(0.0+0.0)x0.0
+..\hbox(0.0+0.0)x0.0, shifted -12.0
+...\pdfdest name{postnote.4.mark} xyz
+...\penalty 10000
+.\write1{\token_to_str:N \post@note {mark@4}{\thepage }}
+.\penalty 10000
+.\pdfstartlink(*+*)x* attr{/Border[0 0 1]/H/I/C[1 0 0]} action goto name{postnote.4.text}
+.\hbox(8.14003+0.0)x4.48613
+..\mathon
+..\hbox(4.51111+0.0)x4.48613, shifted -3.62892
+...\OT1/cmr/m/n/7 3
+..\mathoff
+.\pdfendlink
+! OK.
+<to be read again> 
+                   \box 
+l. ...\box0}
+> \box...=
+\hbox(8.14003+0.0)x4.48613
+.\penalty 10000
+.\hbox(0.0+0.0)x0.0
+..\hbox(0.0+0.0)x0.0, shifted -12.0
+...\pdfdest name{postnote.5.mark} xyz
+...\penalty 10000
+.\write1{\token_to_str:N \post@note {mark@5}{\thepage }}
+.\penalty 10000
+.\pdfstartlink(*+*)x* attr{/Border[0 0 1]/H/I/C[1 0 0]} action goto name{postnote.5.text}
+.\hbox(8.14003+0.0)x4.48613
+..\mathon
+..\hbox(4.51111+0.0)x4.48613, shifted -3.62892
+...\OT1/cmr/m/n/7 3
+..\mathoff
+.\pdfendlink
+! OK.
+<to be read again> 
+                   \box 
+l. ...\box0}
+============================================================
+============================================================
+TEST 4: Print caption
 ============================================================
 Completed box being shipped out [2]
 \vbox(609.60394+0.0)x348.68852
@@ -115,7 +159,7 @@ Completed box being shipped out [2]
 .....\hbox(0.0+0.0)x227.62204
 ...\glue 25.0
 ...\glue(\lineskip) 0.0
-...\vbox(556.47656+0.0)x227.62204, glue set 509.51938fil
+...\vbox(556.47656+0.0)x227.62204, glue set 498.52055fil
 ....\write-{}
 ....\glue(\topskip) 0.12001
 ....\hbox(9.87999+0.0)x227.62204, glue set 186.77371fil
@@ -209,6 +253,40 @@ Completed box being shipped out [2]
 .....\glue(\parfillskip) 0.0 plus 1.0fil
 .....\glue(\rightskip) 0.0
 ....\penalty -51
+....\glue 0.0
+....\glue(\parskip) 0.0 plus 1.0
+....\glue(\parskip) 0.0
+....\glue(\baselineskip) 4.85002
+....\hbox(6.14998+0.0)x227.62204, glue set 177.86328fil
+.....\hbox(5.79999+0.0)x19.6944
+......\glue 7.5
+......\glue 0.0
+......\glue -5.0
+......\hbox(5.79999+0.0)x12.1944
+.......\glue 5.0
+.......\penalty 10000
+.......\hbox(0.0+0.0)x0.0
+........\hbox(0.0+0.0)x0.0, shifted -11.0
+.........\pdfdest name{postnote.5.text} xyz
+.........\penalty 10000
+.......\write1{\token_to_str:N \post@note {text@5}{\int_use:N \c@page }}
+.......\pdfstartlink(*+*)x* attr{/Border[0 0 1]/H/I/C[1 0 0]} action goto name{postnote.5.mark}
+.......\OT1/cmr/m/n/9 3
+.......\OT1/cmr/m/n/9 .
+.......\pdfendlink
+......\glue 5.0
+.....\penalty 0
+.....\OT1/cmr/m/n/9 A
+.....\glue 3.08331 plus 1.5401 minus 1.0288
+.....\OT1/cmr/m/n/9 n
+.....\OT1/cmr/m/n/9 o
+.....\OT1/cmr/m/n/9 t
+.....\OT1/cmr/m/n/9 e
+.....\OT1/cmr/m/n/9 .
+.....\penalty 10000
+.....\glue(\parfillskip) 0.0 plus 1.0fil
+.....\glue(\rightskip) 0.0
+....\penalty -51
 ....\glue 5.0
 ....\glue 0.0 plus 1.0fil
 ....\glue 0.0

testfiles-3runs/pn-examples-caption01.xetex.tlg

@@ -89,7 +89,51 @@ l. ...\box0}
 l. ...\box0}
 ============================================================
 ============================================================
-TEST 3: Print caption
+TEST 3: caption 3
+============================================================
+> \box...=
+\hbox(8.14003+0.0)x4.48613
+.\penalty 10000
+.\hbox(0.0+0.0)x0.0
+..\hbox(0.0+0.0)x0.0, shifted -12.0
+...\special{pdf:dest (postnote.4.mark) [@thispage /XYZ @xpos @ypos null]}
+...\penalty 10000
+.\write1{\token_to_str:N \post@note {mark@4}{\thepage }}
+.\penalty 10000
+.\special{pdf:bann<</Type/Annot/Subtype/Link/Border[0 0 1]/H/I/C[1 0 0]/A<</S/GoTo/D(postnote.4.text)>>>>}
+.\hbox(8.14003+0.0)x4.48613
+..\mathon
+..\hbox(4.51111+0.0)x4.48613, shifted -3.62892
+...\OT1/cmr/m/n/7 3
+..\mathoff
+.\special{pdf:eann}
+! OK.
+<to be read again> 
+                   \box 
+l. ...\box0}
+> \box...=
+\hbox(8.14003+0.0)x4.48613
+.\penalty 10000
+.\hbox(0.0+0.0)x0.0
+..\hbox(0.0+0.0)x0.0, shifted -12.0
+...\special{pdf:dest (postnote.5.mark) [@thispage /XYZ @xpos @ypos null]}
+...\penalty 10000
+.\write1{\token_to_str:N \post@note {mark@5}{\thepage }}
+.\penalty 10000
+.\special{pdf:bann<</Type/Annot/Subtype/Link/Border[0 0 1]/H/I/C[1 0 0]/A<</S/GoTo/D(postnote.5.text)>>>>}
+.\hbox(8.14003+0.0)x4.48613
+..\mathon
+..\hbox(4.51111+0.0)x4.48613, shifted -3.62892
+...\OT1/cmr/m/n/7 3
+..\mathoff
+.\special{pdf:eann}
+! OK.
+<to be read again> 
+                   \box 
+l. ...\box0}
+============================================================
+============================================================
+TEST 4: Print caption
 ============================================================
 Completed box being shipped out [2]
 \vbox(609.60394+0.0)x348.68852
@@ -115,7 +159,7 @@ Completed box being shipped out [2]
 .....\hbox(0.0+0.0)x227.62204
 ...\glue 25.0
 ...\glue(\lineskip) 0.0
-...\vbox(556.47656+0.0)x227.62204, glue set 509.51938fil
+...\vbox(556.47656+0.0)x227.62204, glue set 498.52055fil
 ....\write-{}
 ....\glue(\topskip) 0.12001
 ....\hbox(9.87999+0.0)x227.62204, glue set 186.77371fil
@@ -209,6 +253,40 @@ Completed box being shipped out [2]
 .....\glue(\parfillskip) 0.0 plus 1.0fil
 .....\glue(\rightskip) 0.0
 ....\penalty -51
+....\glue 0.0
+....\glue(\parskip) 0.0 plus 1.0
+....\glue(\parskip) 0.0
+....\glue(\baselineskip) 4.85002
+....\hbox(6.14998+0.0)x227.62204, glue set 177.86328fil
+.....\hbox(5.79999+0.0)x19.6944
+......\glue 7.5
+......\glue 0.0
+......\glue -5.0
+......\hbox(5.79999+0.0)x12.1944
+.......\glue 5.0
+.......\penalty 10000
+.......\hbox(0.0+0.0)x0.0
+........\hbox(0.0+0.0)x0.0, shifted -11.0
+.........\special{pdf:dest (postnote.5.text) [@thispage /XYZ @xpos @ypos null]}
+.........\penalty 10000
+.......\write1{\token_to_str:N \post@note {text@5}{\int_use:N \c@page }}
+.......\special{pdf:bann<</Type/Annot/Subtype/Link/Border[0 0 1]/H/I/C[1 0 0]/A<</S/GoTo/D(postnote.5.mark)>>>>}
+.......\OT1/cmr/m/n/9 3
+.......\OT1/cmr/m/n/9 .
+.......\special{pdf:eann}
+......\glue 5.0
+.....\penalty 0
+.....\OT1/cmr/m/n/9 A
+.....\glue 3.08331 plus 1.5401 minus 1.0288
+.....\OT1/cmr/m/n/9 n
+.....\OT1/cmr/m/n/9 o
+.....\OT1/cmr/m/n/9 t
+.....\OT1/cmr/m/n/9 e
+.....\OT1/cmr/m/n/9 .
+.....\penalty 10000
+.....\glue(\parfillskip) 0.0 plus 1.0fil
+.....\glue(\rightskip) 0.0
+....\penalty -51
 ....\glue 5.0
 ....\glue 0.0 plus 1.0fil
 ....\glue 0.0