This is a weird thing I've uncovered here.

https://typst.app/docs/reference/text/text/#parameters-hyphenate:

Whether to hyphenate text to improve line breaking. When auto, text will be hyphenated if and only if justification is enabled.

https://typst.app/docs/reference/model/par/#parameters-justify:

Hyphenation will be enabled for justified paragraphs if the text function's hyphenate property is set to auto and the current language is known.

https://typst.app/docs/reference/model/par/#what-becomes-a-paragraph:

When you add inline-level content to your document, Typst will automatically wrap it in paragraphs. However, a typical document also contains some text that is not semantically part of a paragraph, for example in a heading or caption.

So, block[text] is not a paragraph, i.e., not a par element/proper paragraph. This means that a thing like first-line-indent does not affect it. Okay.

The par.justify supposed to enable text.hyphenate only for justified paragraphs, which is basically just for paragraphs, since they are all justified (if not disabled). And now:

#set page(width: 250pt, height: auto)
#set par(justify: true)
// #set text(hyphenate: false)
#block(lorem(25))

Not only the "blocked text" text is hyphenated, but it's also justified. Which breaks not only what the docs say, but also my mental model.

Now, if we look elsewhere, things get weird. Non-semantic paragraphs are using things like par.leading for spacing between lines, even though they are not proper paragraphs. But how else would you specify that for such text? No sane alternatives.

Next, @PgBiel noted that to use par.hanging-indent you must create a proper paragraph, and opting into behavior of par.first-line-indent (FLI). What if you just want to use hanging indent without FLI? Or in other words, how come blocked text uses par.leading, par.justify, but doesn't react to par.hanging-indent?

As a result, it's not 100% clear if all of this is truly intended behavior. This also means that whenever a paragraph is mentioned anywhere, it can refer to any paragraph, if not explicitly stated otherwise. This not only confuses me (when proofreading docs), but also confuses the users that are trying to understand how Typst works. I didn't look how many references there are in total to paragraphs, but I bet most of it if not all should be rephrased.

Now, how do we do that? I have no idea. The terms from the docs would be "semantic paragraph" and "non-semantic paragraph". But it doesn't sound that great. @PgBiel said that anywhere, the first mention of a paragraph should clearly state what this means in this context, and then some abbreviation can be used to not make it overly long and harder to read/understand.

I don't know if this is just a docs issue, or maybe some bug as well.