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

Example: Maybe you want to know if the file name extension “foo” is already in use to

report an error, if you can not use it:

\ifattoclist{foo}{%

\PackageError{bar}{%

extension ‘foo’ already in use%

}{%

1

Translation of this chapter has been made by the package author and needs editing!

2

Here we do not talk about the aux-file but the auxiliary files used indirect via the aux-file, e. g., the toc-file,

the lof-file, or the lot-file.

301

Chapter 15.

Each extension may be used only

once.\MessageBreak

The class or another package already

uses extension ‘foo’.\MessageBreak

This error is fatal!\MessageBreak

You should not continue!}%

}{%

\PackageInfo{bar}{using extension ‘foo’}%

}

\addtotoclist[owner ]{extension }

This command adds the extension to the list of known extensions. But if the extension

is a known one already, then an error will be reported to avoid double usage of the same

extension

.

If the optional argument, [owner ], was given, this owner will be stored to be the owner

of the extension . If the optional argument has been omitted, tocbasic tries to find out the

file name of the current processed class or package and stores this as owner. This will fail if

\addtotoclist

was not used, loading a class or package but using a command of a class or

package after loading this class or package. In this case the owner will be set to “.”.

Please note that an empty owner is not the same like omitting the optional argument with

the braces. An empty argument would result in an empty owner.

Example: You want to add the extension “foo” to the list of known extension, while loading

your package with file name “bar.sty”:

\addtotoclist{foo}

This will add the extension “foo” with owner “bar.sty” to the list of known

extensions, if it was not already in the list of known extensions. If the class or

another package already added the extension you will get the error:

Package tocbasic Error: file extension ‘foo’ cannot be used twice

See the tocbasic package documentation for explanation.

Type

H 

for immediate help.

and after typing h and pressing the return key you will get the help:

File extension ‘foo’ is already used by a toc-file, while bar.sty

tried to use it again for a toc-file.

This may be either an incompatibility of packages, an error at a ←

package,

or a mistake by the user.

Maybe your package has a command, that creates list of files dynamically. In this

case you should use the optional argument of \addtotoclist to set the owner.

302

Chapter 15.

\newcommand*{\createnewlistofsomething}[1]{%

\addtotoclist[bar.sty]{#1}%

% Do something more to make this list of something available

}

If the user calls now, e. g.,

\createnewlistofsomething{foo}

this would add the extension “foo” with the owner “bar.sty” to the list of known

extension or report an error, if the extension is already in use.

You may use any owner you want. But it should be unique! So, if you would be, e. g., the author

of package float you could use for example owner “float” instead of owner “float.sty”, so

the KOMA-Script options for the list of figures and the list of tables will also handle the lists

of this package. Those are already added to the known extensions when the option is used.

This is because KOMA-Script already registers file name extension “lof” for the list of figures

and file name extension “lot” for the list of tables with owner “float” and sets options for

this owner. Package scrhack redefines some of package float’s commands to do this.

\AtAddToTocList[owner ]{instructions }

This command adds the instructions to an internal list of instructions that will be processed

whenever a file name extension with the given owner will be added to the list of known

extensions using \addtotoclist. The optional argument is handled in the same way as with

the command \addtotoclist. With an empty owner you may add {instructions }, that

will be processed at every successful \addtotoclist, after processing the instructions for the

individual owner. While processing the instructions, \@currext will be set to the extension

of the currently added extension.

Example: tocbasic itself uses

\AtAddToTocList[]{%

\expandafter\tocbasic@extend@babel

\expandafter{\@currext}%

}

to add every extension to the tocbasic-internal babel handling of files.

The

two

\expandafter

commands

are

needed,

because

the

argument

of \tocbasic@extend@babel has to be expanded!

See the description of

\tocbasic@extend@babel

at

section 15.4

,

page 321

for more information.

\removefromtoclist[owner ]{extension }

This command removes the extension from the list of known extensions. If the optional

argument, [owner ], was given, the extension will only be removed if it was added by this

303

Chapter 15.

owner

. See description of \addtotoclist for information of omitting optional argument.

Note that an empty owner is not the same like omitting the optional argument, but removes

the extension without any owner test.

\doforeachtocfile[owner ]{instructions }

Until now you’ve learned to know commands that result in more safety in handling file name

extensions, but also needs some additional effort. With \doforeachtocfile you will win for

this. The command provides to processes instructions for every known file name extension

of the given owner . While processing the instructions \@currext is the extension of the

current file. If you omit the optional argument, [owner ], every known file name extension

independent from the owner will be used. If the optional argument is empty, only file name

extensions with an empty owner will be processed.

Example: If you want to type out all known extensions, you may simply write:

\doforeachtocfile{\typeout{\@currext}}

and if only the extensions of owner “foo” should be typed out:

\doforeachtocfile[foo]{\typeout{\@currext}}

\tocbasicautomode

This command redefines L

A

TEX kernel macro \@starttoc to add all not yet added extensions

to the list of known extensions and use \tocbasic@starttoc instead of \@starttoc. See

section 15.4

,

page 321

for more information about \tocbasic@starttoc and \@starttoc.

This means that after using \tocbasicautomode every table of contents or list of something,

that will be generated using \@starttoc will be at least partially under control of tocbasic.

Whether or not this will make the wanted result, depends on the individual TOC. At least

the babel control extension for all those TOCs will work. Nevertheless, it would be better

if the author of the corresponding class or package will use tocbasic explicitly. In that case

additional advantages of tocbasic may be used that will be described at the following sections.

15.2. Creating a Table or List of Contents

In the previous section you’ve seen commands to handle a list of known file name extensions

and to trigger commands while adding a new extension to this list. You’ve also seen a command

to do something for all known extensions or all known extensions of one owner. In this section

you will learn to know commands to handle the file corresponding with an extension or the

list of known extensions.

\addtoeachtocfile[owner ]{content }

This command writes content to the TOC-files of every known file name extension of owner

using L

A

TEX kernel command \addtocontents. If you omit the optional argument, content

304

Chapter 15.

is written to the files of every known file name extension. Furthermore, the practical file name

is built from \jobname and the file name extension. While writing the content , \@currext

is the extension of the currently handled file.

Example: You may add a vertical space of one text line to all toc-files.

\addtoeachtocfile{%

\protect\addvspace{\protect\baselineskip}%

}

And if you want to do this, only for the TOC-files of owner “foo”:

\addtoeachtocfile[foo]{%

\protect\addvspace{\protect\baselineskip}%

}

Commands, that shouldn’t be expanded while writing, should be prefixed by \protect in the

same way like they should be in the argument of \addtocontents.

\addxcontentsline{extension }{level }[number ]{text }

The command \addxcontentsline adds an entry of given level to TOC-file with file name

extension

. If the {number } is empty or omitted the entry will not have number for the

entry with the given text . Entries without number may be left aligned to the number of the

numbered entries of the same level or indented like the text of the numbered entries of the

same level , depending on the numberline feature.

Example: Maybe you are not using a KOMA-Script class but need a not numbered chapter

with entry to the table of contents. This may be done using

\cleardoublepage

\csname phantomsection\endcsname

\addxcontentsline{toc}{chapter}

{Chapters without Numbers}

\chapter*{Chapters without Numbers}

\markboth{Chapters without Numbers}{}

As you can see, you simply have to replace usual \addcontentsline by

\addxcontentsline

to support the tocbasic feature numberline.

Note that \addxcontentsline uses \addlevel extension entry if such a macro ex-

ists and \tocbasic@addxcontentsline otherwise. Therefore you cannot define a macro

\addlevel extension entry

using \addxcontentsline but \tocbasic@addxcontentsline.

It is recommended to use \addxcontentsline instead of \addcontentsline whenever pos-

sible.

305

Chapter 15.

\addcontentslinetoeachtocfile[owner ]{level }{contentsline }

\addxcontentslinetoeachtocfile[owner ]{level }[number ]{text }

The first command is something like \addcontentsline from L

A

TEX kernel. In difference to

that it writes the contentsline not only into one file, but into all files of all known file name

extensions or of all known file name extensions of a given owner.

The command \addxcontentslinetoeachtocfile is similar but uses \addxcontentsline

instead of \addcontentsline and therefore supports tocbasic feature numberline.

Example: You are a class author and want to write the chapter entry not only to the table of

contents TOC-file but to all TOC-files, while #1 is the title, that should be written

to the files.

\addxcontentslinetoeachtocfile

{chapter}[\thechapter]{#1}%

In this case the current chapter number should be expanded while writing into the

file. So it isn’t protected from expansion using \protect.

While writing \@currext is the file name extension of the file into which contentsline will

be written.

It

is

recommended

to

use

\addxcontentslinetoeachtocfile

instead

of

\addcontentslinetoeachtocfile

whenever possible.

\listoftoc[list of title ]{extension }

\listoftoc*{extension }

\listofeachtoc[owner ]

\listofextension name

These commands may be used to print the TOC corresponding to file name extension . The

star version \listoftoc* needs only one argument, the extension of the file. It does setup

the vertical and horizontal spacing of paragraphs, calls before hooks, reads the file, and last

but not least calls the after hooks. You may interpret it as direct replacement of the L

A

TEX

kernel macro \@starttoc.

The version without star, prints the whole file with title, optional table of contents entry,

and running heads. If the optional argument [list of title ] was given, it will be used as

title term, optional table of contents entry and running head. Please note: If the optional

argument is empty, this term will be empty, too! If you omit the optional argument, but

\listofextension name

was defined, that will be used. If that is also not defined, a standard

replacement name will be used and reported by a warning message.

The command \listofeachtoc outputs all lists of something of the given owner or of all

known file extensions. Thereby \listofextension name should be defined to get the correct

titles.

It is recommended to define \listofextension name for all used file name extensions, be-

cause the user itself may use \listofeachtoc.

306

Chapter 15.

Example: Assumed, you have a new “list of algorithms” with extension loa and want to

show it:

\listoftoc[List of Algorithms]{loa}

will do it for you. But maybe the “list of algorithms” should not be set with a

title. So you may use

\listof*{loa}

Note that in this case no entry at the table of contents will be created, even if you’d

used the setup command above. See command \setuptoc at

page 308

for more

information about the attribute of generating entries into the table of contents

using \setuptoc.

If you’ve defined

\newcommand*{\listofloaname}{%

List of Algorithms%

}

before, then

\listoftoc{loa}

would be enough to print the list of algorithms with the wanted heading. For the

user it may be easier to operate, if you’d define

\newcommand*{\listofalgorithms}{\listoftoc{loa}}

additionally.

Because L

A

TEX normally opens a new file for each of those lists of something immediately,

the call of each of those commands may result in an error like:

! No room for a new \write .

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

\fi

if there are no more write handles left. Loading package scrwfile (see

chapter 14

) may solve

this problem.

\BeforeStartingTOC[extension ]{instructions }

\AfterStartingTOC[extension ]{instructions }

Sometimes it’s useful, to process instructions immediately before reading the auxiliary file

of a TOC. These commands may be used to process instructions before or after loading

the file with given extension using \listoftoc*, \listoftoc, or \listofeachtoc. If you

omit the optional argument (or set an empty one) the general hooks will be set. The general

before hook will be called before the individuel one and the general after hook will be called

after the individuel one. While calling the hooks \@currext is the extension of the TOC-file

and should not be changed.

307

Chapter 15.

An example for usage of \AfterStartingTOC may be found in

section 14.3

at

page 298

.

\BeforeTOCHead[extension ]{instructions }

\AfterTOCHead[extension ]{instructions }

This commands may be used to process instructions before or after setting the title of

a TOC corresponding to given file name extension using \listoftoc* or \listoftoc. If

you omit the optional argument (or set an empty one) the general hooks will be set. The

general before hook will be called before the individuel one and the general after hook will be

called after the individuel one. While calling the hooks \@currextIndexCmd@currext is the

extension of the corresponding file and should not be changed.

\MakeMarkcase{text }

Whenever tocbasic sets a mark for a running head, The text of the mark will be an argument

of \MakeMarkcase. This command may be used, to change the case of the letters at the

running head if wanted. The default is, to use \@firstofone for KOMA-Script classes. This

means the text of the running head will be set without change of case. \MakeUppercase will

be used for all other classes. If you are the class author you may define \MakeMarkcase on

your own. If scrlayer or another package, that defines \MakeMarkcase will be used, tocbasic

will not overwrite that definition.

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

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

308

Chapter 15.

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

ternal heading command. On the other hand, if an user defined heading com-

mand has been made with \deftocheading, that user is responsible for the eval-

uation of the feature.

The KOMA-Script classes set this feature using option

listof=leveldown

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

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

309

Chapter 15.

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

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

.