Automatic bureaucracy

How the letter is made

There are a couple of nice tricks used to create these files. It can be useful to report them here.

First, the cover letter is essentially a regular markdown document that will be transformed into PDF using LaTeX, such as this:

---
opening: Dear Professor,
closing: Sincerely,
address:
 - Director
 - Molecular Biology and Genetics Dept.
 - Faculty of Science
 - Istanbul University
...

On DATE, YEAR, the conference CONF will be held at PLACE. My paper has been accepted and I need to attend to the conference to present it.

---
fontfamily: palatino
letterhead: Templates/letterhead.pdf
papersize: a4paper
author: |
  Andrés Octavio ARAVENA DUARTE  
  Assistant Professor
compiling: pandoc test.md --template=template-letter.tex -o test.pdf
...

The first YAML section provides the generic text for the letter package in LaTeX. I expect that this part may change often. The second YAML is mostly about the style of the output document. It includes a header (which I prepared separately) and a comment on how to compile the final document. As usual, all the magic is done by pandoc.

In general only the content should be updated, although in some cases also the header should be updated. At least it should include the name of the Director. Notice that some lines, such as the author name, include two spaces at the end to force a line break. Do not delete them.

How the GB form is done

This one is a little more tricky. The final document is a Microsoft Word file (puagh!), which is created by pandoc using the template reference.docx. That is pretty standard. Just remember to use

pandoc --reference-docx=reference.docx -o output.docx

The novelty is that the markdown document itself is created from a YAML file. Since I do not want to ask the same question every time, I translated all options from the Turkish original document, which is the base of the GB.yaml file. The first lines are:

---
name: Andres Octavio ARAVENA DUARTE
title: Yrd. Doç.
dependency: Moleküler Biyoloji ve Genetik Bölümü
department: Moleküler Biyoloji ve Genetik Bölümü
degree: ". . . . . . "

permanent: "()"
temporal: "(X)"

and the last lines are

title_of_work: ". . . . . . "

comment: 
  - The application shall be submitted in two copies.
  - Append Appointment application form, invitation document, meeting announcement or program.
...

Notice that all the document is wrapped in --- and ... to make it a valid YAML for pandoc but not to Jekyll.

So, here we use pandoc as a YAML processor that fills a template, produces a markdown document, which is then fed again to pandoc to create the final output.docx.

pandoc GB.yaml --template GB-template.md -t markdown | pandoc --reference-docx=reference.docx -o output.docx 

Final details

Once the text files are complete, doing make again creates letter.pdf and GB.docx. Usually I open this last file and make some minor corrections. I change the width of the columns on the signature table and add grid lines. Then I print the file into PDF, and sign it.

Everything is saved on the git repository, locally and on cloud servers (github.com and bitbucket.org).

Future

Looking back, now that I’ve done more document pipelines, I thing that the YAML sections can be moved to a separate file. At least the parts that will not change, such as the fontfamily or the opening and closing.

It is a fortunate coincidence that pandoc accepts YAML sections ended with three dots (...), while Jekyll does not. That means that the source files will not be processed by Jekyll.

Since the documents are very standard, it is probably a good idea to update the template-letter.tex and include the defaults for fontfamily, papersize and letterheader. Maybe even author.

The GB document can eventually be remade on HTML. The submission process only requires paper documents, as if we were still on the 20th century. Then it is possible to create the document on HTML, print it to PDF, and eventually put a signature using MacOS Preview.