Add parameter to select pages to be exported by CLI

[PgBiel]

Closes #3095

Adds the --pages parameter to typst compile and typst watch which allows selecting which pages should be exported by the CLI. Supports all export formats (PDF, PNG, SVG).

• Syntax:

  • Simple: typst compile --pages 5,6,11 a.typ a.pdf to export a PDF with just pages 5, 6, 11.
  • Ranges: typst watch --pages 11-13,15- a.typ a-{n}.png to export pages 11 to 13 (inclusive), as well as any pages after page 15.

• Implementation:

  • Had to refactor typst-pdf in several places to consider non-exported pages. Changed ctx.pages to Vec<Option<EncodedPage>> to preserve the relation between indices and real page numbers.
  • For PNG and SVG, the implementation was trivial, since each page is a separate exported file.

• Decisions:

  • (PDF) Should non-exported headings be excluded from PDF bookmarks? Currently, I have excluded them, as this seems to make sense (otherwise they would be broken links).
  • (PDF) The PDF's xmp.num_pages metadata should only contain the amount of exported pages (and should thus always correspond to the number of pages in the actual PDF, not necessarily in the original Typst document), correct? (I have assumed so for now)
  • (PNG/SVG) When using exported-name-{n}.png (for example), should {n} correspond to the real page number in the original typst document? (i.e. with --pages 5,6,7 you'd get name-5.png, name-6.png and name-7.png instead of name-1.png, name-2.png and name-3.png) I've assumed so for now as well, as I'd say this would be expected.

• TODO:

  • Support ranges in --pages
  • Recheck PDF changes
  • Undraft

[laurmaedje]

Syntax looks good. It should be the same as in the web app.

When using exported-name-{n}.png (for example), should {n} correspond to the real page number in the original typst document? (i.e. with --pages 5,6,7 you'd get name-5.png, name-6.png and name-7.png instead of name-1.png, name-2.png and name-3.png) I've assumed so for now as well, as I'd say this would be expected.

I agree that it should be name-5.png etc.

[PgBiel]

I noticed something interesting: without page labels (custom page numbering), the PDF page numbers (in the outline or otherwise) do not correspond to their real page numbers in the original Typst document. Consider the document below compiled with --pages "1,2,3,4,8-10", where each page has a "Bruh" heading:

1. Without page labels - Okular PDF reader shows 5,6,7 (real PDF page number) instead of 8,9,10 (page number in Typst).
   

2. With page labels - Okular PDF reader shows h., i. and j., matching how Typst displays page numbers, although the real PDF page numbers are kept and displayed separately.
   

Same happens for other PDF readers, e.g. in Firefox. The default, if Typst doesn't specify custom page numbering labels, is to just display the real PDF page number instead of the Typst page number.

I wonder if there's much that can be done about this, e.g. always specify page labels if some pages are excluded from exporting. But perhaps we could consider this to be "intended behavior" in a way. Or maybe it's just not worth it to fix this / could fix later (doesn't seem to be that bad of a problem).

[laurmaedje]

always specify page labels if some pages are excluded from exporting

That might make sense indeed, especially since it already happens if a numbering is specified.

[PgBiel]

Alright, I've implemented this, though there are two important notes (and thus potential design decisions):

1. I noticed that, when page numbering was enabled by the Typst document, the page numbers used for the labels are the logical page numbers, not the real page numbers. When page numbering is disabled, however, the page numbers used are always the real page numbers (since just the PDF's final page numbers are used, given no labels are added). In my implementation of adding labels to pages without numbering after non-exported pages, I added labels with the real page numbers, not logical, for consistency with the case of no page numbering. But let me know if that wasn't the right choice.

2. Consider the situation where the first N pages were exported, but page N + 1 wasn't exported, so pages N + 2 and onwards have PDF page numbers which don't correspond to their real page numbers in the Typst document (as shown in my last reply). The solution I implemented was to add labels to pages N + 2 onwards with their respective real page numbers in Typst. However, there was one thing I wasn't sure about: should I have added labels to the first N pages too (redundant labels, equal to the final PDF page numbers in every way) just for consistency? Initially I experimented with doing so in 0ffac2e, but ended up reverting it because it felt unnecessary. Therefore, only pages N + 2 onwards are labeled (just to fix the problem of "drifting" page numbers after non-exported pages). Let me know if this wasn't the right choice as well - I see arguments both in favor (consistency with setting page.numbering from the start, and consistency with the remaining pages) and against (not being necessary since the labels are fully redundant) labeling the first N pages, so I can see this going either way, haha.

[laurmaedje]

Your choices sound fine. Thank you!