Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

sphinxfootnotemark is not working correctly after update sphinx >=3.5.0 #9529

Closed
xstodu07 opened this issue Aug 5, 2021 · 4 comments
Closed

Comments

@xstodu07
Copy link

xstodu07 commented Aug 5, 2021

Describe the bug

After sphinx update to version 3.5.0 or higher, only first footnote is functional after converting rst > tex > pdf. Other references to the same footnote are translated as question mark.

As little example after .rst files are translated to .tex it looks like this:

Some text
\begin{footnote}[1]\sphinxAtStartFootnote
URL: \sphinxurl{https://access.redhat.com/documentation/en-us/red\_hat\_enterprise\_linux/8/html-single/upgrading\_from\_rhel\_7\_to\_rhel\_8/index}.
%
\end{footnote}.

Some other text
\sphinxfootnotemark[1].

But when you translate it from latex to .pdf, output looks like:
Some text1.
Some other text?.

How to Reproduce

$ git clone https://github.com/xstodu07/sphinx-issues
$ cd sphinx-issues
$ pip install tox
$ # tox - Create virtualenv with dependencies in requirements.txt, build latex/*.pdf and html/
$ # OR create own virtualenv, activate it (for example: source .tox/docs/bin/activate) and build latex using 'make pdflatex' from 'docs/' directory
$ tox
$ # check docs/_build/latex/footnotes.pdf

Expected behavior

Some text1.
Some other text1.

Your project

https://github.com/xstodu07/sphinx-issues

Screenshots

No response

OS

Linux RHEL 7.9

Python version

3.6

Sphinx version

3.5.0 or higher

Sphinx extensions

sphinxcontrib.bibtex

  • has no effect, if this extension is used or not, same happened to me when footnotes are used in original way - this extension probably use named labels (see first comment below)

Additional context

I noticed that both sphinx versions (old and version >=3.5.0) use different packages for footnotes, but dont understand much the syntax of latex .sty files:

# sphinx4.0.3
Package: sphinxpackagefootnote
%% [2021/02/04 v1.1d footnotehyper adapted to sphinx (Sphinx team)]
%% Version: based on footnotehyper.sty 2021/02/04 v1.1d
(...)
# sphinx2.3.0
[2017/10/27 v1.7 hyperref aware footnote.sty for sphinx (JFB)]
%% Package: footnotehyper-sphinx
%% Version: based on footnotehyper.sty 2017/03/07 v1.0
(...)

Footnotes are working correctly only with the older version [2017/10/27 v1.7 hyperref aware footnote.sty for sphinx (JFB)]. Of course, only without this functionality:
* #2616 (fifth item): LaTeX: footnotes from captions are not clickable,
  and for manually numbered footnotes only first one with same number is
  an hyperlink

And also, it looks like the problem is between translating latex files to pdf (sphinx generate bad .sty file for footnotes). Because generated '.tex' files are same in use of both sphinx versions.
@xstodu07
Copy link
Author

xstodu07 commented Aug 6, 2021

Actually, when I Tried to reproduce the minimal scenario once again without bibtex extension I found that footnotes are working when label is numeric only.

Some Text [1]_.
Some Other Text [1]_.

.. [1] This is footnote 1.

But in my documentations we used only named labels, like:

Some Text [#some_label]_.
Some Other Text [#some_label]_.

.. [#some_label] This is footnote 1.

And this is not working.

@jfbu jfbu added this to the 4.1.3 milestone Aug 22, 2021
@jfbu
Copy link
Contributor

jfbu commented Aug 22, 2021

Thanks so this demonstrates the issue:

Some Text [1]_.
Some Other Text [1]_.

.. [1] This is footnote 1.

Some Text [#somelabel]_.
Some Other Text [#somelabel]_.

.. [#somelabel] This is footnote with label somelabel.

The generated tex code in the latter case is lacking some extras which one sees in the former case, and this is the cause of dysfunctional \sphinxfootnotemark. The missing extras are caused by this logic:

def visit_footnote(self, node: Element) -> None:
self.in_footnote += 1
label = cast(nodes.label, node[0])
if 'auto' not in node:
self.body.append(r'\sphinxstepexplicit ')
if self.in_parsed_literal:
self.body.append(r'\begin{footnote}[%s]' % label.astext())
else:
self.body.append('%' + CR)
self.body.append(r'\begin{footnote}[%s]' % label.astext())
if 'auto' not in node:
self.body.append(r'\phantomsection'
r'\label{\thesphinxscope.%s}%%' % label.astext() + CR)
self.body.append(r'\sphinxAtStartFootnote' + CR)

The oversight is also illustrated in this comment in the Sphinx LaTeX style file:

% Explicitly numbered footnotes may be referred to, and for this to be
% clickable we need to have only one target. So we will step this at each
% explicit footnote and let \thesphinxscope take it into account
\newcounter{sphinxexplicit}
\newcommand{\sphinxstepexplicit}{\stepcounter{sphinxexplicit}}

The comment should be "Explicitly numbered and named footnotes may be referred to". As it turns out the named footnotes do result in Docutils footnote node with the "auto" in them. So the logic in latex.py is wrong as it excludes from consideration named footnotes.

(i.e. the problem is not in the latex macro \sphinxfootnotemark but in the lacking context for it to behave correctly)

@tk0miya I am not sure what is the correct way for the latex.visit_footnote() to identify both explicitly numbered and named footnotes from testing the node structure. Any suggestion? then I can make PR to fix this. If I recall correctly at time of these changes I did not want to actually modify the node structure itself, and being focused only on the issue of explicitly numbered versus automatically numbered footnotes I was happy to test for "auto". Which is wrong as this bug report demonstrates.

@tk0miya tk0miya modified the milestones: 4.1.3, 4.3.0 Sep 12, 2021
@tk0miya tk0miya modified the milestones: 4.3.0, 4.4.0 Nov 9, 2021
@tk0miya tk0miya modified the milestones: 4.4.0, 4.5.0 Jan 16, 2022
@Jellby
Copy link
Contributor

Jellby commented Feb 5, 2022

I wonder if this is the same bug. I have footnotes inside tables, a few files like this:

One
===

========== ===
Test [#a]_
========== ===
   1       One
========== ===

.. [#a] Footnote one.

Compiling with make latexpdf gives:

Latexmk: List of undefined refs and citations:
  Label `0.0.1' multiply defined
Latexmk: Summary of warnings:
  Latex found 1 multiply defined reference(s)

Examining the LaTeX files, it seems the footnotes are saved with labels \thesphinxscope.#1, and \thesphinxscope is \number\value{sphinxscope}.\number\value{sphinxexplicit}. So far so good. But although both \sphinxstepscope and \sphinxstepexplicit are defined to increase the values of the counters, I don't see they're ever called, so they stay at 0 and the labels are always the same!

@tk0miya
Copy link
Member

tk0miya commented Feb 5, 2022

I am not sure what is the correct way for the latex.visit_footnote() to identify both explicitly numbered and named footnotes from testing the node structure. Any suggestion?

Unfortunately, there is no good way to identify a "named" footnote. It's an auto-numbered footnote having a specific node-ID. So it's difficult to detect "numbered and named footnotes".

If my understanding is correct, what we really have to assign footnote IDs in LaTeX level are footnotes referred by \ sphinxfootnotemark, not "numbered and named" ones. Even for explicitly "numbered" footnotes, footnotes IDs are not needed if they are referred by a single reference. So we need to know which footnotes are referred or not.

tk0miya added a commit to tk0miya/sphinx that referenced this issue Feb 6, 2022
Named auto numbered footnote (ex. ``[#named]``) that is referred
multiple times was rendered to a question mark.

This calls `\sphinxstepexplicit` for every footnote node that is
referred multiple times.
tk0miya added a commit that referenced this issue Feb 11, 2022
Fix #9529: LaTeX: named footnotes are converted to "?"
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Mar 14, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

4 participants