Every time there is a conference I have to fill some paperwork. To make my life easier (it is already short), I’ve made some simplifications that work for me.
Everything is in the folder
_priv of this blog. There is a
Makefile that accepts these parameters:
- optional, defaults to current year
- optional, defaults to current mont
Using the make command creates a folder
$(YEAR)/$(MONTH)/$(DAY) with two source files:
GB.yaml, a structured form describing the conference or mission
letter.md, with the content of the cover letter
The files are created only if they did not exist before. Calling make again produces the final documents
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
... 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
pandoc GB.yaml --template GB-template.md -t markdown | pandoc --reference-docx=reference.docx -o output.docx
Once the text files are complete, doing make again creates
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 (
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.