Note: This document is a translation of the German koma script manual

onecolumn

v3.01

typesets the corresponding TOC with internal one column mode of \onecolumn.

This will be done only, if the corresponding table of contents or list of something does

not use feature leveldown. The KOMA-Script classes scrbook and scrreprt activate this

feature with \AtAddToTocList (see

section 15.1

,

page 302

) for all TOCs with owner

float

or with themselves as owner. With this, e. g., the table of contents, the list of

figures and the list of tables of both classes will be single columned automatically. The

multiple-column-mode of package multicol will not be recognised or changed by this

option.

totoc

writes the title of the corresponding TOC to the table of contents. This feature will

be evaluated by the internal heading command. On the other hand, if an user defined

heading command has been made with \deftocheading, that user is responsible for

the evaluation of the feature. The KOMA-Script classes set this feature using option

listof=totoc

for all file name extensions of the owner float.

Classes and packages may know features, too, e. g, the KOMA-Script classes know following

additional features:

chapteratlist

activates special code to be put into the TOC at start of a new chapter.

This code may either be vertical space or the heading of the chapter. See listof in

section 3.20

,

page 127

for more information about such features.

Example: Because KOMA-Script classes use tocbasic for the list of figures and list of tables,

there’s one more way to remove chapter structuring at those:

\unsettoc{lof}{chapteratlist}

\unsettoc{lot}{chapteratlist}

310

Chapter 15.

And if you want to have the chapter structuring of the KOMA-Script classes at

your own list of algorithms with file name extension “loa” from the previous

examples, you may use

\setuptoc{loa}{chapteratlist}

And if classes with \chapter should also force single column mode for the list of

algorithms you may use

\ifundefinedorrelax{chapter}{}{%

\setuptoc{loa}{onecolumn}%

}

Usage of \ifundefinedorrelax presumes package scrbase (see

section 12.3

,

page 276

).

It doesn’t matter if you’re package would be used with another class. You should

never the less set this feature. And if the other class would also recognise the

feature your package would automatically use the feature of that class.

As you may see, packages that use tocbasic, already provide several interesting features, with-

out the need of a lot of implementation effort. Such an effort would be needed only without

tocbasic and because of this, most packages currently lack of such features.

\iftocfeature{extension }{feature }{true-instructions }{false-instructions }

This command may be used, to test, if a feature was set for file name extension . If so the

true-instructions

will be processed, otherwise the false-instruction will be. This may

be useful, e. g., if you define your own heading command using \deftocheading but want to

support the features totoc, numbered or leveldown.

15.3. Configuration of Entries to a Table or List of Contents

Since

Beta-

Feature

version 3.20 package tocbasic can not only configure the tables or lists of contents and

their auxiliary files but also influence their entries. To do so, you can define new styles or you

can use and configure one of the predefined styles. In the medium term tocbasic will replace the

experimental package tocstyle that never became an official part of the KOMA-Script bundle.

The KOMA-Script classes intensively use the TOC-entry styles of tocbasic since version 3.20.

\numberline{entry number }

\usetocbasicnumberline[code ]

Though

Beta-

Feature

the L

A

TEX kernel already defines command \numberline, the kernel definition is not

sufficient for tocbasic. Therefore tocbasic has its own definition of \numberline. The package

uses \usetocbasicnumberline to activate this definition whenever a TOC-entry needs it.

311

Chapter 15.

1.1.10 Text of an entry to the table of contents with style dottedtocline and

more than one line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

indent

numwidth

\@tocrmarg

\@pnumwidth

Figure 15.1.: Illustrations of some attributes of a TOC-entry with style dottedtocline

Because of this, re-defining \numberline often does not work and even may result in warnings

if you use tocbasic.

You can use the definition of tocbasic putting \usetocbasicnumberline into your doc-

ument’s preamble. The command first of all checks, whether or not the current definition

of \numberline uses essential, internal commands of tocbasic. Only if this is not the case

\usetocbasicnumberline

redefines \numberline and executes code . If you omit the op-

tional argument, a \PackageInfo outputs a message about the successful re-definition. If you

just do not want such a message, use an empty optional argument.

Please note, as a side effect \usetocbasicnumberline can globally change the internal

switch \@tempswa!

\DeclareTOCStyleEntry[option list ]{style }{entry level }

This

Beta-

Feature

command is used to define or configure the TOC-entries of a given entry level . Argu-

ment entry level is a symbolic name, e. g., section for the entry to the table of contents

of the section level with the same name or figure for an entry of a figure to the list of fig-

ures. A style is assigned to each entry level . The style has to be defined before using

it as an argument of \DeclareTOCStyleEntry. The option list is used to configure several

style

-dependent attributes of the entry level .

Currently, tocbasic defines the following entry styles:

default

defaults to a clone of style dottedtocline. It is recommended to class authors, who

use tocbasic, to change this style into the default style of the class using \CloneTOCStyle.

For example the KOMA-Script classes change default into a clone of tocline.

dottedtocline

is similar to the style used by the standard classes book and report for the

section

down to subparagraph entry levels of the table of contents and for the entries

at the list of figures or list of tables. It supports the attributes level, indent, and

numwidth

. The entries will be indented by the value of indent from the left. The width

of the entry number is given by the value of numwidth. For multiline entries the indent

will be increased by the value of numwidth for the second and following lines. The page

number is printed using \normalfont. Entry text and page number are connected by a

dotted line.

Figure 15.1

illustrates the attributes of this style.

312

Chapter 15.

I

Text of an entry to the table of contents with style largetocline

and more than one line

1

3 em

\@pnumwidth

\large\@pnumwidth

Figure 15.2.: Illustrations of some attributes of a TOC-entry with style largetocline

gobble

is the most ordinary style. Independently from the setting of tocdepth, entries with

this style will never be printed. The style simply gobbles the entries. Nevertheless, it

supports the standard attribute level but does ignore it.

largetocline

is similar to the style used by the standard classes for the level part. It

supports attributes level and indent only. The last one is already a variation of the

standard classes that do not support an indent of the part entries.

Before an entry a page break will be made easier. The entries will be indented by the

value of indent from the left. They are printed using \large\bfseries. If \numberline

is used, the number width is 3 em. \numberline is not redefined. The standard classes

do not use \numberline for part entries. The value of indent even does not influence

the indent from the second line of an entry.

Figure 15.2

illustrates the attributes of this style. There you can also see that the style

copies inconsistencies of the standard classes, e. g. the missing indent of the second and

following lines of an entry or the different values of \@pnumwidth that results from the

font size dependency. This can even result in a to small distance between the entry text

and the page number. Please note, the entry number width shown in the figure is only

valid if \numberline has been used. In contrast, the standard classes use a distance of

1 em after the number.

tocline

is a very flexible style. The KOMA-Script classes use this style by default for all

kinds of entries. Classes scrbook and scrreprt respectively scrartcl also define clones part,

chapter

and section respectively section and subsection, but add extra initial

code

to the clones to change their defaults.

The style supports attributes level, beforeskip, dynnumwidth, entryformat,

entrynumberformat

, breakafternumber, indent, linefill, numsep, numwidth,

onstarthigherlevel

, onstartlowerlevel, onstartsamelevel, pagenumberbox,

pagenumberformat

, raggedentrytext, and raggedpagenumber. The defaults of all

these attributes depend on the name of the entry level . They correspond to the results

of the standard classes. So after loading tocbasic, you can change the style of the stan-

dard classes entries to the table of contents into tocline using \DeclareTOCEntryStyle

without obvious visual changes unless you change exactly these attributes that should

313

Chapter 15.

I.

Text of a part entry with style tocline and with at least two lines

of text

12

numwidth

\@tocrmarg

\@pnumwidth

1. Text of a chapter entry with style tocline and for demonstration purpose

with more than one line of text

12

beforeskip

numwidth

\@tocrmarg

\@pnumwidth

1.1. Text of a section entry with style tocline and for demonstration purpose with

more than one line of text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3

1.1.10. Text of a subsection entry with style tocline and for demonstration

purpose with more than one line of text . . . . . . . . . . . . . . . . . . 12

indent

numwidth

\@tocrmarg

\@pnumwidth

Figure 15.3.: Illustrations of some attributes of a TOC-entry with style tocline

induce such changes. Same is valid for list of figures or list of tables of the standard

classes.

Because of the flexibility of this style it even could be used instead of the styles

dottedtocline

, undottedtocline or largetocline. However it needs more effort for

configuration.

Figure 15.3 illustrates some of the length attributes of this style. All attributes are

described in

table 15.1

from

page 314

.

undottedtocline

is similar to the style used by the standard classes book and report for the

chapter

entry level or by article for the section entry level of the table of contents.

It supports the attributes level, indent, and numwidth. The last one is already a

variation of the standard classes that do not support an indent of these entry levels.

Before an entry, a page break will be made easier. The entries will be indented by the

value of indent from the left. They are printed using \bfseries. \numberline is used

unchanged. The width of the entry number is given by the value of numwidth. For

multiline entries the indent will be increased by the value of numwidth for the second

and following lines.

Figure 15.4

illustrates the attributes of this style.

Table 15.1

describes all attributes of all styles defined by tocbasic. If

Beta-

Feature

you want to use these

attributes as options to \DeclareNewTOC (see

page 326

) you have to prefix the names of the

1

Text of an entry to the table of contents with style undottedtocline and

more than one line

3

numwidth

\@tocrmarg

\@pnumwidth

Figure 15.4.: Illustration of some attributes of style undottedtocline by the example of a chapter title

314

Chapter 15.

attribute by tocentry, e g., attribute level becomes option tocentrylevel. If

Beta-

Feature

you want

to use these attributes as options to \DeclareSectionCommand (see

page 390

) and similar

commands you have to prefix the names of the attributes by toc, e g., attribute level becomes

option toclevel.

Last but not least using \DeclareTOCStyleEntry will define internal command

\l@entry level

.

Table 15.1.: Attributes of the predefined TOC-entry styles of tocbasic

beforeskip=length

vertical distance, inserted before an entry of this level using style tocline (see

figure 15.3

). The distance is made using either \vskip or \addvspace depending on

the entry level to adapt the differences of the standard classes and former versions

of KOMA-Script.

At entry level part the attribute will be initialised with 2.25em plus 1pt, at

chapter

with 1em plus 1pt. If entry level currently is unknown, rather section

is initialised with 1em plus 1pt. The initial value for all other levels is 0pt plus

.2pt

.

breakafternumber=switch

switch

is one of the values for simple switches from

table 2.5

,

page 38

. If the switch

is active with style tocline, there will be a line break after the entry number of

\numberline

. The line after the entry number again starts left aligned with the

number.

This switch is not active by default at style tocline.

If the feature numberline of a list of something has been activated (see \setuptoc,

section 15.2

,

page 308

), i. e., if a KOMA-Script class with option toc=numberline

is used, then the not numbered entries will nevertheless have a (by default empty)

number line using the format code of entrynumberformat.

dynnumwidth=switch

switch

is one of the values for simple switches from

table 2.5

,

page 38

. If the switch

is active with style tocline, attribute numwidth is ignored. Instead of that the

maximum number width detected at the previous L

A

TEX run increased by the value

of numsep is used.

. . .

315

Chapter 15.

Table 15.1.: Attributes of the TOC-entry styles (continuation)

entryformat=command

This attributes makes the format of the entry. The value should be a command

with exactly one argument. The command should not expect the argument to be

fully expandable. Commands like \MakeUppercase, that need a fully expandable

argument, must no be used here. Font changes are allowed and are relative to

\normalfont\normalsize

. Please note that the output of linefill and the page

number are independent from entryformat. See also attribute pagenumberformat.

The initial value of the attribute for entry level part is printing the argument in

\large\bfseries

and for chapter printing the argument in \bfseries. If currently

no level chapter exists, section used \bfseries. All other levels print the argument

unchanged.

entrynumberformat=command

This attribute makes the format of the entry number within \numberline. The

value should be a command with exactly one argument. Font changes are relative to

the one of attribute entryformat.

The initial command prints the argument unchanged. This means the entry number

will be printed as it is.

If the feature numberline of a list of something has been activated (see \setuptoc,

section 15.2

,

page 308

), i. e., if a KOMA-Script class with option toc=numberline is

used, then the not numbered entries will nevertheless execute the command .

indent=length

Horizontal distance of the entry relative to the left margin (siehe

figure 15.1

and

figure 15.3

).

At style tocline all entry levels with a name that starts with “sub” are initialised

with the sum of the values of indent and numwidth of the entry level without this

prefix. At styles dottedtocline, undottedtocline and tocline the initial values of

levels part down to subparagraph and the levels figure and table are compatible

with the standard classes. All other levels do not have an initial value. Therefore

you have to set an explicit value for such levels when they are defined first time.

. . .

316

Chapter 15.

Table 15.1.: Attributes of the TOC-entry styles (continuation)

level=integer

The numerical value of the entry level . Only those entries are printed that have

a numerical value less or equal to counter tocdepth.

This attribute is mandatory for all styles and will be defined automatically at the

declaration of the style.

At style tocline all entry levels with a name starting with “sub”, the initial value

is the level value of the entry level without this prefix increased by one. At the

styles dottedtocline, largetocline, tocline, and undottedtocline entry levels

part

down to subparagraph, figure, and table are initialised compatible with

the standard classes. For all other levels the initialisation is done with the value of

\entry level numdepth

if this is defined.

linefill=code

At style tocline there can be a filler between the end of the entry text and the page

number. The value of attribute linefill is a code that prints this filler. For entry

level part

and chapter the attribute is initialised with \hfill. If currently no

entry level chapter

has been defined, section also uses \hfill. All other entry

levels are initialised with \TOCLineLeaderFill (see

page 321

).

If code does not result in filling the distance, you should also activate attribute

raggedpagenumber

, to avoid “underfull \hbox” messages.

numsep=length

Style tocline tries to ensure a minimum distance of length between the entry

number and the entry text. If dynnumwidth is active, it will correct the number

width to achieve this. Otherwise it simply throws a warning, if the condition is

missed.

The initial length is 0.4 em.

numwidth=length

The reserved width for the entry number (see

figure 15.1

until

figure 15.4

). At the

styles dottedtocline, tocline, and undottedtocline this length will be added

to the length of attribute indent for the second and each following entry text line.

At style tocline the initial length of all entries with a name starting with

“sub” is the value of the level without this prefix plus 0.9 em. At the styles

dottedtocline

, undottedtocline and tocline the initial length of levels part

down to subparagraph and levels figure and table is compatible to the standard

classes. All other levels do not have an initial value. Therefore you have to explicitly

set numwidth at the first definition of the entry.

. . .

317

Chapter 15.

Table 15.1.: Attributes of the TOC-entry styles (continuation)

onstarthigherlevel=code

Style tocline can execute code at the start of an entry, if the numerical level is

greater than the numerical level of the previous entry. Remember: The numerical

level of, e. g., section is greater than the numerical level of part. Nevertheless part

has the highest position in the entry hierarchy.

Please note that the detection of the level of the previous entry depends on a valid

unchanged value of \lastpenalty.

The initial code is \LastTOCLevelWasLower (see

page 320

).

onstartlowerlevel=code

Style tocline can execute code at the start of an entry, if the numerical level is

lower than the numerical level of the previous entry. Remember: The numerical level

of, e. g., part is lower than the numerical level of section. Nevertheless part has

the highest position in the entry hierarchy.

Please note that the detection of the level of the previous entry depends on a valid

unchanged value of \lastpenalty.

The initial code is \LastTOCLevelWasHigher (see

page 320

).

onstartsamelevel=code

Style tocline can execute code at the start of an entry, if the level is same like the

level of the previous entry.

Please note that the detection of the level of the previous entry depends on a valid

unchanged value of \lastpenalty.

The initial code is \LastTOCLevelWasSame (see

page 320

).

pagenumberbox=command

By default the page number of an entry is printed right aligned in a box of width

\@pnumwidth

. At style tocline the command to print the number can be changed

using this attribute. The command should have exactly one argument, the page

number.

pagenumberformat=command

This attribute is the format of the page number of an entry. The command should

have exactly one argument, the page number. Font changes are relative to the font

of entryformat followed by \normalfont\normalsize.

The initial command

of entry level part prints the argument in

\large\bfseries

. The initial command of all other levels prints the argument in

\normalfont\normalcolor

.

. . .

318

Chapter 15.

Table 15.1.: Attributes of the TOC-entry styles (continuation)

raggedentrytext=switch

v3.21

switch

is one of the values for simple switches from

table 2.5

,

page 38

. If the switch

is active, style tocline does print the text of an entry left-aligned instead of justified

and only word, that are longer than a text line, are automatically hyphenated.

This switch is not active by default.

raggedpagenumber=switch

switch

is one of the values for simple switches from

table 2.5

,

page 38

. If the switch

is active, style tocline does not force the page number to be right aligned.

Depending on the value of linefill, the setting of this attribute could be needed

for the wanted printing of the number, or only to avoid unwanted warning messages.

So both attributes should correspond.

By default the switch is not activated and therefore corresponds with an initial value

\hfill

or \TOCLineLeaderFill of attribute linefill.

\DeclareTOCEntryStyle{style }[initial code ]{command code }

\DefineTOCEntryOption{option }[default value ]{code }

\DefineTOCEntryBooleanOption{option }[default value ]{prefix }{postfix }{description }

\DefineTOCEntryCommandOption{option }[default value ]{prefix }{postfix }{description }

\DefineTOCEntryIfOption{option }[default value ]{prefix }{postfix }{description }

\DefineTOCEntryLengthOption{option }[default value ]{prefix }{postfix }{description }

\DefineTOCEntryNumberOption{option }[default value ]{prefix }{postfix }{description }

\DeclareTOCEntryStyle

Beta-

Feature

is one of the most complex commands in KOMA-Script. It is ad-

dressed to L

A

TEX developers not the L

A

TEX users. It provides the definition of a new TOC-entry

style

. Usually TOC-entries are made using \addcontentsline, or, if you use tocbasic, with

recommended \addxcontentsline (see

section 15.1

,

page 304

). In both cases L

A

TEX writes

a corresponding \contentsline into the given auxiliary file. Reading this auxiliary file each

\contentsline

results in execution of a command \l@entry level .

Whenever you assign a style to a TOC-entry level using \DeclareTOCStyleEntry, first of

all the initial code is executed and then \l@entry level is defined to be command code .

So command code is the code that will be expanded and executed by \l@entry level . Inside

command code #1

is the name of the TOC-entry level and ##1 and ##2 are the arguments of

\l@entry level

.

The initial code should initialise all attributes of the style . Developers are recom-

mended to use initial code to initialise all internal macros of the style without the need

of using an option list . The second task of the initial code is the definition of options

to setup the attributes of the style . Option level is always defined automatically. The

value of level can be got in command code using \@nameuse{#1tocdepth}, e. g., to compare

it with the counter tocdepth.

319

Chapter 15.

Commands

\DefineTOCEntryBooleanOption

,

\DefineTOCEntryCommandOption

,

\DefineTOCEntryIfOption

,

\DefineTOCEntryLengthOption

,

and

\DefineTOCEntryNumberOption

should be used to define options for the attributes of

the style inside initial code only. If you use an option defined by one of these

commands, a macro \prefix entry level postfix will be defined to be the assigned value

or the default value of the option. Somehow special is \DefineTOCEntryIfOption. It

defines \prefix entry level postfix as a command with two arguments. If the value to

the option is an activation value of

table 2.5

,

page 38

the command expands to the first

argument. If the value to the option is a deactivation value, the command expands to the

second argument.

The description should be a real short text that describes the sense of the option with

some catchwords. Package tocbasic uses this text in error messages, warnings or information

output on the terminal and into the log-file.

The most simple style of tocbasic, gobble, is defined using:

\DeclareTOCEntryStyle{gobble}{}%

If you would define a entry level dummy using:

\DeclareTOCStyleEntry[level=1]{gobble}{dummy}

among others this would do something like:

\def\dummytocdepth{1}

\def\l@dummy#1#2{}

Inside style tocline for example

\DefineTOCEntryCommandOption{linefill}[\TOCLineLeaderFill]%

{scr@tso@}{@linefill}{filling between text and page number}%

is used to define option linefill with default value \TOCLineLeaderFill. A call like:

\RedeclareTOCStyleEntry[linefill]{tocline}{part}

would therefore result in a definition like:

\def\scr@tso@part@linefill{\TOCLineLeaderFill}

Whoever likes to define his own styles is recommended to first study the definition of style

dottedtocline

. If this definition is understood, the much more complex definition of style

tocline

gives a lot of hints of the correct usage of the described commands.

In many cases it will be enough to clone an existing style using \CloneTOCEntryStyle

and to change the initial code of the new style using \TOCEntryStyleInitCode or

\TOCEntryStyleStartInitCode

.

\DefineTOCEntryOption

is merely used to define the other commands. It is not recom-

mended to define options directly using \DefineTOCEntryOption. Normally this is even not

needed. It is alluded only for completeness.

320

Chapter 15.

\CloneTOCEntryStyle{style }{new style }

With

Beta-

Feature

this command you can clone an existing style . This defines a new style with the same

attributes and settings like the existing style . The package itself uses \CloneTOCEntryStyle

to declare style default as a clone of dottedtocline. The KOMA-Script classes use the

command to declare the styles part, section, and chapter or subsection as a clone of

tocline

and the style default new as a clone of section or subsection.

\TOCEntryStyleInitCode{style }{initial code }

\TOCEntryStyleStartInitCode{style }{initial code }

Every

Beta-

Feature

TOC-entry style has an initialisation code. This is used whenever a style is as-

signed to an TOC-entry using \DeclareTOCEntryStyle. This initial code should never

do anything global, because it is also used for local initialisation inside other commands like

\DeclareNewTOC

. The initial code not only defines all attributes of a style . It also should

set the defaults for those attributes.

You can use \TOCEntryStyleStartInitCode and \TOCEntryStyleInitCode to extend the

already existing initialisation code by initial code . \TOCEntryStyleStartInitCode adds

initial code

in front of the existing initialisation code. \TOCEntryStyleInitCode adds the

initial code

at the end of the existing initialisation code. The KOMA-Script classes, e. g.,

are using \TOCEntryStyleStartInitCode to change the filling, font and vertical distances of

style part that is a clone of tocline. Class scrbook and scrreprt use

\CloneTOCEntryStyle{tocline}{section}

\TOCEntryStyleStartInitCode{section}{%

\expandafter\providecommand%

\csname scr@tso@#1@linefill\endcsname

{\TOCLineLeaderFill\relax}%

}

to declare section as a modified clone of tocline.

\LastTOCLevelWasHigher

\LastTOCLevelWasSame

\LastTOCLevelWasLower

At

Beta-

Feature

the very beginning entries with style tocline tocbasic executes one of these three commands

depending on \lastpenalty. \LastTOCLevelWasHigher and \LastTOCLevelWasSame used in

vertical mode add \addpenalty{\@lowpenalty} and therefore permit a page break before

an entry with same or higher hierarchical position. \LastTOCLevelWasLower is an empty

command. Therefore page break between an entry and its sub-entry is not permitted.

Users should not redefine these commands. Instead of a redefinition you should change the

behaviour of single entry levels using attributes onstartlowerlevel, onstartsamelevel, and

onstarthigherlevel

.

321

Chapter 15.

\TOCLineLeaderFill[filling code ]

Command

Beta-

Feature

has been made to be used as value of option linefill of assigning style tocline to

a TOC-entry. It is a line filler between the end of the entry text and the entry page number.

The filling code will be repeated with constant distance. The default for this optional

argument is a dot.

As implied by the name of the command it uses \leaders to put the filling code .

The distance is defined analogous to the L

A

TEX kernel command \@dottedtocline by

\mkern\@dotsep mu

.