Contract macros¶

The LaTeX body of a document comes from tmark's writer, which emits a fixed macro or environment per construct. Structural constructs (emphasis, lists, headings, figures, tables, links, footnotes) are plain LaTeX the writer owns; the constructs a template may want to restyle are contract macros provided by the ts-* fragments. The writer names the fragment in Requires.fragments; the fragment defines the macros; a template restyles a construct by redefining its macro.

The table of contracts is tmark.fragments() (FRAGMENTS in tmark_ir::registry); the names follow one convention: macros \ts<name>, environments ts<name>, at most one optional keyval group first, content last. Keys are parsed with pgfkeys under /ts/<name>/ and unknown keys are ignored, so an older fragment survives a newer writer.

The macros¶

Identity: for a contract macro the writer passes id=; the fragment places \phantomsection\label. Attributes of a container are forwarded as keys (#id → id, classes → class={a,b}, key=val as is); lang and media never are.

The Typst writer emits one hyphenated function per contract (#ts-callout, #ts-code, #ts-keys, …) with the same argument names, defined in src/texsmith/templates/common/texsmith.typ. That library is inlined ahead of the body in the generated .typ, so the file compiles on its own; a Typst template redefines a function after it, as a LaTeX template redefines a macro after \VAR{extra_packages}.

Overriding a construct¶

Three levels, in the template's .tex after \VAR{extra_packages} (the fragments are \usepackaged there):

1. Restyle through the pgfkeys family. tscallout and tscode are tcolorbox boxes; the family style is appended to their options, and a class named in class={…} applies /ts/<name>/class/<class> when it is defined:

   \tcbset{/ts/code/.append style={frame hidden, boxrule=0pt}}
   \tcbset{/ts/callout/class/wide/.style={grow to left by=2cm}}
   

2. Redefine the macro, same signature.

   \RenewDocumentCommand{\tscodeinline}{O{}m}{\mbox{\texttt{#2}}}
   \RenewDocumentCommand{\tsdivider}{}{\bigskip\hrule\bigskip}
   \pgfkeys{/ts/rule/.cd, thickness=1pt, width=0.4\linewidth}
   \RenewDocumentEnvironment{tsdiv@multicolumn}{O{}}{\begin{multicols}{3}}{\end{multicols}}
   

   A custom name container is a tsdiv@name environment defined the same way (one optional argument, the raw key list; the parsed keys are in \ts@div@cols, \ts@div@title, \ts@div@id).

3. Replace the fragment. press.fragments: {disable: [ts-code], append: [./my-code.sty]}; the replacement must define every provides entry of its row in tmark.fragments().

Guard a redefinition when the fragment is conditional (ts-code only loads when the document has code): \ifcsname tscodeinline\endcsname … \fi.

Former partials¶

Until 0.6 the LaTeX came from Jinja partials under src/texsmith/adapters/latex/partials, overridable per template (latex.template.override) and per fragment (partials, required_partials). The partials and all three hooks are gone in 0.8.0: the writer names a macro and a fragment defines it. The mapping: