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

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:

\newenvironment{remarkbox}{%

\@float{remarkbox}%

}{%

\end@float

}

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

371

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

\RequirePackage{tocbasic}

instead.

Now we register the file name extension for package tocbasic:

\addtotoclist[float]{lor}

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

372

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

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.

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

373

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

v3.20

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

v3.20

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 360

by prefix tocentry. Later changes of the

style of the entries can be made using

\DeclareTOCStyleEntry

. See

section 15.3

,

page 357

for more information about the styles.

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.

. . .

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

374

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

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

v3.20

v3.21

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.

indent=length

v3.20

v3.21

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.

. . .

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

375

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

level=number

v3.20

v3.21

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

v3.20

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 356

.

tocentrystyle-option =value

v3.20

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

See

section 15.3

,

page 356

for additional information about TOC-entry styles. See

table 15.1

,

page 360

for information about the attributes of the predefined TOC-entry

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

. . .

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

376

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

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

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:

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

377

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.

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.

Chapter 16: Hacks for Third-Party Packages by Package scrhack

378

Hacks for Third-Party Packages by Package scrhack

Some packages from other authors could have problems with KOMA-Script. In my opinion

some packages could be improved. With some packages this makes only sense, if KOMA-Script

was used. With some other packages the package author has another opinion. Sometimes

proposals was never answered. Package scrhack contains all those improvement proposals for

other packages. This means, scrhack redefines macros of packages from other authors! The

redefinitions are only activated, if those packages were loaded. Users can prevent scrhack from

redefining macros of individual packages.

16.1. State of Development Note

Though this package is part of KOMA-Script for long time and though it has been used by

lot of users, there’s one problem with it. While redefinition of macros of foreign packages,

it depend on the exact definition an usage of those macros. This means additionally, that it

depends on dedicated releases of those packages. If a unknown release of such a package will

be used, scrhack eventually could not do the needed patch. Contrary, in extreme cases the

patch can cause errors and fault.

So scrhack has to be continuously modified to fit new releases of foreign packages and will

never be finished. Because of this scrhack will stay in beta state forever. Though the usage

will generally be a benefit, the correct function could not be guaranteed forever.

16.2. Early or late Selection of Options

All of what is described in

section 2.4

is generally applicable. So if you have alread read and

understood

section 2.4

you can switch to

section 16.3

,

page 379

.

In this section a peculiarity of KOMA-Script is presented, which, apart from the scrhack

package, is also relevant to other KOMA-Script packages and classes. Such that the user can

find all information corresponding to a single package or a single class in the relevant chapter,

this section is found almost identically in several chapters. Users who are not only interested

in a particular package or class, but wish to gain an overview of KOMA-Script as a whole,

may read the section in one chapter and may thereafter skip it wherever coming across it in

the document.

Chapter 16: Hacks for Third-Party Packages by Package scrhack

379

\documentclass[option list ]{KOMA - Script class }

\usepackage[option list ]{package list }

In L

A

TEX, provision is made for the user to pass class options as a comma-separated list of

keywords as optional arguments to \documentclass. Apart from being passed to the class,

these options are also passed on to all packages which can understand the options. Provision

is also made for the user to pass optional arguments as a comma-separated list of keywords

as optional arguments to \usepackage. KOMA-Script expands

v3.00

the option mechanism for the

KOMA-Script classes and various packages to use further possibilities. Thus, most KOMA-

Script options can also take a value. An option may have not only the form Option , but

may also have the form option =value . Apart from this difference \documentclass and

\usepackage

function the same in KOMA-Script as described in [

Tea05b

] or any introduction

to L

A

TEX, for example [

OPHS11

].

You should note, that in opposite to the interface described below the options interface of

\documentclass

and \usepackage is not robust. So commands, lengths, counters and such

constructs may break inside the optional argument of these commands. Because of this, the

usage of a L

A

TEX length inside the value of an option would cause an error before KOMA-Script

can get the control over the option execution. So, if you want to use a L

A

TEX length, counter

or command a part of the value of an option, you have to use

\KOMAoptions

or

\KOMAoption

.

These commands will be described next.

\KOMAoptions{option list }

\KOMAoption{option }{value list }

KOMA-Script

v3.00

offers most class and package options the opportunity to change the value of

options even after loading of the class or package. One may then change the values of a list of

options at will with the \KOMAoptions command. Each option in the option list has the

form option =value .

Some options also have a default value. If one does not give a value, i. e., gives the option

simply in the form option , then the default value will be used.

Some options can assume several values simultaneously. For such options there exists the

possibility, with the help of \KOMAoption, to pass a single option a list of values. The

individual values are given as a comma-separated value list .

To implement this possibility KOMA-Script uses the commands

\FamilyOptions

and

\FamilyOption

with the family “KOMA”. For more information in these commands see

part II

,

section 12.2

,

page 313

.