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

Footnotes are not positioned correctly #85

Open
gAmUssA opened this Issue Jan 12, 2015 · 51 comments

Comments

Projects
None yet
@gAmUssA
Copy link

gAmUssA commented Jan 12, 2015

I trying to use footnotes with pdf like

image

in pdf it doesn't display correctly

image

Thanks

@gAmUssA

This comment has been minimized.

Copy link
Author

gAmUssA commented Jan 12, 2015

Not sure but maybe it relates to #83

@mojavelinux

This comment has been minimized.

Copy link
Member

mojavelinux commented Jan 13, 2015

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

This comment has been minimized.

Copy link

jmini commented May 6, 2015

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:

pdf output

HTML:

html output

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

@mojavelinux

This comment has been minimized.

Copy link
Member

mojavelinux commented May 6, 2015

@mojavelinux

This comment has been minimized.

Copy link
Member

mojavelinux commented May 6, 2015

@mojavelinux

This comment has been minimized.

Copy link
Member

mojavelinux commented May 11, 2015

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

This comment has been minimized.

Copy link
Member

mojavelinux commented May 11, 2015

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

This comment has been minimized.

Copy link
Member

mojavelinux commented May 24, 2015

Related to #73.

@rlopez133

This comment has been minimized.

Copy link

rlopez133 commented Jun 11, 2015

@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

This comment has been minimized.

Copy link
Member

mojavelinux commented Jun 11, 2015

@rlopez133

This comment has been minimized.

Copy link

rlopez133 commented Jun 11, 2015

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

@mojavelinux

This comment has been minimized.

Copy link
Member

mojavelinux commented Jun 11, 2015

Count on it!

@nathany

This comment has been minimized.

Copy link

nathany commented Oct 2, 2015

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

This comment has been minimized.

Copy link
Member

mojavelinux commented Oct 2, 2015

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).

@mojavelinux mojavelinux added the next label Oct 2, 2015

@nathany

This comment has been minimized.

Copy link

nathany commented Oct 2, 2015

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.

footnotes

Thanks.

@nathany

This comment has been minimized.

Copy link

nathany commented Oct 2, 2015

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

This comment has been minimized.

Copy link
Member

mojavelinux commented Oct 8, 2015

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 comment has been minimized.

Copy link
Member

mojavelinux commented Oct 8, 2015

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

This comment has been minimized.

Copy link

nathany commented Oct 8, 2015

Thanks Dan. I can also help test it out.

@mojavelinux mojavelinux modified the milestones: v1.5.0.beta.1, v1.5.0 Oct 14, 2015

@getreu

This comment has been minimized.

Copy link

getreu commented Oct 16, 2015

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

This comment has been minimized.

Copy link

rasusmilch commented Dec 30, 2015

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

This comment has been minimized.

Copy link
Member

mojavelinux commented Dec 30, 2015

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

This comment has been minimized.

Copy link

rasusmilch commented Dec 30, 2015

@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

This comment has been minimized.

Copy link
Member

mojavelinux commented Jan 13, 2017

I've been using something similar in the theming guide. I use square brackets around the number (to match that style) and use an ordered list to refer to the numbers instead of repeating the superscript. But basically it's the same idea. But it has allowed me to think a bit more about where footnotes can go in the future.

@mordae

This comment has been minimized.

Copy link

mordae commented Jan 30, 2017

bounty

@narimiran

This comment has been minimized.

Copy link

narimiran commented Jan 28, 2018

I just tried to make a pdf and footnotes are still inline.

Any update/progress with this?

@mojavelinux

This comment has been minimized.

Copy link
Member

mojavelinux commented Feb 3, 2018

Not yet, but I think about it often. There's absolutely zero chance we'll move forward with implementation until we nail down the expected behavior in detail. So that's what has to happen first.

The problem is, I can't figure how to know how much space to reserve for a bottom of the page footnote, and whether reserving that space knocks the footnote anchor to the next page. Other engines are able to do this because the essentially try multiple times. But we only have a single pass, so it's extraordinarily complicated in my head.

The simple solution, of course, is just to write all the footnotes on the last page (or last page of the chapter). It's the bottom of the page footnotes that are tricky. But that's part of establishing expectations.

@vog

This comment has been minimized.

Copy link

vog commented Feb 6, 2018

I believe the "simple solution" would be a great start, because although not perfect, it would serve the need just fine for 95% of the use cases.

The big problem with asciidoctor-pdf is that footnotes appear inline within the text, which renders them essentially unusable and means you can't use footnotes at all in your document. Every solution that moves them "away" is already a huge improvement.

@narimiran

This comment has been minimized.

Copy link

narimiran commented Feb 6, 2018

If the simple solution is "at the last page of the chapter", this would be indeed good enough!

@AlexanderZobkov

This comment has been minimized.

Copy link
Contributor

AlexanderZobkov commented Feb 6, 2018

Agree. For example, a quite popular digital library uses this approach (endnotes instead of footnotes):

image

@mordae

This comment has been minimized.

Copy link

mordae commented Feb 7, 2018

I would be content with end notes as well ($25 bounty still pending) but would prefer a separate section at the end of the document, with a custom heading. Thanks for your hard work!

@gtebbutt

This comment has been minimized.

Copy link

gtebbutt commented Feb 8, 2018

A major +1 from me on the endnote format. Especially given the similarity to the HTML output, I think that would actually be the preferred option in many cases.

@nathany

This comment has been minimized.

Copy link

nathany commented Feb 10, 2018

$50 bounty still pending from me, and I would also be quite happy with endnotes.

@popdjnz

This comment has been minimized.

Copy link

popdjnz commented Mar 2, 2018

Will match the current $50 bounty for the Q&D end-notes solution. Nothing fancy, just move the footnotes to the end of the chapter for now.

Also, here's a suggestion for an (admittedly dumb) but maybe workable, intermediate single-pass end-of-page solution:

Using the default theme, pre-compute an average for height_of_footnote_line / characters_per_line based on random input. This is some constant that then gets hard-coded. Then, multiplying this by the character length of each footnote, taking ceil(), and summing yields an approximation of the vertical space needed at the bottom of the page for the footnotes that have been encountered so far. Pad this by by something reasonable, say 10%; allow the user to specify a multiplier anywhere in the asciidoc; and call it a day.

When the footnotes occupy too much, or too little, space, the user can update directly in the asciidoc by using their own multiplier.

I'd be more than happy with a solution like this that required me to tweak the final output as an interim single-pass solution. Ultimately, though, I don't see how you get a really clean solution without either doing multiple passes, or having some sort of separate buffer where you can pre-render the footnotes and know the exact page height required.

@mojavelinux

This comment has been minimized.

Copy link
Member

mojavelinux commented Mar 19, 2018

Thanks for these thoughtful suggestions, @popdjnz. That moves me closer to a solution. I'm pretty sure this is how the DocBook toolchain works. It seems to work within a fixed amount of space. It's still tricky in our case since the footnote can fall off the page just by putting the space there...which would be find if we had a layout engine in Prawn...but we don't. So it will still take some trial and error to get something that works.

Either way, I agree that the path to a solution has two steps. The first is to make endnotes. I agree these should go under some sort of heading. Then, in a follow-up step, we can slide them into a footer region.

Unfortunately, I just don't have the time to do this right now. But since there's lot of interests and bounties, I'll do my best to schedule time for it as soon as I can.

@jerome-pouiller

This comment has been minimized.

Copy link

jerome-pouiller commented Mar 21, 2018

Currently, I have a configuration with footnotes placed at bottom of the pages. I use CSS Paged Media specification. Unfortunately, only a few "browsers" implement it. I have to use specialized tools that generate PDF from HTML and implement CSS Paged Media specification (princeXML, pdfreactor, antennahouse, ...).

Note that, some people try to implement parts of CSS Paged Media specification in Javascript for browsers that don't support it.

My suggestion is to add an option to asciidoctor to generate footnotes compliant with CSS Paged Media and delegate the hard work to browsers (or javascript). I think that it is not really possible to implement this feature correctly without browser support.

Information about footnote usage is described in PrinceXML documentation. Basically, we need to define a CSS class with attribute float: footnote:

.fn { float: footnote; }    

Next, footnote have to be defined inline with <span class="fn">footnote content</span>. Unfortunately, current footnote:[content] syntax since it does not place footnote inline in HTML result. So I have to use an alternative way. Something like [.fn]*Footnote content*.

@Eiskasten

This comment has been minimized.

Copy link

Eiskasten commented Mar 27, 2018

Is the asciidoctor-fopub project useful for reserving space? Because asciidoctor-fopub is able to do it. So maybe code from that project can be used, or at least the technique.

@mojavelinux

This comment has been minimized.

Copy link
Member

mojavelinux commented Mar 27, 2018

@PraeluceantBoreus useful for some ideas, perhaps, but the problem really comes down to the fact that Opal cannot undo once it writes to a page. In other words, there isn't a separate layout step, which is something Apache FO has. We work around this problem in many cases by using a scratch document, but that doesn't always tell us what we need to know and it's very expensive time-wise.

@mojavelinux

This comment has been minimized.

Copy link
Member

mojavelinux commented Oct 28, 2018

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

This comment has been minimized.

Copy link

Cellebyte commented Feb 12, 2019

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

@bcourtine

This comment has been minimized.

Copy link

bcourtine commented Mar 22, 2019

Hello.

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.