Unit of measure for image dimensions

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Unit of measure for image dimensions

hijarian
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.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Unit of measure for image dimensions

mojavelinux
Administrator
Mark,

The unit of measure for the height and width of images is pixels by default. In the HTML backend, these values are assigned directly to the width and height attributes on the img tag, as you can see here:


The unit of measure matches the default for HTML (CSS pixels).


I agree this would be good to document.

However, the default stylesheet for Asciidoctor adds responsive characteristics to images, so the pixels are only suggested values. The image will reduce in size to fit the screen as the viewport shrinks. What's really important is the aspect ratio that these numbers capture (as that is preserved). 

The PDF backend (via DocBook) uses these values merely to understand the resolution and aspect ratio of the image. You can set the relative width (relative to the page) using the scaledwidth attribute on the image macro.

image::image.png[Alt Text, 300, 200, scaledwidth=25%]

fopub includes some logic that will scale the image appropriately even when scaledwidth is not set. See:


You could copy and reuse this logic in your DocBook pipeline. I go tit from the PressGang team at Red Hat.

Other than that, we don't have a lot of control yet from the AsciiDoc over image scaling in PDF. This is something we're actively discussing in the issue tracker. Your input is welcome.


Cheers,

-Dan

On Mon, Apr 27, 2015 at 5:12 AM, hijarian [via Asciidoctor :: Discussion] <[hidden email]> wrote:
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.


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Unit-of-measure-for-image-dimensions-tp3040.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Unit of measure for image dimensions

hijarian
Thank you, Dan. It's quite unfortunate that I can specify exact size of images in PDF only in terms of the percentages relative to the page width.

So, in effect, it's impossible to have the same layout in PDF as in HTML?
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Unit of measure for image dimensions

mojavelinux
Administrator

We can change the code, so the question is what do you want to be able to specify? Then, we can make it happen.

The current behavior is very much inherited from AsciiDoc Python, so this is an opportunity to reevaluate.

Cheers,

-Dan

Le 3 mai 2015 11:54 AM, "hijarian [via Asciidoctor :: Discussion]" <[hidden email]> a écrit :
Thank you, Dan. It's quite unfortunate that I can specify exact size of images in PDF only in terms of the percentages relative to the page width.

So, in effect, it's impossible to have the same layout in PDF as in HTML?


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Unit-of-measure-for-image-dimensions-tp3040p3110.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Unit of measure for image dimensions

hijarian
To be blunt, when we are talking about authoring PDF based on plaintext sources, we're competing with LaTeX, right? Doesn't matter that DocBook is targeted on tech docs and domain of LaTeX is scientific papers, we have pictures both here and there. 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. If it's not desirable for some reason, then it should be quite reasonable to allow same level of control as in HTML. In any case it seems quite obvious that the following is needed:

* Ability to specify purely decorative images. Not those from `image::` macro, which are being implicitly placed into container, numbered in TOC and have a subtitle. Not those from `image:` macro, which are treated like a character in line of text. Those which we can just put anywhere on the page and forget about it. As far as I understand, there is no possibility to make such types of images in PDF. Or, rather, to make them in AsciiDoc so PDF will treat them as such. This issue is directly related to the topic of this conversation, it's its context.
* `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.
* 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?
* floats should work both in HTML and PDF, no exception. PostScript happily support this feature AFAIK, so there's no technical obstacle to this.
* 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.


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Unit of measure for image dimensions

mojavelinux
Administrator
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.

<img src="tiger.png" alt="tiger" width="500" height="500" style="width: 25em">

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 

--
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Unit of measure for image dimensions

hijarian
Thank you for thorough answer, it's all a lot more clear now. I apologize that I needed to get an answer from nobody else than the author of the library to get this information, but as far as I researched, it's not recorded anywhere apart from source code and maybe some non-searchable place like some IRC chat. I didn't know that "width" and "height" attributes are just information for Asciidoctor about dimensions of the source image and the resulting dimensions can be completely different by design.

I agree that two distinct width properties seems to be the most viable option. It's a lot more complex task to make Asciidoctor automatically fit images to such different mediums like (essentially width-less) screen and printed matter.

I used LaTeX as a point of reference known to everybody - its capabilities in PS/PDF generation do not need any explanation.

When I talked about the type of images which are neither inline nor block-level I meant exactly that, I repeat it again:

* Block-level images are treated very distinctively by AsciiDoctor (and, subsequently, DocBook): they are being recorded into TOC, have a caption and have a special 100%-width block around them inside which they can be explicitly positioned using separate attribute exclusively for this positioning. This is very convenient for the time we need to actually track and reference them, no complaints here.
* Inline-level images as they are (`image:path[attrs]`, single-colon), are meant to be used as they named: inline, that is, as a in-line characters happen to be raster images. For example, smileys. This is obvious meaning stemming from the fact that by default they are being rendered exactly like that by both DocBook and HTML backends.
* Special property "float" on inline-level images converts them to what I am talking about: purely decorative images placed somewhere in the flow of the document. My personal problem was that "float" seems to not work in the DocBook backend at all: image becomes placed in its own block but is not actually "floated" - text is not wrapping it and right-aligned float does not work. My proposition is to make such images into separate explicit type (or maybe to make inline images instead a separate explicit type, because floated decorative images are a lot more common than inline ones, I totally don't understand intention of the HTML spec here at all). And to not forget to enable this feature in PDF output.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Unit of measure for image dimensions

mojavelinux
Administrator
On Mon, May 18, 2015 at 2:01 AM, hijarian [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Thank you for thorough answer

You're very welcome.
 
, it's all a lot more clear now.

👍
 
I apologize that I needed to get an answer from nobody else than the author of the library to get this information, but as far as I researched, it's not recorded anywhere apart from source code and maybe some non-searchable place like some IRC chat.

We're hard at work getting the information that's in my head, as well as various channels, into the user manual <http://asciidoctor.org/docs/user-manual). There's a lot to document, so it's taking some time.

Thanks for raising this topic because now it's clear what we need to document.
 
I didn't know that "width" and "height" attributes are just information for Asciidoctor about dimensions of the source image and the resulting dimensions can be completely different by design.

That's sort of what this discussion is about...figuring out exactly what they are and documenting it.

 

I agree that two distinct width properties seems to be the most viable option. It's a lot more complex task to make Asciidoctor automatically fit images to such different mediums like (essentially width-less) screen and printed matter.

The more I think about it, the more I think this is the way to go. If these extra attributes aren't provided, we'll do our best to make sense of the width and height alone (or the native size of the image).
 
My personal problem was that "float" seems to not work in the DocBook backend at all: image becomes placed in its own block but is not actually "floated" - text is not wrapping it and right-aligned float does not work.

Thanks for clarifying. So it isn't supported by DocBook after all. We don't maintain the DocBook toolchain, so our best bet is to address this requirement in Asciidoctor PDF.
 
My proposition is to make such images into separate explicit type (or maybe to make inline images instead a separate explicit type, because floated decorative images are a lot more common than inline ones, I totally don't understand intention of the HTML spec here at all). And to not forget to enable this feature in PDF output.

I don't think we need a special type. The existing macro is capable of capturing the necessary information. As far as I understand it, we just need to handle floating images correctly in Asciidoctor PDF. It will likely become a follow-up issue to https://github.com/asciidoctor/asciidoctor-pdf/issues/9.

Cheers,

-Dan


--
Loading...