Asciidoctor :: Discussion

PDF output issues.

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

2 messages Options

Jeremie Bresson

May 06, 2015; 11:04am

PDF output issues.

I have started to show the PDF files obtained with Asciidoctor and some issues were raised.
We are coming from a LaTeX toolchain.

PDF output produced with LaTeX: scout_intro.pdf
Corresponding output produced with Asciidoctor: scout_intro.pdf

== xref links in the PDF are broken.
Clicking on a figure reference jumps to the figure with latex (asciidoctor doesn't work)
Click on section refs does not jump to reference section with asciidoctor (works with latex output)
See:
https://github.com/asciidoctor/asciidoctor-pdf/issues/56
https://github.com/asciidoctor/asciidoctor-pdf/issues/83

== image Scaling
Asciidoctor output has uniform scaling of figures (latex output has figure specific scaling)
Is something planned? I could not find anything.

== Page breaks before new chapter
Asciidoctor does not have page breaks for chapters, etc. (eg. New chapter starts anywhere on page, whereas new chapter with latex starts on a new page, same goes for apendices)
https://github.com/asciidoctor/asciidoctor-pdf/issues/74

== footnotes
Full footnote text appears in asciidoctor output, latex puts it to the footer
https://github.com/asciidoctor/asciidoctor-pdf/issues/85

== title page
We were used to include a single pdf page as first page of our document.
https://github.com/asciidoctor/asciidoctor-pdf/issues/66

I will let you know if additional issues are raised.
I will comment on one of the other issue referenced in this list.

mojavelinux

May 11, 2015; 5:46am

Re: PDF output issues.

Administrator

Jeremie,

This is essentially our burn-down list for Asciidoctor PDF (on the road to 1.5.0).

The good news is that we understand these issues well. The bad news is that we haven't fixed them yet...but we're starting to make progress again.

Jeremie Bresson wrote:

== xref links in the PDF are broken.
Clicking on a figure reference jumps to the figure with latex (asciidoctor doesn't work)
Click on section refs does not jump to reference section with asciidoctor (works with latex output)
See:
https://github.com/asciidoctor/asciidoctor-pdf/issues/56
https://github.com/asciidoctor/asciidoctor-pdf/issues/83

The references to sections is now fixed in git master. I know what to do to fix it for other blocks. Now I just need to apply the code. It's next on my list for Asciidoctor PDF.

== image Scaling
Asciidoctor output has uniform scaling of figures (latex output has figure specific scaling)
Is something planned? I could not find anything.

There is another recent mailinglist post on this topic. http://discuss.asciidoctor.org/Unit-of-measure-for-image-dimensions-td3040.html

In short, the AsciiDoc ecosystem has never properly addressed this issue (to the extent it's solved in LaTeX), so now it's time to face it.

See:

* https://github.com/asciidoctor/asciidoctor-pdf/issues/76

NOTE: You can set the width of the image as a percentage width of the page using the scaledwidth attribute. See http://discuss.asciidoctor.org/How-can-I-scale-images-in-relative-size-percentage-td902.html.

== Page breaks before new chapter
Asciidoctor does not have page breaks for chapters, etc. (eg. New chapter starts anywhere on page, whereas new chapter with latex starts on a new page, same goes for apendices)
https://github.com/asciidoctor/asciidoctor-pdf/issues/74

I want to clarify that page breaks do occur per chapter (level-1), but they don't occur per part (level-0). The best solution is likely to make this customizable via the theme, because it's one size will not fit all.

== footnotes
Full footnote text appears in asciidoctor output, latex puts it to the footer
https://github.com/asciidoctor/asciidoctor-pdf/issues/85

This is the hardest issue to solve. 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. 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). I explained the situation in more detail in the issue.

== title page
We were used to include a single pdf page as first page of our document.
https://github.com/asciidoctor/asciidoctor-pdf/issues/66

We do have an API hook to define your own cover page. See https://github.com/asciidoctor/asciidoctor-pdf/blob/master/lib/asciidoctor-pdf/converter.rb#L1007.

The method currently supports using a full page image. We could detect if the file extension is .pdf and instead insert the PDF page. I've since filed a issue and implemented it. See https://github.com/asciidoctor/asciidoctor-pdf/issues/113

You can now design your cover page however you want, save it as PDF and import it using:

----

= Document Title

:front-cover-image: image:front-cover.pdf[]

----

The file will be resolved just like any other image.

If you want to customize the title page, there's also an API hook for that. See https://github.com/asciidoctor/asciidoctor-pdf/blob/master/lib/asciidoctor-pdf/converter.rb#L974.

Overriding the PDF converter isn't as elegant as other extensions atm. You basically have to monkeypatch the code. But at least there is a method to override. It does need to be documented though.

Thanks for all your feedback!!

Cheers,

-Dan

Dan Allen | http://google.com/profiles/dan.j.allen