Asciidoctor :: Discussion - Re: Unit of measure for image dimensions

Re: Unit of measure for image dimensions

Posted by mojavelinux on May 17, 2015; 9:20am
URL: https://discuss.asciidoctor.org/Unit-of-measure-for-image-dimensions-tp3040p3222.html

On Sun, May 3, 2015 at 1:03 PM, hijarian [via Asciidoctor :: Discussion] <[hidden email]> wrote:

To be blunt, when we are talking about authoring PDF based on plaintext sources, we're competing with LaTeX, right?

Essentially, yes. Our audience is broader, so we have to be more considerate of that, but AsciiDoc is quickly becoming the format of choice for plain text markup, so the LaTeX audience is an important one (give it's being king of plain text for so long).

My humble opinion is that we need to provide at least the same level of control over the pictures in the PDF as in the LaTeX toolchain.

I'd like to restate this slightly. We need to provide a level of control that meets modern requirements (responsive web / HTML5, PDF, etc). I really don't care how many options LaTeX offered if some are no longer relevant. We need to meet modern requirements, plain and simple.

As far as I understand, there is no possibility to make such types of images in PDF.

I'm not sure exactly what you mean here. Currently, Asciidoctor PDF is not parsing inline images, only block-level images. This is a bug and will be fixed (see https://github.com/asciidoctor/asciidoctor-pdf/issues/9). However, you can get a PDF with inline images if you generate DocBook and then convert to PDF from there...so it's possible, Asciidoctor PDF is just not finished yet.

* `width` and `height` should allow explicit specification of units, like "500px", "5em", "5ex", etc. Compatible with CSS and whatever PostScript is allowing in the dimensions of blocks.

The tricky part here is that a single image macro has to serve multiple masters. When I render to HTML, I want to use px (or em). When I render to PDF, I not only need different units, I likely also need a different value because it's a different canvas with different requirements.

One way to do this is to use preprocessor conditionals:

ifdef::backend-pdf[]

image::diagram.png[Diagram, 5in]

endif::[]

ifndef::backend-pdf[]

image::diagram.png[Diagram, 500]

endif::[]

* If `width` and `height` are specified at all, then it should be treated as *explicit* specification of sizes, and it should be obeyed. Current behavior is not obvious at all, and simply means that we are generating waste code each time we specify `width` and `height` parameters. Both AsciiDoc > HTML and AsciiDoc -> PDF converters are able to guess image aspect ratio correctly without specifying sizes at all. Then, what's the point of these parameters?

To be honest, these values were intended to be passed to HTML as metadata and to set the aspect ratio. They weren't designed to be style values. That's the software design issue we are currently facing. How can we accommodate the requirement you are stating?

The width and height of an image in the <img> tag in HTML tells the browser what size of image it is dealing with in pixels (or percentage of the parent). CSS can then come along and totally change that value, using proper image dimensions. And thus, so can we.

If we want to change the dimensions using em units, we have to use CSS in the image tag.

We need to figure out the best way to pass the value of the width CSS attribute from AsciiDoc. Perhaps:

image::tiger.png[tiger, 500, 500, csswidth=25em]

Other names may be htmlwidth, webwidth, etc. But csswidth gets right to the point, I suppose.

See below for more discussion.

* floats should work both in HTML and PDF, no exception. PostScript happily support this feature AFAIK, so there's no technical obstacle to this.

Again, this is just a shortcoming of Asciidoctor PDF at the moment. Floats work fine in the DocBook toolchain to PDF (or they could work fine, but maybe a bug there too). The reason it doesn't work in Asciidoctor PDF yet is because the library we use for making the PDF doesn't have any support for floating images. We have to do it manually (or create our own API) and I just haven't had time to do it yet.

* when the author writes the AsciiDoc and does the following: `image::filename.png[width=45cm,align=center]` we must assume that he knows what he's doing and make it 15 cm wide both in HTML and PDF, keeping proportions (as no height was explicitly specified), and trimming left and right sides of image in PDF, where it obviously cannot fit inside 21cm width of the page. This will allow people to make images without margins in printed pages, spanning from left-hand edge of paper to right-hand one.

We can do this, especially for the PDF backend. Though, I'm thinking about an attribute like pdfwidth (to compliment csswidth), to avoid conflicts with HTML settings since we are going to need different values and units. So, perhaps something like:

image::tiger.png[tiger,500,csswidth=25em,pdfwidth=10cm]

If we don't want to be so specific about the technology names, we could use screenwidth for CSS and printwidth for PDF.

To summarize, we can have width be the image metadata, the scaled with for CSS and the scaled with for PDF. It just can't be all those things at once. I think the solution is multiple attributes. At least that way there is no confusion. Of course, csswidth and pdfwidth would accept units. The "width" attribute is meant to be metadata that communicates the *original* dimensions of the raster image in pixels. We can document that.

-Dan

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