Markdown support (with pandoc)

[quinn-dev]

First of all, I really like your template, great work!

I personally like to write my letters in Markdown and use pandoc together with a template to compile them to beautiful, well-formatted PDFs. This is made possible by pandoc's template syntax, which parses data from a markdown file's YAML frontmatter and places it within the document.

As an example, setting the sender's name using pandoc and YAML works as follows:

1. Replace the sender's name with the sender.name variable in your LaTeX file:

\newcommand{\ownname}{$sender.name$}

2. Mention a sender.name entry in your markdown's YAML frontmatter:

---
sender:
  name: Vorname Nachname
---

...text...

An entire IFG letter written in Markdown may look like this:

---
sender:
  name: Vorname Nachname
  address:
  - ExampleStreet 42
  - 12345 Stadt
  email: [email protected]
  phone: "+49123456789"
  url: http://test.de
receiver:
  - Informationstechnikzentrum Bund
  - Bernkasteler Straße 8
  - 53175 Bonn
date: 24. April 2021 # defaults to today
place: Stadt
location: Stadt
request:
  title: Informationsanfrage zu Beispieldaten
  number: 123456
  mail: [email protected]
  uploadToken: copytokenforuploadhere
  date: "01. Januar 2021"
  noticeDate: "01. Februar 2021"
  noticeRef: "123456#EXAMPLE#0042"
  docNr: "123456#EXAMPLE#0042#0004"
---

# Sachverhalt

...

# Begründung

...

I have not created a PR yet since I first wanted to ask whether this feature could be incorporated into the project.

Since every variable used needs to be referenced in the LaTeX template, the template gets much more complex and becomes less suitable for manual editing. An example of what this looks like can be found here.

Further limitations of this approach:

• Only a predefined set of values can be changed. If someone wants to change the structure of the document, they need to do so in the LaTeX template.
• If the resulting PDF files need to be reproducable, the LaTeX template used needs to be versioned in so far it is subject to change. Since these letters of appeal are meant to be submitted to Frag den Staat, "losing" and therefore having to reproduce a letter is unlikely.
• If the underlying template is updated and includes breaking changes, old Markdown files may not correctly compile or may not compile at all.

I personally think that writing a little markdown with some frontmatter on top is much more enjoyable and quicker than dealing with seperate LaTeX files for every appeal and the limitations above are fairly manageable.

Do you think it makes sense to incorporate such a feature into this project, or is it out of the project's scope?

[rugk]

Thanks for your suggestion and first raising an issue!

I also see the advantages and it looks clearly as a simpler way to write these letters.
So, generally, I’m quite open about that feature.

---

Now as for the technical part, you’d likely also would want to remove this mail merge stuff when doing this:
#6

And I would question how the references and footnotes would still work? Could you still reference things easily and make footnotes etc.? For an example see this text here.
That would be my biggest concern, that this does not work anymore. Everything else is, IMHO, not so bad.

Also how can you enter \, in Markdown, i.e. small spaces? They are quite nice and I use them for separating paragraph symbols, i.e. §\,1, which looks typographically much better.

---

In the end, maybe we could make two versions? One LaTeX-only and one for pandoc+LaTeX?

Or just use the LaTeX template and adjust it somewhat (I mean you only have to replace these variables, don't you?)

One other advantage though: It would make it way easier to copy that text as plaintext into the FdS text field, as Markdown is likely already quite readable. 😃

[quinn-dev]

And I would question how the references and footnotes would still work? Could you still reference things easily and make footnotes etc.? For an example see this text here.
That would be my biggest concern, that this does not work anymore. Everything else is, IMHO, not so bad.

Footnotes are supported in Markdown and generally work fine with pandoc and LaTeX.

Also how can you enter \, in Markdown, i.e. small spaces? They are quite nice and I use them for separating paragraph symbols, i.e. §\,1, which looks typographically much better.

Using Pandoc Lua Filters, an \, could be added automatically after the § sign if it is followed by a number, thus the user wouldn't need to worry about this aspect of the formatting.

Or just use the LaTeX template and adjust it somewhat (I mean you only have to replace these variables, don't you?)

In principle, we only need to adjust the existing LaTeX template to support pandoc's template variables, but the resulting LaTeX file will look quite messy to anyone manually editing the LaTeX template.

This is how most fields would probably look like:

\setkomavar{fromaddress}{
        $for(fromaddress)$
            $fromaddress$$sep$\\
        $endfor$
       % Enter address below
}

Editing the fields manually could therefore become confusing for people who intend to use the LaTeX template without pandoc. Furthermore, I'm unsure how some LaTeX editors and compilers handle pandoc's templating syntax, but I assume they would assume it's invalid LaTeX and throw an error during compilation.

In the end, maybe we could make two versions? One LaTeX-only and one for pandoc+LaTeX?

Making two versions would probably yield the best results, but would require additional maintenance effort (every change in the LaTeX template would need to be adjusted to pandoc's template syntax and be manually merged into the pandoc template). Nonetheless, I don't see any better opportunity.

I'll try to create a pandoc-supported version of the LaTeX template. One question upfront: Should I use German language or English language variable names? On one hand, the LaTeX template itself is commented in English - on the other hand, the project itself currently only supports the German language. Edit: It's also possible to support variable names in both languages.

[rugk]

Thanks, regarding the first problems this is great to hear.

As for the variable names, I'd say use English, it's somewhat of "code". I quite liked the names in your original example.