Skip to content

docs: honor image height and size unsized images by resolution#4202

Open
grandixximo wants to merge 3 commits into
LinuxCNC:masterfrom
grandixximo:docs-img-height
Open

docs: honor image height and size unsized images by resolution#4202
grandixximo wants to merge 3 commits into
LinuxCNC:masterfrom
grandixximo:docs-img-height

Conversation

@grandixximo

Copy link
Copy Markdown
Contributor

Fixes #4201.

Problem

Two related image-sizing problems in the docs build, both reported in #4201:

  1. height is ignored. image::foo.png[height=400] had no effect. In HTML the bundled asciidoctor stylesheet's img{height:auto} (an author rule) overrides the HTML height attribute; in PDF asciidoctor-pdf sizes raster images only by the width family and drops height entirely. So both backends rendered Figures 1 and 4 of motion/5-axis-kinematics.adoc at full size instead of the requested 400px.

  2. Unsized images are blown up. apply_default_width forced 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

  • Honor height in HTML. A postprocessor mirrors the width/height attributes into an inline style, which wins the cascade over the stylesheet. Bare numbers become px; values with a unit or % pass through.
  • Honor height in PDF. When only a height is given, convert it to the equivalent pdfwidth using the image's intrinsic aspect ratio (PNG/JPEG/SVG size read without an image library).
  • Size unsized images by resolution. Instead of a blanket 75%, size each image at its intended resolution: the embedded PNG pHYs when present, else an assumed 96 DPI screen capture. Images wider than the 75% cap, or whose size cannot be read, keep the 75% fallback.
  • Build dependency. The HTML and PDF rules did not depend on docs/src/extensions/*.rb, so editing a resolver left previously built docs stale. Added DOC_EXTENSIONS as a prerequisite of both rules.

Verification

Full make htmldocs pdfdocs build, no errors. Confirmed in the rendered output:

  • HTML: Figures 1 and 4 now carry style="height:400px".
  • PDF (measured via the image transform matrix): Figure 1 (792x612) and Figure 4 (612x792, portrait) both render 300pt tall; the no-height figure stays at the 75% default.
  • Equations now render at their 96-DPI size (e.g. equation__38, 130px, drops from 374pt to 97pt).
  • The pyvcp dial drops from 374pt to 157pt (~2.2in), matching its on-screen size.

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.

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: height attribute not honored

1 participant