Search code examples
imagepdfasciidoctor

Unit of measure for image dimensions in AsciiDoc/AsciiDoctor documents

There is no indication neither in the docs nor on first three pages of Google search results about what is the unit of measure of the images in AsciiDoc documents. This is significant topic, because AsciiDoc converts both to HTML (native unit is pixel) and to PDF (native unit is either cm or pt).

So, can someone answer and/or add a section to documentation about the following:

  • When I write image::path/to/image.png["Caption",300,200], what is those 300 and 200? Pixels?
  • When I produce a PDF from the AsciiDoc document, what DPI it uses, if we are using pixels? Can I control it in some configuration setting?
  • If those dimensions are in some abstract units, then, what is the widths of HTML and PDF pages in those units?
  • Is there any way to make output-agnostic AsciiDoc document with images? I don't want pixel-perfect identical layout in both formats, but it would be great to preserve the relative sizes of images at least.

I am using asciidoctor -b html for HTML output and asciidoctor-fopub for PDF. I will not use asciidoctor-pdf until it'll support at least the same feature set as fopub.

Thank you beforehand.

Solution

  • For html, it's pixels: https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/converter/html5.rb#L520-L523

    For pdf, I'm not really sure, but it probably depends on Apache FOP, as that's what's being used. The xslt seems to indicate inches without any scaling. You'll have to dig into that whole mess to actually figure out what's being used and how to modify it.