Better documentation of relative lengths: page, region, block, container, element, etc. #6346
Description
Description
Hello, I am trying out Typst and while the documentation has a reasonably good tutorial and reference, and also guides to some extent, I find it lacking in the “explanation” quadrant — I was interested in understanding the typesetting/layout model, and there was too little in the tutorial and most of the reference section seemed more interested in the programming model than basic questions of layout.
A specific example is relative lengths like "100%", which are documented only as “A length in relation to some known length”, but I have not been able to find in the docs a way of figuring out what that known length is, in a given context.
On the forum, user Andrew pointed me to this section of the source code:
typst/crates/typst-library/src/layout/rel.rs
Lines 11 to 68 in 2f18657
-
relative lengths are, in a “common use case”, relative to the “width of the page”, which is “the page's inner width (the width minus margins)”.
-
in general they are relative to the “container”, when a “layout element” is nested in “another layout container”.
So there seem to be a bunch of undefined/undocumented terms here, like “ region”, “container”, and “element”. (For example, is there a list of all the elements, or different kinds of regions?)
The most useful has been the “What becomes a paragraph?” at https://typst.app/docs/reference/model/par/ and I'd like more such sections.
The basic thing I'm trying to understand is: in general, what does a page consist of? For example, I understand the TeX model where the page is a vbox containing hboxes (and glue and penalties), and I can also debug this myself or check my understanding in any given situation, with \tracingoutput — it seems that the Typst model is more sophisticated, as regular paragraphs and (say) headings are first-class concepts treated differently, so a page can be some combination of different things, and the documentation has not been helpful in understanding what these things are and what exactly is going on in any given context. A concrete test is: can a user who has read the documentation correctly answer, given a location in the Typst source code, what a relative length like "50%" there is going to be relative to?
(Also, IMO a user ought to be able to learn these things from documentation rather than having to read the source code comments, ideally.)