Best practices for working with longer documents

General
1

The Typst by Example Book tells how to work with larger documents in principle.

But how should I handle packages? Where should I import them?
It would make sense to import them in the template, but this does not seem to work.

I have a project with the structure as in the website, i.e.
image
and it does not compile, because when I #include "chapters/chapter_1.typ"
it gives me error: unknown variable: dd even though the variable is defined in the package physika which I import in my template.typ and I import template.typ in my chapter_1.typ. If I import the package again in the chapter, everything works as expected.

Am I supposed to include every package in every chapter again? This seems like a non-optimal way to do this.

Interestingly, when I use dd in the main.typ, where physika is also not imported but template is (which is the same situation as in the chapter), everything works fine. So for some reason, the indirect import over the template works for the main function, but does not for the chapter-function. Why is that the case?

2 Likes
2

Hi @Sinthoras ,

After creating many multi-file documents, I would recommend doing exactly what you proposed:

  • Import packages in the template.typ (or similar)
  • Also make definitions here that you want available everywhere.

Then, in each chapter (as well as the main) file, import everything from the template file:

#import "template.typ": *

This should indeed work! Can you confirm that you added the star in the chapter files or did you forget it there?

2 Likes
3

If you work with a really large™ document and everything is getting super slow (maybe because of many tables or graphics and complex layout), you might you want to compile single chapters while you work on them.

This can in principle be done by compiling just the chapter file – if it weren’t for references to sections/equations/… in other chapters.

A handy thing that can help you out here is adding this

#let no-ref(it) = {
  show ref: _ => [[?]]
  it
}

to your template. By writing

#show: no-ref

at the top of a chapter (right after importing the template), you can replace all references with a dummy temporarily.

Indeed, you can add this always to all chapters and just comment out the line show ref: _ => [[?]] in the template file when you want to go back to the full document.

1 Like
4

I forgot the star. Thank you for making me notice!

5

This is no longer required in 0.12.0, as unknown references were downgraded to warnings, although this still helps to avoid the slew of warnings that may spam your diagnostic screen.

EDIT: I was wrong, it appears that this was not added in 0.12.0 for some reason.

1 Like
6

Nice! I had seen some discussion about this but I had thought that in the end, the behaviour wasn’t changed

Thanks for letting me know

7

You were right, I’ve updated my post. I wasn’t aware of the discussion to not go through with it, could you link this if you still have it?

8

Here it is Downgrade missing references and citations from errors to warning by laurmaedje · Pull Request #4974 · typst/typst.

Maybe this should be configurable.

1 Like