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

Example: Assumed, you want a short table of contents with only the chapter level but an

additional entry with the table of contents:

\usepackage{scrwfile}

\TOCclone[Short \contentsname]{toc}{stoc}

Chapter 14: Economise and Replace Files Using scrwfile

344

This would create a new table of contents with the heading “Short Contents”. The

new table of contents uses a helper file with extension stoc. All entries to the

helper file with extension toc will also be copied to this new helper file.

The new short table of contents should only have the chapter entries. This may

be done using:

\addtocontents{stoc}{\protect\value{tocdepth}=0}

Normally you cannot write into a helper file before \begin{document}. But using

scrwfile changes this. So the code above is correct already after loading scrwfile.

To show the new short contents of helper file extension stoc we use

\listofstoc

somewhere after \begin{document}.

If we also want an entry for the table of contents at the short contents, we cannot

use

\addtocontents{toc}{% write to the Contents

\protect\addcontentslinedefault{stoc}% write to Short Contents

{chapter}% a chapter entry with

{\contentsname}% the Contents’ name

}

because the \addcontentsline command would be copied to stoc too. So we

cannot add the command to the toc-file. Package tocbasic may be used to solve

this:

\BeforeStartingTOC[toc]{%

\addcontentslinedefault{stoc}{chapter}

{\protect\contentsname}%

}

However, this needs, that the file with extension toc is under control of package

tocbasic, which is indeed the case within all KOMA-Script classes. See

section 15.2

on

page 353

for more information about

page 353

.

14.4. Note on State of Development

Eventhough this package has been tested by several users and even is in productivity usage

several times it is still under construction. Therefore, there might be amendments especially to

the internal functionality. Most likely the package will be extended. Some code for extensions

is already in the package. However, there is currently no user documentation available, as up

to now nobody has requested any of these extensions.

Chapter 14: Economise and Replace Files Using scrwfile

345

14.5. Known Package Incompatibilities

As mentioned in

section 14.1

, scrwfile redefines some commands of the L

A

TEX kernel. This

happens not only while loading the package, but indeed at different times of processing a

document, e. g., just before reading the aux-file. This results in incompatibility with packages

that also redefine these commands at run-time.

The titletoc package is an example for such an incompatibility. That package redefines

\@writefile

under some conditions at run-time. If you use both, scrwfile and titletoc, there

is no warranty for the correct behaviour of neither of them. This is neither an error of titletoc

nor of scrwfile.

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

346

Management of Tables and Lists of Contents Using tocbasic

1

The main purpose of package tocbasic is to provide features for authors of classes and packages

to create own tables or lists of contents like the list of figures and the list of tables and thereby

allow other classes or packages some types of control over these. For examples package tocbasic

delegates language control of all these tables and lists of contents to package babel (see [

BB13

]).

So automatic change of language will be provided inside all these tables and lists of contents.

Using tocbasic will exculpate authors of classes and packages from implementation of such

features.

KOMA-Script itself uses tocbasic not only for the table of contents but also for the already

mentioned lists of figures and tables. In this chapter we call all kinds of tables of contents or

lists of contents simply TOC.

15.1. Basic Commands

Basic commands are used to handle a list of all file name extensions known for files representing

a table or list of contents. We call these auxiliary files

2

TOC-files independent from the file

name extension that is used. Entries to such files are typically written using \addtocontents

or \addcontentsline. Later in this chapter you will learn to know recommended, additional

commands. There are also commands to do something for all known extensions. Additionally,

there are commands to set or unset features of a file name extension or the file represented by

the extension. Typically an extension also has an owner. This owner may be a class or package

or a term decided by the author of the class or package using tocbasic, e. g., KOMA-Script

uses the owner float for list of figures and list of tables, and the file name of the class file as

owner for the table of contents.

\ifattoclist{extension }{truepart }{false part }

This command may be used to ask, whether or not a file name extension is already a known

extension. If the extension is already known the true instructions will be used, otherwise

the false instructions will be used.

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.

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

347

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.

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

348

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

for more information.

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

349

\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

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 368

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.

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

350

\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

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

.

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

351

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

sible.

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

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

352

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.

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 354

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.

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

353

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

An example for usage of \BeforeStartingTOC may be found in

section 14.3

at

page 344

.

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