Best way to structure multi-volume works

Questions
, ,
1

I am writing a language teaching-learning curriculum with Typst. The expected output is multi-volume / multi-format (vastly different layout: book-like layouts and slides)

  1. a curriculum (driven from external data source)
  2. a dictionary (driven from external data source)
  3. a teacher’s guide
  4. teacher’s slides for lessons
  5. a student’s workbook

These are tightly coupled to one another (e.g., the teacher’s guide may reference (curriculum) “Skill 3.2” and “page 65 of student’s workbook” and these numbering are dynamic). This will take up three years of my life, so I want to investigate some manageable way of handling the typesetting, so I can “just write”.

I can see this being done in one of two ways:

  • single document, post-process splitting. I’ll keep page numbers for each work in separate indices, and cut up the PDF manually.
    • (+): all references are internal references
    • (-): no way to change document type (i.e., touying slides have to be managed separately). Typst had been extremely fast for me even on large complex documents, so I think the friction from compiling all documents every time is negligible.
  • external index. Each output is its own Typst file, and at each typeset run there is also an external index being written to and referenced from.
    • (+): flexibility for each document
    • (-): I think this introduces lots of room for error, dependencies becomes cyclic etc.

I’m leaning towards a single document, and handle irregular materials manually at some later stage. Thoughts / suggestions / comments on considerations entirely amiss?

1 Like
2

The single-document approach seems impractical, since you would have to split up the resulting PDF afterwards.

As far as I know, it is not possible to reference labels that are outside of the document typst is compiling at one time. Some kind of shell escape would be necessary to query from other typst files.

You might want to have a look at Prequery

3

Years before I found out about Typst, I tried to do something very similar and never found a suitable solution. You might try looking into the sys function, though.

There is definitely good reason to keep it all in a single document if possible. It reduces the opportunity for drift between views and versions.

Assuming you are using the command line compiler, you might be able to use --input view=guide to pass the view variable to your Typst file. From there, use conditionals to decide what to print and where.

There are trade-offs, of course, but if you want to keep it all in one file, I think passing parameters through the command line would be the easiest way to do it.

1 Like
4

Thank you @wjdenny and @Mario. I’m coming from a LaTeX shell-escape-everything background, and didn’t think about the tight sandboxing.

Passing variables from the CLI is also new to me. Splitting up PDFs from a file is usually manual (from Adobe Acrobat), but reliable and not difficult; however CLI variables might make it possible to write a little bash script to render multiple formats of multiple documents in one command.

My sense is that this is somewhat uncharted territory. I’ll try to blog about the experiments and final approach.

2 Likes
5

Re that, the Typst compiler can easily be told to only output a subrange of pages:

$ typst compile --help

      --pages <PAGES>
          Which pages to export. When unspecified, all pages are exported.
          
          Pages to export are separated by commas, and can be either simple page
          numbers (e.g. '2,5' to export only pages 2 and 5) or page ranges (e.g.
          '2,3-6,8-' to export page 2, pages 3 to 6 (inclusive), page 8 and any
          pages after it).
          
          Page numbers are one-indexed and correspond to physical page numbers
          in the document (therefore not being affected by the document's page
          counter).

together with typst query, you should be able to first determine what documents are at what page ranges, and then typst compile a few times for the individual ranges. That will probably take a bit longer than only compiling the whole document ensemble once, but still be quicker than doing the splitting multiple times.

I don’t think single document is a super clean way to go about this, but all things considered probably still the easiest one. Personally I don’t think (as the author) that Prequery will get you a lot here; it does give you something similar to shell escape, but since your documents would mutually depend on each other, it still sounds complex.

I’m not certain that’s true. If you can handle bibliographies, outlines, states, counters and similar “global” things properly, Touying should likewise work. As long as you have a separate scope for your slides (i.e. #show: your-theme is in its own file/ a [] or {} block), it shouldn’t impact the rest.

My biggest concern would be that this compound document would not converge because of the many different layout needs and state updates, or that it would be slow because of Touying slide animations.

1 Like