Slight aside...today I received a pdf that was 90 degrees from being correct on screen in Adobe reader, and I clicked on the 'rotate' button to find that Adobe has made this a subscription feature!
I'm used to seeing markup languages (ab)used as configuration languages, but this is the first time I've seen markdown used that way. Though the input has a lot of links, so it makes sense in a way.
I haven't used Pdftk for some of the things detailed in the article, so I don't know: other than being declarative, what's better about this than Pdftk? I've always been able to use Pdftk for my needs, and it satisfies picky publishers' tools that barfed on other ways of achieving my goals.
For complicated tasks (say merging two PDFs, one of which needs to be upscaled and rotated) - it will take a dew attempts. And if this ends up being a repetitive task, you can commit the markdown file to code, which explains the intent much better than pdftk’s command line arguments.
I've tested it against a 800 page compilation and didn't face any issues : https://github.com/captn3m0/pdp-book. Takes ~2 seconds for a fresh build on my system right now.
time pystitcher --verbose complete.md output.pdf
[2021-12-31 00:00:48] INFO:pystitcher.stitcher:Deleting temporary files
real 2.244 user 2.160 sys 0.063 pcpu 99.07
I've run it against entr[0] for live-recompilations, and it was pretty good.
If you unwrap the covers a bit more behind the terminology it becomes a little more clear when to use what terms (and what they imply).
Terraform and Make implement declarative domain-specific programming languages. They have their own data types and primitives, including a syntax, grammar, operators, functions, etc in order to create a new interpreted program in a higher order language.
Your tool seems to use Markdown as a format to set variables for your program to use in creating a document, and then an ordered data set which is converted into new object types and rendered as a pdf, in combination with the previously set variables.
You can separate the variables as command-line options or include them with the data set, but either way they're not creating a new program, they're using your program's existing logic. Plus, your file format doesn't have the properties of a language. So this would be called a configuration file (or 'input file' since it's sort of data + configuration) rather than a programming language or configuration language.
Not a huge distinction from the user's perspective, but it actually is important in terms of your program's design. For example, if you did want to implement a language, you don't want to implement it as some other format, like YAML (a data serialization format) or Markdown (a document markup format). Languages work best with their own parser/lexer/format and thus avoid all the inherited pitfalls and limitations of a different file format.
'Declarative' is used mainly in terms of languages because it's distinct from 'imperative' where you execute one statement at a time. If you don't have a language, you could still have imperative/declarative if your program either executes one task at a time, or has advanced logic that tries to predict what might happen and changes its operation accordingly. And you can actually do both in the same program, making the whole thing more confusing!
I do like your idea of embedding options/variables in your dataset! It's a slick way to allow more reproducible results and a simpler user experience.
> So this would be called a configuration file (or 'input file' since it's sort of data + configuration) rather than a programming language or configuration language.
The readme calls it an input file. ("declarative input in the form of a markdown file"). It never claims to be a DSL or a programming language, just calls the input declarative. "Declarative" is a bit of cop-out, but I want a way to showcase that it is different from a standard YAML config that would only take the variables part - it defines the end state, and is just an alternate representation of the final PDF in a way.
Wikipedia defines declarative as:
>a style of building the structure and elements of computer programs—that expresses the logic of a computation without describing its control flow.
I'm just using it in a sense closer to configuration management systems (so declarative config) - similar to how something like Ansible would call its configuration YAML files (`apt: [a,b,c]` is a declarative config).
