Indent configuration for multiline headings

[haenoe]

This PR adds the multiline-indent option for (multiline-)headings, as discussed in #2410.
(Also related is #2411, but proposes this for outlines)

Let me know what you think about all of this! ^^'

Thank you all very much!

[frozolotl]

I would prefer the name hanging-indent over multiline-indent.

Additionally, I think such an API should mimic the one of outline's indent parameter.
That would mean:

• hanging-indent: none (default): No indent.
• hanging-indent: auto: Indents the body where each line is aligned.

This API would allow other values, which could be added in a later PR (or this one), if wished for:

• hanging-indent: 1em: Indents the body by a certain length.

[laurmaedje]

@frozolotl That sounds nice in principle. Would the hanging indent affect the first line here? Because I'm not sure it makes sense, but it would for sure be useful to be able to fix the x position of the heading's body independently from the numbering.

[frozolotl]

@frozolotl That sounds nice in principle. Would the hanging indent affect the first line here? Because I'm not sure it makes sense, but it would for sure be useful to be able to fix the x position of the heading's body independently from the numbering.

In my line of thinking, when the hanging indent was set to a certain length, only the lines after the first line would be indented by it.

I'll henceforth call hanging-indent the indent used by all lines, excluding the first. body-indent will be the indent used by all lines.
No matter what, I think hanging-indent with a certain length is likely a more desirable property than body-indent.

First idea, body-indent always indents the heading by a certain amount. There we quickly have a problem when the numbering is wider than the indent long:

Second idea, body-indent indents the heading's body by max(measure(numbering + space).width, body-indent).

Third idea, body-indent is actually the offset by which the heading is rendered, relative to the start of the body. This is effectively #heading(hanging-indent: auto, pad(left: body-indent, body)).
In combination with hanging-indent: auto, it is also very similar to a hypothetical space property, which, I think, is a more useful and flexible property to have:

#set heading(hanging-indent: auto, space: space-between-numbering-and-body)

(In the current impl Show for Packed<HeadingElem>, that's a hard-coded 0.3em.)

So, the first idea is problematic, and the third idea should probably be implemented with a different API.
That leaves the second one. I think that could work, but I don't know whether it is common enough to warrant an extra attribute. It can be implemented with a show-rule if there is a need.

[laurmaedje]

I do agree with your points, However, one requirement that I'm not sure is covered by this is one where all headings should have the same indent, independently of the numbering, so that they align nicely.

I think that could work, but I don't know whether it is common enough to warrant an extra attribute. It can be implemented with a show-rule if there is a need.

I think it is overall a very tricky design space, which "settings of the default show rule" warrant properties on the element. In an ideal world, an element's properties are all semantical and the rest is left to show rules, but in practice it's useful to be able to configure the default show rule with some properties without rewriting it from scratch.

[laurmaedje]

Hey @haenoe, are you still interested in working on this or should we close it?

[haenoe]

Hii @laurmaedje

It seems like I misinterpreted the conversation and thought that the idea was not approved -- sorry for that.
I would be glad to contribute, though I can only start working on it this weekend.

Hope this is okay ^^'

[laurmaedje]

I think the design #set heading(hanging-indent: auto | length) is good. I think we should set it to auto by default. That's nicer than what we currently have.

[haenoe]

Hi @laurmaedje
I'm currently thinking about the best way to implement this and would be glad to hear your feedback.

1. I took a look at the implementation of outline, which achieves the indenting by rendering hidden ghost text (is my understanding correct here?) -- This approach is not applicable to this problem here, because of multiline
2. In the existing implementation I used a Grid with column-gutter, is this the best approach? I could then use Content::measure to calculate the right spacing.

Thank you!

[laurmaedje]

I think you probably just apply ParElem::set_hanging_indent(..) in the heading show rule. For the auto case, you'd indeed use measure then.

[haenoe]

Sorry for the long waiting times :/

I hope the new implementation is more or less what you imagined ^^'
If that is the case I will gladly add the required tests and the documentation :D

If not I would be happy about every feedback.

[laurmaedje]

I hope the new implementation is more or less what you imagined ^^'
If that is the case I will gladly add the required tests and the documentation :D

It does! I left just a few comments on the implementation.

[laurmaedje]

I'm quite happy about this. The old default style really wasn't great when multiline. Thanks!

[haenoe]

No problem! Thanks for your guidance :D
Should I also take a look at #2411 (multiline headings in outline)?

[laurmaedje]

Yeah sure!