directory 0.98 User’s Guide

Christophe Geuzaine^{(p.6)}

February 2, 1998

Contents

1 Introduction 1

2 General description 2 2.1 Package inclusion and options . . . . . . . . . . . . . . . . . . . . 2 2.2 Making a citation . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2.3 The bst styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2.4 The bib file fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.5 Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3 Using both directory and bibliography  4

4 Example 4 4.1 Source file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4.2 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

5 Versions 7

1 Introduction

directory is a macro package for L^{A}TEX 2ε and BibTEX that facilitates the construction, the maintenance and the exploitation of an address book like database. It consists of five BibTEX style files (address.bst, phone.bst, email.bst, birthday.bst and letter.bst) designed to be used in conjunction with the L^{A}TEX 2ε style file directory.sty. According to the bibliographical style used, the package has two main applications:

1. the construction of a list of informations (address, phone number, etc) about selected persons, companies or places;

2. the inclusion of selected informations concerning a person, a place or a company at a desired location in a document.

In the first case, directory behaves just like standard bibliographical packages do with lists of information concerning books, articles, proceedings, etc. For example, the name in the title of this guide refers to the corresponding entry in the directory listed in section 4.2. The first four BibTEX files permit several handlings of these informations.

In the second case, the package enables the extraction of information of the database to be put in your document. It can for example be used to put the address of your correspondent in the address field of a letter.

2 General description

2.1 Package inclusion and options

The package is included by the usual \usepackage[option]{directory} command at the top of the document, where option stands for one of the following:

symbol: a symbol is produced in the text after a directory cited key. The labels are typeset in the default document font;

underline, bold or emphase: the directory entries are underlined, typeset in bold format or emphasized (both in the main text and in the directory);

bracket: the directory entries are enclosed in brackets, just the way they are in the standard BibTEX formats.

The directory is produced by the \directory[extension]{filename} command, where filename represents the name of the bib file (without the bib extension) and where the optional argument extension represents, if necessary, the extension of the file output by BibTEX (see section 3). As usual, multiple bib files can be included, a comma separating the different filenames.

2.2 Making a citation

An entry is cited in the text by a \dir{key}, \pdir{key}, \rdir{key} or \wdir{key} command, equivalent to the standard \cite{key} command, where key is used in the same way as ever (referring to an entry in a bib file). The differences between the four citation commands will be explained in the next section. A \nodir{key} command exists and acts exactly like \nocite{key} for standard bibliographies.

2.3 The bst styles

The style of the directory is chosen by a \directorystyle{style} command, where style is one of the following:

address: full listing in the directory of all fields corresponding to the key entry in the bib file. The \dir{key} command also prints the name field of the entry in the document; phone: only the phone and fax fields corresponding to the cited entry are dis-

played in the directory. The \dir{key} command acts in the same way as with the address style, except that the names are abbreviated;

email: only e-mail addresses are displayed in the directory. The \dir{key} command acts in the same way as with the address style;

birthday: only the birthdays are displayed, sorting the entries in chronological order. The \dir{key} command acts in the same way as with the address style;

letter: acts in a slightly different way than the four preceding styles. No directory is produced with the \directory command. The \dir{key} command results in the name field of the key entry to be printed in the document. The \pdir{key} (respectively \rdir{key} or \wdir{key}) command prints the name and the private (respectively residence or work) address in the document in a tabular way.

2.4 The bib file fields

In all entry types, name is the only obligatory field, since it serves as a key for sorting the entries.

person: besides the name, nickname, birthday, birthyear and note fields,

the available fields for the person entry in a bib file are divided in three main categories. The first one (its associated keys begin with ‘p.’, which stands for ‘private’) refers to the person’s private information: p.address,

p.phone, p.fax, p.email, p.url and p.account. The second one (for

which all the keys begin with ‘r.’) refers to stuff relative to a person’s residence (i.e. a secondary or temporary address, which is for example

useful for students): r.address, r.phone, r.fax, r.email and r.url.

The last one (associated keys begin with ‘w.’, standing for ‘work’) refers to

professional informations: w.title, w.name, w.address, w.phone, w.fax,
w.email, w.url and w.account.

company: the available fields for the company entry are: name, address, phone,

fax, email, url, account and note.

place: the available fields for the place entry are: name, address, phone, fax

and note.

2.5 Customization

The symbol produced in the text after a directory label when the symbol option is chosen can be easily redefined. The value used in this user’s guide is:

\renewcommand{\dirsymbol}
   {\raisebox{1ex}{\tiny\textit{(p.\pageref{directory})}}}

The flags marking the beginning of the different fields are easily customizable. The values used in this user’s guide are:

     \renewcommand{\birthdayflag}{\footnotesize$\heartsuit$}
     \renewcommand{\privateflag}{\emph{home}}
     \renewcommand{\residenceflag}{\emph{residence}}
     \renewcommand{\workflag}{\emph{work}}
     \renewcommand{\noteflag}{\emph{note}}

Two new dimensions defining the indentation of the fields and the amount of space between two entries have been introduced. The values used in this user’s guide are:

     \setlength{\dirindent}{6em}
     \setlength{\dirsep}{3ex}

3 Using both directory and bibliography

Since BibTEX always produces an output file of the form ‘filename.bbl’, it is necessary—in order to use both directory and bibliography entries—, after generating the bbl file corresponding to the directory, to rename it with a new extension (for example dir), and to give this new extension as an optional argument to the \directory command. The normal procedure can then be followed during the rest of the bibliography processing. Remember that changing the directory (adding an entry or suppressing one) forces you to restart from the beginning.

4 Example

Despite the option described in section 3, one of the most interesting way of using directory is to build a separate address book, including several bib files referring to several categories of people, companies or places, as in the example shown in this document:

     \nodir{*}
     \directory{family,business}

A second interesting way of using directory is to use it in your faxes or letters. Using the standard L^{A}TEX 2ε class letter.cls with the directory style letter, you may for example begin a letter by the following command (\wdir must be protect’ed since the argument of the letter environment is a moving argument):

     \begin{letter}{\protect\wdir{c.geuzaine}}

Take a look at the example tex and bib files—directory.tex, family.bib and business.bib—and try the few options out. The source files are commented and easy to customize. I would be very happy to get your suggestions to improve this helpful little package.

4.1 Source file

Here are four bib entries (taken from family.bib and business.bib):

@Person{c.geuzaine,
name      = "Christophe Geuzaine",
w.title   = "Ir., Research Assistant",
w.name    = "University of Li\`ege \\
             Department of Electrical Engineering",
w.address = "Institut Montefiore (B28, P32, I21) \\
             Sart Tilman, B-4000 Li\`ege, Belgium",
w.phone   = "+32-(0)4-366.37.10",
w.fax     = "/29.10",
w.email   = "Christophe.Geuzaine@ulg.ac.be",
w.url     = "http://www.montefiore.ulg.ac.be/~geuzaine",
birthday  = "06 02",
p.email   = "Christophe.Geuzaine@advalvas.be",
}
@Person{d.d.knu,
name      = "Knudson, Daffy D. and Bugs Bunny",
nickname  = "gnat and gnu",
birthday  = "10 02 and 05 11",
p.address = "Haight Street 512, 80214 Novosibirsk, Gnuland",
p.phone   = "+01-(0)2-765.43.21",
p.account = "010-1234567-05",
r.address = "Manor Lane 2, 80214 Novosibirsk, Gnuland",
r.phone   = "+01-(0)2-876.54.32",
w.name    = "University of Novosibirsk \\
             Department of Octopus Parthenogenesis",
w.address = "Planck Institut (V1-V2, Park. U-67) \\
             Hessenberg Road, 80214 Novosibirsk, Gnuland",
}
@Company{knudsoft,
name      = "The Knudsoft Company",
email     = "knud@knudsoft.com",
url       = "http://knudsoft.com/hole/gates.htm",
}
@Place{knudsoft:rs.2,
name      = "Knudsoft (RS.2 Cmptr Room)",
phone     = "+01-(0)2-434.23.23",
}

4.2 Output

The output resulting from the \directory{family,business} command is shown below (all entries are listed, thanks to the \nodir{*} command):

Christophe Geuzaine

♡ 06.02

home Christophe.Geuzaine@advalvas.be

work Ir., Research Assistant University of Liège Department of Electrical Engineering Institut Montefiore (B28, P32, I21) Sart Tilman, B-4000 Liège, Belgium +32-(0)4-366.37.10 (Fax: /29.10)

Christophe.Geuzaine@ulg.ac.be
http://www.montefiore.ulg.ac.be/~geuzaine

The Knudsoft Company

knud@knudsoft.com
http://knudsoft.com/hole/gates.htm

Knudsoft (RS.2 Cmptr Room)

+01-(0)2-434.23.23

Bip B. Knudson (road runner)

♡ 27.02

home bip_bip@free.prov.gnu
work bip_bip@novosi.uni.gnu

Daffy D. Knudson & Bugs Bunny (gnat & gnu)

♡ 10.02 & 05.11 home Haight Street 512, 80214 Novosibirsk, Gnuland

+01-(0)2-765.43.21

010-1234567-05

residence Manor Lane 2, 80214 Novosibirsk, Gnuland

+01-(0)2-876.54.32 work University of Novosibirsk

Department of Octopus Parthenogenesis Planck Institut (V1-V2, Park. U-67) Hessenberg Road, 80214 Novosibirsk, Gnuland

Donald E. Knudson

♡ 29.01 home +01-(0)2-234.56.78

duck@novosi.uni.gnu

note 1952 Permafrost Press Award winner Microknud Corp.

Haight Street 513, 80214 Novosibirsk, Gnuland +01-(0)2-465.83.99 (Fax: 005.79.00)

           http://microknu.com/ass/bill.html

5 Versions

0.95 First distributed version.

0.96 New documentation. Introduction of customization commands. New alignment mechanism in the addressbook and phonebook environments.

0.97 Entries ccp and p.ccp changed to account and p.account.

0.98 New style letter.bst. New commands \pdir, \rdir and \wdir to produce in-text addresses when used with the letter.bst style. New internal key generation.