Adds explanation about HTML relative image sizing support

asciidoctor / asciidoctor.org

:globe_with_meridians: Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.

https://asciidoctor.org

Other

323 stars 805 forks source link

Adds explanation about HTML relative image sizing support #867

Closed abelsromero closed 3 years ago

abelsromero commented 5 years ago

As mentioned in https://github.com/asciidoctor/asciidoctor.org/issues/866.

This PR attempts to reduce ambiguity in the image sizing summaries.

abelsromero commented 5 years ago

My goals with this PR are avoid confusion:

when using the documentation as quick-reference (not reading the whole section)
for newcomers that may find two slightly conflicting definitions.

mojavelinux commented 4 years ago

The only time the % width is allows is when converting to HTML and the image is an SVG with opts=inline. (And even that is discouraged).

When converting to PDF using Asciidoctor PDF, the pdfwidth attribute is always preferred.

The true purpose of the width attribute is to provide the intrinsic width of the image as a hint.

mojavelinux commented 4 years ago

I think the docs should simply say "the purpose of the width attribute is to define or override the image's intrinsic width". A % value should not be used here.