typst: Downgrade missing references from errors to warning
Description
Coming from LaTeX, you could compile a document even if a reference is not defined. This would trigger a warning and a “??” would be printed on the resulting file.
Currently, Typst just errs and exits the whole compiler process (e.g. if using typst watch).
Use Case
A similar functionality where the error is ignored and a warning is emitted instead would help creative flow while writing so that one does not have to immediately go back to a missing reference and try to address it.
About this issue
- Original URL
- State: open
- Created 3 years ago
- Reactions: 18
- Comments: 24 (11 by maintainers)
I would definitely prefer this to be opt-in instead opt out, i.e.
--draftinstead of--releaseMartin and I had thoughts in a similar direction. I don’t like
--allow-missing-refsat all, but a generic preview/draft compile that demotes certain errors to warnings and is enabled by default for previews sounds like a good idea.I think instead of having a specific flags just for refs we should instead think about how to implement a more generalized system for enabling/disabling warnings, then this could be extended to this specific use case as well.
Re: https://github.com/typst/typst/pull/4974#issuecomment-2355791728 Cc @Enivex
I think arguing in terms of amount of users isn’t productive in this discussion (and was a mistake in my part) because there is actually overlap between the groups “users who would like missing references to not block compilation” and “users who would like missing references to block compilation”. Rather, the same user may want both at different moments.
Let’s consider the two “purposes” for triggering a Typst compilation below (which would influence what would block it or not), in a usual workflow for writing a document:
#ref, so not all documents would produce accurate preview compilations if missing references are allowed, so it should still be toggleable somehow (see one potential proposal below).@typstlaurtext. A warning would help in this case, but it is often the case that people export with warnings anyway because they’re satisfied with how everything looks and don’t want to spend more precious time satisfying the Typst compiler (and thus may miss this warning which is clearly different from something like redundant**, which can be safely ignored).Therefore, I’d argue that
--previewflag which downgrades dismissible errors.Hopefully this clarifies my position better; I think this isn’t a matter of catering to a certain group users or another, but rather (since those groups do have an intersection) appealing to different needs they may have in their workflow with Typst.
I’d argue that the compiler is right to be loud about this by default: the main use case is when the references do, in fact, exist, to the point that we have autocomplete for existing references, and I’d certainly not want to accidentally share a document with missing references at some spots (can be easy to miss when the document is large) - warnings are good, but an error is even better and ensures you won’t miss it. I feel like blocking compilation unless you’re certain this is what you want is a good default, and you only have to change it once per module. Warning by default feels like a step backwards on reliability, imo.
Sounds like a good idea to me!
Another thing to consider is how this could be exposed to package authors. Consider for example the fletcher package. It has the option to display grid lines for debugging purposes. You would not want to keep this on for the final version.
Having an option as a plugin author to mark certain features as “draft-only” would be great!
I’d argue that warning by default is better for usability. Otherwise you’ll have to add preamble to every single subfile (chapters e.g.) to compile them stand-alone.
I don’t think I would mind as long as the compiler tells me how to switch it to a warning in the error message
I think deny-by-default would make things inconvenient again. The whole thing is that people want to just keep writing before filling in their references. Having to manually allow it would probably be a hassle.
I think this is a good use case for deny-by-default warnings - a simple
alloworwarnannotation would solve the problem. I believe erroring is a preferred behavior over replacing the reference with some ad-hoc thing (or nothing) together with a warning, which feels off (one should at least be able to pick what appears for missing references; also, the compiler should indeed be loud about this problem by default). But having a warning that starts as an error which one can optionally downgrade seems right to me.At this point, I think the best solution is to just downgrade it to a warning.
Yes! You want to be able to just put the references in as you’re writing and add the actual reference targets at the end. An
--ignore-refsflag or something would be ideal. The current behavior encourages putting in a bunch of dummy referands just to get the compiler off your back, which is worse since you might forget them.This at the beginning of the document makes a good workaround:
However, this doesn’t solve the problem because now all refs will be replaced by a placeholder, even ones that work, so you can’t gradually fix broken refs and have them fill in. This will do both: