LaTeX builder: pdflatex "Counter too large" error from footnotes inside tables of contents

[jfbu]

With

latex_show_urls = 'footnote'

issues arise when URLs make their ways in tables of contents. Indeed currently the \footnote command ends up as \footnote[xx] with some number xx. When xx>26 an error arise, because LaTeX inside minipages wants to use alphabetical footnotes. And tables of contents are done inside such minipages.

To create the problem (zip archive attached, without build/ to make it smaller), two files:

File test1.rst:

=====================
Testing footnotes (A)
=====================


.. contents:: 
   :local:


aaaa
----

Not much to say here apart that I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`


bbbb
----

 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`
 I want to use :py:meth:`int.bit_length`

and file test2.rst

=====================
Testing footnotes (B)
=====================


.. contents:: 
   :local:


cccc
----

Nothing here

Using :py:meth:`int.bit_length`
-------------------------------

Neither here

and file index.rst:

Welcome to TEST's documentation!
================================

Contents:

.. toctree::
   :maxdepth: 2

   test1.rst
   test2.rst


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

and inside conf.py:

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinx.ext.mathjax',
]

intersphinx_mapping = {'python': ('http://docs.python.org/3', None),
   'numpy': ('http://docs.scipy.org/doc/numpy/', None),
   'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None),
   'matplotlib': ('http://matplotlib.sourceforge.net/', None)}

and

latex_show_urls = 'footnote'

One does then make latex and tries to compile the resulting tex file with pdflatex.

./TEST.tex:261: LaTeX Error: Counter too large.

This issue does not arise with Sphinx 1.3.1. It does on Sphinx 1.3.5. The issue is with using \footnote[xx] systematically rather than \footnote. I did not yet look for the commit which introduced the \footnote[xx] things.

tocfootnotelatexsphinx.zip

[jfbu]

@tk0miya I have identified commit
9fec96d as the first "bad" commit on master branch.

[tk0miya]

Fixed at 9b958b6.
After that, latex_show_urls ignores references inside contents block.

Thank you for reporting!

[jfbu]

@tk0miya This has solved the problem also for the original project where I first encountered it. Thanks.

[jfbu]

@tk0miya

I have made an attempt at https://github.com/jfbu/sphinx/tree/topicblocksfootnotes

https://github.com/jfbu/sphinx/tree/footnotes_in_topic_and_tables

to reenable footnotes in topic directives. This is on top of current PR #2453.

This uses package footnote already loaded by sphinx.sty. Unfortunately this package is very old (1997) and is definitely not hyperlink aware. Thus, the produced PDF is correct if printed but the hyperlinks are not functional (only the last one in each shadowed box or warning box works).

Update: The branch above has apparently found a way to patch footnote.sty for hyperref compatibility (sufficient for Sphinx use)

By the way, I see that footnote package is used by Sphinx for footnotes in tables rendered in LaTeX by use of package tabulary. Testing shows that hyperlinks do no work. As this is already "feature" of Sphinx, perhaps nevertheless my branch could be considered for potential merge, as it does bring some extra functionality.

Update: branch above enables working footnotes in tabular, tabulary, threeparttable but for this the Sphinx LaTeX writer must not split into \footnotemark/\footnotetext.

Here is my test file index.rst:

==============
TEST FOOTNOTES
==============

.. toctree::
   :maxdepth: 2

   index.rst

=====================
Testing footnotes (A)
=====================

.. contents:: 
   :local:


Using :py:meth:`int.bit_length`
-------------------------------

Hyperlinks work when there is **only one footnote** involved in the topic or
warning box. With more footnotes there is no problem from the purely LaTeX
point of view. But hyperlinks fail. This is an intrinsic incompatiblity of
footnote package with hyperref which can't be fixed easily, one would need a
completely rewritten approach, taking into account package hyperref.



.. topic:: Test de topic

   I want to use :py:meth:`int.bit_length`

.. warning::

   I want to use :py:meth:`int.bit_length`

This does not work anymore:

.. topic:: Test de topic

   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`

.. warning::

   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`

=======================
 Testing footnotes (B)
=======================


.. contents:: 
   :local:


aaaa
----

.. topic:: First test of topic

   Not much to say here apart that I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`


bbbb
----

I want to use :py:meth:`int.bit_length`


I want to use :py:meth:`int.bit_length`

.. topic:: Second test of topic

   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`

cccc
----


I want to use :py:meth:`int.bit_length`
I want to use :py:meth:`int.bit_length`
I want to use :py:meth:`int.bit_length`
I want to use :py:meth:`int.bit_length`
I want to use :py:meth:`int.bit_length`
I want to use :py:meth:`int.bit_length`

.. warning::

   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`
   I want to use :py:meth:`int.bit_length`

I want to use :py:meth:`int.bit_length`
I want to use :py:meth:`int.bit_length`
I want to use :py:meth:`int.bit_length`
I want to use :py:meth:`int.bit_length`
I want to use :py:meth:`int.bit_length`
I want to use :py:meth:`int.bit_length`

=================
Testing in tables
=================

False [#f1]_

Seems Sphinx does not handle either hyperfootnotes in tables ?
(no supprise as footnote package used by sphinx.sty for tabulary)

=====  =====  =======
A      B      A and B
=====  =====  =======
False  False  False [#f2]_
True   False  False
False  True   False
True   True   True
=====  =====  =======

.. raw:: latex

   \clearpage
   make a last page to better check if hypertargets ok

.. rubric:: Footnotes

.. [#f1] Hello

.. [#f2] are you sure?

with latex_show_urls = 'footnote' in conf.py and also

extensions = [
#    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
#    'sphinx.ext.mathjax',
]

intersphinx_mapping = {'python': ('http://docs.python.org/3', None),
#   'numpy': ('http://docs.scipy.org/doc/numpy/', None),
#   'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None),
#   'matplotlib': ('http://matplotlib.sourceforge.net/', None)
}

[jfbu]

@tk0miya It seems I have found a way to patch LaTeX package footnote to be hyperref-compatible, at least for the footnotes as produces by Sphinx \footnote[N]{text}. Already sphinx.sty changed tabulary environment using footnote.sty but this serves nothing because table node generate automatically split footnotes with \footnotemark/\footnotetext which are not handled at all by hyperref. With latest commit to

https://github.com/jfbu/sphinx/tree/footnotes_in_topic_and_tables

I tested that it now works to remove that restriction, also when the table will be handled by threeparttable or by tabular. Already longtable was hyperref compatible.

Works fine in my brief testing ... where can I find rst sources to test more tables ? (I am not at all familar with tables in Sphinx).

[tk0miya]

Oh, I'd overlooked the topic directive. It should be able to use footnotes in the directive.
But I think enabling footnotes in contents directive is not needed. The footnotes are only labeled to section titles, not to ToC.

So we have two actions to fix this:

1. reenable footnotes on topic nodes
2. disable footnotes (and hyperlinks) on contents directive.

On the other hand, about the footnotes on tables, we have to consider carefully. We already have some troubles in representations tables; for example #1574 and #1681.
So we have to discuss that including switching table packages.
I believe there is no reason to use threeparttable. because Sphinx does not use the third part. so we can move to major table packages.

BTW, these themes are already far from the issue. Could you file new issues please?
(We already have too much issues, so I often lose sight of discussions on closed issues)

[jfbu]

done at #2461, sorry for inconvenience.