How does this toolkit work?

[denismaier]

Hi, this project looks really promising and I'm trying to figure out how it works. Especially, I'm wondering what is the status of the CLI in Rust here? IIUC, most of what is happening here, is controlled by a makefile, right?

Background: I'm the managing (technical) editor of the journal Judaica, and I have set up a workflow using pandoc, ConTeXt and a couple of python scripts, lua filters, and xslt transformations, all held together by a makefile. Nowhere near what casile seems to provide, but anyway... I will now try to revise the workflow (especially to make it more flexible), and therefore I'm also trying to learn from other's solutions to similar problems.

[alerque]

CaSILE started out as just a Makefile that could be copied into a project. That turned out to be unmaintainable, and it evolved into a whole suite of things that could be added to a project via a submodule. As it grew that turned out to be unmaintainable too (especially since it was hard to get everything running in a remote CI runner), so it turned into a stand alone project. Notably since one packaging option is now a Docker container with all batteries included, you can combine a project with source files and the Docker image to build everything remotely.

The CLI is does a few things, but most of what it does is provide a wrapper that calls make with all the paths and resources setup to wire up a local project to the CaSILE install (whether system local or Docker). It is very complicated to call make directly with all the right rule files and environment variables. The CLI takes most of the fuss away and makes sure all the right variables and include paths are there on each invocation. The rest of argument are eventually passed directly to make: casile make -- <TARGETS and/or make ARGUMENTS here>.

If you've already started down the Makefile path, what you'd want to do is convert it to a casile.mk file that will get automatically added in the right order to mix in your additional variables/targets/recipes. Additionally you'll want to substitute any targets you've made that are redundant with CaSILE's built in targets.

One drawback to this approach is that make does not allow you to override existing recipes. What you can do is add new ones, and avoid overlap with target names CaSILE handles automatically. This is usually not an issue since it builds all intermediary artifacts between the source and final name in a cache directory out of the way of your project. Also for some of the targets that you may want to customize there are usually hooks of some kind or other ways to inject customization in an existing recipe (such as adding Lua filters to Pandoc conversions).

I'd be happy to answer more specific questions about the porting process. Are your sources posted publicly?If not can they be?

[denismaier]

Thanks you very much for your response. That's very helpful. I actually did not plan to migrate to CaSILE or to another existing build system. I don't use SILE, so I'm not sure that would make much sense. Or would it? (I've wanted to take a look a SILE quite for some time, but I never managed to do so. Should do at some point probably... ) OTOH, would it be possible to integrate other build targets to CaSILE?

Basically, I'm trying to understand how others build such systems. I have basically two goals/challenges:

1. I want to be able to make changes to my source documents as long as possible, and as easily as possible, i.e., no "once we're in typesetting mode only minor changes are allowed". From your readme, I think you've had a similar goal. Currently, my setup allows me to go straight from markdown or jats xml to pdf and html. So I can edit the markdown or xml sources really until an article is ready, which is nice.
2. I need a proper inheritance setup, i.e., I want to define some sort of general layout for a journal, a book series, etc., use them in an article or a book, and maybe define additional elements only for a particular article, book, etc.

The first goal is mostly accomplished, although I might want to add some way to mark a certain step in production as complete. E.g., in most cases I go directly from markdown to pdf, producing the xml files only as intermediary artefacts. In other cases though, I need to make edits in the xml files since some things are easier to express there than in the markdown. So I would like to prevent accidental overrides by invoking the wrong recipe.

The second goal is only partly accomplished. I have a working inheritance setup, but every article reuses the complete setup of the journal. If a new article needs a new element, I just add it to the global environment, maybe using some namespacing construct. Until now, that was really a problem, but it's already really messy and it could get problematic at some point.

Any hints regarding these issues? How would you solve that? I was thinking about creating a similar tool like CaSILE for my purposes, maybe with a nice CLI interface written in Go or Rust (but see below), or perhaps using an established build system like Rake, which should be quite a bit more flexible and less archane than Make.

My sources aren't public, mostly because they are not sopisticated enough. It's currently just a standard makefile that get's included into a distinct makefile for each article. I've created a gist: https://gist.github.com/denismaier/beab4953c9ad6825e7b0d98bee081a00

Another question: Why did you choose Rust for such a tool? I was also intrigued by Rust as a language, but my first guess would be to use something simpler for such a tool. What was your experience using Rust here?