Introduction to komaletter

Robert Nuske

2019-08-23

Letters are fairly standardized products and as such lend themselves to be written in Markdown. This package is heavily based on linl but it wraps the very configurable KOMA-Script class scrlttr2 instead of the standard LaTeX document class letter.

komaletter strives to turn a simple R Markdown document together with a layout definition into a beautiful letter (PDF). Layout definitions can be one of KOMA-Script’s standard styles, the package default style or a user defined style. For more details refer to the section Letter Layouts.

Various aspects of the letter can be determined via variables in the R Markdown document metadata (aka YAML header), see Letter settings.

Usage

An easy way to start a new komaletter is to ask for the skeleton document in RStudio via New File > R Markdown > From Template > komaletter or rmarkdown::draft("myletter.Rmd", template="pdf", package="komaletter"). To turn the markown in a beautiful PDF use the Knit Button in RStudio or rmarkdown::render("myletter.Rmd").

The skeleton creates a very simple letter as a starting point for your own writing. Several formatting defaults for font, fontsize, indentation are in use. The following figure shows the complete source on the left and the rendered PDF on the right.

Letter Settings

Various aspects of the letter can be customized via the following variables in the R Markdown document metadata (aka YAML header).

Although it rarely makes sense to write a letter without sender and recipient, a komaletter can be constructed by merely specifying the output format. All other variables are optional.

Most commonly used variables.
Variable Description
author Writer of the letter
return-address Address of the sender; takes a list for a multi-line address.
address Name and address of the recipient; takes a list.
date Custom date; if not specified, current date will be inserted.
subject Subject line.
opening Text for the salutation.
closing Text for the complementary close.
signature Typed signature or image placed below closing.
signature-before Allows adjustment of vertical space before signature.

All variables understood by rmarkdown’s pdf_document format may be used in addition to the komaletter variables defined in the following table to further customize your letter. These variables do not change the placement of elements of the letter (address, letter head, text). For those aspects refer to Letter Layouts.

Further komaletter variables.
Variable Description
lco Letter Class Option File (cf. Letter Layouts).
lang Language code according to BCP 47 (e.g. en or en-GB).
papersize Size of paper eg. a4, letter.
return-phone Phone number of sender used in letter head.
return-email Email address of sender used in letter head.
return-url Website of sender used in letter head.
place Sender’s place used near date.
yourref Addressee’s reference as part of reference line.
yourmail Date of addressee’s referenced mail as part of reference line.
myref Sender’s reference as part of reference line.
customer Customer number as part of reference line.
invoice Invoice number as part of reference line.
cc Recipients to be carbon-copied; can take a list.
encl List of enclosures.
ps Text to be added at the end of the letter as a postscript.
komaoption Specify further KOMA options; takes a list (see KOMA-Script documentation).
parskip Defines how to mark new paragraphs, e.g. full, half, off (see KOMA-Script documentation).

Letter Layouts

The layout of letters is defined in so-called Letter Class Option files. KOMA-Script provides a number of standard styles (see following table). The package comes with a default style defined in maintainersDelight.lco. Users may as well define there own layout.

Styles can be selected via the variable lco in the YAML header of the rmarkdown document. Provide either the name of one of the standard styles listed below or the path to a self defined style without file extension. If LaTeX can not find the lco file, it uses KOMA-Script’s default: DIN. Common errors besides typos are paths with extension, underscores in paths mangeled by pandoc.

Custom lco’s may be constructed either based on one of the standard lco-files or by defining all aspects such as position of the recpients address, foldmarks etc.. For a comprehensive description refer to the KOMA-Script Guide.

Some of KOMA-Script’s standard LCOs.
Country Standard Window Envelope Paper Size lco
Germany DIN 676 DIN lang, C4, C5 A4 DIN, DINmtext
France NF Z 11-001 DL A4 NF
Switzerland SN 010 130 DIN lang, C4, C5 A4 SN, SNleft
United States commercial #9 Letter UScommercial9, UScommercial9DW
Japan Chou/You 3 & 4 A4 NipponEL, …

Internationalisation

It is easy to write letters in non English languages. The necessary language and layout settings can be achieved with the YAML variables lang and lco. komaletter passes these on to the LaTeX template and the nicely internationalized KOMA-Script letter class.

The language can be specified via the two letter code such as en, de, fr, es. Or if you want to be more precise by adding a country en-US for American English or de-CH for Swiss German. KOMA-Script then generates e.g. the date according to language and country conventions.

Beware that you need additional LaTeX language packages if you choose a non English language. Make sure you have the necessary LaTeX language packs, i.e. texlive-lang-german for a German letter (lang: de) which should be present if you write LaTeX Documents in that language.

A letter layout fitting for the local window envelope style can be select using the YAML variable lco. The various letter layouts are discussed in the previous section. A french letter layout for the window envelope style DL would be selected via lco: NF.

Hints