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

Example: For incomprehensible reasons, you want to set the running heads in lower case

letters only. To make this automatically for all running heads, that will be set by

tocbasic, you define:

\let\MakeMarkcase\MakeLowercase

Please allow me some words about \MakeUppercase, First of all this command isn’t fully

expandable. This means, that problems may occur using it in the context of other commands.

Beyond that typographers accord, that whenever setting whole words or phrases in capitals,

letter spacing is absolutely necessary. But correct letter spacing of capitals should not be

done with a fix white space between all letters. Different pairs of letters need different space

between each other. Additional some letters build holes in the text, that have to be taken

Chapter 15: Management of Tables and Lists of Contents Using tocbasic

354

into account. Packages like ulem or soul doesn’t provide this and \MakeUppercase does not

do anything like this. Also automatic letter spacing using package microtype is only one step

to a less-than-ideal solution, because it cannot recognize and take into account the glyphs of

the letters. Because of this typesetting whole words and phrases is expert work and almost

ever must be hand made. So average users are recommended to not do that or to use it only

spare and not at exposed places like running heads.

\deftocheading{extension }{definition }

The package tocbasic contains a standard definition for typesetting headings of TOCs. This

standard definition is configurable by several features, described at

\setuptoc

next. But

if all those features are not enough, an alternative heading command may be defined using

\deftocheading

. Thereby extension is the file name extension of the corresponding TOC-

file. The definition of the heading command may use one single parameter #1. While

calling the newly defined command inside of

\listoftoc

or

\listofeachtoc

that #1 will be

replaced by the corresponding heading term.

\setuptoc{extension }{feature list }

\unsettoc{extension }{feature list }

This commands set up and unset features bound to a file name extension . The feature

list

is a comma separated list of single features. tocbasic does know following features:

leveldown

uses not the top level heading below

\part

—

\chapter

if available,

\section

otherwise — but the first sub level. 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=leveldown

important

listof=

leveldown

for all file name extensions of the owner float.

nobabel

prevents usage of the language switch of babel at the TOC-file with the corresponding

file name extension . This feature should be used only for auxiliary files, that contain

text in one language only. Changes of the language inside of the document will not longer

regarded at the TOC-file. Package scrwfile uses this feature also for clone destinations,

because those will get the language change from the clone source already.

Please note, the feature is executed while adding a file extension to the list of known file

extension. Changing the feature afterwards would not have any effect.

noparskipfake

prevents

v3.17

usage of an extra \parskip before switching \parskip off. In gen-

eral, the consequence of this feature for documents using paragraph distance is less ver-

tical space between heading and first entry than between normal headings and normal

text.

Chapter 15: Management of Tables and Lists of Contents Using tocbasic

355

noprotrusion

prevents

v3.10

disabling character protrusion at the TOC. Character protrusion at

the TOCs will be disabled by default if package microtype or another package, that

supports \microtypesetup, was loaded. So if you want protrusion at a TOC, you have

to set this feature. But note, with character protrusion TOC-entries may be printed

wrong. This is a known issue of character protrusion.

numbered

uses a numbered heading for the TOC and because of this also generates an entry

to the table of contents. This feature will be evaluated by the internal heading com-

mand. 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=numbered

for all file name extensions

of the owner float.

numberline

v3.12

redefines \nonumberline to use

\numberline

. With this the not numbered

entries generated by KOMA-Script or using \nonumberline at the very beginning of

the last argument of \addcontentline will also be indented like numbered entries of

the same type. Using

v3.20

\numberline

for entries without number

v3.20

can have additional

side effects if you use entry style tocline. See style attribute breakafternumber and

entrynumberformat

in

table 15.1

from

page 360

downwards.

KOMA-Script classes set this feature for the file name extensions of the owner float if

you use option

listof=numberline

and for file name extension toc if you use option

toc=numberline

. Analogous they reset this feature if you use

listof=nonumberline

or

toc=nonumberline

.

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 348

) 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:

Chapter 15: Management of Tables and Lists of Contents Using tocbasic

356

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 133

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}

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 321

).

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

Chapter 15: Management of Tables and Lists of Contents Using tocbasic

357

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.

tocdepth

Entries to tables or lists of contents are in hierarchical order. Therefore each entry level has

a numerical value. Higher values correspond with deeper levels. Within the standard classes,

e. g., parts have the numerical entry level -1 in the table of contents and chapter entries have

value 0. Counter tocdepth defines the deepest level that should be shown in the tables and

lists of any contents.

Class book sets tocdepth to 2, so entries of the levels part, chapter, section, and

subsection

are printed. Deeper levels like subsubsection, which has the numerical value 3,

are not printed. Nevertheless the entries are part of the auxiliary file for the table of contents.

Most entry styles of tocbasic also cares about tocdepth.

Only style gobble (see

\DeclareTOCStyleEntry

) ignores tocdepth.

\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.

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:

Chapter 15: Management of Tables and Lists of Contents Using tocbasic

358

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

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.

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

Chapter 15: Management of Tables and Lists of Contents Using tocbasic

359

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

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

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 360

.

undottedtocline

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

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

Chapter 15: Management of Tables and Lists of Contents Using tocbasic

360

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

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 373

) you have to prefix the names of the

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

v3.20

you want

to use these attributes as options to

\DeclareSectionCommand

(see

page 446

) 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

.

. . .

Chapter 15: Management of Tables and Lists of Contents Using tocbasic

361

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

breakafternumber=switch

switch

is one of the values for simple switches from

table 2.5

,

page 39

. 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 354

), 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 39

. 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.

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 354

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

toc=numberline

is

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

. . .