Chapter 1: Introduction 20

Introduction

This chapter contains, among other things, important information about the structure of the
manual and the history of KOMA - Script, which begins years before the first version. You will
also find information on how to install KOMA - Script and what to do if you encounter errors.

1.1. Preliminary Note

KOMA-Script is very complex. This is due to the fact that it consists of not just a single
class or a single package but a bundle of many classes and packages. Although the classes
are designed as counterparts to the standard classes, that does not mean they provide only
the commands, environments, and settings of the standard classes, or that they imitate their
appearance. The capabilities of KOMA - Script sometimes far surpass those of the standard
classes. Some of them should be considered extensions to the basic capabilities of the LATEX
kernel.
The foregoing means that the documentation of KOMA - Script has to be extensive. In
addition, KOMA - Script is not normally taught. That means there are no teachers who know
their students and can therefore choose the teaching materials and adapt them accordingly.
It would be easy to write documentation for a specific audience. The difficulty facing the
author, however, is that the manual must serve all potential audiences. I have tried to create
a guide that is equally suitable for the computer scientist and the fishmonger’s secretary. I
have tried, although this is actually an impossible task. The result is numerous compromises,
and I would ask you to take this issue into account if you have any complaints or suggestions
to help improve the current situation.
Despite the length of this manual, I would ask you to consult the documentation first in
case you have problems. You should start by referring to the multi-part index at the end of
this document. In addition to this manual, documentation includes all the text documents
that are part of the bundle. See manifest.tex for a complete list.

1.2. Structure of the Guide

This manual is divided into several parts: There is a section for average users, one for advanced
users and experts, and an appendix with further information and examples for those who want
to understand KOMA - Script thoroughly.
part I is intended for all KOMA - Script users. This means that some information in this
section is directed at newcomers to LATEX. In particular, this part contains many examples
that are intended to clarify the explanations. Do not hesitate to try these examples yourself
and discover how KOMA - Script works by modifying them. That said, the KOMA - Script user
guide is not intended to be a LATEX primer. Those new to LATEX should look at The Not So
Chapter 1: Introduction 21

Short Introduction to LATEX 2ε [OPHS11] or LATEX 2ε for Authors [Tea05b] or a LATEX reference
book. You will also find useful information in the many LATEX FAQs, including the TEX
Frequently Asked Questions on the Web [FAQ13]. Although the length of the TEX Frequently
Asked Questions on the Web is considerable, you should get at least a rough overview of it
and consult it in case you have problems, as well as this guide.
part II is intended for advanced KOMA - Script users, those who are already familiar with
LATEX or who have been working with KOMA - Script for a while and want to understand more
about how KOMA - Script works, how it interacts with other packages, and how to perform
more specialized tasks with it. For this purpose, we return to some aspects of the class
descriptions from part I and explain them in more detail. In addition we document some
commands that are particularly intended for advanced users and experts. This is supplemented
by the documentation of packages that are normally hidden from the user, insofar as they do
their work beneath the surface of the classes and user packages. These packages are specifically
designed to be used by authors of classes and packages.
The appendix, which can only be found in the German book version, contains information
beyond that which is covered in part I and part II. Advanced users will find background
information on issues of typography to give them a basis for their own decisions. In addition,
the appendix provides examples for aspiring package authors. These examples are not intended
simply to be copied. Rather, they provide information about planning and implementing
projects, as well as some basic LATEX commands for package authors.
The guide’s layout should help you read only those parts that are actually of interest. Each
class and package typically has its own chapter. Cross-references to another chapter are thus
usually also references to another part of the overall package. However, since the three main
classes (scrbook, scrrprt, and scrartcl) largely agree, they are introduced together in chapter 3.
scrartcl Differences between the classes, e. g., for something that only affects the class scrartcl, are
clearly highlighted in the margin, as shown here with scrartcl.
The primary documentation for KOMA - Script is in German and has been translated for your
convenience; like most of the LATEX world, its commands, environments, options, etc., are in
English. In a few cases, the name of a command may sound a little strange, but even so, we hope
and believe that with the help of this guide, KOMA - Script will be usable and useful to you.
At this point you should know enough to understand the guide. It might, however, still be
worth reading the rest of this chapter.

1.3. History of KOMA - Script

In the early 1990s, Frank Neukam needed a method to publish an instructor’s lecture notes. At
that time LATEX was LATEX2.09 and there was no distinction between classes and packages —
there were only styles. Frank felt that the standard document styles were not good enough
for his work; he wanted additional commands and environments. At the same time he was
interested in typography and, after reading Tschichold’s Ausgewählte Aufsätze über Fragen der
Chapter 1: Introduction 22

Gestalt des Buches und der Typographie (Selected Articles on the Problems of Book Design and
Typography) [Tsc87], he decided to write his own document style — and not just a one-time
solution to his lecture notes, but an entire style family, one specifically designed for European
and German typography. Thus Script was born.
Markus Kohm, the developer of KOMA - Script, came across Script in December 1992 and
added an option to use the A5 paper format. At that time neither the standard style nor
Script provided support for A5 paper. Therefore it did not take long until Markus made the
first changes to Script. This and other changes were then incorporated into Script-2, released
by Frank in December 1993.
In mid-1994, LATEX 2ε became available and brought with it many changes. Users of Script-2
were faced with either limiting their usage to LATEX 2ε ’s compatibility mode or giving up Script
altogether. This situation led Markus to put together a new LATEX 2ε package, released on
7 July 1994 as KOMA - Script. A few months later, Frank declared KOMA - Script to be the
official successor to Script. KOMA - Script originally provided no letter class, but this deficiency
was soon remedied by Axel Kielhorn, and the result became part of KOMA - Script in December
1994. Axel also wrote the first true German-language user guide, which was followed by an
English-language guide by Werner Lemberg.
Since then much time has passed. LATEX has changed in only minor ways, but the LATEX
landscape has changed a great deal; many new packages and classes are now available and
KOMA-Script itself has grown far beyond what it was in 1994. The initial goal was to pro-
vide good LATEX classes for German-language authors, but today its primary purpose is to
provide more-flexible alternatives to the standard classes. KOMA - Script’s success has led
to e-mail from users all over the world, and this has led to many new macros — all needing
documentation; hence this “small guide.”

1.4. Special Thanks

Acknowledgements in the introduction? No, the proper acknowledgements can be found in

the addendum. My comments here are not intended for the authors of this guide — and
those thanks should rightly come from you, the reader, anyhow. I, the author of KOMA -
Script, would like to extend my personal thanks to Frank Neukam. Without his Script family,
KOMA-Script would not have come about. I am indebted to the many persons who have
contributed to KOMA - Script, but with their indulgence, I would like to specifically mention
Jens-Uwe Morawski and Torsten Krüger. The English translation of the guide is, among many
other things, due to Jens’s untiring commitment. Torsten was the best beta-tester I ever had.
His work has particularly enhanced the usability of scrlttr2 and scrpage2. Many thanks to all
who encouraged me to go on, to make things better and less error-prone, or to implement
additional features.
Special thanks go as well to the founders and members of DANTE, Deutschsprachige An-
wendervereinigung TEX e.V, (the German-Language TEX User Group). Without the DANTE
Chapter 1: Introduction 23

server, KOMA - Script could not have been released and distributed. Thanks as well to ev-
erybody on the TEX newsgroups and mailing lists who answer questions and have helped me
provide support for KOMA - Script.
My thanks also go to all those who have always encouraged me to go further and to imple-
ment this or that feature better, with fewer flaws, or simply as an extension. I would also like
to thank the very generous donor who has given me the most significant amount of money I
have ever been paid for the work done so far on KOMA - Script.

1.5. Legal Notes

KOMA-Script is released under the LATEX Project Public License. You will find it in the file
lppl.txt. An unofficial German-language translation is also available in lppl-de.txt and is
valid for all German-speaking countries.
This document and the KOMA - Script bundle are provided “as is” and without warranty of
any kind.

1.6. Installation

The three most important TEX distributions, MacTEX, MiKTEX, and TEX Live, make KOMA -
Script available through their package management software. You should install and update
KOMA-Script using these tools, if possible. Manual installation without using the package
managers is described in the file INSTALL.txt, which is part of every KOMA - Script distribu-
tion. You should also read the documentation that comes with the TEX distribution you are
using.

1.7. Bug Reports and Other Requests

If you think you have found an error in the documentation or a bug in one of the KOMA - Script
classes, packages, or another part of KOMA - Script, please do the following:

• Does the problem also occur if a standard class is used instead of a KOMA - Script class?
In this case, the error is most likely not with KOMA - Script, and it makes more sense to
ask your question in a public forum, a mailing list, or Usenet.

• Which KOMA - Script version do you use? For related information, see the log file of the
LATEX run of any document that uses a KOMA - Script class.

• If you do not use an up-to-date KOMA - Script version, please consider to install a new
KOMA- Script release. If the problem does not occur with an updated KOMA - Script,
you’ve already found a solution.
Chapter 1: Introduction 24

• Which operating system and which TEX distribution do you use? This information might
seem rather superfluous for a system-independent package like KOMA - Script or LATEX,
but time and again they have certainly been shown to play a role.

• What exactly is the problem or the error? Describe the problem. It’s better to be too
detailed than too short. Often it makes sense to explain the background.

• What does a minimal working example look like? You can easily create one by comment-
ing out content and packages from the document step by step. The result is a document
that only contains the packages and parts necessary to reproduce the problem. In ad-
dition, all loaded images should be replaced by \rule statements of the appropriate
size or by an example image from package mwe [Sch18]. Before sending your minimal
working example,remove the commented-out parts, insert the command \listfiles in
the preamble, and perform another LATEX run. At the end of the log file, you will see
an overview of the packages used. Add the minimal working example and the log file to
the end of your description of the problem.

Do not send packages, PDF, PS, or DVI files. If the entire issue or bug description, including
the minimal example and the log file is larger than a few tens of kilobytes, you’re likely doing
something wrong.
If you’ve followed all these steps, please create a new ticket in the KOMA - Script ticket
system at https://sf.net/p/koma-script/tickets. If you are not able to do so, you may
alternatively send your KOMA - Script (only) bug report to komascript@gmx.info.
If you want to ask your question in a Usenet group, mailing list, or Internet forum, you
should follow the procedures mentioned above and include a minimal working example as part
of your question, but usually you don’t need to provide the log-file. Instead, just add the
list of packages and package versions from the log-file and, if your minimal working example
compiles with errors, you should quote those messages from the log file.
Please note that default settings which are not typographically optimal do not represent
errors. For reasons of compatibility, defaults are preserved whenever possible in new versions
of KOMA-Script. Furthermore, typographical best practices are partly a matter of language
and culture, and so the default settings of KOMA - Script are necessarily a compromise.

1.8. Additional Information

Once you become familiar with KOMA - Script, you may want examples that show how to
accomplish more difficult tasks. Such examples go beyond the basic instructional scope of
this manual and so are not included. However, you will find more examples on the website of
the KOMA-Script Documentation Project [KDP]. These examples are designed for advanced
LATEX users and are not particularly suitable for beginners. The main language of the site is
German, but English is also welcome.
 Part I.
KOMA - Script for Authors

This part provides information for writers of articles, reports, books, and letters. The average
user is probably less interested in how things are implemented in KOMA - Script and what
pitfalls exist. Also, normal users aren’t interested in obsolete options and instructions. They
want to know how to achieve things using current options and instructions, and perhaps in
some background information about typography.
The few passages in this part which contain extra information and explanations that may be
of less interest for the impatient reader are set in a sans-serif typeface and can be skipped if de-
sired. For those who are interested in more information about the implementation, side-effects
with other packages, or obsolete options and instructions, please refer to part II beginning on
page 312. That part of the KOMA - Script guide also describes all the features that were created
specially for authors of packages and classes.
Chapter 2: Calculating the Page Layout with typearea 26

Calculating the Page Layout with typearea

Many LATEX classes, including the standard classes, present the user with a largely fixed
configuration of margins and page layout. In the standard classes, the choice is limited to
selecting a font size. There are separate packages, such as geometry (see [Ume10]), which
give the user complete control over, but also full responsibility for, setting the type area and
margins.
KOMA-Script takes a somewhat different approach with the typearea package. Users are
offered ways to adjust the design and algorithms based on established typographic standards,
making it easier for them to make good choices.

2.1. Fundamentals of Page Layout

At first glance, a single page of a book or other printed material consists of the margins, a header,
a body of text, and a footer. More precisely, there is also a space between the header area and the
text body, as well as between the body and the footer. The text body is called, in the jargon of
typographers and typesetters, the type area. The division of these areas, as well as their relations
to each other and to the paper, is called the page layout.
Various algorithms and heuristic methods for constructing an appropriate type area have been
discussed in the literature [Koh02]. These rules are known as the “canons of page construction.”
One approach often mentioned involves diagonals and their intersections. The result is that the
aspect ratio of the type area corresponds to the proportions of the page. In a one-sided document,
the left and right margins should have equal widths, while the ratio of the top and bottom margins
should be 1:2. In a two-sided document (e. g. a book), however, the entire inner margin (the
margin at the spine) should be the same size as each of the two outer margins; in other words, a
single page contributes only half of the inner margin.
In the previous paragraph, we mentioned and emphasised the page. It is often mistakenly thought
that the format of the page is the same as the format of the paper. However, if you look at a bound
document, you can see that part of the paper disappears in the binding and is no longer part of the
visible page. For the type area, however, it is not the format of the paper which is important; it is
the impression of the visible page to the reader. Thus, it is clear that the calculation of the type
area must account for the “lost” paper in the binding and add this amount to the width of the
inner margin. This is called the binding correction. The binding correction is therefore calculated
as part of the gutter but not the visible inner margin.
The binding correction depends on the production process and cannot be defined in general
terms. It is therefore a parameter that must be redefined for each project. In professional printing,
this value plays only a minor role, since printing is done on larger sheets of paper and then cropped
to the right size. The cropping is done so that the above relations for the visible, two-sided page
are maintained.
Chapter 2: Calculating the Page Layout with typearea 27

So now we know how the individual parts of a page relate to each other. However, we do not
yet know how wide and high the type area is. Once we know one of these two dimensions, we
can calculate all the other dimensions from the paper format and the page format or the binding
correction.

type area height : type area width = page height : page width
top margin : footer margin = 1 : 2
left margin : right margin = 1 : 1
half inner margin : outer margin = 1 : 2
page width = paper width − binding correction
top margin + bottom margin = page height − type area height
left margin + right margin = page width − type area width
half inner margin + outer margin = page width − type area width
half inner margin + binding correction = gutter

The values left margin and right margin only exist in a one-sided document while half inner margin
and outer margin only exist in a two-sided document. We use half inner margin in these equations,
since the full inner margin is an element of the whole two-page spread. Thus, only half of the inner
margin, half inner margin, belongs to a single page.
The question of the width of the type area is also discussed in the literature. The optimum
width depends on several factors:

• the size, width, and type of font used,

• the line spacing,

• the word length,

• the available space.

The importance of the font becomes clear once you realize what serifs are for. Serifs are small
strokes that finish off the lines of letters. Letters with vertical lines touching the text baseline
disturb the flow rather than keeping the eye on the line. It is precisely with these letters that the
serifs lie horizontally on the baseline and thus enhance the horizontal effect of the font. The eye
can better follow the line of text, not only when reading the words but also when jumping back to
the beginning of the next line. Thus, the line length can actually be slightly longer for a serif font
than for a sans serif font.
Leading refers to the vertical distance between individual lines of text. In LATEX, the leading is
set at about 20% of the font size. With commands like \linespread, or better, packages like
setspace (see [TF11]), you can change the leading. A wider leading makes it easy for the eye to
follow the line. A very wide leading, however, disturbs reading because the eye has to travel long
Chapter 2: Calculating the Page Layout with typearea 28

distances between the lines. In addition, the reader becomes uncomfortable because of the visible
striped effect. The uniform grey value of the page is thereby spoiled. Nevertheless, the lines can
be longer with a wider leading.
The literature gives different values for good line lengths, depending on the author. To some
extent, this is related to the author’s native language. Since the eye usually jumps from word
to word, short words make this task easier. Across all languages and fonts, a line length of 60
to 70 characters, including spaces and punctuation, forms a usable compromise. This requires
well-chosen leading, but LATEX’s default is usually good enough. Longer line lengths should only be
considered for highly-developed readers who spend many hours a day reading. But even then, line
lengths beyond 80 characters are unacceptable. In each case, the leading must be appropriately
chosen. An extra 5% to 10% is recommended as a good rule of thumb. For typefaces like Palatino,
which require more than 5% leading for normal line lengths, even more can be required.
Before looking at the actual construction of the page layout, there are a few minor points you
should know. LATEX does not start the first line in the text area of a page at the upper edge
of the text area but sets the baseline at a defined distance from the top of the text area. Also,
LATEX recognizes the commands \raggedbottom and \flushbottom. \raggedbottom specifies
that the last line of a page should be positioned wherever it was calculated. This means that the
position of this line can be different on each page, up to the height of one line — even more when
the end of the page coincides with headings, figures, tables, or the like. In two-sided documents
that is usually undesirable. The second command, \flushbottom, makes sure that the last line is
always at the lower edge of the text area. To achieve this vertical compensation, LATEX may have
to stretch vertical glue beyond what is normally allowed. Paragraph skip is such a stretchable,
vertical glue, even when set to zero. To avoid stretching on normal pages where paragraph spacing
is the only stretchable glue, the height of the text area should be a multiple of the height of the
text line, including the distance of the first line from the top of the text area.
This concludes the fundamentals. In the following two sections, the methods of construction
offered by KOMA - Script are presented in detail.

2.2. Constructing the Type Area by Division

The easiest way to make sure that the text area has the same ratio as the page is as follows:
• First, subtract the BCOR required for the binding correction from the inner edge of the
paper, and divide the rest of the page vertically into DIV rows of equal height.

• Next, divide the page horizontally into the same number (DIV) of columns of equal width.

• Then, take the uppermost row as the upper margin and the two lowermost rows as the lower
margin. If you are printing two-sided, you similarly take the innermost column as the inner
margin and the two outermost columns as the outer margin.

• Then add the binding correction BCOR to the inner margin.

Chapter 2: Calculating the Page Layout with typearea 29

1 2 3 4 5 6 7 8 9 9 8 7 6 5 4 3 2 1

2 2

3 3

binding correction
4 4

5 page layout left page layout right 5

6 6

7 7

Figure 2.1.: Two-sided layout 8 8

with the box construction of the
9 9
classical nine-part division, after
subtracting a binding correction

What remains within the page is the text area. The width and height of the text area and margins
result automatically from the number of rows and columns, DIV. Since the margins always need
three stripes, DIV must be greater than three. In order that the text area occupy at least twice as
much space as the margins, DIV should really be at least nine. With this value, the design is also
known as the classical nine-part division (see figure 2.1).
In KOMA-Script, this kind of design is implemented with the typearea package, where the
bottom margin may drop any fractions of a line in order to comply with the constraint for the
height of the type area mentioned in the previous paragraph and thereby reduce the problem
mentioned with \flushbottom. For A4 paper, DIV is predefined according to the font size (see
table 2.2, page 35). If there is no binding correction (BCOR = 0 pt), the results roughly match
the values of table 2.1, page 34.
In addition to the predefined values, you can specify BCOR and DIV as options when loading
the package (see section 2.4, starting on page 32). There is also a command to calculate the type
area explicitly by providing these values as parameters (see also section 2.4, page 38).
The typearea package can automatically determine the optimal value of DIV for the font and
leading used. Again, see section 2.4, page 35.

2.3. Constructing the Type Area by Describing a Circle

In addition to the construction method for the type area described above, there is an even more
traditional, or even medieval, method found in the literature. The aim of this method is not just
to have the same ratios between page size and type area; it is considered optimal when the height
of the text area corresponds to the width of the page. This means that a circle can be drawn
Chapter 2: Calculating the Page Layout with typearea 30

that will touch both the sides of the page and the top and bottom of the text area. The exact
procedure can be found in [Tsc87].
A disadvantage of this late-medieval canon of page construction is that the width of the text
area no longer depends on the font. One no longer chooses the text area to match the font.
Instead, the author or typesetter must choose the appropriate font for the text area. This should
be considered mandatory.
In the typearea package, this construction is modified to determine the DIV value by selecting
a special (normally meaningless) DIV value or a special, symbolic indication of the DIV value so
that the resulting type area comes as close as possible to the late-medieval page canon. Hence it
relies in turn on the method of constructing the type area by division.

2.4. Early or Late Selection of Options

This section introduces a special feature of KOMA - Script which, in addition to typearea, is also
relevant to other KOMA - Script packages and classes. This section appears in nearly identical
form in several chapters, so you can find all the information about a single package or class in
the relevant chapter. Users who are interested not just in a particular package or class but in
getting an overview of KOMA - Script as a whole only need to read this section in one of the
chapters and can then skip it as they study the guide.

\documentclass[option list ]{KOMA - Script class }

\usepackage[option list ]{package list }
LATEX allows users to pass class options as a comma-separated list of keywords in the optional
argument to \documentclass. In addition to being passed to the class, these options are also
passed on to all packages that can understand them. Users can also pass a similar comma-
v3.00 separated list of keywords in the optional argument of \usepackage. KOMA - Script extends
the option mechanism for the KOMA - Script classes and some packages with further options.
Thus most KOMA - Script options can also take a value, so an option does not necessarily
take the form option , but can also take the form option =value . Except for this difference,
\documentclass and \usepackage in KOMA - Script function as described in [Tea05b] or any
introduction to LATEX, for example [OPHS11].
When using a KOMA - Script class, you should not specify options when loading the typearea
or scrbase packages. The reason for this restriction is that the class already loads these
packages without options, and LATEX refuses to load a package multiple times with different
option settings.
Setting the options with \documentclass has one major disadvantage: unlike the interface
described below, the options in \documentclass are not robust. So commands, lengths,
counters, and similar constructs may break inside the optional argument of this command.
For example, with many non-KOMA - Script classes, using a LATEX length in the value of an
option results in an error before the value is passed to a KOMA - Script package and it can take