4 ms·

"using a declarative input in the form of a markdown file" You mean a markdown formatted config file. All config files are declarative; an imperative config fi

"using a declarative input in the form of a markdown file" You mean a markdown formatted config file. All config files are declarative; an imperative config file would be bizarre.

captn3m0 5y ago
I need to rephrase this, but I mean declarative like Terraform here - you specify the end state, and don’t worry about how to get there. 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.
- throwaway984393 5y ago
  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.
  - captn3m0 5y ago
    > 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).
    - throwaway984393 5y ago
      Well you can call it anything you want, I'm just saying it looks weird to call it declarative when you're not describing either control flow or logic.

"using a declarative input in the form of a markdown file" You mean a markdown formatted config file. All config files are declarative; an imperative config file would be bizarre.

captn3m0 5y ago

I need to rephrase this, but I mean declarative like Terraform here - you specify the end state, and don’t worry about how to get there. 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.

throwaway984393 5y ago
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.
- captn3m0 5y ago
  > 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).
  - throwaway984393 5y ago
    Well you can call it anything you want, I'm just saying it looks weird to call it declarative when you're not describing either control flow or logic.