Template inheritance

[DreamerPhi]

Hello,

I’m struggling to define templates for my different documents types, such that they inherit from the definition of a more general template.

In concrete term, what I want is to be able to have one general template document doc-template.typ such as:

#let template(
  doc_title: [],
  author: "",
  doc
) = [
  // Some template rules
  ...
]

One other template document my-doc-template, that inherits from the previous one, but fixing some of its arguments and adding new rules:

#let my_template(
  doc_title: [],
  doc
) = [
  // Definition of the template inheritance
  #show template.with(
    doc_title: doc_title,
    author: "DreamerPhi",
  )

  // Definition of the new template rules
  ...
]
 

And finally being able to use this second template in a document my-document.typ:

#import "my-doc-template.typ": my_template

#show my_template.with(
  doc_title: [My document title],
)

Thanks in advance!

[JosephTao]

Hi. As far as I know, it is difficult to arbitrarily adjust the behavior of the inner template. For example, if a fixed font size/color is set in the inner template.

// template.typ
#let template(
  doc_title: [],
  author: "",
  doc
) = [
  #set text(fill: blue)
  Title: *#doc_title* \
  Author: *#author* \
  #doc
]

// my-doc-template.typ
// import "template.typ": *
#let my_template(
  doc_title: [],
  doc
) = [
  // new rules (not working)
  #set text(fill: maroon)

  #show: template.with(
    doc_title: doc_title,
    author: "DreamerPhi"
  )

  #doc
]

// main.typ
// import "my-doc-template.typ": my_template
#show: my_template.with(
  doc_title: [My document title],
)

Content

[maucejo]

You may have a look at community-cnam-thesis which is built on top of bookly.

[ensko]

Not necessarily a thread with concrete answers, but a lot of relevant discussion:

Overriding template parameters; missing social convention or Typst design flaw?

TL;DR: in my experience it is difficult or impossible to “tweak” Typst templates to change some layout policies without copying and modifying its source code. Is it just that we are collectively bad at writing templates, or a fundamental design flaw or missing feature in the Typst language? Context I’ve been using Typst for various documents for a few months now (free-form documents, talk slides, more structured document looking like math research papers). My experience is that “packages” work …

[gasche]

@JosephTao

Hi. As far as I know, it is difficult to arbitrarily adjust the behavior of the inner template. For example, if a fixed font size/color is set in the inner template.

I suspect that for Typst beginners it may not be completely clear what you mean. Your version has the following:

#let my_template(
  doc_title: [],
  doc
) = [
  // new rules (not working)
  #set text(fill: maroon)

  #show: template.with(
    doc_title: doc_title,
    author: "DreamerPhi"
  )

  #doc
]

With this version, #set text(fill: maroon) is called before the parent-template logic (which has #set text(fill: blue)), so the parent-template logic will take precedence and all the text will remain blue. It is also possible to use the other order:

  #show: template.with(
    doc_title: doc_title,
    author: "DreamerPhi"
  )

  #set text(fill: maroon)

  #doc

With this version, the text input by the user (“Content” is in example) will be maroon (given that it has seen this set-rule “last”, shadowing/hiding/replacing the set rule from template.with), but the title will remain in blue – and with the current document structure there is no easy way to change the color of the title, which I think is the point you were making.

[gasche]

I looked at the bookly package to try to understand how it enables modularity. (Minor point: I wonder if you @maucejo considered providing a HTML build of the manual, which would be convenient from a browser. I gave up trying to browse the PDFs and went to read the Typst sources directly.)

I collected the following aspects as related to modularity:

• The obvious: the main template provides plenty of options. This is good but:

  • it does not scale super well, and users typically want to tweak something we forgot to make an option
  • if I remember correctly, when we do this it is tempting for intermediate packages to define “my preferred set of overrides for these parameters”, and Typst does not have language features to make this convenient (for example: it is possible to merge dictionaries with +, but this is a shallow merge when in fact we want a deep merge also merging sub-dictionaries)

• Another approach you use is to make a lot of things convenience functions, provide as many functions as possible. (Ideally the main part of the template is mostly a composition of these convenience functions, and people interested in creating a derivative can reuse these compositions and tweak them without having to copy-paste too much logic). I think that it is important, and tends to come with the experience of trying to keep things tweakable.

[maucejo]

Actually, bookly is not necessarily the good entry point. community-cnam-thesis is better in this respect. Bookly does not aim to cover all the needs and standard Typst can be used for fine-grained tuning. When users want a feature that can be easily implemented outside bookly, I encourage them to do so.

(Regarding your question about a web documentation, I thought to create one after having written that of slydekit. But it won’t be done soon).