Templates in tectonic -X new ?

[sneakers-the-rat]

Hello! I'm wondering if the maintainers would be interested in a templates feature?

Of course it's possible to copy and paste/symlink everything manually, but especially when you're working on a family of documents it would be lovely to be able to have some parent template for creating documents with tectonic -X new, and even better if it was possible for templates to include each other so there could be one root template and then elaborations for different subtypes of documents.

I see that the project structure is currently hardcoded here:

tectonic/crates/docmodel/src/workspace.rs

Line 119 in 9896567

impl WorkspaceCreator {

So it seems like it shouldn't be too challenging to add an additional flag that just pulls some existing files from another project? And maybe even possible to specify which files in a project are template files in case you want to reuse them? eg.

[[template]]
include = [
    'file1.sty',
    'file2.sty'
]
extends = 'path to another Tectonic.toml'

Just checking if this is something you'd be interested in/had any preference on how it was written. Would be happy to draft a PR if so :)

[pkgw]

Hi,

Thanks for inquiring! (Sorry for taking a little while to reply.) This is definitely the kind of feature that we'd be interested in having.

To give a bit of architectural context, the vision for workspaces is to basically be very similar to how Cargo does things — I'd like to have a model where a "workspace" contains some bunch of Tectonic documents (each defined by a Tectonic.toml) that might refer to each other in various ways. I think it makes sense for the workspace root to also be defined by a Tectonic.toml file containg a special keyword, mirroring the Cargo model as well.

In that general framework, I can think of a few general ways that templates might be implemented. The one that might be the simplest, which I think we have another open issue for, would be to make it so that you could add a workspace directory to a document's file lookup path:

+ (root)
- common/
    - mypackage.sty
- doc1/
    - Tectonic.toml
    - src/
        - _preamble.tex  
        - index.tex
        - _postamble.tex  
- doc2/
    - Tectonic.toml
    - src/
        - _preamble.tex  
        - index.tex
        - _postamble.tex  

.. where both doc1 and doc2 could do a \usepackage{mypackage} and the right thing would happen. I envision that doc?/Tectonic.toml could have a stanza like

include_paths = ["../common"]

The key thing here is that for encapsulation and reproducibility reasons, I would not want to allow the above syntax outside of the workspace framework: all of the files referenced during a document build should either be in a bundle, or contained in its source tree.

I could see how an extends model could also be helpful, e.g. if a whole bunch of documents are going to have a very similar set of output profiles. But I think it would be more challenging to implement. For the use case you're envisioning, would an include-path feature suffice, or do you think you'd need an extends feature?

Regardless, I think that workspace support needs to be pretty carefully designed to deliver a combination of security, usefulness, and scalability — I think that there are actually a lot of interesting use cases that open up if the framework makes it possible to create a whole graph of documents that "depend" on each other like a Cargo crate graph. I'd be delighted to talk through the design process if this is something you continue to be interested in working on!

[sneakers-the-rat]

be very similar to how Cargo does things

for clarity on my experience -- i'm a Rust-curious, dependency-generalist kinda person, so I don't know exactly how Cargo works but am interested in schemes of exact dependency graphs.

I'd like to have a model where a "workspace" contains some bunch of Tectonic documents (each defined by a Tectonic.toml) that might refer to each other in various ways. I think it makes sense for the workspace root to also be defined by a Tectonic.toml file containg a special keyword, mirroring the Cargo model as well.

[...]

.. where both doc1 and doc2 could do a \usepackage{mypackage} and the right thing would happen. I envision that doc?/Tectonic.toml could have a stanza like

include_paths = ["../common"]

This makes sense, and maybe a few parallel ideas/implementations here:

1. it might make sense to make all keywords specify "intra" package structure with perhaps a singular extends keyword that can import from other packages. So you imply hierarchy in what can take/give to what, with self-contained packages being privileged. In this scheme one might imagine multiple Tectonic.toml files per project.
2. Alternatively it might make sense to have a namespacing system that lets workspaces declare an @identifier so that upstream/downstream dependencies could work with relative specs like @identifier:preamble more flexibly
3. Another model would be more like a liquid/jekyll-like template syntax where a template provides specific template files, which can then be overridden like hooks -- eg. you have a /templates directory, and then if you make /templates/colors.sty you can override the color mapping, or /templates/_frontmatter.tex for more general overwriting of the frontmatter structure, etc.

I could see how an extends model could also be helpful, e.g. if a whole bunch of documents are going to have a very similar set of output profiles. But I think it would be more challenging to implement. For the use case you're envisioning, would an include-path feature suffice, or do you think you'd need an extends feature?

I see it in a sort of architectural lens, so like "good for me" is subordinate to "good for the tool." I think encapsulation so that includes would be symbolic (rather than a path), so include a specific 'packagelike' thing, which to me is maybe a simpler way of framing an extends-like syntax (if that makes sense).

I think that there are actually a lot of interesting use cases that open up if the framework makes it possible to create a whole graph of documents that "depend" on each other like a Cargo crate graph. I'd be delighted to talk through the design process if this is something you continue to be interested in working on!

basically this! maybe this is worth having as more of an "open question" design discussion. at least for me as a rust novice i would need a bit more information about the existing structure of the library to know what's possible/advisable :)

[pkgw]

maybe this is worth having as more of an "open question" design discussion

Well, I just recently turned on GitHub Discussions for this repo, and I think you're right, so I'll try converting this to a Discussion and we can see what that flow is like ...

[totikom]

Is it possible to customize _preamble.tex templates for all the projects?

For instance, I use almost identical set of packages and initial setups in all my documents.
It would be quite useful for me to have a ~/.config/tectonic folder with templates for _preamble.tex, _postamble.tex and Tectonic.toml.