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:
After — config.config(description-width: 460), same schema, same page:
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:

**After** — `config.config(description-width: 460)`, same schema, same page:

## 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.
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
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)
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.
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.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
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:After —
config.config(description-width: 460), same schema, same page:What the option does
description-widthwraps labels at that width, so the length of a description nolonger 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-sideandltr-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
rendergained acontextblock.Compatibility
The option defaults to
none, which keeps the single-line behaviour on the originalcode paths.
Any thoughts on this change?
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
Nice addition, just a few things, mainly some adjustments to the documentation
@@ -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 lineSeparator between types should be a comma for Tidy to parse it correctly
@@ -203,6 +203,36 @@ For values depending on other ranges, see #link(<format-dependencies>)[Dependenc}```=== Wrapping descriptions <format-description-width>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)
@@ -206,0 +228,4 @@occupies, so wrapping onto several lines does not make labels overlap.```typschema.render(sch, config: config.config(description-width: 300))Missing a
#at the start of the line@@ -158,0 +193,4 @@// to its left edge: exactly the box width when wrapping, an estimate from// the character count otherwisetxt-x -= if config.description-width == none {range_.description.len() * config.default-font-size / 2ptCould we use
measureinstead?ab3ccfcceatof4c3fc7f61Good 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 whendescription-widthis 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.I agree but I do think it is for the better
Thank you for your contribution!