Nothing
scrartcl
In komadown: R Markdown Templates for the 'KOMA-Script' Classes
knitr::knit_hooks$set(crop = knitr::hook_pdfcrop)
# Fix subfigs for rmarkdown
if (identical(knitr:::pandoc_to(), 'latex'))
knitr::knit_hooks$set(plot = knitr::hook_plot_tex)
knitr::opts_chunk$set(
echo = FALSE,
fig.width = 2.3,
fig.height = 2.1,
dev = "pdf",
dev.args = list(pointsize = 8),
crop = TRUE
)
options(digits = 3)
Motivation
The default \LaTeX\ template for R Markdown and,
by proxy, pandoc take liberties with the original design of \LaTeX\ documents.
The title page is compressed, margins are minimized, and first-line indentation
is usurped by paragraph spacing. This makes sense for markdown documents that
are intended for several output formats since consistency between those are
important to uphold. From a typographical standpoint, however, the design leaves
much to desire.
Without delving into the details of this, I think it suffices to say
that the design of \LaTeX\ documents have been wrought with care
and should only be meddled with if one knows what
they are doing.
This, coincidently, is the case with the
KOMA-Script bundle, which is a
reimagining of the original \LaTeX\ classes article, book, letter, and book.
In many ways, the KOMA-Script classes are incontrovertible upgrades to the
original classes, adding a significant deal of functionality to boot.
In addition to this, komadown pulls in a small set of other packages
to handle the different needs that KOMA-Script does not cover. All in all,
the package interface introduces
- an interface to
\KOMAoptions, which makes the majority of KOMA-Script
accessible to the user,
- automatic or manual headers and footers using yaml metadata,
- caption customization via the caption package,
- author and affiliation setups via the authblk package, and
- font combinations with excellent support for math (mostly using the
newtx package).
In addition to this, komadown also leans on the
bookdown package to provide support for
cross-references of tables, figures, theorems, sections, and equations in
R Markdown syntax.
My minor role in this is to provide a \LaTeX\ template for pandoc and
interface for R to make it easier for R users to draw on the power of
KOMA-Script (and friends).
Installation
Install komadown by running install.packages("komadown").
If you are running RStudio, this will set you up to begin a KOMA-Script
article with komadown's default template (which this document is based on)
simply by going File -> New File -> R Markdown and picking the scrartcl
template. The code that makes this work is borrowed from
rticles.
Besides installing the package, the only other necessary step is to
include
---
output: komadown::scrartcl
---
somewhere in the metadata. This will eventually call
pdf_document2() from bookdown and then \LaTeX\ a .tex document,
producing PDF output.
Settings
Most of the settings for KOMA-Script are called using a metadata block
called KOMAoptions, which takes items in the element=value form.
For instance, this document uses this option to switch headings to versions
similar to the standard classes using
---
KOMAoptions:
- headings=standardclasses
---
The reader is referred to the KOMA-script manual for information on the many
options available. Of special interest may be the DIV argument -- which we
will talk about next.
Type area calculations
One of the strengths of KOMA-Script is its facilities for intelligently
computing type-area layouts. The core \LaTeX\ classes work well out-of-the-box
if the default font options (size, family, line spread) are used. However,
if the user wants to forego Latin/Computer Modern for another font family
or simply change its size, these settings no longer fullfill their purpose
of keeping the text at an adequate number of words per line.
The core classes solution to this is to use the geometry package
and modify the margins manually, but this might take several attempts to get
right and moreover requires that the user knows to get the proportions right.
KOMA-Script solves this automatically using an algorithm. This involes
the DIV=x setting, which is implemented in komadown via
the metadata block classoption. The simplest use of DIV is to set it to
default.
---
classoption:
- DIV=calc
---
This uses a predefined table based on the paper size and default font to arrive
at a type area.
A more advanced use of DIV might be to set it to calc, in which case
a DIV size is calculated based on the other options given KOMA-Script,
such as BCOR (binding correction). calc also bases its calculations on the
current font settings, but because the calculations are performed at the
time when the document class is loaded and hence
before any font packages are included, it does not make sense to set
DIV for this reason alone. To get around this, one can use the
KOMAoptions block. KOMAoptions are called after font packages are loaded,
and hence if the user specifies DIV=last (if DIV=calc was set in
classoption) or DIV=calc here, it will successfully adapt the type area.
Headers and footers
Headers and footers can be specified via the following syntax.
---
header:
- pos: r
first: "scrartcl"
next: "komadown"
footers:
- pos: l
next: "\today"
---
pos gives alignment of the header---one of r, l, and c for right, left,
and center respectively. first is the text for the header or footer on the
first page and next for the latter pages. First and next are optional but
pos is not.
Additionally, the user can set
---
automark: yes
---
which will then create a running header displaying the current section in
the left spot of the header (which is the setting used in this vignette).
Captions
Captions can be customized using the caption metadata block.
---
caption:
- labelfont: bf
- labelsep: period
- font: small
---
The reader is referred to documentation for the
caption package
to read about the various settings.
The default settings (the ones above) produce captions with bold face for
the label and a dot separator (Figure \@ref(fig:histogram)).
set.seed(1)
hist(rnorm(10), col = "grey70", xlab = "", main = "")
Additionally, we call the floatrow package to setup table floats to place
their captions above the floats. Settings from this package are currently
not configurable.
Cross-references
Cross-references are available in markdown syntax via the bookdown
package. The basic syntax is \@ref(label) where label will differ depending
on context:
Figures
: label will be fig:id where id is the label given the chunk
the figure is produced by. Note that this requires the fig.cap argument
to be set or else there won't be a \figure environment to attach the label
to.
Sections
: Add {#id} to the end of the section name and you can
reference it with \@ref(id).
Equations
: Add (\#eq:id) inside the math environment and you will be able to
refer to it by \@ref(eq:id)
Theorems
: Add label="id" to the theorem chunk and you will be able to refer to
it by \@ref(prefix:id) where prefix depends on the type of theorem. See
this table
for a description of the various prefixes.
Font packages
komadown includes a few font packs of selected combinations of
serif, sans-serif, and monospace fonts. All are based on the
tremendous \LaTeX\ package newtx from Michael
Sharpe. They are accessed with the metadata option fontpack-x, x being one
of the options in Table \@ref(tab:fontpack).
Table: (#tab:fontpack) Customized fontpackages
Font pack Serif Sans-serif Monospace
--------------- -------- ------------ ----------
times (default) Times New Roman Helvetica newtxtt
charter XCharter (Charter) Cabin Inconsolata
erewhon Erewhon (utopia) Cabin Inconsolata
libertine Libertine Biolinum Inconsolata
Hence, to use the erewhon font pack, you would need to set the following.
---
fontpack-erewhon: yes
---
If no font package is specified, the default is set to Latin Modern.
Font settings
All of the font settings can be set or modified with the metadata blocks
addtokomafont and setkomafont; the former modifies the current options --
the latter resets them. Both use the subitems element and commands.
This document, for instance, using the following
settings to modify description lists to use a roman font instead of the
KOMA-Script default of sans-serif.
---
setkomafont:
- element: descriptionlabel
commands: \normalfont\scshape\bfseries
---
As always, please refer to the KOMA-Script manual for a thorough
take on this.
Bibliography style
The default bibliography style is the Vancouver Style [@patrias_2007], which
has been authored by Michael Berkowitz and been included in the package
(licensed under CC BY-SA 3.0.
It can be replaced with any .csl style using the usual pandoc interface or
any configuration via biblatex or `natbib.
Author blocks
The komadown template includes scripting for author blocks as well; in fact,
you must use the author blocks. The settings are somewhat involved compared
to the usual author calls.
author:
- name: "Johan Larsson"
affil:
- name: "Lund Unviversity"
affil is, of course, optional. We use the authblk package for this. If you
have several authors you use the id tag to match authors to their
affiliations.
author:
- name: "Johan Larsson"
id: 1
- name: "John Doe"
id: 1
affil:
- name: "Lund University"
id: 1
and the authors will link up with the affiliation.
Design choices
I've attempted to leave most of the design choices at their default values,
putting most of my personal preferences in the default template instead in
order to make them easy to shake off. However, there are a few things
that I have opted to modify. They are
- table captions are always placed on top,
number_sections in the call to rmarkdown::pdf_document() is set to TRUE
by default, and- the default bibliography style is set to the Uniform Requirements style
(also known as Vancouver).
This document
This document uses the following YAML metadata setup.
---
title: "scrartcl"
subtitle: "KOMA-script articles with komadown"
author:
- name: "Johan Larsson"
affil: "Lund University"
date: "`r Sys.Date()`"
automark: yes
colorlinks: yes
fontpack-libertine: yes
classoption:
- DIV=calc
- headsepline=true
header:
- pos: ro
next: komadown
caption:
- labelfont=bf
- labelsep=period
- font=small
setkomafont:
- element: descriptionlabel
commands: \normalfont\scshape\bfseries
KOMAoptions:
- headings=standardclasses
- DIV=last
output: komadown::scrartcl
---
References
Try the komadown package in your browser
Any scripts or data that you put into this service are public.
komadown documentation built on May 2, 2019, 2:22 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
knitr::knit_hooks$set(crop = knitr::hook_pdfcrop) # Fix subfigs for rmarkdown if (identical(knitr:::pandoc_to(), 'latex')) knitr::knit_hooks$set(plot = knitr::hook_plot_tex) knitr::opts_chunk$set( echo = FALSE, fig.width = 2.3, fig.height = 2.1, dev = "pdf", dev.args = list(pointsize = 8), crop = TRUE ) options(digits = 3)
Motivation
The default \LaTeX\ template for R Markdown and, by proxy, pandoc take liberties with the original design of \LaTeX\ documents. The title page is compressed, margins are minimized, and first-line indentation is usurped by paragraph spacing. This makes sense for markdown documents that are intended for several output formats since consistency between those are important to uphold. From a typographical standpoint, however, the design leaves much to desire.
Without delving into the details of this, I think it suffices to say that the design of \LaTeX\ documents have been wrought with care and should only be meddled with if one knows what they are doing.
This, coincidently, is the case with the KOMA-Script bundle, which is a reimagining of the original \LaTeX\ classes article, book, letter, and book. In many ways, the KOMA-Script classes are incontrovertible upgrades to the original classes, adding a significant deal of functionality to boot.
In addition to this, komadown pulls in a small set of other packages to handle the different needs that KOMA-Script does not cover. All in all, the package interface introduces
- an interface to
\KOMAoptions, which makes the majority of KOMA-Script accessible to the user, - automatic or manual headers and footers using yaml metadata,
- caption customization via the caption package,
- author and affiliation setups via the authblk package, and
- font combinations with excellent support for math (mostly using the newtx package).
In addition to this, komadown also leans on the bookdown package to provide support for cross-references of tables, figures, theorems, sections, and equations in R Markdown syntax.
My minor role in this is to provide a \LaTeX\ template for pandoc and interface for R to make it easier for R users to draw on the power of KOMA-Script (and friends).
Installation
Install komadown by running install.packages("komadown").
If you are running RStudio, this will set you up to begin a KOMA-Script
article with komadown's default template (which this document is based on)
simply by going File -> New File -> R Markdown and picking the scrartcl
template. The code that makes this work is borrowed from
rticles.
Besides installing the package, the only other necessary step is to include
--- output: komadown::scrartcl ---
somewhere in the metadata. This will eventually call
pdf_document2() from bookdown and then \LaTeX\ a .tex document,
producing PDF output.
Settings
Most of the settings for KOMA-Script are called using a metadata block
called KOMAoptions, which takes items in the element=value form.
For instance, this document uses this option to switch headings to versions
similar to the standard classes using
--- KOMAoptions: - headings=standardclasses ---
The reader is referred to the KOMA-script manual for information on the many
options available. Of special interest may be the DIV argument -- which we
will talk about next.
Type area calculations
One of the strengths of KOMA-Script is its facilities for intelligently computing type-area layouts. The core \LaTeX\ classes work well out-of-the-box if the default font options (size, family, line spread) are used. However, if the user wants to forego Latin/Computer Modern for another font family or simply change its size, these settings no longer fullfill their purpose of keeping the text at an adequate number of words per line.
The core classes solution to this is to use the geometry package and modify the margins manually, but this might take several attempts to get right and moreover requires that the user knows to get the proportions right.
KOMA-Script solves this automatically using an algorithm. This involes
the DIV=x setting, which is implemented in komadown via
the metadata block classoption. The simplest use of DIV is to set it to
default.
--- classoption: - DIV=calc ---
This uses a predefined table based on the paper size and default font to arrive at a type area.
A more advanced use of DIV might be to set it to calc, in which case
a DIV size is calculated based on the other options given KOMA-Script,
such as BCOR (binding correction). calc also bases its calculations on the
current font settings, but because the calculations are performed at the
time when the document class is loaded and hence
before any font packages are included, it does not make sense to set
DIV for this reason alone. To get around this, one can use the
KOMAoptions block. KOMAoptions are called after font packages are loaded,
and hence if the user specifies DIV=last (if DIV=calc was set in
classoption) or DIV=calc here, it will successfully adapt the type area.
Headers and footers
Headers and footers can be specified via the following syntax.
--- header: - pos: r first: "scrartcl" next: "komadown" footers: - pos: l next: "\today" ---
pos gives alignment of the header---one of r, l, and c for right, left,
and center respectively. first is the text for the header or footer on the
first page and next for the latter pages. First and next are optional but
pos is not.
Additionally, the user can set
--- automark: yes ---
which will then create a running header displaying the current section in the left spot of the header (which is the setting used in this vignette).
Captions
Captions can be customized using the caption metadata block.
--- caption: - labelfont: bf - labelsep: period - font: small ---
The reader is referred to documentation for the caption package to read about the various settings.
The default settings (the ones above) produce captions with bold face for the label and a dot separator (Figure \@ref(fig:histogram)).
set.seed(1) hist(rnorm(10), col = "grey70", xlab = "", main = "")
Additionally, we call the floatrow package to setup table floats to place their captions above the floats. Settings from this package are currently not configurable.
Cross-references
Cross-references are available in markdown syntax via the bookdown
package. The basic syntax is \@ref(label) where label will differ depending
on context:
Figures
: label will be fig:id where id is the label given the chunk
the figure is produced by. Note that this requires the fig.cap argument
to be set or else there won't be a \figure environment to attach the label
to.
Sections
: Add {#id} to the end of the section name and you can
reference it with \@ref(id).
Equations
: Add (\#eq:id) inside the math environment and you will be able to
refer to it by \@ref(eq:id)
Theorems
: Add label="id" to the theorem chunk and you will be able to refer to
it by \@ref(prefix:id) where prefix depends on the type of theorem. See
this table
for a description of the various prefixes.
Font packages
komadown includes a few font packs of selected combinations of
serif, sans-serif, and monospace fonts. All are based on the
tremendous \LaTeX\ package newtx from Michael
Sharpe. They are accessed with the metadata option fontpack-x, x being one
of the options in Table \@ref(tab:fontpack).
Table: (#tab:fontpack) Customized fontpackages
Font pack Serif Sans-serif Monospace --------------- -------- ------------ ---------- times (default) Times New Roman Helvetica newtxtt charter XCharter (Charter) Cabin Inconsolata erewhon Erewhon (utopia) Cabin Inconsolata libertine Libertine Biolinum Inconsolata
Hence, to use the erewhon font pack, you would need to set the following.
--- fontpack-erewhon: yes ---
If no font package is specified, the default is set to Latin Modern.
Font settings
All of the font settings can be set or modified with the metadata blocks
addtokomafont and setkomafont; the former modifies the current options --
the latter resets them. Both use the subitems element and commands.
This document, for instance, using the following
settings to modify description lists to use a roman font instead of the
KOMA-Script default of sans-serif.
---
setkomafont:
- element: descriptionlabel
commands: \normalfont\scshape\bfseries
---
As always, please refer to the KOMA-Script manual for a thorough take on this.
Bibliography style
The default bibliography style is the Vancouver Style [@patrias_2007], which
has been authored by Michael Berkowitz and been included in the package
(licensed under CC BY-SA 3.0.
It can be replaced with any .csl style using the usual pandoc interface or
any configuration via biblatex or `natbib.
Author blocks
The komadown template includes scripting for author blocks as well; in fact, you must use the author blocks. The settings are somewhat involved compared to the usual author calls.
author: - name: "Johan Larsson" affil: - name: "Lund Unviversity"
affil is, of course, optional. We use the authblk package for this. If you
have several authors you use the id tag to match authors to their
affiliations.
author: - name: "Johan Larsson" id: 1 - name: "John Doe" id: 1 affil: - name: "Lund University" id: 1
and the authors will link up with the affiliation.
Design choices
I've attempted to leave most of the design choices at their default values, putting most of my personal preferences in the default template instead in order to make them easy to shake off. However, there are a few things that I have opted to modify. They are
- table captions are always placed on top,
number_sectionsin the call tormarkdown::pdf_document()is set toTRUEby default, and- the default bibliography style is set to the Uniform Requirements style (also known as Vancouver).
This document
This document uses the following YAML metadata setup.
--- title: "scrartcl" subtitle: "KOMA-script articles with komadown" author: - name: "Johan Larsson" affil: "Lund University" date: "`r Sys.Date()`" automark: yes colorlinks: yes fontpack-libertine: yes classoption: - DIV=calc - headsepline=true header: - pos: ro next: komadown caption: - labelfont=bf - labelsep=period - font=small setkomafont: - element: descriptionlabel commands: \normalfont\scshape\bfseries KOMAoptions: - headings=standardclasses - DIV=last output: komadown::scrartcl ---
References
Try the komadown package in your browser
Any scripts or data that you put into this service are public.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.