Per-document footnote numbering generates confusing latex documents

[bgeron]

Background

Currently in HTML, Sphinx gives each footnote a number. Numbers are per document (.rst file), so different HTML output files will both use [1] for the first footnote in that HTML file.

Those numbers are transferred to the LaTeX input. This is slightly unconventional in LaTeX land, since there usually footnotes are numbered per physical page, it does mostly work. In fact, it may be nice for certain technical reports to have a robust footnote numbering: it can make it easier to refer in conversation to a given footnote.

The problem

However, it only works in the manual documentclass, not in howto. It works in manual because each section will start on a new page, and so the footnotes on a page only come from one section. The howto documentclass instead allows multiple sections on one page, and so you can get footnote 2 from a section before footnote 1 from the next section.

Worse, this can lead to two footnotes with the same number on the same page.

I have made a GitHub repository with a simple proof of concept. You can view the full PDF output here, or a screenshot below.

Environment info

• OS: Ubuntu 16.04.2
• Python version: 3.5.2
• Sphinx version: 1.5.5 via pip3

Proposed approach

I think it would be nice to be able to configure this; particularly because I don't use howto but document classes for scientific articles. Maybe configure it via latex_elements, even though it's not really a string-like option. Alternatively we might configure it using the tuples in latex_documents, but we wouldn't want to extend that too much either.

What do you think?

[jfbu]

Thanks for the report and the project showing the issue. Indeed footnote numbering is reset at each rst source. Independently of the collision of numbers in case sections are short enough this also brings a discrepancy between one big rst or multiple ones. Getting footnote 2 of section A before footnote 1 of section B is not so much a problem, imho. But LaTeX output (table of contents) is generally independent on how the contents is spread across rst files (in a way it is like singlehtml), because it generally produces a single document (depending on latex_documents). I agree there should be a setting forcing continuous numbering without reset of footnotes. @tk0miya any idea about this ?

[jfbu]

regarding:

This is slightly unconventional in LaTeX land, since there usually footnotes are numbered per physical page, it does mostly work.

the standard classes (article, report, book) do not reset footnote numbering per physical page. But report and book do reset the footnotenumbering per chapter.

The problem you point out is that with howto which uses \section as top level, the standard LaTeX has continuous footnote numbering throughout the document, but Sphinx resets the numbering according to the various pieces from individual rst files.

[bgeron]

But report and book do reset the footnotenumbering per chapter.

Interesting, I didn't know!

[bgeron]

Ping @tk0miya.

@jfbu wrote:

I agree there should be a setting forcing continuous numbering without reset of footnotes. @tk0miya any idea about this ?

[tk0miya]

sorry for late. +1 for adding new configuration.

Now Sphinx no longer control the footnote numbers by default.

• footnotes having specified numbers (ex. [1]): use the specified number as is.
• footnote having no specific numbers (ex. [#]): a footnote number is assigned by docutils per document. Sphinx simply use it.

Note: Sphinx does not uses a footnote counter on LaTeX. So this behavior might not be related with standard classes.

What about this?

# renumbering footnotes by specific sectioning unit
#  all: whole of document
#  part: reseted at each part
#  chapter: reseted at each chapter
#  section: reseted at each section
#  document: reseted at each document (source file)
#  None: not renumbered (default)
latex_renumbering_footnotes = ['all'|'part'|'chapter'|'section'|'document'|None]

[bgeron]

Not exactly what I meant. I want footnotes numbered per page for my project, and I think some other people want footnotes per chapter for Sphinx's manual documentclass. I don't know if there's demand for all the alternatives you propose.

• Footnotes per page are clear, but only really work when there is only ever one reference.
• Footnotes per chapter references to the same footnote from multiple places, but they only really work when there are no references across chapters, and only when every page contains at most one chapter.

In LaTeX, there are documentclasses that have either style, for instance article for the former and report for the latter.

The default LaTeX numbering is fine, but by default Sphinx forces the footnote numbers to match the HTML version. So I would propose to have the option something like:

# Whether to use per-document footnote numbers
#   latex:
#       Footnote numbers are determined by LaTeX. For documentclass
#       manual, new chapters re-start numbering again from 1;
#       for howto, footnotes are numbered per page from 1.
#   document:
#       Footnote numbers come from the document, so that they match
#       numbers in other outputs such as HTML; this may look slightly
#       less consistent.
#   auto: (default)
#       For manual, as in 'document'; for howto, as in 'latex'.
latex_footnote_numbering = ['source'|'latex'|'auto']

In document mode, we would keep generating \begin{footnote}[1234]...\end{footnote} as we do now; for latex mode, we would generate \begin{footnote}...\end{footnote}.

Implementing this option would not require much work I think; currently the behaviour is as document; for latex essentially we have to stop overriding footnote numbers. It seems overkill to re-number in Sphinx itself, because LaTeX can already do that for us.

I'm not completely sure what we should do when a footnote has multiple references in latex mode, probably raise a warning.

[jfbu]

demand for all the alternatives you propose.

Footnotes per page are clear, but only really work when there is only ever one reference. Footnotes per chapter references to the same footnote from multiple places, but they only really work when there are no references across chapters, and only when every page contains at most one chapter. In LaTeX, there are documentclasses that have either style, for instance article for the former and report for the latter

Hi, peripheral to this discussion, I just want to point out that there is to the best of my knowledge no standard LaTeX document class which numbers footnotes per page. This is certainly not the case of the article class, and there is no option to achieve that with this class.

There are LaTeX solutions though:

https://tex.stackexchange.com/questions/1656/footnote-counter-would-like-to-restart-from-1-each-page

https://tex.stackexchange.com/a/6753

Best, (will return to this when I get time)

[jfbu]

Also this:

http://www.tex.ac.uk/FAQ-footnpp.html

however this is only theoretical reference for general LaTeX background

because currently Sphinx latex writer enumerates as you said beforehand; besides we use a custom footnote package to achieve things which are not otherwise obtainable via LaTeX and other footnote packages

[bgeron]

Apologies, I was wrong. Apparently Sphinx's current mechanism tricked me well into thinking that per-page was normal :)

I don't really care particularly about per page numbering, just that it is consistent. So something like:

#   latex:
#       Footnote numbers are determined by LaTeX. For documentclass
#       manual, new chapters re-start numbering again from 1;
#       for howto, footnotes numbering continues throughout the PDF.

[jfbu]

I will return to this issue, but for time being you can add this to your conf.py

latex_elements = {
    'preamble': r'''
\makeatletter
\def\FNH@footnoteenv@i[#1]{\FNH@footnoteenv}
\def\FNH@footnotetextenv@i[#1]{\FNH@footnotetextenv}
\makeatother
''',
}

and it should make LaTeX ignore the footnote numbers hard-coded in the tex file.

This works in simple case, and might be enough for your use case. Needs sufficiently recent Sphinx, I tested it briefly with 1.6.1.

The effect for 'howto' documents is continuous numbering independently of how the rst sources are split, and for 'manual' documents the footnote numbering is reset per chapter. This is the "LaTeX" mode in your terminology. I have not tested thoroughly as this would need more time I can afford now to make sure all fringe cases work well (footnotes from tables, parsed literal blocks, interactions with footnotes being assigned numbers by user in source file, etc..)

[jfbu]

Actually you need a bit more

\makeatletter
\def\FNH@footnoteenv@i[#1]{\FNH@footnoteenv}
\def\FNH@footnotetextenv@i[#1]{\FNH@footnotetextenv}
\def\sphinxfootnotemark [#1]%
   {\ifx\thepage\relax\else\protect\spx@opt@BeforeFootnote
                             \protect\footnotemark\fi}%
\makeatother

I noticed an issue with a footnote from inside a caption of a code-block and there are some complaints by hyperref. It might be enough for your use case for the time being.

[bgeron]

Much appreciated @jfbu! If I find any problems with footnotes I'll let you know, though I must admit I only tend to use footnotes from the main text.