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

Chapter 8: Access to Address Files with scraddr

259

Access to Address Files with scraddr

8.1. Overview

The package scraddr is a small extension to the KOMA-Script letter class. Its aim is to make

access to the data of address files more flexible and easier. Basically, the package implements a

new loading mechanism for address files which contain address entries in the form of

\adrentry

and newer

\addrentry

commands, as described in

chapter 4

from

page 220

.

\InputAddressFile{file name }

The command \InputAddressFile is the main command of the scraddr, and reads the content

of the address file given as its parameter. If the file does not exist the command returns an

error message.

For every entry in the address file the command generates a set of macros for accessing the

data. For large address files this will take a lot of TEX memory.

\adrentry{Lastname }{Firstname }{Address }{Phone }{F1 }{F2 }{Comment }{Key }

\addrentry{Lastname }{Firstname }{Address }{Phone }{F1 }{F2 }{F3 }{F4 }{Key }

\adrchar{initial }

\addrchar{initial }

The structure of the address entries in the address file was discussed in detail in

section 4.22

from

page 220

onwards. The division of the address file with the help of \adrchar or

\addrchar

, also discussed therein, has no meaning for scraddr and is simply ignored.

The commands for accessing the data are given by the name of the data field they are

intended for.

Chapter 8: Access to Address Files with scraddr

260

\Name{key }

\FirstName{key }

\LastName{key }

\Address{key }

\Telephone{key }

\FreeI{key }

\FreeII{key }

\Comment{key }

\FreeIII{key }

\FreeIV{key }

These commands give access to data of your address file. The last parameter, i. e., parameter

8 for the

\adrentry

entry and parameter 9 for the

\addrentry

entry, is the identifier of an

entry, thus the key has to be unique and non-blank. The key should only be composed of

multiple uppercase letters out of the namespace of TEX macro names.

If the file contains more than one entry with the same key value, the last occurrence will

be used.

8.2. Usage

First of all, we need an address file with valid address entries. In this example the file has the

name lotr.adr and contains the following entries.

\addrentry{Baggins}{Frodo}%

{The Hill\\ Bag End/Hobbiton in the Shire}{}%

{Bilbo Baggins}{pipe-weed}%

{the Ring-bearer}{Bilbo’s heir}{FRODO}

\adrentry{Gamgee}{Samwise}%

{Bagshot Row 3\\Hobbiton in the Shire}{}%

{Rosie Cotton}{taters}%

{the Ring-bearer’s faithful servant}{SAM}

\adrentry{Bombadil}{Tom}%

{The Old Forest}{}%

{Goldberry}{trill queer songs}%

{The Master of Wood, Water and Hill}{TOM}

The 4th parameter, the telephone number, has been left blank. If you know the story behind

these addresses you will agree that a telephone number makes no sense here, and besides, it

should simply be possible to leave them out.

The command \InputAddressFile is used to load the address file shown above:

\InputAddressFile{lotr}

With the help of the commands introduced in this chapter we can now write a letter to old

Tom Bombadil. In this letter we ask him if he can remember two fellow-travelers from Elder

Chapter 8: Access to Address Files with scraddr

261

Days.

\begin{letter}{\Name{TOM}\\\Address{TOM}}

\opening{Dear \FirstName{TOM} \LastName{TOM},}

or \FreeIII{TOM}, how your delightful \FreeI{TOM} calls you.

Can

you remember Mr.\,\LastName{FRODO}, strictly speaking

\Name{FRODO}, since there was Mr.\,\FreeI{FRODO} too.

He was

\Comment{FRODO} in the Third Age and \FreeIV{FRODO} \Name{SAM},

\Comment{SAM}, has attended him.

Their passions were very worldly.

\FirstName{FRODO} enjoyed

smoking \FreeII{FRODO}, his attendant appreciated a good meal with

\FreeII{SAM}.

Do you remember? Certainly Mithrandir has told you much

about their deeds and adventures .

\closing{‘‘O spring-time and summer-time

and spring again after!\\

O wind on the waterfall,

and the leaves’ laughter!’’}

\end{letter}

In the address of letters often both firstname and lastname are required, als shown above

in

\opening

. Thus, the command \Name{key} is an abridgement for \FirstName{key}

\LastName{key}

.

The 5th and 6th parameters of the

\adrentry

or

\adrentry

commands are for free use.

They are accessible with the commands \FreeI and \FreeII. In this example, the 5th pa-

rameter contains the name of a person who is the most important in the life of the entry’s

person, the 6th contains the person’s passion. The 7th parameter is a comment or in general

also a free parameter. The commands \Comment or \FreeIII give access to this data. Use

of \FreeIV is only valid for

\addrentry

entries; for

\adrentry

entries it results in an error.

More on this is covered in the next section.

8.3. Package Warning Options

As mentioned above, the command \FreeIV leads to an error if it is used for

\adrentry

entries. How scraddr reacts in such a situation is decide by package options.

Chapter 8: Access to Address Files with scraddr

262

adrFreeIVempty

adrFreeIVshow

adrFreeIVwarn

adrFreeIVstop

These four options allow the user to choose between ignore and rupture during the L

A

TEX run

if \FreeIV has been used with an

\adrentry

entry.

adrFreeIVempty

– the command \FreeIV will be ignored

adrFreeIVshow

– “(entry FreeIV undefined at key )” will be written as warning in the text

adrFreeIVwarn

– writes a warning in the logfile

adrFreeIVstop

– the L

A

TEX run will be interrupted with an error message

To choose the desired reaction, one of these options can be given in the optional argument of

the \usepackage command. The default setting is adrFreeIVshow.

Chapter 9: Creating Address Files from an Address Database

263

Creating Address Files from an Address Database

In former versions of KOMA-Script the package addrconv was a permanent part of the KOMA-

Script system. The chief involvement with KOMA-Script was that with the help of addrconv

it was possible from an address database in B

IB

TEX format to create address files compatible

with the KOMA-Script letter class or with the package scraddr.

@address{HMUS,

name =

{Carl McExample},

title =

{Dr.},

city =

{Anywhere},

zip =

01234,

country =

{Great Britain},

street =

{A long Road},

phone =

{01234 / 5 67 89},

note =

{always forget his birthday},

key =

{HMUS},

}

From entries such as that given above, address files can be generated. For this addrconv

employs B

IB

TEX and various B

IB

TEX styles. Additionally, there are some L

A

TEX files which

can help to create various telephone and address lists for printing.

However, the package addrconv was actually an independent package, since besides what

is required for KOMA-Script it includes several more interesting features. Therefore, the

package addrconv has for some time already been removed from the KOMA-Script system.

The package adrconv, with a single d, entirely replaces addrconv. If it is not included in your

TEX distribution then it can be downloaded from [

Kie10

] and you can install it separately.

Chapter 10: KOMA-Script Features for other Classes with Package scrextend

264

Making Basic Feature of the KOMA-Script Classes Available with

Package scrextend while Using Other Classes

There are several features, that are shared by all KOMA-Script classes. This means not only

the classes scrbook, scrreprt, and scrartcl, that has been made as a drop-in replacement for the

standard classes book, report, and article, but also for several features of the KOMA-Script

class scrlttr2, the successor of scrlettr, that may be used for letters. These basic features,

that may be found in the above-named classes, are also provided by package scrextend since

KOMA-Script release 3.00. This package should not be used together with a KOMA-Script

class, but may be used together with many other classes. Package scrextend would recognize,

if it would be used with a KOMA-Script class, and would terminate with a warning message

in that case.

There is no warranty for compatibility of scrextend with every class. The package has been

designed primary to extend the standard classes and derived classed. Anyway, before using

scrextend you should make sure that the used class does not already provide the feature you

need.

Beside the features from this chapter, there are additional common features, that are mainly

provides for authors of classes and packages. These may be found in

chapter 12

from

page 308

.

The package scrbase, that has been described at that chapter, was designed to be used mainly

by authors of classes and packages. Package scrextend and all KOMA-Script classes also use

that package.

KOMA-Script classes and package scrextend also load package scrlfile described in

chapter 13

from

page 331

. Because of this the features of that package are also available when using

scrextend.

In difference to the above, only the KOMA-Script classes scrbook, scrreprt, and scrartcl load

package tocbasic (see

chapter 15

from

page 346

), that has been designed to be used by authors

of classes and packages too. Because of this scrextend does not provide the features of this

package. Nevertheless you may use tocbasic together with scrextend.

10.1. 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 10.2

,

page 266

.

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

the scrextend package is also relevant to several other KOMA-Script packages. 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

Chapter 10: KOMA-Script Features for other Classes with Package scrextend

265

it in the document.

\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

.

Chapter 10: KOMA-Script Features for other Classes with Package scrextend

266

10.2. Compatibility with Earlier Versions of KOMA-Script

It applies, mutatis mutandis, what is written in

section 2.5

. So if you have alread read and

understood

section 2.5

you can switch to

page 266

,

page 266

.

Those who achieve their documents in source code set utmost value to the fact that future

L

A

TEX runs will yield exactly the same result. In some cases improvement and bug corrections

of packages will result in changes of the behaviour and make-up. But sometimes this is not

wanted.

version=value

version=first

version=last

At

v2.96a

v2.9t

v3.01b

scrextend it’s your choice if your source code should result in the same make-up at fu-

ture L

A

TEX runs or if you like to participate in all improvements of new releases. You may

select the compatible version of KOMA-Script with option version. Compatibility to the

lowest supported KOMA-Script release may be achieved by version=first or version=2.9

or version=2.9t. Setting value to an unknown release number will result in a warning

message and selects version=first for safety.

With version=last the most recent version will be selected at every L

A

TEX run. Be warned,

though, that using version=last poses possibilities of compatibility issues for future L

A

TEX

runs. Option version without any value means the same.

v3.01a

This is the default behaviour as

long as you do not use any deprecated options.

If you use a deprecated option of KOMA-Script 2, KOMA-Script 3 will switch to version=

first

automatically. This will also result in a warning message that explains how to prevent

this switching. Alternatively you may select another adjustment using option version with

the wanted compatibility after the deprecated option.

Compatibility is primarily make-up compatibility. New features not related to the mark-up

will be available even if you switch compatibility to a version before first implementation of

the feature. Option version does not influence make-up changes that are motivated by bug

fixes. If you need bug compatibility you should physically save the used KOMA-Script version

together with your document.

Please note that you cannot change option version anymore after loading the package

scrextend. Therefore, the usage of option version within the argument of

\KOMAoptions

or

\KOMAoption

is not recommended and will cause an error.

10.3. Optional, Extended Features

Package scrextend provides some optional, extended features. Such features are not available

by default, but may be activated additionally. These features are optional, i. e., because the

conflict with features of the standard classes of often used packages.

Chapter 10: KOMA-Script Features for other Classes with Package scrextend

267

Table 10.1.: overview of the optional available extended features of scrextend

title

extends the title pages to the features of the KOMA-Script classes; this means not

only the commands for the title page but also option

titlepage

(see

section 10.7

,

from

page 270

)

extendedfeature=feature

With this option an extended feature of scrextend may be activated.

Option

extendedfeature

is available only while loading the package scrextend. User have to set

the option in the optional argument of

\usepackage

[optional argument ]{scrextend}

. An

overview of all available optional features is shown in

table 10.1

.

10.4. Draft Mode

What is written in

section 3.3

applies, mutatis mutandis. So if you have alread read and

understood

section 3.3

you can jump to

section 10.5

on

page 267

.

Many classes and packages provide a draft mode aside from the final typesetting mode. The

difference of draft and final mode may be as manifold as the classes and package that support

these modes. For instance, the graphics and the graphicx packages do not actually output the

graphics in their own draft mode. Instead they output a framed box of the appropriate size

containing only the graphic’s file name (see [

Car05

]).

draft=simple switch

This option

v3.00

is normally used to distinguish between the draft and final versions of a document.

simple switch

value may be any standard value from

table 2.5

,

page 39

. In particular,

switching on the option activates small black boxes that are set at the end of overly long

lines. The boxes help the untrained eye to find paragraphs that have to be treated manually.

With the default draft=false option no such boxes are shown. Such overly long lines often

vanish using package microtype [

Sch13

].

10.5. Selection of the Document Font Size

What is described in

section 3.5

applies, mutatis mutandis. So if you have alread read and

understood

section 3.5

you can jump to the end of this section on

page 268

.

The main document font size is one of the basic decisions for the document layout. The

maximum width of the text area, and therefore splitting the page into text area and margins,

depends on the font size as stated in

chapter 2

. The main document font will be used for most

Chapter 10: KOMA-Script Features for other Classes with Package scrextend

268

of the text. All font variations either in mode, weight, declination, or size should relate to the

main document font.

fontsize=size

In contrast to the standard classes and most other classes that provide only a very limited

number of font sizes, the KOMA-Script classes offer the feature of selection of any desired

size

for the main document font. In this context, any well known TEX unit of measure may

be used and using a number without unit of measure means pt.

If you use this option inside the document, the main document font size and all dependent

sizes will change from this point. This may be useful, e. g., if the appendix should be set using

smaller fonts on the whole. It should be noted that changing the main font size does not result

in an automatic recalculation of type area and margins (see

\recalctypearea

,

section 2.4

,

page 37

). On the other hand, each recalculation of type area and margins will be done on

the basis of the current main font size. The effects of changing the main font size to other

additionally loaded packages or the used document class depend on those packages and the

class. This may even result in error messages or typesetting errors, which cannot be considered

a fault of KOMA-Script, and even the KOMA-Script classes do not change all lengths if the

main font size changes after loading the class.

This option is not intended to be a substitution for \fontsize (see [

Tea05a

]). Also, you

should not use it instead of one of the main font depending font size commands \tiny up to

\Huge

!