footnotehyper (4feb21)

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

1 files changed, 261 insertions, 84 deletions

diff --git a/Master/texmf-dist/source/latex/footnotehyper/footnotehyper.dtx b/Master/texmf-dist/source/latex/footnotehyper/footnotehyper.dtx
index 83e6d30bbe1..b42e003c2b1 100644
--- a/Master/texmf-dist/source/latex/footnotehyper/footnotehyper.dtx
+++ b/Master/texmf-dist/source/latex/footnotehyper/footnotehyper.dtx
@@ -1,20 +1,20 @@
 % -*- coding: utf-8; time-stamp-format: "%02d-%02m-%:y at %02H:%02M:%02S %Z" -*-
 %<*none>
-\def\dtxtimestamp {Time-stamp: <29-01-2021 at 19:18:01 CET>}
+\def\dtxtimestamp {Time-stamp: <04-02-2021 at 12:57:09 CET>}
 %</none>
 %<*!readme>
 %%
 %% Package: footnotehyper
-%% Version: 1.1c (2021/01/29)
+%% Version: 1.1d (2021/02/04)
 %% License: LPPL 1.3c
 %% Copyright (C) 2016-2021 Jean-Francois Burnol <jfbu at free dot fr>.
 %%
 %</!readme>
 %<*tex>
 \def\pkgname        {footnotehyper}
-\def\pkgdate        {2021/01/29}
-\def\docdate        {2021/01/29}
-\def\pkgversion     {v1.1c}
+\def\pkgdate        {2021/02/04}
+\def\docdate        {2021/02/04}
+\def\pkgversion     {v1.1d}
 \def\pkgdescription {hyperref aware footnote.sty (JFB)}
 %</tex>
 %<*none>
@@ -25,7 +25,7 @@
     \catcode32=13\catcode`\\=12^^Brelax^^A
 ^^Bfirstofone{^^Bendgroup^^Bdef^^BpkgLicense^^A
 {% Package: footnotehyper
-% Version: 1.1c (2021/01/29)
+% Version: 1.1d (2021/02/04)
 % License: LPPL 1.3c
 % Copyright (C) 2016-2021 Jean-Francois Burnol <jfbu at free dot fr>.
 %
@@ -54,7 +54,7 @@
 %<*readme>
 <!-- -->
 
-    Source:  footnotehyper.dtx (v1.1c 2021/01/29)
+    Source:  footnotehyper.dtx (v1.1d 2021/02/04)
     Author:  Jean-Francois Burnol
     Info:    hyperref aware footnote.sty
     License: LPPL 1.3c
@@ -392,6 +392,22 @@ See related remarks at end of \autoref{sec:notes}.
   |savenotes| environment directly wraps the enclosed list environment,
   mid-paragraph).
 
+\item[v1.1d (2021/02/04)] Fix regression at |v1.1b| which caused a build crash
+  whenever \fnh decided to raise a warning relative to |\@makefntext|.%
+%
+\footnote{Thanks to Leon K. for reporting the bug.}
+
+  Refactor analysis of \cs{@makefntext} for simpler and better support of
+  |babel-french|.%
+\footnote{Only basic
+  context has been tested with |babel-french|: standard classes, |KOMA|-script,
+  |memoir|. Extra packages may make the \fnh environments cause breakage.}
+%
+  Better support
+  contexts such as presence of package |cleveref|.%
+
+  Add \verb=\iffootnotehyperparse= and \verb=\iffootnotehyperwarn= booleans.
+
 \end{description}
 \section{Usage}
 
@@ -405,42 +421,94 @@ As summarized in the abstract, the package provides:
     verbatim material.
   \end{itemize}
 \end{savenotes}
-But the constructability of the |footnote/footnotetext| environments depends
-on how |\@makefntext| has been customized by the class or other packages; a
-warning is issued if the situation appears to be desperate.\footnote{original
-  |footnote.sty| could end up in a low level \TeX\ error.}
-
-  Some details: \fnh inherits from |footnote| original package the aim to
-  convert the macro |\@makefntext| into two parts, the first one to be inserted
-  at the start of a footnote in environment form, the second one at its end.
-  It thus hopes that the replacement text of |\@makefntext| contains only once
-  its parameter token |#1|, and that it is used unbraced.
+Setting-up the environments proceeds from an analysis of the pre-existing
+internal \LaTeX\ macro |\@makefntext|. The next section discusses problems
+which may arise.
 
-\begin{savenotes}
-\begin{framed}
-  \fnh has a more robust, but still naive, way of analysing this than the
-  original package. But even seemingly innocent redefinitions such as the one
+\subsection{Potential difficulties with the footnote and footnotetext
+  environments}
+
+  What is discussed here only affects the \emph{environments} |footnote| and
+  |footnotetext| not the macros \cs{footnote} and \cs{footnotetext}.
+
+  \fnh inherits from |footnote| original package the aim to
+  convert |\@makefntext| into two parts, the first one to be inserted
+  at the start of a footnote in environment form, the second one (usually
+  empty) at its end.%
+%
+\begin{footnote}
+  \LaTeX\ inserts some stuff before and after the footnote text, even before
+  handing it over as argument to \cs{@makefntext}. These tokens are currently
+  hardcoded into the \fnh environments for footnotes.
+\end{footnote}
+%
+  It thus hopes that the replacement text of |\@makefntext| contains only once
+  its parameter token |#1|, and that it is used there unbraced. This is the case
+  with the |article| class.
+
+  Known bug (may be promoted to feature at some point): the analysis is done
+  only once at begin document, whereas the |article.cls|'s redefines
+  |\@makefntext| during execution of |\maketitle|. However, it does not look
+  really urgent to support at all costs usage of the environment |footnote| in
+  the |\author| etc... data which contributes to the |\maketitle| expansion.%
+%
+    \begin{footnote}
+\phantomsection\label{fn:texperts}%
+      \TeX perts note: |\def\FNH@prefntext{\@makefntext{}}| would make the
+      footnote environment dynamically adjust to circumstances, when
+      |\@makefntext| only adds some prefix and no postfix. In fact, this is
+      (in a more complicated form for compatibility with |KOMA|-script and to
+      obey the |FBFrenchFootnotes| setting and the additional extra stuff
+      inserted by |babel-french| before and after) basically what is done by
+      \fnh to handle
+      |babel-french|.
+
+      As it may cause instability if extra packages fiddle
+      with |\@makefntext|, or |\@makefntext| is radically re-defined in some
+      environments provided by the class, \fnh does not use this when its
+      begin document analysis concluded the argument was used unbraced and at
+      last position in replacement text of |\@makefntext|, but it freezes the
+      found prefix. However, when it is concluded that probably |\@makefntext|
+      has been redefined in an |<extra tokens>\old@makefntext| way (for
+      example, this is the case with |cleveref| package), then the
+      |\def\FNH@prefntext{\@makefntext{}}| approach is taken, despite the
+      risks inherent to it.
+
+      You can provide your own definitions of
+      \cs{FNH@prefntext} and \cs{FNH@postfntext}. Then add
+      \cs{footnotehyperparsefalse} to the preamble.
+    \end{footnote}
+
+  Some seemingly innocent redefinitions such as the one
   of |beamer| which was last time I checked (that was in 2019):
 \begin{verbatim}
 macro:#1->\def \insertfootnotetext {#1}\def \insertfootnotemark
 {\@makefnmark }
 \usebeamertemplate ***{footnote}
 \end{verbatim}
-   is not compatible. Since |v1.1a|, \fnh simply aborts under |beamer| class.
-
-  The package could possibly be much improved here, but at update |v1.1b| it
-  simply adds a specific fix to handle a problem of another type arising with
-  |memoir| together with |babel-french|%
-  \begin{footnote}
-    In the |babel-french| context, \fnh attempts to analyse |\@makefntextFB|
-    rather than |\@makefntext| itself. The problem arose in that (automated)
-    analysis.
-  \end{footnote}
-  This fix uses a bit daring |\scantokens| which could be useful to solve
-  other incompatibilities of the similar nature, but we have limited the fix
-  to those exact circumstances, until we get alerted by some bug report.
-\end{framed}
-\end{savenotes}
+  are not (easily) compatible with environment forms for footnotes
+  allowing verbatim material, as they require fetching the footnote
+  contents.%
+  \footnote{%\phantomsection\label{fn:beamer}% test, ça marche!
+  Since |v1.1a|, \fnh simply aborts under |beamer| class.}
+
+  In case of such a problematic |\@makefntext| \fnh raises a warning, to
+  explain that footnotes typeset using the environment forms will be
+  dysfunctional (the footnote marker at bottom of page will be missing,
+  probably). Footnotes using |\footnote| are not impacted by this.
+
+  % See \ref{fn:beamer} % test, ça marche, aussi avec environnement
+
+  Also \fnh emits some info message if |\@makefntext| was not as simple as
+  expected but nevertheless there is some hope that the |footnote| and
+  |footnotetext| environments will be fully functional. This is currently the
+  case in presence of package |cleveref| (see the \TeX perts
+  footnote \ref{fn:texperts}).
+
+  You can turn off these messages by adding \cs{footnotehyperwarnfalse}
+  to the document preamble.
+
+\subsection{Other potential or actual limitations}
 
 It should be recalled that in case of |\footnotemark[N]| and
 |\footnotetext[N]{...}| mark-up |hyperref| creates no hyperlink. This is not
@@ -458,6 +526,8 @@ Environments typesetting multiple times their contents are the most hostile to
 footnotes. Currently, \fnh only handles especially the |amsmath|
 environments (as in |footnote.sty|.)
 
+\subsection{A legacy macro from the original package, usage not recommended}
+
 Finally there is a |\makesavenoteenv| command which takes as
 argument an environment name and patches it to do the
 |\savenotes/\spewnotes| automatically.%
@@ -472,6 +542,7 @@ one never knows what happens with such patches: for example the |[H]|
 specifier provided by the |float| package overwrites the |\end{table}|
 definition during the execution of |\begin{table}|\dots !
 
+\subsection{Example of use}
 \begin{savenotes}
 \begin{framed}
 \DeleteShortVerb{\|}\MakeShortVerb{\*}%
@@ -486,7 +557,7 @@ definition during the execution of |\begin{table}|\dots !
       could have been used.\end{footnote}\\\hline
 \end{tabular}\par}
 \DeleteShortVerb{\*}\MakeShortVerb{\|}%
-An example:
+Here is an illustrative example of usage of the |savenotes| environment:
 \begin{verbatim}
 \begin{savenotes}
 \begin{framed}
@@ -494,15 +565,16 @@ An example:
   \footnote{\url{http://ctan.org/pkg/footnote}}
 
   Particularly you may check its |savenotes| environment.%
-  \footnote{It doesn't bring any
+  \footnote{\phantomsection\label{fn:floats}It doesn't bring any
   feature to especially handle the issues related to footnotes in floating
   environments, though.}
 \end{framed}
 \end{savenotes}
+Here is a link to an interesting footnote: \ref{fn:floats}.
 \end{verbatim}
 and the present frame has \cs{footnote}'s from inside a |tabular| and is
 inside a |savenotes| environment.%
-\begin{footnote}
+\begin{footnote}\phantomsection\label{fn:minipage}
   Here is an issue which has nothing (as I finally figured out) to
   do with |footnote|, and only indirectly with \LaTeX: if you embed
   a \emph{full-width} minipage (with initial \cs{noindent}) in any
@@ -575,20 +647,19 @@ No hyperfootnote link was inserted.%
   |\footnotemark[N]/\footnotetext[N]{<foo>}| case. It does when
   the |[N]| is absent or when it is used with a |\footnote| command
   (or a |footnote| environment.)
-
-  By the way, \fnh |v0.9f|'s |\footnotetext[N]| and |\begin{footnotetext}[N]|
-  each had a bug and they were unusable \emph{inside} the |savenotes|
-  environment. There was no issue \emph{outside}.
 \end{footnotetext}
 And a final footnote, done with |\begin{footnote}[57]|%
-\begin{footnote}[57]\csname @minipagetrue\endcsname % to reduce
-                                % framed inserted vertical spacing
-  \begin{framed}
-    \noindent\fnh works since |v1.0| also in absence of |hyperref| or when the
+\begin{footnote}[57]%\csname @minipagetrue\endcsname % to reduce
+%                                % framed inserted vertical spacing
+%  \begin{framed}
+%    \noindent
+    \fnh works since |v1.0| also in absence of |hyperref| or when the
     latter was passed |hyperfootnotes=false| option.
-  \end{framed}
+%  \end{framed}
 \end{footnote}.
-There is no problem with the hyperlink, then.
+There is no problem with the hyperlink, then. Oh, and don't forget to read
+this interesting footnote: \ref{fn:minipage} (just in case you skipped on
+first reading).
 
 \section{Notes}\label{sec:notes}
 
@@ -690,8 +761,10 @@ is still there, as I checked now. This has nothing to do with \fnh.
 %</none>
 %<*package>
 % \begin{macro}{no options}
-% The package has no options.
+% The package has no options. I am too lazy.
 %    \begin{macrocode}
+\newif\iffootnotehyperparse\footnotehyperparsetrue
+\newif\iffootnotehyperwarn \footnotehyperwarntrue
 \DeclareOption*%
     {\PackageWarning{footnotehyper}{Option `\CurrentOption' is unknown}}%
 \ProcessOptions\relax
@@ -1031,6 +1104,7 @@ is still there, as I checked now. This has nothing to do with \fnh.
 % \begin{macro}{\@makefntext}
 % \begin{macro}{\FNH@prefntext}
 % \begin{macro}{\FNH@postfntext}
+% \begin{macro}{\FNH@check}
 %   The definitions of |\FNH@prefntext| and |\FNH@postfntext| (which are needed
 %   for the |footnote| environment, |\FNH@startfntext| and |\FNH@endfntext|)
 %   are extracted from a somewhat daring analysis of |\@makefntext|.
@@ -1041,68 +1115,171 @@ is still there, as I checked now. This has nothing to do with \fnh.
 %   there multiple times. We also insert here some code to handle especially
 %   the case of |babel-frenchb|.
 %
+%   Refactoring at |v1.1d|. This will make \fnh compatible with |cleveref| for
+%   example, if nothing else interferes. Not all combinations of classes and
+%   packages can be handled and we can not hardcode a pre-analysis for all
+%   possible cases. Of course, one can not expect \fnh to be compatible with
+%   other footnote dedicated packages, but at best only with slight
+%   modifications of \LaTeX's defaults. At |v1.1d| the |babel-french| context
+%   is handled especially (to support it better with KOMAscript classes and
+%   simplify handling the |memoir| situation); there was no real other way
+%   than hardcode it more or less, but it can possibly break in presence of
+%   additional footnote packages.
+%
+%   Also the \cs{iffootnotehyperparse} and \cs{iffootnotehyperwarn} booleans
+%   were added.
+%
+%   Provide at least some definitions for \cs{FNH@prefntext} and
+%   \cs{FNH@postfntext} in case of \cs{footnotehyperparsefalse} in preamble.
+%    \begin{macrocode}
+\let\FNH@prefntext\@empty
+\let\FNH@postfntext\@empty
+\AtBeginDocument{\iffootnotehyperparse\expandafter\FNH@check\fi}%
+%    \end{macrocode}
+%
 %   As |\ifFBFrenchFootnotes| is not a \TeX\ boolean if |babel-frenchb| isn't
 %   loaded, we have to work around this for |\if..\fi| pairs.
 %
+%   |v1.1d| fixes a |v1.1b| bug: any situation in |\FNH@check@a| causing the
+%   |\FNH@bad@makefntext@alert| branch to be chosen crashed the build due
+%   precisely to this problem with |\ifFBFrenchFootnotes| status. I had taken
+%   precautions for the |\else| branch but not for the ``warning'' branch.
+%
+%   So let's fix this, and do it in such a way (with \cs{FNH@safeif}) that the
+%   \TeX\ |\if..\fi| balancing count does not perturbate enclosing the package
+%   loading in a \TeX\ conditional. Why I am bothering, I don't know.
+%
+%   Finally, I refactored entirely the way |frenchb| context is handled,
+%   (using multiple times \cs{FNH@safeif} although now only for the artistic
+%   aim of balanced conditionals, as all |frenchb|-related stuff being in
+%   their dedicated macro, direct usage of |\ifFB...| is possible).
+%
+%   As long as nothing else interferes |babel-french| should be ok with
+%   standard classes, KOMA and memoir.
+%
 %    \begin{macrocode}
-\AtBeginDocument{\let\FNH@@makefntext\@makefntext
-   \ifx\@makefntextFB\undefined
-   \expandafter\@gobble\else\expandafter\@firstofone\fi
-   {\ifFBFrenchFootnotes \let\FNH@@makefntext\@makefntextFB \else
-                         \let\FNH@@makefntext\@makefntextORI\fi}%
-   \expandafter\FNH@check@a\FNH@@makefntext{1.2!3?4,}%
-               \FNH@@@1.2!3?4,\FNH@@@\relax
+\def\FNH@safeif#1{%
+   \iftrue\csname if#1\endcsname\csname fi\endcsname\expandafter\@firstoftwo
+   \else\csname fi\endcsname\expandafter\@secondoftwo
+   \fi
+}%
+\def\FNH@check{%
+   \ifx\@makefntextFB\@undefined\expandafter\FNH@check@
+                           \else\expandafter\FNH@frenchb@
+   \fi
+}%
+\def\FNH@frenchb@{%
+   \def\FNH@prefntext{%
+     \localleftbox{}%
+     \let\FBeverypar@save\FBeverypar@quote
+     \let\FBeverypar@quote\relax
+     \FNH@safeif{FB@koma}%
+       {\FNH@safeif{FBFrenchFootnotes}%
+          {\ifx\footnote\thanks
+             \let\@@makefnmark\@@makefnmarkTH
+             \@makefntextTH{} % space as in french.ldf
+           \else
+             \let\@@makefnmark\@@makefnmarkFB
+             \@makefntextFB{} % space as in french.ldf
+             \fi
+          }{\let\@@makefnmark\@@makefnmarkORI
+             \@makefntextORI{}% no space as in french.ldf
+          }%
+       }%
+       {\FNH@safeif{FBFrenchFootnotes}%
+          {\@makefntextFB{}}%
+          {\@makefntextORI{}}%
+       }%
+   }%
+   \def\FNH@postfntext{%
+     \let\FBeverypar@quote\FBeverypar@save
+     \localleftbox{\FBeveryline@quote}%
+   }%
+   \iffootnotehyperwarn
+    \PackageInfo{footnotehyper}%
+      {frenchb compatibility patch activated.^^J It will not work in
+       all circumstances.^^J In case of problems with the `footnote' or
+       `footnotetext' environments,^^J please send to the author a small
+       file demonstrating the problem.^^J To turn off this message, add
+       \string\footnotehyperwarnfalse\space to the preamble.^^J}%
+   \fi
 }%
 %    \end{macrocode}
-%   ``Daring analysis'' is un understatement. At |v1.1b| we add a dangerous
+% \end{macro}
+%   ``Daring analysis'' is un understatement. At |v1.1b| we added a dangerous
 %   twist to fix a memoir + frenchb triggered issue: if the
 %   |\@makefntext|, as in memoir + frenchb situation, uses |\def| syntax to
 %   define a macro with parameter we had a problem with the |#| token not
 %   being doubled in the replacement fetched by
-%   |\FNH@check@a|. As expedient work-around we fix this by adding a
-%   |\scantokens| wrapper. The induced end of line space will only be from
-%   loading of \fnh itself, so we can ignore. Problem is we
-%   assume here |\@makefntext| does not rely on weird catcodes. Very
-%   problematic if LaTeX3 syntax is used. So I add a layer a security to do
-%   this \emph{only} under memoir + frenchb situation. Which is a pity
-%   as it could be more generally useful. But let's wait for bug reports if
-%   really needed.
+%   |\FNH@check@a|. As expedient work-around we fixed this by adding a
+%   |\scantokens| wrapper.
 %
-%   Maybe I should add some user interface to customize directly what
-%   |\FNH@prefntext| and |\FNH@postfntext| do, but I am aiming today for a
-%   quick bug fix, as we are |2021/01/26| and first heard of the bug on
-%   |2020/06/15|.
+%   At |v1.1d| I refactored the |babel-french| situation, moving it to an
+%   entirely dedicated \cs{FNH@frenchb@}, and dropped the |v1.1b| usage of
+%   |\scantokens|.
+%
+%   |v1.1d| adds \cs{FNH@checkagain@} which will identify circumstances likely
+%   to be safe for the approach via |\def\FNH@prefntext{\@makefntext{}}|. For
+%   example this is what will happen with |cleveref| (if not modified by other
+%   packages).
 %    \begin{macrocode}
+\def\FNH@check@{%
+    \expandafter\FNH@check@a\@makefntext{1.2!3?4,}%
+                \FNH@@@1.2!3?4,\FNH@@@\relax
+}%
 \long\def\FNH@check@a #11.2!3?4,#2\FNH@@@#3{%
-    \ifx\relax#3\FNH@bad@makefntext@alert
+    \ifx\relax#3\expandafter\FNH@checkagain@
     \else
-      \edef\FNH@restore@{\catcode`\noexpand\@\the\catcode`\@\relax}%
-      \makeatletter
-      \ifx\@makefntextFB\undefined
-      \expandafter\@gobble\else\expandafter\@firstofone\fi
-      {\@ifclassloaded{memoir}%
-           {\ifFBFrenchFootnotes\expandafter\@gobble\fi}%
-           {}}%
-      \@secondoftwo
-      \scantokens{\def\FNH@prefntext{#1}\def\FNH@postfntext{#2}}%
-      \FNH@restore@
+      \def\FNH@prefntext{#1}\def\FNH@postfntext{#2}%
       \expandafter\FNH@check@b
     \fi
 }%
+%    \end{macrocode}
+% The argument was not seen unbraced at top. Maybe it is not fetched, or it was
+% but was left at the end, braced. If this is the case we use the fallback
+% |\def\FNH@prefntext{\@makefntext{}}|, which may work.
+%    \begin{macrocode}
+\def\FNH@checkagain@{%
+    \expandafter\FNH@checkagain@a
+    \detokenize\expandafter{\@makefntext{1.2!3?4,}}\relax\FNH@@@
+}%
+\edef\FNH@temp{\noexpand\FNH@checkagain@a ##1\string{1.2!3?4,\string}}%
+\expandafter\def\FNH@temp#2#3\FNH@@@{%
+    \ifx\relax#2%
+      \def\FNH@prefntext{\@makefntext{}}%
+      \iffootnotehyperwarn
+        \PackageInfo{footnotehyper}%
+        {using \string\@makefntext{} approach.^^J
+         In case of problems with the footnote environments, please send^^J
+         to the author a small document source illustrating them. To turn^^J
+         off this message, add
+         \string\footnotehyperwarnfalse\space to preamble.^^J}%
+      \fi
+    \else\FNH@bad@makefntext@alert
+    \fi
+}%
+%    \end{macrocode}
+% Back to non |babel-french| context. Let's check that |pre| and |post| do not
+% contain some weird stuff from original |\@makefntext{#1}| containing
+% multiple times |#1|.
+%    \begin{macrocode}
 \def\FNH@check@b #1\relax{%
     \expandafter\expandafter\expandafter\FNH@check@c
     \expandafter\meaning\expandafter\FNH@prefntext
     \meaning\FNH@postfntext1.2!3?4,\FNH@check@c\relax
 }%
 \def\FNH@check@c #11.2!3?4,#2#3\relax{%
-    \ifx\FNH@check@c#2\expandafter\@gobble\fi\FNH@bad@makefntext@alert
+    \ifx\FNH@check@c#2\else\FNH@bad@makefntext@alert\fi
 }%
 \def\FNH@bad@makefntext@alert{%
+    \iffootnotehyperwarn
     \PackageWarningNoLine{footnotehyper}%
-      {^^J The footnote environment will not be fully functional, sorry.^^J
+      {^^J The footnote environments will probably lack footnote numbers at^^J
+       bottom of pages, sorry.^^J
        You may try to email the author this meaning of \string\@makefntext:^^J
        \meaning\@makefntext^^J
-       together with the used preamble}%
+       together with the document preamble}%
+    \fi
     \let\FNH@prefntext\@empty\let\FNH@postfntext\@empty
 }%
 %    \end{macrocode}