%% directory.tex
%% Copyright 1999 Christophe Geuzaine
%
% This program can be redistributed and/or modified under the terms
% of the LaTeX Project Public License distributed from CTAN
% archives in directory macros/latex/base/lppl.txt; either
% version 1 of the License, or (at your option) any later version.
%
% 'directory' user's guide and example file
% 
% Christophe.Geuzaine@advalvas.be
%
% Last modified 26/08/1999
% 
% The parts you may want to customize are labeled with "CUSTOM"
%
% The lines beginning with %%tth: are used by TTH (TeX->HTML translator)
%

\documentclass[10pt]{article}

% CUSTOM  try e.g. \usepackage[split]{directory} 
\usepackage{directory} 

% CUSTOM  uncomment only one of these
% \directorystyle{email-html}
% \directorystyle{email}
% \directorystyle{phone}
% \directorystyle{birthday}
% \directorystyle{letter}
% \directorystyle{address-html}
\directorystyle{address}

% CUSTOM  here is how I customized the directory for this document
\renewcommand{\dirsymbol}{\raisebox{1ex}{\tiny\textit{(cf.\ section~\ref{dir})}}}
\renewcommand{\Dirlabel}[1]{{#1}}
\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}}
\renewcommand{\Dirheader}[1]{\item\hspace{-\dirindent}\textbf{\MakeUppercase{#1}}}

% Some other definitions
\newcommand{\BibTeX}{\textsc{Bib}\TeX}
\newcommand{\TitleTT}[1]{\texttt{#1}}
\newcommand{\Quote}[1]{`{#1}'}
\newcommand{\DbleQuote}[1]{``{#1}''}
\newcommand{\Download}{\footnote{\texttt{directory} is available at
\url{http://www.geuz.org/directory/}
or through the CTAN in the 
\url{biblio/bibtex/contrib/directory/}
subdirectory. \texttt{directory} is distributed under the \LaTeX\ Project
Public License (LPPL) since version 1.11.}} 

%%tth:\def\TitleTT#1{#1}
%%tth:\def\Quote#1{'{#1}'}
%%tth:\def\DbleQuote#1{''{#1}''}
%%tth:\def\Download{\footnote{\texttt{directory} is distributed under the
%%tth:\LaTeX\ Project Public License (LPPL) since version 1.11.}}

\pagestyle{headings}

\begin{document}

\title{\TitleTT{directory} 1.14 User's Guide}

% CUSTOM  try \author{\wdir{c.geuzaine}} with \directorystyle{letter}
\author{\dir{c.geuzaine}}

%%tth:\special{html:<H3 align=center>Christophe Geuzaine</H3>}

\date{August 26, 1999}

\maketitle

%%tth:\section*{Download}
%%tth:The current archive of the package is available
%%tth:\href{http://www.geuz.org/directory/directory-1.14.tar.gz}{here}.
%%tth:The separate files are also available through the
%%tth:\href{http://www.ctan.org/}{CTAN} 
%%tth:sites in the 
%%tth:\href{http://www.ctan.org/tex-archive/biblio/bibtex/contrib/directory/}
%%tth:{biblio/bibtex/contrib/directory/} 
%%tth:subdirectory. Any questions, comments or suggestions? Send me an 
%%tth:\href{mailto:Christophe.Geuzaine@AdValvas.be}{e-mail}. 

\tableofcontents

\section{Introduction}

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

\begin{enumerate}
\item
the construction of a list of informations (address, phone number, etc)
about selected persons, companies or places;
\item
the inclusion of selected informations concerning a person, a place
or a company at a desired location in a document.
\end{enumerate}

In the first case, \texttt{directory} behaves just like standard
bibliographical styles: while standard bibliographical styles handle lists of
information concerning books, articles, proceedings, etc, \texttt{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~\ref{dir}. 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 (\texttt{address-html.bst} and
\texttt{email-html.bst}) are also provided for an easy generation of
HTML versions of your directories. 

\section{General description}

\subsection{Package inclusion and options}

The package is included by the usual \verb'\usepackage['\emph{options}\verb']{directory}'
command at the top of the document, where \emph{options} stands for a
combination of the following options: 
\begin{description}
\item[\textmd{\texttt{split}:}] 
the directory entries are split on separate pages according to the first
letter used in the sorting algorithm;
\item[\textmd{\texttt{break}:}] 
the directory fields can be broken across pages.
\end{description}
The old (before version 1.10) formatting options are now handled by the same
command mechanism as all other customization options (see
section~\ref{sec:custom}).

The directory is produced by the
\verb'\directory['\emph{extension}\verb']{'\emph{filename}\verb'}' command, 
where \emph{filename} stands for the name of the \texttt{bib} file (without the
\texttt{bib} extension) and where the optional argument \emph{extension}
gives, if necessary, the extension of the file output by \BibTeX\ (see
section~\ref{sec:usingboth}). As usual, multiple \texttt{bib} files can be
included, a comma separating the different file names. 

\subsection{Making a citation}

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

\subsection{The \texttt{bst} styles}

The style of the directory is chosen by a \verb'\directorystyle{'\emph{style}\verb'}'  
command, where \emph{style} is one of the following:
\begin{description}
\item[\textmd{\texttt{address}:}] 
full listing in the directory of all fields corresponding to the
\emph{key} entry. The \verb'\dir{'\emph{key}\verb'}' command also prints the
\texttt{name} field of the entry in the document;  
\item[\textmd{\texttt{phone}:}] 
only the phone and fax fields corresponding to the cited entry are
displayed in the directory. The \verb'\dir{'\emph{key}\verb'}' command acts in
the same way as with the \texttt{address} style, except that the names are
abbreviated; 
\item[\textmd{\texttt{email}:}] 
only e-mail addresses are displayed in the directory. The
\verb'\dir{'\emph{key}\verb'}' command acts in the same way as with the
\texttt{address} style;
\item[\textmd{\texttt{birthday}:}] 
only the birthdays are displayed, sorting the entries in chronological
order. The \verb'\dir{'\emph{key}\verb'}' command acts in the same way as with
the \texttt{address} style;
\item[\textmd{\texttt{letter}:}] 
acts in a slightly different way than the four preceding styles. No directory
is produced with the \verb|\directory| command. The
\verb'\dir{'\emph{key}\verb'}' command results in the \texttt{name} field of
the \emph{key} entry to be printed in the document. The
\verb'\pdir{'\emph{key}\verb'}' (respectively \verb'\rdir{'\emph{key}\verb'}'
or \verb'\wdir{'\emph{key}\verb'}') command prints the name and the private
(respectively residence or work) address in the document in a tabulated way.
\end{description}


\subsection{The \texttt{bib} file fields}

In all entry types, \texttt{name} is the only mandatory field, since it
serves as a key for sorting the entries. 

\begin{description}
\item[\textmd{\texttt{person}:}]
besides the \texttt{name}, \texttt{nickname}, \texttt{birthday},
\texttt{birthyear} and \texttt{note} fields, the available fields for the
\texttt{person} entry in a \texttt{bib} file are divided in three main
categories. The first one (its associated keys begin with \Quote{\texttt{p.}},
which stands for \Quote{private}) refers to the person's private information:
\texttt{p.address}, \texttt{p.phone}, \texttt{p.fax}, \texttt{p.email},
\texttt{p.url} and \texttt{p.account}. The second one (for which all the keys
begin with \Quote{\texttt{r.}}) refers to stuff relative to a person's residence
(i.e.\ a secondary or temporary address, which is for example useful for
students): \texttt{r.address}, \texttt{r.phone}, \texttt{r.fax},
\texttt{r.email}, \texttt{r.url} and \texttt{r.account}. The last one
(associated keys begin with \Quote{\texttt{w.}}, standing for \Quote{work}) refers to
professional informations: \texttt{w.title}, \texttt{w.name},
\texttt{w.address}, \texttt{w.phone}, \texttt{w.fax}, \texttt{w.email},
\texttt{w.url} and \texttt{w.account}.
\item[\textmd{\texttt{company}:}]
the available fields for the \texttt{company} entry are: \texttt{name},
\texttt{address}, \texttt{phone}, \texttt{fax}, \texttt{email}, \texttt{url},
\texttt{account} and \texttt{note}.  
\item[\textmd{\texttt{place}:}]
the available fields for the \texttt{place} entry are: \texttt{name},
\texttt{address}, \texttt{phone}, \texttt{fax} and \texttt{note}. 
\end{description}


\section{Customization}
\label{sec:custom}

\subsection{Dimensions}

Three new dimensions defining the indentation of the fields (\verb'\dirindent'
and \verb'\dirparindent') and the amount of space between two entries
(\verb'\dirsep') have been introduced. The default values are:
\begin{quote}
\begin{verbatim}
\setlength{\dirindent}{3em}
\setlength{\dirparindent}{0em}
\setlength{\dirsep}{3ex}
\end{verbatim}
\end{quote}

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

\subsection{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~\pageref{tab:commands}). 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: 
\begin{quote}
\begin{verbatim}
\renewcommand{\dirsymbol}
  {\raisebox{1ex}{\tiny\textit{(cf.\ section~\ref{dir})}}}
\renewcommand{\Dirlabel}[1]{{#1}}
\end{verbatim}
\end{quote}

A somewhat more complex example is the redefinition of the birthday format used
in this document to produce a nice literal expression for dates:
\begin{quote}
\begin{verbatim}
\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}}
\end{verbatim}
\end{quote}

\subsection{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
\texttt{phone} type field in a full \texttt{person} entry, i.e.\
\texttt{p.phone}, \texttt{r.phone} and \texttt{w.phone}, and the
\verb'\dirphone' and \verb'\Dirphone' customization commands apply to these
three instances in the same way.

To particularize the formatting of one of these instances, you can use
special versions of the customization commands, constructed by inserting
\texttt{p}, \texttt{r} or \texttt{w} after the \verb'\dir' or \verb'\Dir'
prefix of the original commands. For example, to customize only the
\texttt{phone} field in the work part, you should use \verb'\dirwphone' and
\verb'\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
\begin{quote}
\begin{verbatim}
s nameptr "{ff }{vv }{ll}{, jj}" format.name$ 't :=
\end{verbatim}
\end{quote}
in the file \texttt{address.bst} by the line
\begin{quote}
\begin{verbatim}
s nameptr "{vv }{ll}{ f.}{, jj}" format.name$ 't :=
\end{verbatim}
\end{quote}


\section{Using both \texttt{directory} and \texttt{bibliography}}
\label{sec:usingboth}

Since \BibTeX\ always produces an output file of the form
\Quote{\emph{filename}\texttt{.bbl}}, it is necessary---in order to use \emph{both} 
directory and bibliography entries---, after generating the \texttt{bbl} file
corresponding to the directory, to rename it with a new extension (for example
\texttt{dir}), and to give this new extension as an optional argument to the
\verb'\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. 

\section{Generating HTML directories}

Two special \BibTeX\ style files (\texttt{address-html} and
\texttt{email-html}) allow the easy generation of HTML versions of 
your directories:

\begin{description}
\item[\textmd{\texttt{address-html}:}] 
full listing in the HTML directory of all fields corresponding to the
\emph{key} entry. The output formatting is similar to that produced by \LaTeX\
with the \texttt{address} style;
\item[\textmd{\texttt{email-html}:}] 
only e-mail addresses are displayed in the HTML directory. 
\end{description}

Since \BibTeX\ directly outputs a \texttt{bbl} file in HTML format, no
additional program is needed to make the HTML conversion. The \texttt{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
\LaTeX\ file, running \LaTeX\ on the same file (even with another non-HTML
\verb|\directorystyle|) would produce errors, since the \texttt{bbl} file 
is not understandable by \LaTeX. You have either to delete the \texttt{bbl}
file or to override the error messages (and to change the
\verb|\directorystyle|) before any subsequent successful \LaTeX\ run. 

The handling of special characters in the HTML directories is also quite
imperfect: any special \LaTeX\ character sequence is output the way it is in
the \texttt{bib} file. This implies for example that \verb|{\'e}| is printed in
the HTML document as \verb|{\'e}|, and not as \verb|&eacute;|.


\section{Example}

Despite the option described in section~\ref{sec:usingboth}, one of the most
interesting way of using \texttt{directory} is to build a separate address
book, including several \texttt{bib} files referring to several categories of
people, companies or places, as in the example shown in this document:  
\begin{quote}  
\verb|\nodir{*}| \\
\verb|\directory{family,business}|
\end{quote}
The use of the \texttt{split} option, along with the redefinition of the
\verb'\Dirheader' command allows you to produce nicely formatted
address booklets.

A second interesting way of using \texttt{directory} is to use it in your faxes
or letters. Using the standard \LaTeXe\ class \texttt{letter.cls} with the
directory style \texttt{letter}, you may for example begin a letter by the
following command (\verb'\wdir' must be \texttt{protect}'ed since the argument
of the \texttt{letter} environment is a moving argument):
\begin{quote}  
\verb'\begin{letter}{\protect\wdir{c.geuzaine}}'
\end{quote}

Take a look at the example \texttt{tex} and \texttt{bib}
files (\texttt{directory.tex}, \texttt{family.bib} and
\texttt{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. 

\subsection{Source file}

Here are four \texttt{bib} entries (taken from \texttt{family.bib} and 
\texttt{business.bib}):

\begin{verbatim}
@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.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",
}
\end{verbatim}

\subsection{Output}
\label{dir}

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

% CUSTOM  try e.g. citing just some of the entries
\nodir{*}

% CUSTOM  this has the same effect: \directory[bbl]{family,business}
\newpage
\directory{family,business} 

%%tth:directory generated with 
%%tth:\href{http://www.geuz.org/directory/directory.html.address}
%%tth:{address-html.bst} and with
%%tth:\href{http://www.geuz.org/directory/directory.html.email}
%%tth:{email-html.bst}.


\section{Contributors}

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

\section{Versions}

\begin{description}
\item[0.95] 
First distributed version. 
\item[0.96] 
New documentation. Introduction of customization commands. New alignment
mechanism in the \texttt{addressbook} and \texttt{phonebook} environments.  
\item[0.97] 
Entries \texttt{ccp} and \texttt{p.ccp} changed to \texttt{account} and
\texttt{p.account}.
\item[0.98] 
New style \texttt{letter.bst}. New commands \verb|\pdir|, \verb|\rdir| and
\verb|\wdir| to produce in-text addresses when used with the
\texttt{letter.bst} style. New internal key generation. 
\item[0.99]
Name change of old customization flags (\verb'\'\emph{name}\verb'flag' becomes
\verb'\dir'\emph{name}). New flags introduced: \verb|\dirnickname|, \verb|\dirphone|,
\verb|\dirfax|, \verb|\diremail|, \verb|\dirurl|, \verb|\diraccount| and
\verb|\dirand|.
\item[1.00]
New HTML styles (\texttt{address-html.bst} and \texttt{email-html.bst}). 
\item[1.01]
Minor corrections.
\item[1.10]
Major rewriting of \texttt{bst} files (suppression of direct \LaTeX\
formatting). Definition of new customization commands. New package global
options to split directories across pages and allow page breaks inside
directory fields. The \texttt{url.sty} package is now required. 
\item[1.11]
Introduction of \verb'\dirparindent'. 
\item[1.12]
Formatting commands can be particularized to each subfield by adding
\texttt{p}, \texttt{r} or \texttt{w} after the \verb'\dir' or \verb'\Dir'
prefix of the original customization command. Many simplifications and small
corrections in the page breaking mechanism and in the list environments.
\item[1.13] 
Fixed bug for long entries without blank spaces (e.g.\ in \texttt{url}
fields).
\item[1.14] 
More flexible definition of \verb|\Dirheader|.
\end{description}


\begin{table}[p]
\caption{Summary of customization commands\label{tab:commands}}
\begin{center}\small
\begin{tabular}{@{}l@{\hspace{5pt}}c@{\hspace{5pt}}p{3.8cm}l@{}}
\hline
Command & Arg. & Explanation & Default \\
\hline

\verb'\dirsymbol' & 0 & 
\raggedright In-text symbol produced after a directory citation & 
\verb*'' \\

\verb'\dirand' & 0 &
\DbleQuote{anding} string &
\verb*'and' \\

\verb'\dirbirthday' & 0 &
Birthday field flag &
\verb*'$\star$~' \\

\verb'\dirprivate' & 0 &
Private field flag &
\verb*'\emph{p}~' \\

\verb'\dirresidence' & 0 &
Residence field flag &
\verb*'\emph{r}~' \\

\verb'\dirwork' & 0 &
Work field flag &
\verb*'\emph{w}~' \\

\verb'\dirnote' & 0 &
Note field flag &
\verb*'$\triangleright$~' \\

\verb'\dirnickname' & 0 &
Nickname field flag &
\verb*'' \\

\verb'\diraddress' & 0 &
Address fields flag &
\verb*'' \\

\verb'\dirphone'$^*$ & 0 &
Phone fields flag &
\verb*'phn: ' \\

\verb'\dirfax'$^*$ & 0 &
Fax fields flag &
\verb*'fax: ' \\

\verb'\diremail'$^*$ & 0 &
E-mail fields flag &
\verb*'' \\

\verb'\dirurl'$^*$ & 0 &
Url fields flag &
\verb*'' \\

\verb'\diraccount'$^*$ & 0 &
Account fields flag &
\verb*'acc: ' \\

\verb'\dirtitle' & 0 &
Title field flag &
\verb*'' \\

\verb'\dirname' & 0 &
Name field flag &
\verb*'' \\

\verb'\Dirlabel' & 1 &
Label format &
\verb*'{\textbf{#1}}' \\

\verb'\Dirheader' & 1 & \raggedright Header format when &
\verb'\newpage\markboth' \\
&& the \texttt{split} option is &
\verb'  {\MakeUppercase{#1}}' \\
&&\raggedright used$^\dag$ (the arg.\ is the first letter used in the
sorting algorithm) &
\verb'  {\MakeUppercase{#1}}' \\

\verb'\Dirbirthday' & 2 &
\raggedright Birthday format (the first arg.\ is the day, the second
is the month) & 
\verb*'{\number#1}/{\number#2}' \\

\verb'\Dirbirthyear' & 1 &
\raggedright Birth year format when a \texttt{birthday} field exists &
\verb*'/{#1}' \\

\verb'\DirbirthyearAlone' & 1 &
\raggedright Birth year format when no \texttt{birthday} field exists &
\verb*'{#1}' \\

\verb'\Dirnickname' & 1 &
Nickname format &
\verb*'(aka {#1})' \\

\verb'\Diraddress'$^*$ & 1 &
Address format &
\verb*'{#1}' \\

\verb'\Dirphone'$^*$ & 1 &
Phone format &
\verb*'{#1}' \\

\verb'\Dirfax'$^*$ & 1 &
Fax format &
\verb*'{#1}' \\

\verb'\Diremail'$^*$ & 1 &
E-mail format &
\verb*'\url{#1}' \\

\verb'\Dirurl'$^*$ & 1 &
Url format &
\verb*'\url{#1}' \\

\verb'\Diraccount'$^*$ & 1 &
Account format &
\verb*'\url{#1}' \\

\verb'\Dirtitle' & 1 &
Title format &
\verb*'{#1}' \\

\verb'\Dirname' & 1 &
Name format &
\verb*'{#1}' \\

\verb'\Dirnote' & 1 &
Note format &
\verb*'{#1}' \\

\hline
\end{tabular}
\end{center}
\vspace{-5pt}\small
$^*$\,The commands marked with an asterisk also exist
in three other versions, controlling independently the private, residence and
work parts (e.g.\ \verb'\dirphone' can be particularized to \verb'\dirpphone',
\verb'\dirrphone' and \verb'\dirwphone')\\[3pt]
$^\dag$\,and a coherent page style selected 
(e.g.\ \verb'\pagestyle{headings})'
\end{table}

\end{document}

