Show HN: Pystitcher – A Declarative Alternative to Pdftk
github.com
github.com
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
You mean a markdown formatted config file. All config files are declarative; an imperative config file would be bizarre.
It’s close to a Makefile in intent that way (which I wouldn’t call a config file).
Other tools end up with confusing CLI args as a hacky config.
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.
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).