Flexible preamble/postamble architecture

[rm-dr]

The current tectonic -X new preamble/main/postamble document organization is promising, but it's a bit limited.

My use case:

I often write handouts, which come in two versions: just problems, and problems with solutions. This is implemented with some flags in a custom document class. In short, \documentclass[solutions]{handout} shows solutions, and \documentclass[nosolutions]{handout} hides them.

Using Tectonic.toml with two output configs allows me to compile both versions with one command. That's pretty cool. However, my approach is a bit hacky: in order to avoid having two copies of the same preamble which differ at only one line, my preamble tex files only include \documentclass, with the rest of the TeX preamble in index.tex.

If I wanted to do anything more complicated, I'd have an awful mess on my hands.

A possible solution:

Instead of limiting users to three input files (preamble, index, postamble), we could instead implement an array of input files that would all be concatenated when compiling the final document. Something like the following:

[[output]]
name = "solutions"
type = "pdf"

# The following replaces preamble, postamble, and index.
# These files are read in order on build.
inputs = [
    "header-solutions.tex",
    "preamble.tex",
    "main.tex",
    "postamble.tex"
]

This also improves compatibility with traditional single-file LaTeX. Instead of hackishly setting preamble="" and postamble="", one could just set inputs = "bigfile.tex" and be confident that nothing will break.

This could even be extended to support single-line inputs, to remove the need for many tiny files:

# mixed-type arrays are allowed in the TOML spec, but Rust doesn't seem to like them
# Edit: THIS IS FALSE. See my comment below.
inputs = [
    "preamble.tex",
    {type = "raw", text="\\nosolutions" },
    "main.tex"
]

# Maybe a stringly-typed approach?
# I don't love this, it's a hack.
inputs = [
    "preamble.tex",
    "text:\\nosolutions",
    "main.tex"
]

Note: I have a working demo, but I won't PR until we decide if (and how) we want to implement this.

[esselltwo]

Would allowing Tectonic to pass options to the document class be a good solution? I think this increased flexibility would be good for other reasons, but it could be good to have a simple way to also produce an output with "draft" enabled, for example.

[rm-dr]

I think I'd prefer a simple "input array" solution...

• it's easier to implement, more transparent, and makes fewer places for bugs to hide
• it's more powerful. Documentclass options do a good job solving this specific problem, but they won't help with any other use case.

[pkgw]

Hi @rm-dr,

First off, sorry for taking so long to reply!

I think this idea has a lot of promise. It's clear that the current preamble/postamble approach is, at best, polarizing, and this feels like a nice generalization. I also think that you're on to something with the idea that "inputs" could be things besides files; either lines of raw text or potentially other pseudo-files.

Something that I've thought of, that might be another piece of the puzzle, is a sort of "dynamic" use of the preamble/postamble: the engine could test if the preamble/postamble files exist, and only include them in the build sequence if they exist. Then, in the current framework, if you don't like the the preamble/postamble you can just delete them. I'd be OK with making it the default to have tectonic -X new not even generate them, so that new projects seemed to just have a single entrypoint file.

There's no reason this idea and yours couldn't go together, I think. So, the default inputs could be a list of preamble / index / postamble, but if any of those are missing, they're just skipped.

OK, the more I think about your idea, the more I like it! It's too bad if Rust's TOML implementation has trouble with mixed-type lists, although I can understand how the type system might cause that. It might be worth thinking about ways to implement that kind of functionality that are compatible with the crate; maybe something like this?

inputs = ["pseudofile", "src/index.tex"]

[inputinfo.pseudofile]
text = "\\nosolutions"

[rm-dr]

# mixed-type arrays are allowed in the TOML spec, but Rust doesn't seem to like them

I just tested this again, and it seems that these do, in fact, work. Oops.
It's just a bit tricky to make this work in serde.

Tables as inputs could now be a viable option!

[pkgw]

Good to know, thanks!