Export to pdf is not rendering math expressions and pictures

[jfernandz]

Description

When you use the export to pdf option math expressions and pictures are not rendered.

System Information

OS: Arch Linux 5.3.13 kernel version
VSCode version: 1.40.2
Asciidoctor extension: v2.7.7

To Reproduce

Steps to reproduce the issue:

1. Create an .adoc example document with a MWE like this one

:stem: latexmath

= Table example with latex syntax

== Testing

I'm also testing a few admonitions

[NOTE]
.First admonition
Here you have a note. 
====
.Table inside a block
[cols=".^,<.^a,>.^a"]
|===
| (Test) \[X_nY_m\]
| * \(X\) with \(i\)
* \(Y\) with \(j\)
| [cols=">.^"]
!===
! FOO ! BAR
!===
|===
====

IMPORTANT: Here a second admonition with no title.

.Image
image::./picture.jpg[Picture!]

2. Use ctrl+shift+p to open the command palette and choose AciiDoc: Export document as PDF
3. Open the generated pdf file, you should not see properly rendered the math expressions an the picture.

Screenshots & Files

Additional Context

Add any other context about the problem here.

[danyill]

I think there is two unrelated things here.

The lack of embedding images is an upstream issue, see wkhtmltopdf/wkhtmltopdf#2687. To work around this I believe if you set data-uri on your document by including :data-uri: in the document header you will see images (I do in my testing). This embeds the data directly into the html file which is handled better by wkhtmltopdf.

The lack of equations seems to be a problem with SSL negotiation in wkhtmltopdf. I could reproduce this issue in wkhtmltopdf 0.12.4 (with patched qt) but not when I symlinked it to a local install of wkhtmltopdf 0.12.5.

@joaompinto can we update to 0.12.5? I'm not sure what process we use for retrieving and updating these binaries.

Note that the other option is to use asciidoctor-pdf (the Ruby version) in conjunction with e.g. asciidoctor-mathematical which will render equations and embed images.
Within a short time I think we will be able to support asciidoctor-pdf (the Javascript version) which is similar to wkhtmltopdf (but, I think likely better for Asciidoc users).

I might look into doing a PR to provide :data-uri: if wkhtmltopdf is used for the conversion at some stage.

[danyill]

Note that using asciidoctor-pdf (the Javascript version) is now possible that stdin support has been added. It uses the same command line arguments as its Ruby cousin and is (in that sense) a drop-in replacement.

I can confirm that both images and math work just fine with it out of the box and IMHO although it is still in alpha it is looking really good (thank you @Mogztter).

Within the npm ecosystem, this can be installed using npm i -g @asciidoctor/core asciidoctor-pdf. For more information see the README. Then all that is necessary is to ensure the binary path is correct in the extension settings and that the preference is selected to use asciidoctor-pdf.

@joaompinto we could consider bundling or adding this "on demand" at some stage. Bundling is attractive except that it would increase the extension filesize significantly because of the Chrome binary. I'm not sure if it's possible with a vs-code extension to load a node package on demand (like we do with wkhtmltopdf) but if we could that would be really neat.

[ggrossetie]

An intermediate step could be to configure the binary path to chrome? I mean it would require some changes to asciidoctor-pdf but it won't be necessary to manually install asciidoctor-pdf.
We could even try to guess the chrome installation path depending on the OS so it could potentially work out-of-the-box. I believe that Puppeteer is already doing something like that...

Do you think it's worth it?

[joaompinto]

The binaries are download from https://github.com/asciidoctor/asciidoctor-vscode/tree/master/wkhtmltopdf-bin (using raw), but there is no "upgrade" logic :(

[joaompinto]

Unfortunately there are no generic upstream binaries for 0.12.5 https://github.com/wkhtmltopdf/wkhtmltopdf/releases.

The "Export to PDF" option on the editor is expected to be a quick/simple export option, it does not need to support all the bells & whistles of a well tuned PDF generator.

What would we lose on switching to asciidoctor-pdf (JS) as it stands now ?

[danyill]

@joaompinto:

Unfortunately there are no generic upstream binaries for 0.12.5 https://github.com/wkhtmltopdf/wkhtmltopdf/releases.

Thanks -- Yes, the build infrastructure seems to be somewhat inconsistent/broken. I also looked at https://builds.wkhtmltopdf.org/ which is even more patchy.

It looks like there is some ongoing work in automating builds (see wkhtmltopdf/wkhtmltopdf#4578 (comment)).

I don't think we want to get into compiling binaries for another project to support this feature.

@Mogztter:

An intermediate step could be to configure the binary path to chrome? I mean it would require some changes to asciidoctor-pdf but it won't be necessary to manually install asciidoctor-pdf.
We could even try to guess the chrome installation path depending on the OS so it could potentially work out-of-the-box. I believe that Puppeteer is already doing something like that...

Do you think it's worth it?

Puppeteer suggests keeping Chromium versions in lock-step and provides no guarantee that things will work. But maybe they would work well enough for our use case?

I worry that we'll end up trying to follow user's individual installation/environment issues or other incompatibilities. I guess we could try it and see?

I don't think the size of asciidoctor-pdf.js is a problem unless we bundle it into this extension directly. The extension is currently 8.8 Mb. Puppeteer is 118 Mb and a zipped node_modules folder for asciidoctor-pdf.js is 146 Mb compressed. Compressed wkhtmltopdf is about 15-17 Mb.

I think it would be pleasing to re-use the "download on demand" logic in this extension with an asciidoctor-pdf binary which looks like it might not be very difficult (see ggrossetie/asciidoctor-web-pdf#137). We might need to provide a warning about the total size.

Ideally we wouldn't have any user pre-requisites like ("you must install Chrome" or "you must install asciidoctor-pdf.js prior"). Many users don't have much control over their environment and that would be a showstopper for them.

@joaompinto:

What would we lose on switching to asciidoctor-pdf (JS) as it stands now ?

If we switched by adding it as a package for node the extension would be excessively large. Not everyone has an unmetered high bandwidth connection and new extension releases would start to be a significant amount of data...

I would like to look into using an asciidoctor-pdf binary sometime (maybe the next few months, my free time comes to an end in about a week).

[ams-tschoening]

To work around this I believe if you set data-uri on your document by including :data-uri: in the document header you will see images (I do in my testing).

Do you have a more complete example? I'm trying to get images into a PDF rendered based on a ADOC document using wkhtmltopdf and even though I'm setting :data-uri:, the images are not available in the PDF. OTOH, the preview of VScode itself does show the images even without :data-uri:.

When enabling the setting Use_asciidoctorpdf, the resulting PDF looks different, but images are still not available. Instead I get text like this:

[no GUI] | git_install_01.webp

Changing images to be PNGs works and images are available, but they look bad. The PNG itself is OK, but some renders have problems with screenshots of Windows dialogs like these and apply transparency where simply black color should be used instead and stuff. The preview in VScode shows these PNGs badly as well, while IrfanView and GIMP show the PNGs just fine.

That's why I tried WEBP, that is supported by the preview, shows just fine, but isn't available in the resulting PDF anymore. Is there any additional option to make WEBP available in the PDF?

[ams-tschoening]

I'm trying to get images into a PDF rendered based on a ADOC document using wkhtmltopdf and even though I'm setting :data-uri:

Found the error, simply adding :data-uri: seems to work as long as the referenced image format is supported. I tried with WEBP and that isn't supported using :data-uri: and wkhtmltopdf as well. I guess I need asciidoctor-js as the PDF renderer in the end? Looks to me like that is used for the preview in VSCode and supports WEBP just fine.

[ams-tschoening]

Changing images to be PNGs works and images are available, but they look bad. The PNG itself is OK, but some renders have problems with screenshots of Windows dialogs like these and apply transparency where simply black color should be used instead and stuff. The preview in VScode shows these PNGs badly as well, while IrfanView and GIMP show the PNGs just fine.

Another workaround: While IrfanView and Gimp render those images properly, e.g. IrfanView simply allows to store PNG without any transparency at all. So when one knows that this isn't needed, simply disable it and images look fine even in the browser. Should have thought about that earlier. :-)