typst: A list item starting with = should not result in a heading
Description
With this code:
1 + 2
- = 3
The tip (commit 176b070) generates a heading 3:
While v0.12.0 works as expected:
Reproduction URL
No response
Operating system
Windows
Typst version
- I am using the latest version of Typst
About this issue
- Original URL
- State: closed
- Created 2 years ago
- Comments: 23 (8 by maintainers)
This is just a matter of design, and either choice can work (I’m more than willing to do the implementation if this is desired). But I am of the opinion that headings should not have a special-case here.
I have two arguments:
First, no one is arguing against
- list\n = headproducing a heading, even if headings in lists are an odd typographic choice. So this special case really is just for lists that would start with a heading vs. an equals-sign. At some point it might make more sense to use an equals-sign as the bullet itself, or use a term-list with equals as a separator, but these are secondary concerns.My main point is that if someone is going to place a heading in a list, wouldn’t its most common location be the first line?
It doesn’t make sense to me to allow syntax for headings in lists, but not allow them to start on the first line. This is exactly the reason why #5719 was an issue in the first place.
Second, I think having fewer conceptually simple rules will make markup easier to learn. Edge cases and special handling do come with the domain of typesetting and communication, but I don’t think allowing equals-signs after list markers is a good-enough tradeoff for another edge case.
I said this in #5728:
I think this is important because the fix created a new simple rule: list markers act like the start of a line, even if there is no newline.
The actual code change for #5728 was flipping three booleans. Adding the special case for avoiding headings will be a good bit more complex, particularly that we would start to distinguish three types of “line starts”: top-level newlines, nested newlines, and list/enum markers. Code simplicity does not create conceptual simplicity, but they are correlated.
That is a good argument.
Speaking broadly, the only guarantee you have that your document will remain compiling is by using the same compiler version. Typst is a highly dynamic language, and any change, as small as it can seem, can be “breaking”. For a quick (but unusual) example, you might have a for loop over all functions in the standard library which would break if a new function were to be added. So we can’t really tell you that your document will remain compiling across versions.
With that said, sometimes larger changes happen and there is an attempt to indicate them in the changelog, of course. Some larger changes are to be expected in the future, for example regarding the addition of custom types and elements to the language - we don’t know yet how much that will change or break, but overall you can expect that there’ll continue to be changes (breaking or not) to the language as long as that brings value to Typst users.
Wrzian voiced many of the opinions and thoughts I had but was unable to properly explain
But why shouldn’t this be a heading?
You’re writing math in content mode.
@PgBiel Disallowing headings in lists entirely is a bit too non-local of an effect for my liking. When I’m writing an equals sign at indent level 2, I shouldn’t have to care whether the indent comes from a list item or block scope 100 lines earlier. Even if you never use headings in list, you might want an explicit equals sign at the start of a line outside of a list. Switching the parsing behaviour of the
=in lists will make things unpredictable in such situations. As soon you move the equals sign out of your list, you’ll have to escape it to not change the behaviour.@earmer We aim to avoid breaking things unnecessarily or going back and forth between approaches, but in general breaking changes are to be expected at this stage.
I’ll apologize for not mentioning it explicitly in my response, but I disagree with your premise. In particular, I am not in favor of having headings work inside lists at all either, and in fact, I was not even aware that was possible (or whether it now became a possibility) 😅. I simply cannot think of any case where you would want to include a heading inside a list. As mentioned by @DorianXGH, this kind of document structure is virtually inexistent in typical documents. Here, I’m treating lists in the semantic and structural way that they should be treated, given their special syntax.
For me, headings should only work at the top-level of a scope, which includes the document itself and explicit markup blocks. I disagree that it’d be simpler to just have them work at any level of nesting since Typst’s syntax should be tailored for the most common use cases, not the opposite, which is also why you don’t have an equals sign turning into a heading at any point of the document.
From my view, the rules wouldn’t be “starts at list or not”, but rather “is at the top of the scope or not”, if this makes sense. I think a list item just doesn’t have the same power as starting an entirely new scope, and this could set, in my opinion, a problematic precedence in terms of semantics.
Edit: With that said, I agree that having headings work on all lines is better than not working on just the first line. I’d be in favor of either not working inside lists at all or always working inside lists, with preference for the former.
In a way, the way things have changed to be now (ignoring this particular issue) is overall better as the list shorthand syntax always felt a bit finnicky to use for me, so the improved consistency is great. With that in mind, I have to agree that it just feels out of place for headings to work here. In my mental model, they are always at the start of a line or markup block, but if there’s something else before the equals sign, then it shouldn’t resolve to a heading, but rather remain as the sign (which is a very commonly used symbol). I’m in favor of reverting the behavior for headings specifically. (Not sure if there’s anything else in this situation, but I also admit I didn’t think that far into it.)
@Enivex Sorry, but I highly disagree with you. Not all numbers should be in math mode.
Numbers in text serve different purposes, and not all of them warrant math mode formatting.
When numbers appear as part of natural narrative flow, like “Chapter 3” or “2 characters walking down 5th Avenue,” putting them in math mode would actually harm readability and meaning.
This becomes especially apparent in typography, where numbers in running text should harmoniously match the surrounding font. When a sans-serif font is used for the main text, having numbers suddenly appear in math mode’s serif font creates an awkward visual disruption.
Regarding the specific case of
- = I think it likely, the equals sign appears to serve as a continuation marker or connector within a structured format, not as a mathematical equality symbol.If this were interpreted as a heading, it would create several problems: it would disrupt the document’s logical hierarchy, the equals sign would lack clear semantic purpose, and it would generate confusing entries in any table of contents.
Last, most established editors and compilers, including LaTeX, Markdown, Pages, and MS Word, follow similar principles in distinguishing between lists and headings.
Typst is not something which has a “unique idea” about typesetting, or, it does?
Proof:
Isn’t the behavior on main more reasonable? You shouldn’t be writing math in content mode in the first place.
Whether this was a conscious change or not, it seems like an improvement.
Edit: It was pointed out by @EpicEricEE that this might be due to https://github.com/typst/typst/pull/5728