summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/footnotehyper/footnotehyper.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2021-02-05 03:01:00 +0000
committerNorbert Preining <norbert@preining.info>2021-02-05 03:01:00 +0000
commit6dd01829674e94f8b6b4829e703e6e0686f07a25 (patch)
tree2d7666cb4df65d2e581d1c20dc5df6b826a2ac63 /macros/latex/contrib/footnotehyper/footnotehyper.dtx
parentc18f29fc8bbdc114e808b53b99e9244054483190 (diff)
CTAN sync 202102050301
Diffstat (limited to 'macros/latex/contrib/footnotehyper/footnotehyper.dtx')
-rw-r--r--macros/latex/contrib/footnotehyper/footnotehyper.dtx345
1 files changed, 261 insertions, 84 deletions
diff --git a/macros/latex/contrib/footnotehyper/footnotehyper.dtx b/macros/latex/contrib/footnotehyper/footnotehyper.dtx
index 83e6d30bbe..b42e003c2b 100644
--- a/macros/latex/contrib/footnotehyper/footnotehyper.dtx
+++ b/macros/latex/contrib/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}