5

I've got a rather large asciidoc document that I translate dynamically to PDF for our developer guide. Since the doc often refers to Java classes that are documented in our developer guide we converted them into links directly in the docs e.g.:

In this block we create a new 
https://www.codenameone.com/javadoc/com/codename1/ui/Form.html[Form] 
named `hi`.

This works rather well for the most part and looks great in HTML as every reference to a class leads directly to its JavaDoc making the reference/guide process much simpler.

However when we generate a PDF we end up with something like this on some pages:

Footnote hell

Normally I wouldn't mind a lot of footnotes or even repeats from a previous page. However, in this case the link to Container appears 3 times.

I could remove some of the links but I'd rather not since they make a lot of sense on the web version. Since I also have no idea where the page break will land I'd rather not do it myself.

This looks to me like a bug somewhere, if the link is the same the footnote for the link should only be generated once.

I'm fine with removing all link footnotes in the document if that is the price to pay although I'd rather be able to do this on a case by case basis so some links would remain printable

Shai Almog
  • 51,749
  • 5
  • 35
  • 65
  • 1
    I don't see it as a bug: according to the XSL-FO recommendation a footnote is simply an object which produces one or more areas in the output, and the fact that the footnote text is the same as another one is completely irrelevant; there is not a "conditional footnote" object. Unfortunately, automatically avoiding "duplicate" footnotes while generating the FO file is impossible, as it would require knowing where page breaks will be. I don't know if it's a feasible option for you, but what about creating clickable links instead of footnotes with the URL? – lfurini Jan 25 '16 at 20:30
  • Then I'm guessing its an issue for asciidoc to hide. That's exactly what I'm asking... Notice that I just used the hyperlink syntax of asciidoc. Is there a way to disable the footnote for a hyperlink at least for some of the cases in asciidoc? – Shai Almog Jan 26 '16 at 03:21
  • AFAIK, in order to produce PDF output, AsciiDoc converts its source text to DocBook XML and then uses the DocBook XSLT stylesheets to transform that to XSL-FO. I think you would need to either customize the XSLT stylesheets or somehow post-process the intermediary DocBook XML or XSL-FO files. – mzjn Jan 31 '16 at 14:05
  • The Antenna House FO processor (not free) has an extension that seems to do what you are looking for: http://www.antennahouse.com/xslfo/axf4-extension.htm#axf.suppress-duplicate-footnote. – mzjn Jan 31 '16 at 14:07
  • We're an open source project, although I don't mind paying for software that seems a bit excessive! I can pre process the asciidoc files and just remove some of the links based on some logic. I'd rather not do that. – Shai Almog Jan 31 '16 at 17:59

2 Answers2

2

Adding these two parameters in fo-pdf.xsl remove footnotes: 

<xsl:param name="ulink.footnotes" select="0"></xsl:param>
<xsl:param name="ulink.show" select="0"></xsl:param>

The first parameter disable footnotes, which triggers urls to re-appear inline.
The second parameter removes urls from the text. Links remain active and clickable.

Non-zero values toggle these parameters.

Source:
http://docbook.sourceforge.net/release/xsl/1.78.1/doc/fo/ulink.show.html

seinecle
  • 10,118
  • 14
  • 61
  • 120
1

We were looking for something similar in a slightly different situation and didn't find a solution. We ended up writing a processor that just stripped away some of the links e.g. every link to the same URL within a section that started with '==='.

Not an ideal situation but as far as I know its the only way.

David Cohen
  • 429
  • 2
  • 4
  • Thanks, not what I want to pick as the answer as I was hoping for something in asciidoc but due to the lack of answers I'm guessing this is as close as possible. If something better comes along I'll switch that to be the accepted answer. – Shai Almog Feb 02 '16 at 18:27