docs: honor image height and size unsized images by resolution#4202
Open
grandixximo wants to merge 3 commits into
Open
docs: honor image height and size unsized images by resolution#4202grandixximo wants to merge 3 commits into
grandixximo wants to merge 3 commits into
Conversation
The bundled asciidoctor stylesheet's img{height:auto} overrides the HTML
height attribute, and asciidoctor-pdf ignores height entirely for raster
images, so image::foo[height=400] was dropped in both backends.
HTML: a postprocessor mirrors the width/height attributes into an inline
style, which wins the cascade. PDF: convert a lone height into the
equivalent pdfwidth using the file's intrinsic aspect ratio (PNG/JPEG/SVG
size read without an image library).
Closes LinuxCNC#4201
apply_default_width forced every width/height-less image to 75% of the text column, stretching small images far beyond their intent: the 96-DPI equation captures rendered ~4x too large, and screenshots like the pyvcp dial (210px) rendered at 40 DPI / 5.2in. Size each image at its intended resolution instead: the embedded PNG pHYs when present, else an assumed 96 DPI screen capture. Images wider than the 75% cap, or whose size can't be read, keep the 75% fallback.
The HTML and PDF rules did not depend on docs/src/extensions/*.rb, so editing a resolver left previously built docs stale. Add DOC_EXTENSIONS as a prerequisite of both rules.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #4201.
Problem
Two related image-sizing problems in the docs build, both reported in #4201:
heightis ignored.image::foo.png[height=400]had no effect. In HTML the bundled asciidoctor stylesheet'simg{height:auto}(an author rule) overrides the HTMLheightattribute; in PDF asciidoctor-pdf sizes raster images only by the width family and dropsheightentirely. So both backends rendered Figures 1 and 4 ofmotion/5-axis-kinematics.adocat full size instead of the requested 400px.Unsized images are blown up.
apply_default_widthforced every width/height-less image to 75% of the text column. That stretched small images far beyond their intent: the 96-DPI equation captures rendered about 4x too large, and screenshots such as the pyvcp dial (a 210px window) rendered at roughly 40 DPI / 5.2in.Changes
heightin HTML. A postprocessor mirrors thewidth/heightattributes into an inlinestyle, which wins the cascade over the stylesheet. Bare numbers become px; values with a unit or % pass through.heightin PDF. When only a height is given, convert it to the equivalentpdfwidthusing the image's intrinsic aspect ratio (PNG/JPEG/SVG size read without an image library).pHYswhen present, else an assumed 96 DPI screen capture. Images wider than the 75% cap, or whose size cannot be read, keep the 75% fallback.docs/src/extensions/*.rb, so editing a resolver left previously built docs stale. AddedDOC_EXTENSIONSas a prerequisite of both rules.Verification
Full
make htmldocs pdfdocsbuild, no errors. Confirmed in the rendered output:style="height:400px".Note for reviewers
The resolution-based sizing affects many metadata-less screenshots across the docs: any raster narrower than about 498px now renders at its native 96-DPI size rather than 75% of the column; wider images are unchanged (still capped at 75%). This is a broad but intentional visual change. I spot-checked GUI/virtual-panel pages and the results look correct, but it is worth a look across chapters.