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

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

362

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

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.

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 367

).

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.

. . .

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

363

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

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.

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 367

).

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 367

).

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 367

).

. . .

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

364

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

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

.

raggedentrytext=switch

v3.21

switch

is one of the values for simple switches from

table 2.5

,

page 39

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

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

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

365

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

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

.

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 39

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}{}%

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

366

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.

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

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

367

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

.

\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

.

15.4. Internal Commands for Class and Package Authors

Commands with prefix \tocbasic@ are internal but class and package authors may use them.

But even if you are a class or package author you should not change them!

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

368

\tocbasic@extend@babel{extension }

The Package babel (see [

BB13

]), or more specifically a L

A

TEX kernel that has been extended

by the language management of babel writes instructions to change the language inside of

the files with the file name extensions toc, lof, and lot into those files at every change of

the current language either at the begin of the document or inside the document. Package

tocbasic extends this mechanism with \tocbasic@extend@babel to be used for other file name

extensions too. Argument extension has to be expandable! Otherwise the meaning of the

argument may change until it will be used really.

Normally this command will be used by default for every file name extension that will be

added to the list of known extensions using

\addtotoclist

. This may be suppressed using

feature nobabel (see

\setuptoc

,

section 15.2

,

page 354

). For the file name extensions toc,

lof

, and lot this will be done automatically by tocbasic to avoid double language switching

in the corresponding files.

Normally there isn’t any reason to call this command yourself. But there may by lists

of something, that should not be under control of tocbasic, and so are not in tocbasic’s list

of known file name extensions, but nevertheless should be handled by the language change

mechanism of babel. The command may be used explicitly for those files. But please note

that this should be done only once per file name extension!

\tocbasic@starttoc{extension }

This command is something like the L

A

TEX kernel macro \@starttoc. It is the command

behind

\listoftoc*

(see

section 15.2

,

page 351

). Authors of classes or packages who want to

participate from the advantages of tocbasic should at least use this command. Nevertheless it is

recommended to use

\listoftoc

. Command \tocbasic@starttoc internally uses \starttoc,

but sets \parskip and \parindent to 0 and \parfillskip to 0 until infinite before. Moreover,

\@currext

will be set to the file name extension of the current TOC-file, so this will be available

while the execution of the hooks, that will be done before and after reading the auxiliary files.

Because of L

A

TEX will immediately open a new TOC-file for writing after reading that file,

the usage of \tocbasic@starttoc may result in an error message like

! No room for a new \write .

\ch@ck ...\else \errmessage {No room for a new #3}

\fi

if there are no more unused write handles. This may be solved, e. g., using package scrwfile.

See

chapter 14

for more information about that package.

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

369

\tocbasic@@before@hook

\tocbasic@@after@hook

The hook \tocbasic@@before@hook will be executed immediately before reading a auxiliary

file for a TOC even before execution of the instructions of a

\BeforeStartingTOC

command.

It is permitted to extend this hook using \g@addto@macro.

Similarly \tocbasic@@after@hook will be executed immediately after reading such an aux-

iliary file and before execution of instructions of

\AfterStartingTOC

. It is permitted to extend

this hook using \g@addto@macro.

KOMA-Script uses these hooks, to provide the automatic width calculation of the place

needed by heading numbers. Only classes and packages should use these hooks. Users should

really use

\BeforeStartingTOC

and

\AfterStartingTOC

instead. Authors of packages should

also favour those commands! These hooks should not be used to generate any output!

If neither

\listofeachtoc

nor

\listoftoc

nor

\listoftoc*

are used for the output of a

TOC, the hooks should be executed explicitly.

\tocbasic@extension @before@hook

\tocbasic@extension @after@hook

These hooks are processed after

\tocbasic@@before@hook

,

respectively before

\tocbasic@@after@hook

before and after loading the TOC-file with the corresponding

file extension . Authors of classes and packages should never manipulate them! But if

neither

\listofeachtoc

nor

\listoftoc

nor

\listoftoc*

are used for the output of a TOC,

the hooks should be executed explicitly, if they are defined. Please note that they even can

be undefined.

\tocbasic@listhead{title }

This command is used by

\listoftoc

to set the heading of the TOC, either the default

heading or the individually defined heading. If you define your own TOC-command not using

\listoftoc

you may use \tocbasic@listhead. In this case you should define \@currext to

be the file extension of the corresponding TOC-file before using \tocbasic@listhead.

\tocbasic@listhead@extension {title }

This command is used in

\tocbasic@listhead

to set the individual headings, optional table

of contents entry, and running head, if it was defined. If it was not defined it will be defined

and used in

\tocbasic@listhead

automatically.

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

370

\tocbasic@addxcontentsline{extension }{level }{number }{text }

\nonumberline

Command

v3.12

\tocbasic@addxcontentsline

uses \addcontentsline to either create a num-

bered or not numbered text entry to the TOC-file with the given extension . Note, all param-

eters of \tocbasic@addxcontentsline are mandatory. But you may use an empty number ar-

gument, if you do not want a number. In this case the text will be prefixed by \nonumberline

without any argument. In the other case, if number is not empty,

\numberline

with argument

number

will used as usual.

Command \nonumberline is redefined inside

\listoftoc

(see

section 15.2

,

page 351

) de-

pending on feature numberline (see

section 15.2

,

page 354

). This guarantees that changes of

the feature results in changes of the corresponding TOC immediately at the next L

A

TEX run.

\tocbasic@DependOnPenaltyAndTOCLevel{entry level }

\tocbasic@SetPenaltyByTOCLevel{entry level }

At

Beta-Feature

the end of TOC-entry style tocline (see

section 15.3

) \penalty is set to pro-

hibit page breaks.

The used penalty value depends on the entry level .

This

is done by \tocbasic@SetPenaltyByTOCLevel.

At the very beginning of an entry

\tocbasic@DependOnPenaltyAndTOCLevel

is used to execute the value of either style

option onstartlowerlevel, onstartsamelevel, or onstarthigherlevel depending on

\lastpenalty

and the current entry level . The default of the first and second option

would be to permit a page break, if used in vertical mode.

Developers of tocline-compatible styles should adapt this.

To do so, they

are even allowed to copy the style option declarations of onstartlowerlevel,

onstartsamelevel

,

and onstarthigherlevel.

These options should even

use

the

same

internal

macros

\scr@tso@entry level @LastTOCLevelWasHigher

,

\scr@tso@entry level @LastTOCLevelWasSame

and \scr@tso@entry level @LastTOCLevelWasLower

to store the current values of the options.