Add description-width config option #21

Merged
HEL merged 2 commits from dromell/rivet-typst:feat/description-width into dev 2026-08-29 10:22:36 +00:00
Contributor

Problem

Descriptions and values are drawn as a single line that never wraps. A diagram is
scaled to fit the width it is rendered into, so the longest label is what decides
that scale — one long description makes the whole diagram, bit cells and indices
included, shrink until that line fits.

Beforeconfig.config(), in a document 700pt wide:

before.png

Afterconfig.config(description-width: 460), same schema, same page:

after.png

What the option does

description-width wraps labels at that width, so the length of a description no
longer decides how large the diagram is drawn. Values wrap at the same right edge as
the description they belong to. It composes with left-labels,
force-descs-on-side and ltr-bits.

Wrapping means a label is no longer one line tall, so labels can no longer be spaced
by a fixed line height. Each is now offset by the height it actually occupies,
measured before it is placed. That is why render gained a context block.

Compatibility

The option defaults to none, which keeps the single-line behaviour on the original
code paths.

## Problem Descriptions and values are drawn as a single line that never wraps. A diagram is scaled to fit the width it is rendered into, so the longest label is what decides that scale — one long description makes the whole diagram, bit cells and indices included, shrink until that line fits. **Before** — `config.config()`, in a document 700pt wide: ![before.png](/attachments/901466e1-e6f1-4c8f-ad91-2a1812e50342) **After** — `config.config(description-width: 460)`, same schema, same page: ![after.png](/attachments/52fe356d-336f-4270-9688-96b650d1e985) ## What the option does `description-width` wraps labels at that width, so the length of a description no longer decides how large the diagram is drawn. Values wrap at the same right edge as the description they belong to. It composes with `left-labels`, `force-descs-on-side` and `ltr-bits`. Wrapping means a label is no longer one line tall, so labels can no longer be spaced by a fixed line height. Each is now offset by the height it actually occupies, measured before it is placed. That is why `render` gained a `context` block. ## Compatibility The option defaults to `none`, which keeps the single-line behaviour on the original code paths.
HEL added the enhancement label 2026-08-18 12:32:59 +00:00
Author
Contributor

Any thoughts on this change?

Any thoughts on this change?
Owner

Yes it looks very nice
I've skimmed the changes and it seems alright to me, I've just been quite busy this week and haven't had the time to review it
Will do asap

Yes it looks very nice I've skimmed the changes and it seems alright to me, I've just been quite busy this week and haven't had the time to review it Will do asap
HEL requested changes 2026-08-24 20:06:22 +00:00
Dismissed
HEL left a comment
Owner

Nice addition, just a few things, mainly some adjustments to the documentation

Nice addition, just a few things, mainly some adjustments to the documentation
docs/config.typ Outdated
@@ -26,6 +26,7 @@
/// - full-page (bool): If true, the page will be resized to fit the diagram and take the background color
/// - all-bit-i (bool): If true, all bit indices will be rendered, otherwise, only the ends of each range will be displayed
/// - ltr-bits (bool): If true, bits are placed with the LSB on the left instead of the right
/// - description-width (float | none): If set, descriptions and values wrap at this width instead of being drawn on a single line
Owner

Separator between types should be a comma for Tidy to parse it correctly

Separator between types should be a comma for Tidy to parse it correctly
HEL marked this conversation as resolved
manual.typ Outdated
@@ -203,6 +203,36 @@ For values depending on other ranges, see #link(<format-dependencies>)[Dependenc
}
```
=== Wrapping descriptions <format-description-width>
Owner

I'm not sure this is the best place to put this section. This chapter is rather dedicated to the schema definition format.
I think we should put config related stuff in the Config chapter (which could be renamed instead of only talking about Config presets)

I'm not sure this is the best place to put this section. This chapter is rather dedicated to the schema definition format. I think we should put config related stuff in the Config chapter (which could be renamed instead of only talking about Config presets)
HEL marked this conversation as resolved
manual.typ Outdated
@@ -206,0 +228,4 @@
occupies, so wrapping onto several lines does not make labels overlap.
```typ
schema.render(sch, config: config.config(description-width: 300))
Owner

Missing a # at the start of the line

Missing a `#` at the start of the line
HEL marked this conversation as resolved
src/renderer.typ Outdated
@@ -158,0 +193,4 @@
// to its left edge: exactly the box width when wrapping, an estimate from
// the character count otherwise
txt-x -= if config.description-width == none {
range_.description.len() * config.default-font-size / 2pt
Owner

Could we use measure instead?

Could we use `measure` instead?
dromell added 2 commits 2026-08-25 12:56:57 +00:00
Descriptions and values are drawn as a single line that never wraps.
Because a diagram is scaled to fit the width it is rendered into, the
longest label is what decides that scale: one long description makes the
whole diagram -- bit cells, indices and every other label with it --
shrink until that line fits. A register whose fields carry a sentence
each is then unreadable at any page width, and since each diagram is
measured on its own, a document full of them renders every one at a
different size.

Setting description-width wraps labels at that width instead, so the
length of a description no longer decides how large the diagram is
drawn. Values wrap at the same right edge as the description they belong
to, and the option composes with left-labels, force-descs-on-side and
ltr-bits.

Wrapping means a label is no longer one line tall, so labels can no
longer be spaced by a fixed line height. Each is now offset by the
height it actually occupies, measured before it is placed, which is why
render gained a context block.

The option defaults to none, which keeps the single-line behaviour on
the original code paths. With it unset every diagram in the gallery
renders byte-identical to before.
With left-labels a description is placed by subtracting its width from
desc-x. That width was estimated as half the font size per character,
which undershoots Ubuntu Mono's advance of 0.56em by 12%, so the leader
line struck through the last letter of every label, as it does on the
manual's own cover page. Proportional fonts were off by more.

render is now a context block, so the text can be measured instead. The
font has to be passed explicitly: the set rule at the top of render is
not in scope for a measure further down the same context block.
dromell force-pushed feat/description-width from ab3ccfccea to f4c3fc7f61 2026-08-25 12:56:57 +00:00 Compare
Author
Contributor

Good points! I think I've addressed all of them.
Regarding changing to measure, I agree it's better, but note that it's changing the default behavior rather than when description-width is actually set. I kept that as a separate commit, so it's up to you if you want it as part of this PR or as a separate one.

Good points! I think I've addressed all of them. Regarding changing to `measure`, I agree it's better, but note that it's changing the default behavior rather than when `description-width` is actually set. I kept that as a separate commit, so it's up to you if you want it as part of this PR or as a separate one.
Owner

note that it's changing the default behavior

I agree but I do think it is for the better

> note that it's changing the default behavior I agree but I do think it is for the better
HEL approved these changes 2026-08-29 10:22:16 +00:00
HEL left a comment
Owner

Thank you for your contribution!

Thank you for your contribution!
HEL merged commit dcc07ede35 into dev 2026-08-29 10:22:36 +00:00
Sign in to join this conversation.
No Reviewers
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: HEL/rivet-typst#21