directory 1.15 User’s Guide

Christophe Geuzaine^{(cf. section 6.2)}

August 27, 2000

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.4 The bib file fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3 Customization 4 3.1 Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.2 Flags and formats . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.3 More customization . . . . . . . . . . . . . . . . . . . . . . . . . 4

4 Using both directory and bibliography  5

5 Generating directories with hypertext links 5 5.1 Direct HTML output . . . . . . . . . . . . . . . . . . . . . . . . . 5 5.2 Using the hyperref package . . . . . . . . . . . . . . . . . . . . . 6

6 Example 6 6.1 Source file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 6.2 Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

7 Contributors 9

8 Versions 9

1 Introduction

directory^{1} is a macro package for L^{A}TEX 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,

1directory is available at http://www.geuz.org/directory/ or through the CTAN in the biblio/bibtex/contrib/directory/ subdirectory. directory is distributed under the L^{A}TEX Project Public License (LPPL) since version 1.11.

email.bst, birthday.bst and letter.bst) designed to be used in conjunc-

tion with the L^{A}TEX 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 styles: while standard bibliographical styles handle lists of information concerning books, articles, proceedings, etc., directory handles lists of informations relative to people, companies or places. For example, the name in the title of this guide refers to the corresponding entry in the directory listed in section 6.2. The first four BibTEX files permit several handlings of these informations.

In the second case, the package enables bits 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.

   Two special BibTEX style files (address-html.bst and email-html.bst)

are also provided for an easy generation of HTML versions of your directories.

2 General description

2.1 Package inclusion and options

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

split: the directory entries are split on separate pages according to the first letter used in the sorting algorithm;

break: the directory fields can be broken across pages.

The old (before version 1.10) formatting options are now handled by the same command mechanism as all other customization options (see section 3).

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

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. The \dir{key} command also prints the name field of the entry in the document;

phone: only the phone, cellular and fax fields corresponding to the cited entry are displayed 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 tabulated way.

2.4 The bib file fields

In all entry types, name is the only mandatory 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.cellular, p.fax, p.email, p.url and p.account. The sec-

ond 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.cellular, r.fax,

r.email, r.url and r.account. The last one (associated keys begin with ‘w.’, standing for ‘work’) refers to professional informations: w.title,

w.name, w.address, w.phone, w.cellular, w.fax, w.email, w.url and
w.account.

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

     cellular, fax, email, url, account and note.

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

     cellular, fax and note.

3 Customization

3.1 Dimensions

Three new dimensions defining the indentation of the fields (\dirindent and \dirparindent) and the amount of space between two entries (\dirsep) have been introduced. The default values are:

     \setlength{\dirindent}{3em}
     \setlength{\dirparindent}{0em}
     \setlength{\dirsep}{3ex}

If you want to explicitly introduce a new paragraph in a field, you should use the \dirbreak command.

3.2 Flags and formats

Each field of a directory is easily customizable by redefining one of the commands summarized in the table at the end of this user’s guide (page 11). For example, here is how the symbol produced in the text after a directory label and the formatting of the label itself are redefined in this document:

     \renewcommand{\dirsymbol}
       {\raisebox{1ex}{\tiny\textit{(cf.\ section~\ref{dir})}}}
     \renewcommand{\Dirlabel}[1]{{#1}}

A somewhat more complex example is the redefinition of the birthday format used in this document to produce a nice literal expression for dates:

     \renewcommand{\Dirbirthday}[2]
       {{\ifcase #2\or January\or February\or March\or April%
                  \or May\or June\or July\or August\or September%
                  \or October\or November\or December\fi}%
        {\space\ifnum #1=1 1st\else\number#1\fi}}
     \renewcommand{\Dirbirthyear}[1]{, {#1}}

3.3 More customization

When a field type multiply appears in an entry, the default settings assume the same formatting for each one. For example, there are three instances of a phone type field in a full person entry, i.e. p.phone, r.phone and w.phone, and the \dirphone and \Dirphone customization commands apply to these three instances in the same way.

4 USING BOTH DIRECTORY AND BIBLIOGRAPHY  5

To particularize the formatting of one of these instances, you can use special versions of the customization commands, constructed by inserting p, r or w after the \dir or \Dir prefix of the original commands. For example, to customize only the phone field in the work part, you should use \dirwphone and

\Dirwphone.

To change the formatting of names, you have to edit the BibTEX style files. For example, the default name format “Christophe von Geuzaine, Jr.” can be changed into “von Geuzaine C., Jr.” in your address books by replacing the line

     s nameptr "{ff }{vv }{ll}{, jj}" format.name$ 't :=

in the file address.bst by the line

     s nameptr "{vv }{ll}{ f.}{, jj}" format.name$ 't :=

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

5 Generating directories with hypertext links

5.1 Direct HTML output

Two special BibTEX style files (address-html and email-html) allow the easy generation of HTML versions of your directories:

address-html: full listing in the HTML directory of all fields corresponding to the key entry. The output formatting is similar to that produced by L^{A}TEX with the address style;

email-html: only e-mail addresses are displayed in the HTML directory.

Since BibTEX directly outputs a bbl file in HTML format, no additional program is needed to make the HTML conversion. The bbl file directly contains the HTML code, ready to be included in any HTML document.

This method presents nevertheless a little drawback: after BibTEX’ing your L^{A}TEX file, running L^{A}TEX on the same file (even with another non-HTML \directorystyle) would produce errors, since the bbl file is not understandable by L^{A}TEX. You have either to delete the bbl file or to override the error messages (and to change the \directorystyle) before any subsequent successful L^{A}TEX run.

The handling of special characters in the HTML directories is also quite imperfect: any special L^{A}TEX character sequence is output the way it is in the bib file. This implies for example that {\'e} is printed in the HTML document

as {\'e}, and not as &eacute;.

5.2 Using the hyperref package

You can use the hyperref package along with directory. For example, adding the following lines in the preamble of your document and using pdflatex will produce a PDF version of your directory, with working links for the email and url fields.

     \ifx\pdfoutput\undefined\else
       \usepackage{hyperref}
       \newcommand\MyURL{\begingroup\Url}
       \renewcommand{\Diremail}[1]{\href{mailto:#1}{\MyURL{#1}}}
       \renewcommand{\Dirurl}[1]{\href{#1}{\MyURL{#1}}}
     \fi

6 Example

Despite the option described in section 4, 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}

The use of the split option, along with the redefinition of the \Dirheader command allows you to produce nicely formatted address booklets.

A second interesting way of using directory is to use it in your faxes or letters. Using the standard L^{A}TEX 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 options out. The source files are commented and easy to customize. I would be very happy to get your suggestions to improve this package.

6.1 Source file

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

@Person{c.geuzaine,
name       = "Christophe Geuzaine",
birthday   = "06 02",
birthyear  = "1973",
p.email    = "Christophe.Geuzaine@advalvas.be",
w.title    = "Ir., Research Assistant",
w.name     = "University of Li{\`e}ge,
              Dept. of Electrical Engineering",
w.address  = "Institut Montefiore (B28, P32, I21),\\
              Sart Tilman Campus, B-4000 Li{\`e}ge, Belgium",
w.phone    = "+32-(0)4-366.37.10",
w.fax      = "+32-(0)4-366.29.10",
w.email    = "Christophe.Geuzaine@ulg.ac.be",
w.url      = "http://www.geuz.org/",
}
@Person{d.d.knu,
name       = "Knudson, Daffy Duck and Bunny, Bugs and Pluto",
nickname   = "gnat and gnu and pluto",
birthday   = "10 02 and 05 11 and 01 01",
p.address  = "Haight Street 512, 80214 Novosibirsk, Gnuland",
p.phone    = "+01-(0)2-765.43.21",
p.cellular = "+01-(0)5-555.55.55",
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 Computer Room)",
phone  = "+01-(0)2-434.23.23",
}

6.2 Output

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

G

Christophe Geuzaine ⋆ February 6, 1973

p Christophe.Geuzaine@advalvas.be

w Ir., Research Assistant University of Liège, Dept. of Electrical Engineering Institut Montefiore (B28, P32, I21), Sart Tilman Campus, B-4000 Liège, Belgium phn: +32-(0)4-366.37.10 fax: +32-(0)4-366.29.10

Christophe.Geuzaine@ulg.ac.be
http://www.geuz.org/

K

The Knudsoft Company

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

Knudsoft (RS.2 Computer Room)

phn: +01-(0)2-434.23.23

Bip B. Knudson (aka road runner)

⋆ February 27

p bip_bip@free.prov.gnu

Daffy Duck Knudson, Bugs Bunny and Pluto (aka gnat, gnu and pluto) ⋆ February 10, November 5 and January 1st p Haight Street 512, 80214 Novosibirsk, Gnuland

phn: +01-(0)2-765.43.21 gsm: +01-(0)5-555.55.55

acc: 010-1234567-05

r Manor Lane 2, 80214 Novosibirsk, Gnuland

phn: +01-(0)2-876.54.32 w University of Novosibirsk, Department of Octopus Parthenogenesis

Planck Institut (V1-V2, Park. U-67), Hessenberg Road, 80214 Novosibirsk, Gnuland Donald Ernest Knudson

⋆ January 29

p phn: +01-(0)2-234.56.78

      duck@novosi.uni.gnu

▷ 1952 Permafrost Press Award winner

M

Microknud Corp.

Haight Street 513

80214 Novosibirsk, Gnuland phn: +01-(0)2-465.83.99 fax: 005.79.00

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

7 Contributors

Many thanks to Bernd Schandl, Robert Walker Sumner and Thomas Ruedas for their suggestions and corrections.

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

0.99 Name change of old customization flags (\nameflag becomes \dirname).

     New flags introduced: \dirnickname, \dirphone, \dirfax, \diremail,
     \dirurl, \diraccount and \dirand.
1.00 New HTML styles (address-html.bst and email-html.bst).

1.01 Minor corrections.

1.10 Major rewriting of bst files (suppression of direct L^{A}TEX formatting). Definition of new customization commands. New package global options to split directories across pages and allow page breaks inside directory fields. The url.sty package is now required.

1.11 Introduction of \dirparindent.

1.12 Formatting commands can be particularized to each subfield by adding p, r or w after the \dir or \Dir prefix of the original customization command. Many simplifications and small corrections in the page breaking mechanism and in the list environments.

1.13 Fixed bug for long entries without blank spaces (e.g. in url fields).

1.14 More flexible definition of \Dirheader.

1.15 Added fields for cellular phones (suggested by Stefano Ferrari). Added section explaining how to use hyperref to generate PDF documents with hyperlinks. Updated web site address.

8 VERSIONS 11

Table 1: Summary of customization commands

Command  Arg. Explanation  Default

\dirsymbol 0 In-text symbol produced

after a directory citation

\dirand  0 “anding” string  and

\dirbirthday  0 Birthday field flag  $\star$~
\dirprivate  0 Private field flag  \emph{p}~
\dirresidence  0 Residence field flag  \emph{r}~
\dirwork  0 Work field flag  \emph{w}~
\dirnote  0 Note field flag  $\triangleright$~

\dirnickname  0 Nickname field flag
\diraddress  0 Address fields flag
\dirphone^{∗}  0 Phone fields flag  phn:␣
\dircellular^{∗}  0 Cellular phone fields flag  gsm:␣
\dirfax^{∗}  0 Fax fields flag  fax:␣
\diremail^{∗}  0 E-mail fields flag
\dirurl^{∗}  0 Url fields flag
\diraccount^{∗} 0 Account fields flag acc:␣
\dirtitle  0 Title field flag
\dirname  0 Name field flag

\Dirlabel  1 Label format  {\textbf{#1}}
\Dirheader  1 Header format when  \newpage\markboth
                        the split option is  {\MakeUppercase{#1}}

used^{†} (the arg. is the first letter used in the sorting algorithm)

                                                   {\MakeUppercase{#1}}

\Dirbirthday 2 Birthday format (the first arg. is the day, the second is the month)

                                                 {\number#1}/{\number#2}

\Dirbirthyear 1 Birth year format when a birthday field exists

                                                 /{#1}

\DirbirthyearAlone 1 Birth year format when no birthday field exists

                                                 {#1}

\Dirnickname  1 Nickname format  (aka␣{#1})
\Diraddress^{∗}  1 Address format  {#1}
\Dirphone^{∗}  1 Phone format  {#1}

\Dircellular^{∗}  1 Cellular phone format  {#1}

\Dirfax^{∗}  1 Fax format  {#1}
\Diremail^{∗}  1 E-mail format  \url{#1}
\Dirurl^{∗}  1 Url format  \url{#1}
\Diraccount^{∗}  1 Account format  \url{#1}
\Dirtitle  1 Title format  {#1}
\Dirname  1 Name format  {#1}
\Dirnote  1 Note format  {#1}

∗ The commands marked with an asterisk also exist in three other versions, controlling independently the private, residence and work parts (e.g. \dirphone can be particu-

larized to \dirpphone, \dirrphone and \dirwphone).

† and a coherent page style selected (e.g. \pagestyle{headings}).