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)

Most upvoted comments

I would definitely prefer this to be opt-in instead opt out, i.e. --draft instead of --release

Martin and I had thoughts in a similar direction. I don’t like --allow-missing-refs at 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 have the exact opposite impression. The majority would rather have references be a warning, without blocking compilation.

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:

  1. Preview: when you just want to preview your document, missing references are usually OK, since you’re just looking to have an idea of how it looks.
    • Although a missing reference might still change how the document looks due to show rules on #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).
  2. Export: when you want to share your document to others (e.g. turn in your thesis, present your slides and so on), you certainly do not want to allow missing references for obvious reasons. For example, you wouldn’t want a reviewer to ask what is this red @typstlaur text. 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

  1. Being stricter by default is better, as I’d rather have the compiler, by default, reject otherwise valid preview compilations than accept one invalid export compilation. Typst is here to ensure quality in your documents, and detecting this kind of problem (at the right time) is part of what makes the Typst compiler so useful and helpful.
  2. But it should still be possible to make the compiler more flexible. One potential proposal here is to differentiate preview and export compilations somehow. This could be implemented by marking some errors as dismissible for preview compilations (/ “deny-by-default warnings”), and:
    • The web app and LSPs would compile in “preview mode” / downgrade those warnings by default when displaying the document preview, allowing the user to still preview their documents, whereas clicking the export button would either fail or at least prompt the user for confirmation, listing problems which should be given attention;
    • The Typst CLI is more often than not used for final exports, so it should fail compilation by default, but could simulate the same behavior through a --preview flag 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.

The whole thing is that people want to just keep writing before filling in their references.

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.

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

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.

At this point, I think the best solution is to just downgrade it to a warning.

I think this is a good use case for deny-by-default warnings - a simple allow or warn annotation 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-refs flag 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:

#show ref: it => {
  it.target
}

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:

#show ref: it => {
  if query(it.target).len() > 0 {
    it
  } else {
    it.target
  }
}