diff options
Diffstat (limited to 'Master/texmf-dist/source')
| -rw-r--r-- | Master/texmf-dist/source/latex/footnotehyper/footnotehyper.dtx | 345 |
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} |