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

Chapter 21: Additional Information about the Main Classes and scrextend

446

\DeclareSectionCommand[attributes ]{name }

\DeclareNewSectionCommand[attributes ]{name }

\RedeclareSectionCommand[attributes ]{name }

\ProvideSectionCommand[attributes ]{name }

With

v3.15

these commands you can either define a new section-like command \name or change

an already defined sectioning command \name . To do so you use the optional argument

to setup several attributes . The attributes are a comma-separated list of key =value

assignments. Beside the style-independent attributes shown in

table 21.1

, there are style

dependent attributes, too. Currently the following styles are provided:

chapter

:

v3.18

Style of chapter headings. This style is currently used for

\chapter

and indirectly

for

\addchap

. You can define new section-like commands using this style. To

define new or to reconfigure existing commands you can also use the additional

attributes of

table 21.3

,

page 449

. Note that command

\addchap

and the star

variants are configured automatically together with

\chapter

and should not be

changed independently. Note that scrartcl does not provide this style.

scrbook

,

scrreprt

part

:

v3.18

Style part headings. This style is currently used for

\part

and indirectly for

\addpart

. You can define new section-like commands using this style. To define

new or to reconfigure existing commands you can also use the additional attributes

of

table 21.4

,

page 450

. Note that command

\addpart

and the star variants are

configured automatically together with

\part

and should not be changed indepen-

dently.

section

: Style of section headings. This style is currently used for

\section

,

\subsection

,

\subsubsection

,

\paragraph

, and

\subparagraph

. You can define new section-

like commands using this style. To define new or to reconfigure existing commands

you can also use the additional attributes of

table 21.2

,

page 448

. Definitions of new

commands need at least the key s style, afterskip, beforeskip, font, indent,

level

, tocindent, and tocnumwidth. This is also true if a command that was not

a section-like command before will be redefined as a section-like command using

\RedeclareSectionCommand

. Note that command \addsec and the star variants

are configured automatically together with

\section

and should not be changed

independently. Defining a new section-like command with this style will also de-

fine an element with the same name and the possibility to change its font using

\setkomafont

or

\addtokomafont

(see

section 3.6

,

page 57

), if such an element

does not already exist.

\DeclareNewSectionCommand

defines a new section-like command. If the same name is

already used by TEX for something else, the command will result in an error message and will

not define anything.

\ProvideSectionSommand

is similar but does not show any error message.

Chapter 21: Additional Information about the Main Classes and scrextend

447

Table 21.1.: Available key s and value s for the style-independent attributes declaring a section-like

command

key

value

Description

counterwithin

counter name

The value of the counter of the heading should de-

pend on counter name . Whenever \stepcounter

or \refstepcounter increases the value of counter

name

, the value of the counter of this heading should

be set to 0. Also the output of the value of this head-

ing should be prefixed by \thecounter name followed

by a dot.

v3.19

counterwithout

counter name

Cancels a prior counterwithin setting. Therefore it

makes sense only if you re-define an existing section-

like command.

expandtopt

switch

If the switch is on, all following values for lengths will

be completely expanded, evaluated and stored as pt

values. If the switch is off, all following values for

lengths will be completely expanded, tentatively eval-

uated but only expanded stored. Any values from

ta-

ble 2.5

,

page 39

may be used. Default is false.

level

integer

A number, denoting depth of section (see counter

secnumdepth

,

section 3.16

,

page 106

); the value should

be unique.

style

name

Defines the style of the heading.

Beta-Feature

tocstyle

name

Defines the style of the entries into the table of con-

tents. You can use every already defined toc-entry style

(see

section 15.3

). An empty name prevents a new def-

inition of the toc-entry command.

Beta-Feature

tocoption

value

Additional options depending on the TOC-entry style

given by tocstyle. See

section 15.3

,

page 356

for ad-

ditional information about TOC-entry styles. See

ta-

ble 15.1

,

page 360

for information about the attributes

of the predefined TOC-entry styles of package tocbasic,

that can be used as option .

Chapter 21: Additional Information about the Main Classes and scrextend

448

Table 21.2.: Additional keys and value s of attributes declaring a section-like command with style

section

key

value

Description

afterskip

length

A negative value activates a run-in heading. The absolute

value is the skip to leave to right of the run-in heading. A

positive value is the vertical skip below the heading.

beforeskip

length

The absolute value of the vertical skip before the heading.

If the value is negative, then the paragraph indent of the

text following the heading is suppressed.

font

font commands

The initial font setting that should be used beside

disposition

for the heading. You can use all settings,

that are allowed for

\setkomafont

and

\addtokomafont

for the element of the heading.

indent

length

Indentation of heading from the left margin.

\RedeclareSectionCommand

can only change an existing command to a section-like com-

mand with given attributes . There is no pre-validation to make sure that \name was a

section-like command before. However, it has to be an already used command sequence name .

\DeclareSectionCommand

does not check whether or not name is an already used TEX

command sequence. It just defines a section-like command \name with the given attributes .

Every section-like command has also a corresponding counter with the same name , that

will be allocated using \newcounter if necessary. The same rule applies to the corresponding

output of the counter: \thename , the output format: \name format, the command to generate

a running head: \name mark, the counter format of the running head: \name markformat, the

font element: name , and the section depth number: \name numdepth. The command for the

running head \name mark will be defined to not generate any running head. The output of the

counter, \thename , will show an Arabic number. If the key counterwithin defines a counter

the heading number depends on, the output of the counter will be prefixed by the output of

that counter followed by a dot.

Beside

Beta-Feature

the section-like command, a command for corresponding entries to the table of

contents is defined also. This is done using package tocbasic. Attribute tocstyle defines the

style of those entries. If you set an empty name , e. g., using tocstyle= or tocstyle={}, the

entry command will not be changed. This is important, if you use another package to modify

the table of contents. If you do not set attribute tocstyle the already configured style will

be used again.

The

Beta-Feature

different toc-entry styles also have different, additional attributes. You can set them

here too, if you prefix them with toc. For example, you can setup the level of the toc-

entries, level, using toclevel, the indention, indent, using tocindent, or the number width,

Chapter 21: Additional Information about the Main Classes and scrextend

449

Table 21.3.: Additional keys and value s of attributes declaring a section-like command with style

chapter

key

value

Description

afterskip

length

The absolute value is the vertical skip below the head-

ing.

beforeskip

length

The absolute value of the vertical skip before the head-

ing. If the value is negative, then the paragraph indent

of the text following the heading is suppressed. This will

be done also for positive values if class option

version

is set to a value less than 3.22.

font

font commands

The initial font setting that should be used be-

side

disposition

for the heading.

You can use

all settings, that are allowed for

\setkomafont

and

\addtokomafont

for the element of the heading.

innerskip

length

The vertical skip between the prefix line and the head-

ing’s text, if a prefix line is used.

pagestyle

page style name

The name of the page style that should be used auto-

matically on pages with the heading. There is no val-

idation whether or not page style name is really the

name of a page style. Therefore, wrong names will result

in error messages at usage of the section-like command.

prefixfont

font commands

The initial font setting that should be used beside

disposition

and the element of the heading for the

prefix line of the heading. You can use all settings that

are allowed for

\setkomafont

and

\addtokomafont

for

the element of the prefix line.

numwidth

, using tocnumwidth. For more toc-entry style attributes see

section 15.3

,

page 356

.

Example: Because of incomprehensible reasons, the headings of

\paragraph

shouldn’t be

run-in headings any longer but headings similar to

\subsubsection

. The vertical

skip above the heading should be 10 pt and the following text should be set without

any vertical distance. To do so, you can simply use:

\RedeclareSectionCommand[%

beforeskip=-10pt,%

afterskip=1sp%

]{paragraph}

The negative value of beforeskip does not only result in a positive vertical skip

Chapter 21: Additional Information about the Main Classes and scrextend

450

Table 21.4.: Additional keys and value s of attributes declaring a section-like command with style

part

key

value

Description

afterskip

length

The absolute value is the vertical skip below the head-

ing.

beforeskip

length

The absolute value of the vertical skip before the head-

ing.

font

font commands

The initial font setting that should be used be-

side

disposition

for the heading.

You can use

all settings, that are allowed for

\setkomafont

and

\addtokomafont

for the element of the heading.

innerskip

length

The vertical skip between the prefix line and the head-

ing’s text of scrbook and scrreprt.

pagestyle

page style name

The name of the page style that should be used auto-

matically on pages with the heading. There is no val-

idation whether or not page style name is really the

name of a page style. Therefore, wrong names will result

in error messages at usage of the section-like command.

This feature is only available with scrbook or scrreprt.

prefixfont

font commands

The initial font setting that should be used beside

disposition

and the element of the heading for the

prefix line of the heading. You can use all settings that

are allowed for

\setkomafont

and

\addtokomafont

for

the element of the prefix line.

before the heading, but also deactivates the paragraph indentation of the following

text. Despite the specification of no vertical skip after the heading a value of 1 sp

has been given to afterskip. This is because L

A

TEX here doesn’t accept 0 pt as

positive value. So 1 sp is the lowest possible positive value.

Generally, for the vertical adjustment it is better to have some tolerance in the

declaration of gaps — the so called glue:

\RedeclareSectionCommand[%

beforeskip=-10pt plus -2pt minus -1pt,%

afterskip=1sp plus -1sp minus 1sp%

]{paragraph}

Doing so you have to know, that the glue also switches the algebraic sign before

becoming a skip, if the value is negative. That is the reason for the negative glue

values in the example. Additionally we used the occasion to minimize the vertical

Chapter 21: Additional Information about the Main Classes and scrextend

451

skip after the heading using glue too.

In the example above only beforeskip and afterskip were needed, because since v3.15

KOMA-Script defines

\paragraph

itself using \DeclareSectionCommand. All other values are

just reused with their initial definition. Furthermore, the original definition of

\paragraph

in

scrartcl reads:

\DeclareSectionCommand[%

level=4,

indent=0pt,

beforeskip=3.25ex plus 1ex minus .2ex,

afterskip=-1em,

font={},

tocindent=7em,

tocnumwidth=4.1em,

counterwithin=subsubsection

]{paragraph}

scrreprt and scrbook use slightly different values.

Some settings of

\chapter

depend on option

headings

(see

section 3.16

,

page 91

).

Ta-

ble 21.5

shows the default values of these settings. An overview of all settings is shown in

table 21.6

. For more information

Beta-Feature

about the default of the toc-entry styles see

section 15.3

,

page 356

. Please note, that 1ex and \baselineskip depend on the default font size of the

heading or the table of contents entry.

Table 21.6.: Default of the headings of scrbook and scrreprt

\part

:

Attribute

Default Value

afterskip

0pt plus 1fil

beforeskip

0pt plus 1fil + \baselineskip

font

see element

part

,

table 3.15

,

page 98

innerskip

20pt

level

-1

prefixfont

see element

partnumber

,

table 3.15

,

page 98

tocindent

0pt

toclevel

-1

tocnumwidth

2em

tocstyle

part

. . .

Chapter 21: Additional Information about the Main Classes and scrextend

452

Table 21.6.: Default of the headings of scrbook and scrreprt (Continuation)

\chapter

:

Attribute

Default Value

afterskip

see

table 21.5

beforeskip

see

table 21.5

font

see element

chapter

,

table 3.15

,

page 98

innerskip

0pt

level

0

prefixfont

see element

chapterprefix

,

table 3.15

,

page 98

tocindent

0pt

toclevel

0

tocnumwidth

1.5em

tocstyle

chapter

\section

:

Attribute

Default Value

afterskip

2.3ex plus .2ex

beforeskip

-3.5ex plus -1ex minus -.2ex

font

see element

section

,

table 3.15

,

page 98

indent

0pt

level

1

tocindent

1.5em

toclevel

1

tocnumwidth

2.3em

tocstyle

section

. . .

Chapter 21: Additional Information about the Main Classes and scrextend

453

Table 21.6.: Default of the headings of scrbook and scrreprt (Continuation)

\subsection

:

Attribute

Default Value

afterskip

1.5ex plus .2ex

beforeskip

-3.25ex plus -1ex minus -.2ex

font

see element

subsection

,

table 3.15

,

page 98

indent

0pt

level

2

tocindent

3.8em

toclevel

2

tocnumwidth

3.2em

tocstyle

section

\subsubsection

:

Attribute

Default Value

afterskip

1.5ex plus .2ex

beforeskip

-3.25ex plus -1ex minus -.2ex

font

see element

subsubsection

,

table 3.15

,

page 98

indent

0pt

level

3

tocindent

7.0em

tocnumwidth

4.1em

toclevel

3

tocstyle

section

\paragraph

:

Attribute

Default Value

afterskip

-1em

beforeskip

3.25ex plus 1ex minus .2ex

font

see element

paragraph

,

table 3.15

,

page 98

indent

0pt

level

4

tocindent

10em

toclevel

4

tocnumwidth

5em

tocstyle

section

. . .

Chapter 21: Additional Information about the Main Classes and scrextend

454

Table 21.6.: Default of the headings of scrbook and scrreprt (Continuation)

\subparagraph

:

Attribute

Default Value

afterskip

-1em

beforeskip

3.25ex plus 1ex minus .2ex

font

see element

subparagraph

,

table 3.15

,

page 98

indent

\scr@parindent

level

5

tocindent

12em

toclevel

5

tocnumwidth

6em

tocstyle

section

\DeclareSectionCommands[attributes ]{list of names }

\DeclareNewSectionCommands[attributes ]{list of names }

\RedeclareSectionCommands[attributes ]{list of names }

\ProvideSectionCommands[attributes ]{list of names }

With

v3.15

these commands you can either define or change several section-like commands at once.

The names of the section-like commands are given by the comma-separated list of names .

There are two more differences to the previously described commands that only

define or change a single section-like command.

Firstly, in case of error — if

\DeclareNewSectionCommands

is used for an already defined TEX command sequence or if

\RedeclareSectionCommands

is used for an undefined TEX command sequence — the defini-

tion will be done in spite of raising an error message.

Secondly, there is one more attribute increaselevel with an optional integer argument.

This attribute changes the meaning of the attributes level and toclevel (see

table 21.1

)

so their values become start values for the first section-like command of the list of names .

From section-like command to section-like command of the list of names the value of level

and toclevel will be increased by the value of increaselevel. If attribute increaselevel

is used without an assignment the increase value is 1.

Chapter 21: Additional Information about the Main Classes and scrextend

455

Table 21.5.: Defaults of the chapter headings of scrbook and scrreprt subject to option

headings

With

headings=big

:

Attribute

Default Value

afterskip

1.725\baselineskip plus .115\baselineskip minus .192\baselineskip

beforeskip

-3.3\baselineskip-\parskip

font

\huge

With

headings=normal

:

Attribute

Default Value

afterskip

1.5\baselineskip plus .1\baselineskip minus .167\baselineskip

beforeskip

-3\baselineskip-\parskip

font

\LARGE