postnotes (28dec22)

git-svn-id: svn://tug.org/texlive/trunk@65385 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 71 insertions, 89 deletions

diff --git a/Master/texmf-dist/source/latex/postnotes/postnotes.dtx b/Master/texmf-dist/source/latex/postnotes/postnotes.dtx
index 2ab7308acea..b6a9a15572c 100644
--- a/Master/texmf-dist/source/latex/postnotes/postnotes.dtx
+++ b/Master/texmf-dist/source/latex/postnotes/postnotes.dtx
@@ -65,8 +65,8 @@
 % \NewDocumentCommand\githubPR{m}{^^A
 %   PR~\href{https://github.com/gusbrs/postnotes/pull/#1}{\##1}}
 %
-% ^^A Currently just for keeping semantic markup on this.
 % \NewDocumentCommand\contributor{m}{#1}
+% \NewDocumentCommand\username{m}{`\texttt{#1}'}
 %
 % \NewDocumentCommand\opt{m}{\texttt{#1}}
 %
@@ -128,17 +128,23 @@
 %    \end{macrocode}
 %
 %
-% Require the new syntax for file/package hooks (\texttt{ltnews34},
-% \texttt{ltfilehook}).
+% The new syntax for file/package hooks, which the package assumes, requires
+% kernel 2021-11-15 (\texttt{ltnews34}, \texttt{ltfilehook}).  Furthermore,
+% the kernel of 2022-06-01 introduced a couple of very nice features which
+% simplifies the relation with \pkg{hyperref} (\texttt{ltnews35},
+% \texttt{hyperref-linktarget}): the provision of \cs{MakeLinkTarget} and the
+% definition by the kernel of the starred version of \cs{ref}, which we can
+% use regardless of \pkg{hyperref} being loaded.  So we require the 2022-06-01
+% kernel or newer.
 %
 %    \begin{macrocode}
 \providecommand\IfFormatAtLeastTF{\@ifl@t@r\fmtversion}
-\IfFormatAtLeastTF{2021-11-15}
+\IfFormatAtLeastTF{2022-06-01}
   {}
   {%
     \PackageError{postnotes}{LaTeX kernel too old}
       {%
-        'postnotes' requires a LaTeX kernel 2021-11-15 or newer.%
+        'postnotes' requires a LaTeX kernel 2022-06-01 or newer.%
         \MessageBreak Loading will abort!%
       }%
     \endinput
@@ -147,7 +153,7 @@
 %
 %
 %    \begin{macrocode}
-\ProvidesExplPackage {postnotes} {2022-11-13} {0.1.7}
+\ProvidesExplPackage {postnotes} {2022-12-28} {0.2.0}
   {Endnotes for LaTeX}
 %    \end{macrocode}
 %
@@ -233,6 +239,7 @@
       { \thesection }
     \prop_gput:cnn { \@@_data_name:e {#1} } { content } {#2}
   }
+\cs_generate_variant:Nn \@@_store_section:nn { nx }
 %    \end{macrocode}
 % \end{macro}
 %
@@ -863,18 +870,10 @@
         \UseHook { postnotes/note/begin }
         \cs_set:Npn \@currentcounter { postnote }
         \cs_set:Npx \@currentlabel { \p@postnote \l_@@_mark_tl }
-        \@@_hyperref_make_currentHref:n
-          { postnote. \l_@@_note_id_tl .mark }
+        \MakeLinkTarget* { postnote. \l_@@_note_id_tl .mark }
         \@@_set_mark_page_label:x { \l_@@_note_id_tl }
         \@@_set_user_labels:
-        \bool_if:NTF \l_@@_nomark_bool
-          {
-            \bool_if:NT \l_@@_hyperlink_bool
-              {
-                \@@_hyperref_set_anchor:n
-                  { postnote. \l_@@_note_id_tl .mark }
-              }
-          }
+        \bool_if:NF \l_@@_nomark_bool
           {
             \@@_typeset_mark:xV
               { \l_@@_note_id_tl } \l_@@_mark_tl
@@ -898,16 +897,22 @@
 \bool_new:N \l_@@_maybe_multi_bool
 \keys_define:nn { postnotes/note }
   {
-    mark .tl_set:N = \l_@@_mark_tl ,
-    mark .value_required:n = true ,
-    nomark .bool_set:N = \l_@@_nomark_bool ,
-    nomark .default:n = true ,
+    markstr .tl_set:N = \l_@@_mark_tl ,
+    markstr .value_required:n = true ,
     sortnum .code:n =
       {
         \fp_set:Nn \l_@@_sort_num_fp {#1}
         \bool_set_true:N \l_@@_manual_sortnum_bool
       } ,
     sortnum .value_required:n = true ,
+    mark .meta:n =
+      {
+        markstr = {#1} ,
+        sortnum = {#1} ,
+      } ,
+    mark .value_required:n = true ,
+    nomark .bool_set:N = \l_@@_nomark_bool ,
+    nomark .default:n = true ,
     label .tl_set:N = \l_@@_note_label_tl ,
     label .value_required:n = true ,
   }
@@ -981,7 +986,6 @@
       {
         \bool_if:NTF \l_@@_hyperlink_bool
           {
-            \@@_hyperref_set_anchor:n { postnote. #1 .mark }
             \@@_make_mark:nnn {#2}
               { \hyper@linkstart { link } { postnote. #1 .text } }
               { \hyper@linkend }
@@ -1054,7 +1058,7 @@
             \hyperref [#2]
               { \@@_make_mark:nnn { \ref*{#2} } { } { } }
           }
-          { \@@_make_mark:nnn { \@@_ref_star:n {#2} } { } { } }
+          { \@@_make_mark:nnn { \ref*{#2} } { } { } }
       }
     \group_end:
   }
@@ -1078,7 +1082,16 @@
 \NewDocumentCommand \postnotesection { O { } +m }
   { \@@_section:nn {#1} {#2} }
 \NewDocumentCommand \postnotesectionx { O { } +m }
-  { \@@_section:nx {#1} {#2} }
+  {
+    % NOTE Command deprecated in 2022-12-27 for v0.2.0.
+    \msg_warning:nn { postnotes } { postnotesectionx-deprecated }
+    \postnotesection [ #1 , exp ] {#2}
+  }
+\msg_new:nnn { postnotes } { postnotesectionx-deprecated }
+  {
+    '\iow_char:N\\postnotesectionx'~is~deprecated~\msg_line_context:.~
+    Use~the~'exp'~option~of~'\iow_char:N\\postnotesection'~instead.
+  }
 %    \end{macrocode}
 % \end{macro}
 %
@@ -1097,10 +1110,11 @@
     \seq_gput_right:Nx \g_@@_queue_seq { \l_@@_note_id_tl }
     \tl_gclear:N \g_@@_section_name_tl
     \keys_set:nn { postnotes/section } {#1}
-    \@@_store_section:nn { \l_@@_note_id_tl } {#2}
+    \bool_if:NTF \l_@@_section_exp_bool
+      { \@@_store_section:nx { \l_@@_note_id_tl } {#2} }
+      { \@@_store_section:nn { \l_@@_note_id_tl } {#2} }
     \group_end:
   }
-\cs_generate_variant:Nn \@@_section:nn { nx }
 %    \end{macrocode}
 % \end{macro}
 %
@@ -1111,10 +1125,14 @@
 %
 %    \begin{macrocode}
 \tl_new:N \g_@@_section_name_tl
+\bool_new:N \l_@@_section_exp_bool
 \keys_define:nn { postnotes/section }
   {
     name .tl_gset:N = \g_@@_section_name_tl ,
     name .value_required:n = true ,
+    exp .bool_set:N = \l_@@_section_exp_bool ,
+    exp .initial:n = false ,
+    exp .default:n = true ,
   }
 %    \end{macrocode}
 %
@@ -1208,7 +1226,8 @@
 % that the particular value of \texttt{postnotesection} is of little practical
 % meaning, it really is just meant to provide recognizable ``bounds'' for
 % \texttt{postnote} along the printing of the notes.  Indeed, it is
-% initialized to a very high value, so that ``marks'' and ``texts'' don't mix
+% initialized to a very high value (larger than the conceivable number of
+% postnote sections in a document), so that ``marks'' and ``texts'' don't mix
 % in the same reference list, which would occur if the enclosing counters of
 % both belonged to the same range, and with somewhat arbitrary results, since
 % we cannot ensure the step of the enclosing counter along the document
@@ -1341,10 +1360,10 @@
                   { \l_@@_print_counter_tl }
                 \cs_set:Npx \@currentlabel
                   { \p@postnote \l_@@_print_mark_tl }
-                \@@_hyperref_make_currentHref:n
-                  { postnote. \l_@@_print_note_id_tl .text }
                 \@@_text_mark_wrapper:n
                   {
+                    \MakeLinkTarget*
+                      { postnote. \l_@@_print_note_id_tl .text }
                     \@@_set_text_page_label:x
                       { \l_@@_print_note_id_tl }
                     \@@_typeset_text_mark:eV
@@ -1420,16 +1439,13 @@
 %    \begin{macrocode}
 \cs_new_protected:Npn \@@_typeset_text_mark:nn #1#2
   {
-    \bool_if:NTF \l_@@_hyperlink_bool
+    \bool_lazy_and:nnTF
+      { \l_@@_hyperlink_bool }
+      { \l_@@_backlink_bool  }
       {
-        \@@_hyperref_set_anchor:n { postnote. #1 .text }
-        \bool_if:NTF \l_@@_backlink_bool
-          {
-            \@@_make_text_mark:nnn {#2}
-              { \hyper@linkstart { link } { postnote. #1 .mark } }
-              { \hyper@linkend }
-          }
-          { \@@_make_text_mark:nnn {#2} { } { } }
+        \@@_make_text_mark:nnn {#2}
+          { \hyper@linkstart { link } { postnote. #1 .mark } }
+          { \hyper@linkend }
       }
       { \@@_make_text_mark:nnn {#2} { } { } }
   }
@@ -1437,10 +1453,7 @@
 \cs_new_protected:Npn \@@_text_mark_wrapper:n #1
   {
     \bool_if:NTF \l_@@_print_as_list_bool
-      {
-        \item
-          [ \l_@@_pre_textmark_tl #1 \l_@@_post_textmark_tl ]
-      }
+      { \item [ \l_@@_pre_textmark_tl #1 \l_@@_post_textmark_tl ] }
       { \l_@@_pre_textmark_tl #1 \l_@@_post_textmark_tl }
   }
 %    \end{macrocode}
@@ -1968,47 +1981,6 @@
 %    \end{macrocode}
 %
 %
-% \subsection*{\pkg{hyperref}}
-%
-%    \begin{macrocode}
-\bool_new:N \g_@@_hyperref_loaded_bool
-\AddToHook { package/hyperref/after }
-  { \bool_gset_true:N \g_@@_hyperref_loaded_bool }
-%    \end{macrocode}
-%
-% \begin{macro}
-%   {
-%     \@@_hyperref_make_currentHref:n ,
-%     \@@_hyperref_set_anchor:n ,
-%     \@@_ref_star:n ,
-%   }
-%   Auxiliary functions for \pkg{hyperref} support.
-%   \begin{syntax}
-%     \cs{@@_hyperref_make_currentHref:n} \Arg{anchor/destination}
-%     \cs{@@_hyperref_set_anchor:n} \Arg{anchor/destination}
-%     \cs{@@_ref_star:n} \Arg{label}
-%   \end{syntax}
-%    \begin{macrocode}
-\cs_new_protected:Npn \@@_hyperref_make_currentHref:n #1
-  {
-    \bool_if:NT \g_@@_hyperref_loaded_bool
-      { \Hy@MakeCurrentHref {#1} }
-  }
-\cs_new_protected:Npn \@@_hyperref_set_anchor:n #1
-  {
-    \bool_if:NT \g_@@_hyperref_loaded_bool
-      { \Hy@raisedlink { \hyper@anchor {#1} } }
-  }
-\cs_new_protected:Npn \@@_ref_star:n #1
-  {
-    \bool_if:NTF \g_@@_hyperref_loaded_bool
-      { \ref*{#1} }
-      { \ref{#1} }
-  }
-%    \end{macrocode}
-% \end{macro}
-%
-%
 % \subsection*{\pkg{biblatex}}
 %
 % Thanks \contributor{Moritz Wemheuer}:
@@ -2389,7 +2361,12 @@
 % \cs{textnormal}, \cs{textup}, etc.) in inline math environments is not
 % supported.  If a note really needs to be there, one can use the \opt{nomark}
 % option and \cs{postnoteref}.  Things should work in text mode and in display
-% style.
+% style.  For some related discussion with regard to footnotes,
+% see \url{https://tex.stackexchange.com/a/82820} and, in particular, Barbara
+% Beeton's comment: ``This is certainly bravura code.  I do hope it doesn't
+% result in a request to add \cs{footnote} capabilities to \pkg{amsmath}'s
+% multi-line display facilities.  (The answer will almost certainly be "no".
+% We agree with Kopka \& Daly.)''
 %    \begin{macrocode}
     \AddToHook { postnotes/note/begin } [ postnotes ]
       {
@@ -2640,9 +2617,13 @@
 %
 % \subsection*{French}
 %
-% French localization validated by \contributor{\texttt{Pika78}} at
+% French localization validated by \contributor{\username{Pika78}} at
 % \githubissue{1}.
 %
+% \pkg{babel-french} also has \file{.ldf}s for \texttt{francais},
+% \texttt{frenchb}, and \texttt{canadien}, but they are deprecated as options
+% and, if used, they fall back to either \texttt{french} or \texttt{acadian}.
+%
 %    \begin{macrocode}
 \@@_define_language:nn { french }
   {
@@ -2651,11 +2632,8 @@
     \tl_set:Nn \pnhdtopage  { de~la~page }
     \tl_set:Nn \pnhdtopages { des~pages }
   }
-\@@_set_babel_language:nn { french }   { french }
-\@@_set_babel_language:nn { acadian }  { french }
-\@@_set_babel_language:nn { canadien } { french }
-\@@_set_babel_language:nn { francais } { french }
-\@@_set_babel_language:nn { frenchb }  { french }
+\@@_set_babel_language:nn { french }  { french }
+\@@_set_babel_language:nn { acadian } { french }
 \@@_set_polyglossia_language:nn { french } { french }
 %    \end{macrocode}
 %
@@ -2665,6 +2643,10 @@
 % German localization provided by \contributor{Herbert Voß} at
 % \githubissue{2}.
 %
+% \pkg{babel-german} also has \file{.ldf}s for \texttt{germanb} and
+% \texttt{ngermanb}, but they are deprecated as options and, if used, they
+% fall back respectively to \texttt{german} and \texttt{ngerman}.
+%
 %    \begin{macrocode}
 \@@_define_language:nn { german }
   {