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

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!

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

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

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

322

Chapter 15.

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

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

323

Chapter 15.

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

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

) de-

pending on feature numberline (see

section 15.2

,

page 308

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

15.5. A Complete Example

This section will show you a complete example of a user defined floating environment with list

of that kind of floats and KOMA-Script integration using tocbasic. This example uses internal

commands, that have a “@” in their name. This means, that the code has to be put into a

package or class, or has to be placed between \makeatletter and \makeatother.

First of all, a new floating environment will be needed. This could simply be done using:

324

Chapter 15.

\newenvironment{remarkbox}{%

\@float{remarkbox}%

}{%

\end@float

}

To the new environment is named remarkbox.

Each floating environment has a default placement. This is build by some of the well known

placement options:

\newcommand*{\fps@remarkbox}{tbp}

So, the new floating environment should be placed by default only either at the top of a page,

at the bottom of a page, or on a page on its own.

Floating environments have a numerical floating type. Environments with the same active

bit at the floating type cannot change their order. Figures and table normally use type 1 and

2. So a figure that comes later at the source code than a table, may be output earlier than

the table and vica versa.

\newcommand*{\ftype@remarkbox}{4}

The new environment has floating type 4, so it may pass figures and floats and may be passed

by those.

The captions of floating environment also have numbers.

\newcounter{remarkbox}

\newcommand*{\remarkboxformat}{%

Remark~\theremarkbox\csname autodot\endcsname}

\newcommand*{\fnum@remarkbox}{\remarkboxformat}

Here first a new counter has been defined, that is independent from chapters or the counters of

other structural levels. L

A

TEX itself also defines \theremarkbox with the default Arabic repre-

sentation of the counter’s value. Afterwards this has been used defining the formatted output

of the counter. Last this formatted output has been used for the output of the environment

number of the \caption command.

Floating environments have lists of themselves and those need a auxiliary file with name

\jobname

and a file name extension, the TOC-file:

\newcommand*{\ext@remarkbox}{lor}

The file name extension of the TOC-file for the list of remarkboxes is “lor”.

This was the definition of the floating environment. But the list of this new environment’s

captions is still missing. To reduce the implementation effort package tocbasic will be used for

this. This will be loaded using

\usepackage{tocbasic}

inside of document preambles. Authors of classes or packages would use

325

Chapter 15.

\RequirePackage{tocbasic}

instead.

Now we register the file name extension for package tocbasic:

\addtotoclist[float]{lor}

Thereby the owner float has been used, to allude all further KOMA-Script options for list of

figures and list of tables also to the new one.

Next we define a title or heading for the list of remarkboxes:

\newcommand*{\listoflorname}{List of Remarks}

You may use package scrbase to additionally support titles in other languages than English.

Also a command is needed to define the layout of the entries to the list of remarks:

\newcommand*{\l@remarkbox}{\l@figure}

Here simply the entries to the list of remarks get the same layout like the entries to the list of

figures. This would be the easiest solution. A more explicit would be, e. g.,

\DeclareTOCStyleEntry[level=1,indent=1em,numwidth=1.5em]%

{tocline}{remarkbox}

Additionally you may want structure the list of remarks depending on chapters.

\setuptoc{lor}{chapteratlist}

The KOMA-Script classes provide that feature and maybe other classes do so too. Unfortu-

nately the standard classes do not.

This would already be enough. Now, users may already select different kinds of headings

either using the corresponding options of the KOMA-Script classes, or \setuptoc, e. g., with

or without entry in the table of contents, with or without number. But a simple

\newcommand*{\listofremarkboxes}{\listoftoc{lor}}

may make the usage a little bit easier again.

As you’ve seen only five commands refers to the list of remarks. Only three of them are

necessary. Nevertheless the new list of remarks already provides optional numbering of the

heading and optional not numbered entry into the table of contents. Optional even a lower

document structure level may be used for the heading. Running headers are provides with

the KOMA-Script classes, the standard classes, and all classes that explicitly support tocbasic.

Supporting classes even pay attention to this new list of remarks at every new \chapter. Even

changes of the current language are handled inside the list of remarks like they will inside the

list of figures or inside the list of tables.

Moreover, an author of a package may add more features. For example, options to hide

\setuptoc

from the users may be added. On the other hand, the tocbasic manual may be

referenced to describe the corresponding features. The advantage of this would be that user

would get information about new features provides by tocbasic. But if the user should be able

326

Chapter 15.

to set the features of the remarks even without knowledge about the file name extension lor

a simple

\newcommand*{\setupremarkboxes}{\setuptoc{lor}}

would be enough to use a list of features argument to \setupremarkboxes as list of features

of file name extension lor.

15.6. Everything with One Command Only

The example from the previous section shows, that using tocbasic to define floating environ-

ments and lists with the captions of those floating environments is easy. The following example

will show, that it may be even easier.

\DeclareNewTOC[options ]{extension }

This command declares

v3.06

in one step only a new TOC, the heading of that TOC, the term used

for the TOC-entries, and to manage the file name extension . Additionally optional floating

and non-floating environments may be defined, and inside of both such environments \caption

may be used. The additional features \captionabove, \captionbelow, and captionbeside

of the KOMA-Script classes (see

section 3.20

) may also be used inside of those environments.

Argument extension is the file name extension of the TOC-file, that represents the list of

something. See

section 15.1

for more information about this. This argument is mandatory

and must not be empty!

Argument options is a comma separated list, like you know it from, e. g., \KOMAoptions

(see

section 2.4

). Nevertheless, those options cannot be set using \KOMAoptions! An overview

of all available options may be found in

table 15.2

.

If

Beta-

Feature

option tocentrystyle is not used, style default will be used. For information about

this style see

section 15.3

. If you do not want to define a command for entries to the list

of something, you can use an empty argument, i. e., tocentrystyle= or tocentrystyle={}.

Nevertheless, this would contain the risk to get a lot of errors while printing that list.

Depending

Beta-

Feature

Beta-

Feature

on the style of the entries to the list of something, you can setup all valid

attributes of the selected style as part of the options . To do so you have to prefix the names

of the attributes given in

table 15.1

from

page 314

by prefix tocentry. Later changes of the

style of the entries can be made using \DeclareTOCStyleEntry. See

section 15.3

,

page 311

for more information about the styles.

327

Chapter 15.

Table 15.2.: Options for command \DeclareNewTOC

v3.06

atbegin=instructions

v3.09

The instructions will be executed at the begin of the floating or non-floating

environment.

atend=instructions

v3.09

The instructions will be executed at the end of the floating or non-floating envi-

ronment.

counterwithin=L

A

TEX counter

If you define a float or non-float, the captions will be numbered and a counter type

(see option type) will be defined. You may declare another counter to be the parent

L

A

TEX counter. In this case, the parent counter will be set before the float counter

and the float counter will be reset whenever the parent counter is increased using

\stepcounter

or \refstepcounter.

float

If set, float environments for that type will be defined. The names of the environ-

ments are the value of type and for double column floats the value of type with

addendum “*”.

floatpos=float positions

The default floating position of the float. If no float position was given, “tbp” will

be used like the standard classes do for figures and tables.

floattype=number

The numerical float type of the defined floats. Float types with common bits cannot

be reordered. At the standard classes figures has float type 1 and tables has float

type 2. If no float type was given, 16 will be used.

forcenames

If set, the names will be even defined, if they where already defined before.

hang=length

Beta-

Feature

Beta-

Feature

This option is deprecated since KOMA-Script 3.20. Now, the amount of the hanging

indent of the entries for that list depend on attributes of the TOC-entry style given by

option tocentrystyle. The styles of KOMA-Script provide an attribute numwidth.

If the used style has such an attribute, \DeclareNewTOC will initialise it with 1.5 em.

You can change the real value using tocentrynumwidth=value . The KOMA-Script

classed for example use tocentrynumwidth=2.3em.

. . .

328

Chapter 15.

Table 15.2.: Options for command \DeclareNewTOC (continuation)

indent=length

Beta-

Feature

Beta-

Feature

This option is deprecated since KOMA-Script 3.20. Now, the amount of indenting

the entries of that list depend on attributes of the TOC-entry style given by option

tocentrystyle

. The styles of KOMA-Script provide an attribute indent. If the

used style has such an attribute, \DeclareNewTOC will initialise it with 1 em. You can

change the real value using tocentryindent=value . The KOMA-Script classed for

example use tocentrynumwidth=1.5em.

level=number

Beta-

Feature

Beta-

Feature

This option is deprecated since KOMA-Script 3.20. Now, the level of the en-

tries of that list depend on attributes of the TOC-entry style given by op-

tion tocentrystyle.

Nevertheless all styles have an attribute level and

\DeclareNewTOC

initialises it with 1. You can change the real value using

tocentrylevel=value

.

listname=string

The name of the TOC. If not given the value of types with upper case first char

using \MakeUppercase prefixed by “List of ” will be used.

name=string

The name of an element. If no name is given, the value of type with upper case first

char will be used.

nonfloat

If set, a non floating environment will be defined. The name of the environment is

the value of type with attached “-”.

owner=string

The owner as described in the sections before. If no owner was given owner float

will be used.

tocentrystyle=TOC-entry style

Beta-

Feature

TOC-entry style

is the style that should be used for all entries into the TOC

corresponding to the extension . The name of the entry level is given by option

type

. Additional to the options of this table all attributes of the TOC-entry style

can be used as options. To do so, you have to prefix the name of such an attribute

by toc. For example, you can change the numerical level of the entries using option

tocentrylevel

. For more information about the styles and their attributes see

section 15.3

from

page 310

.

. . .

329

Chapter 15.

Table 15.2.: Options for command \DeclareNewTOC (continuation)

tocentrystyle-option =value

Beta-

Feature

Additional options depending on the TOC-entry style given by tocentrystyle.

See

section 15.3

,

page 310

for additional information about TOC-entry styles. See

table 15.1

,

page 314

for information about the attributes of the predefined TOC-entry

styles of package tocbasic, that can be used as style-option .

type=string

sets the type of the new declared TOC. The type will be used e. g. to defined a

\listofstring

. If no type is set up the extension from the mandatory argument

will be used.

types=string

the plural of the type. If no plural was given the value of type with attached “s”

will be used.

Example: Using \DeclareNewTOC reduces the example from

section 15.5

to:

\DeclareNewTOC[%

type=remarkbox,%

types=remarkboxes,%

float,% define a floating environment

floattype=4,%

name=Remark,%

listname={List of Remarks}%

]{lor}

\setuptoc{lor}{chapteratlist}

Beside environments remarkbox and remarkbox* the counter remarkbox, the com-

mands \theremarkbox, \remarkboxname, and \remarkboxformat that are used

for captions; the commands \listremarkboxnames and \listofremarkboxes that

are used at the list of remarks; and some internal commands that depends on the

file name extension lor are defined. If the package should use a default for the

floating type, option Optionfloattype may be omitted. If option nonfloat will be

used additionally, then a non-floating environment remarkbox- will be also de-

fined. You may use \caption inside of that non-floating environment as usual for

floating environments.

Figure 15.3

shows a comparison of the commands, counters

and environments of the example environment remarkbox and of the commands,

counters and environments for figures.

And now a possible usage of the example environment:

\begin{remarkbox}

\centering

330

Chapter 15.

Table 15.3.: Comparison of example environment remarkbox and environment figure

remarkbox

figure

options of

\DeclareNewTOC

short description

remarkbox

figure

type

, float

floating environments of the

respective types

remarkbox*

figure*

type

, float

columns spanning floating en-

vironments of the respective

types

remarkbox

figure

type

, float

counter used by \caption

\theremarkbox

\thefigure

type

, float

output command to the re-

spective counters

\remarkboxformat

\figureformat

type

, float

formatting command to the

respective counters used by

\caption

\remarkboxname

\figurename

type

, float,

name

names used in the label of

\caption

\listofremarkboxes

\listoffigures

types

, float command to show the list of

the respective environments

\listremarboxname

\listfigurename

type

, float,

listname

heading text of the respective

list

\fps@remarkbox

\fps@figure

type

, float,

floattype

numeric float type for order

perpetuation

lor

lof

file name extension of the

TOC-file of the respective list

Equal should be typeset equally

and with equal formatting.

\caption{First theorem of typography}

\label{rem:typo1}

\end{remarkbox}

A segment of an example page with this environment could be:

331

Chapter 15.

Equal should be typeset equally and with equal

formatting.

Remark 1: First theorem of typography

Users of hyperref should always use option listname. Otherwise they may get an error

message, because hyperref usually has a problem with the \MakeUppercase command that is

used to change the case of the first letter of types in the name of the list.

332

Chapter 16.