Ambigous image height & width sizing explanation

[abelsromero]

The options for image sizing are contradictory between the sections and the summary at the end.

While https://asciidoctor.org/docs/user-manual/#width-and-height and https://asciidoctor.org/docs/user-manual/#image-sizing-recap it is show that you can use "%" to set image size relative to content in HTML.

Later on, in the section summary https://asciidoctor.org/docs/user-manual/#summary-2, it says that width & height are "in pixels". I think that a mention to the "%" usage in HTML in the "Comments" column of the summay is enough to avoid any confusion or jumping through the document.

[mojavelinux]

If you'd like to update the docs, I'd be happy to review the change.

In general, using % for the image width is hazardous. First, it doesn't serve the purpose of the attribute, which is to communicate the intrinsic width of the image. Second, it's not entirely clear whether browsers actually support the % value. For example, MDN doesn't mention it (see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Img#attr-width).

This is why we have pdfwidth for PDF output and are considering having htmlwidth to do the same (see https://github.com/asciidoctor/asciidoctor/issues/1894). Those attribute are designed specifically for sizing the image.

[abelsromero]

It makes much more sense once you see the rationale and https://github.com/asciidoctor/asciidoctor/issues/1894 addresses my concerns. Also found some references that say that % was supported in HTML4 but not officially in 5, which explains why it works in Mozilla. I suppose they maintain it even when % should not work.

[krOoze]

BTW I also noticed that the example in Image Sizing Recap uses other units for width:

ifdef::backend-docbook5[]
:twoinches: width='50mm'
:full-width: scaledwidth='100%'
:half-width: scaledwidth='50%'
:half-size: width='50%'
:thumbnail: width='20mm'
endif::[]

So basically I think width units allowed are the same as the target specific units (pdfwidth), except it makes the document unportable?

[mojavelinux]

DocBook allows units on the width, but the behavior if very non-portable. scaledwidth is preferred when creating DocBook.

[mojavelinux]

(Asciidoctor PDF also supports scaledwidth, but pdfwidth is more powerful...because we know the context).

[mojavelinux]

I believe all this information has been captured and clarified on the page in the new docs site. See https://docs.asciidoctor.org/asciidoc/latest/macros/image-size/

If there is an assertion you see that needs fixing, or want to elaborate on a point, feel free to click "Edit this Page" and propose an update.