Footnotes are not positioned correctly

[gAmUssA]

I trying to use footnotes with pdf like

in pdf it doesn't display correctly

Thanks

[gAmUssA]

Not sure but maybe it relates to #83

[mojavelinux]

You should be able to use cross references inside a footnote (keep in mind that footnotes display inline currently). Thus, you can do something like:

SPI footnote:[More information about the SPI can be found in <<chapter_13#,Chapter 13>>

I recommend using an explicit title in the xref as I have done, though the implicit title should work when creating the PDF.

[jmini]

In my opinion this has nothing to do with references but with the fact that footnotes display inline currently:

Example:

Just the Java code.footnote:[
With the exception of the [filename]+plugin.xml+ and [filename]+MANIFEST.MF+ files required for Eclipse plugins.
]. 
Developers preferring to write the necessary code manually, may do so. 

PDF:

HTML:

Footnotes looks much better in the HTML output because they are not inlined.

[mojavelinux]

We inlined the footnotes as a temporary, short term solution. The long term solution is to put them at the bottom of page or chapter. The challenge is that we have to reserve space for the footnotes, but we have to know how much space we need and on which page. Thus, we have to hook into the page transition, which turns out to be a lot of work. This is where PDF gets really hard :/

[mojavelinux]

If we use the end of chapter, things get a lot simpler (but still some work).

[mojavelinux]

The way Prawn works, it makes it very difficult to figure out how to reserve space for the footnotes at the bottom of the page. First, we have to know if there are any footnotes on the current page. Then, we have to calculate how many lines we need to render those footnotes. If we need a lot of lines, there's a chance that it pushes a paragraph off the page. If that paragraph was the source of a footnote, then we have less footnotes and we need less space. It gets pretty complicated pretty quickly.

@graphitefriction suggested that once we have at least one footnote on a page, we reserve a fixed amount of space and reduce the font size of the footnotes to fit in that space. I think this is how the DocBook toolchain works (but we should double check).

The easiest solution is to put the footnotes at the end of the chapter (which is a standard place for them to go, just not always the most convenient).

[mojavelinux]

If that paragraph was the source of a footnote, then we have less footnotes and we need less space.

We may just let this be an edge case where we end up with more space for footnotes than needed. At least we are able to fit the footnotes.

[mojavelinux]

Related to #73.

[rlopez133]

@mojavelinux Definitely a difficult task to fix indeed. What about instead of trying to automatically figure out spacing, statically add space to the footer as the # of footnotes are added to page by X up to only Y # of footnotes. If additional footnotes reside on page, move footnotes to following page. For example, say I have 6 footnotes on a page. However, you have decided that per page the most footnote space I'll allocate to a page is X which would only fit 5 footnotes. The 6th footnote would just be moved to the following page. Also the edge case where it pushes a paragraph containing footnotes to following pg, then the footnotes should reside on that new page not the previous page.

In the end, all I'm trying to say is maybe its better to have the user help define how many footnotes they need versus trying to automagically render all the info. :) It at least would be way better than inline footnotes IMO.

[mojavelinux]

Thanks for the input @rlopez133! As it turns out, the exploration I did to implement inline images uncovered a technique to solve the footnote calculation problem. In short, I have access to the text layout, at which point I can detect a footnote and push in the bottom margin by the amount of space the footnote needs. If there isn't enough space, I can force it to go to the next page. In theory, this should work. What's left is to try it.

[rlopez133]

Let me know if you need someone to test it out :)

[mojavelinux]

Count on it!

[nathany]

I just added footnotes and ran into this issue with them rendering inline in PDFs.

They appear at the end of the document (a chapter) when using the AsciiDoctor Chrome extension.

[mojavelinux]

Putting them at the end of the document / chapter would be the easiest way, and probably the first step. But in a page-oriented layout like PDF, the correct place to put them is at the bottom of the page. That requires some tricks, but as I mentioned above, I think I sorted out a creative solution. Prawn is a bit stiff in this area, so it requires that we be creative. (It would be nice if Prawn had flexible regions, but it doesn't really abstract to that level).

[nathany]

Either would be an improvement over having the footnotes inline, though the bottom of the page makes sense. For now I'm going to comment them out, because this just doesn't look good.

Thanks.

[nathany]

How easy would it be to have the footnotes appear at the end of the chapter?

I only have a few footnotes right now, so it's probably easiest if I emulate that behaviour by hand. I can just do some superscript numbers and regular text at the end.

[mojavelinux]

Easy enough that I'm going to split this issue into two parts. First I'm going to implement the end of the chapter approach. I'll commit that as a short-term workaround. Then I'll dig into getting them at the bottom of the page (perhaps using an option to control the placement).

[mojavelinux]

This is one of the next things I'll work on.

Putting footnotes inline wasn't really intended for production output. That was more to remind us that they weren't being handled and so we didn't drop content. More like debugging output.

[nathany]

Thanks Dan. I can also help test it out.

[getreu]

For scientific use of asciidoctor-pdf bottom footnotes are indispensable. As this feature is not yet available in asciidoctor-pdf-1.5.0.alpha.9 another workaround could be using asciidoctor-latex <file>.adoc or asciidoctor -b docbook <file>.adoc.

[rasusmilch]

Noticed this myself trying to write an archival document. I figure that plain ASCII is the way to go, and seems ASCIIDoc is a nice implementation. I agree that footnotes at the bottom of the page is indispensable. This PDF renderer is much nicer than the others, so I appreciate the work done.

I look forward to at least the end-of-chapter workaround. How can I help?

[mojavelinux]

I pretty much know what I have to do, so it's just a matter of doing it. I'll try to prototype soon so that I can see what help is needed. Usually, I discover stuff in the first few minutes of hacking.

[rasusmilch]

@mojavelinux You know what you need to do for end notes or bottom-of-page footnotes? Obviously I'm more excited about the later, but that's good news regardless.

[mojavelinux]

If someone wants to try to solve this problem, I'd be happy to assist. I just have too many things on my plate to dedicated time to it right now.

[Cellebyte]

@mojavelinux, how far is your progress at putting endnotes on the last page of a chapter?

[bcourtine]

Hello.

I opened a PR for a partial fix to this footnotes problem: #1010

[mojavelinux]

@bcourtine Thanks for submitting that PR! That provided me with the raw materials for a full solution. Stay tuned for a revised proposal.

[mojavelinux]

So the logic will be that the footnotes will go at the end of the chapter for a book (or the end of the document if there are any remaining) and the end of the document for an article.

One open question is whether the footnote definition should be duplicated if the reference to the footnote appears in multiple chapters. For now, I think we'll just link to where the footnote was original defined. If that feels to unnatural, we can think about how to duplicate it.

[mojavelinux]

Please test PR #1016. I believe you will be pleased. Thanks again to @bcourtine for getting the ball rolling on this!

[mojavelinux]

This is solved in master in so far as we made the end notes.

I've though long and hard about whether it's possible to make bottom-of-the-page footnotes. While I have better ideas now about how it might work, I simply don't have the time it would take to implement a solution. Regardless, that will need to be tracked in a separate issue.

[rv0]

Did any "bottom-of-the-page footnote" efforts happen after this?

[mojavelinux]

No, it's not possible (unless someone can prove me wrong). We'll be sticking with the current solution (unless someone comes forward to show that it's possible to do it another way).

[arjantijms]

No, it's not possible (unless someone can prove me wrong).

Just wondering, but if it's not possible, how do tools like FrameMaker and LaTeX accomplish this? Would it not be possible to study the LaTeX source code?

[mojavelinux]

It's not possible because of how Prawn is implemented. It writes directly to the PDF stream with no way to rollback. Tools like FrameMaker and LaTeX use multiple passes of trial and error until all the content fits. Prawn just can't do that. It would require implementing Prawn (and pdf-core) from scratch with a different architecture.

[mojavelinux]

We will not be implementing footnotes in this converter. That will be a key requirement for the browser-based PDF converter, currently called asciidoctor-pdf.js.

[arjantijms]

Interesting. I can't see that it isn't possible with the current engine, I thought you meant it wasn't possible in general (for PDF).

How will the browser-based PDF converter work? Render everything into HTML first, and then generate PDF from that?

[mojavelinux]

I can't see that it isn't possible with the current engine, I thought you meant it wasn't possible in general (for PDF).

Exactly. Thanks for pointing that out. I'm specifically talking about a limitation of the tech stack in this converter.

Render everything into HTML first, and then generate PDF from that?

Correct, though it's all in memory / via an API. We're using browser tech as the layout engine. I'll post more details once the 1.5.0 and 2.0.0 releases are out. Though you can read up on it here: https://github.com/Mogztter/asciidoctor-pdf.js/

[mishka88ru]

Hi @mojavelinux
May be it will be easier if a long footnote(s) will be allowed to overflow to the next page?
Like here, note arrows >>>

[mojavelinux]

We're sticking with putting footnotes at the end of chapter or article. The PDF generator we use simply cannot easily accommodate more advanced layouts.

[radekosmulski]

@mojavelinux is there a way to put the footnotes at the end of the chapter at the bottom of the page? Right now they immediately follow the text and it does not look great, not sure what would be a good solution to go about this.

[vog]

As this issue is closed, I assume it would be better to open a separate issue for this new problem.

[mojavelinux]

Please open a separate issue with this idea. It might be possible to vertically align the footnotes at the bottom of the last page of the chapter by using the dry run technique. We could at least give it a try.

[radekosmulski]

Thank you very much for your replies @vog and @mojavelinux! Opened a new issue #1833