birthday bibtex package update (2004)

git-svn-id: svn://tug.org/texlive/trunk@2366 c570f23f-e606-0410-a88d-b1316a301751

3 files changed, 304 insertions, 220 deletions

diff --git a/Master/texmf-dist/doc/latex/directory/README b/Master/texmf-dist/doc/latex/directory/README
index 75fd0ac5fc6..1497e9c80cb 100644
--- a/Master/texmf-dist/doc/latex/directory/README
+++ b/Master/texmf-dist/doc/latex/directory/README
@@ -1,14 +1,15 @@
+This is the 'directory 1.20' distribution.
 
-This is the 'directory 1.15' distribution.
-
-'directory' is a macro package for LaTeX and BibTeX that facilitates the
-construction, the maintenance and the exploitation of an address book like
-database. 
+'directory' is a macro package for LaTeX and BibTeX that facilitates
+the construction, the maintenance and the exploitation of an address
+book like database.
 
 Files included:
 
   README
   address-html.bst
+  address-ldif.bst
+  address-vcard.bst
   address.bst
   birthday.bst
   business.bib
@@ -28,5 +29,4 @@ run LaTeX, run BibTeX and then run LaTeX twice on the file
 
 Enjoy!
 
-Christophe Geuzaine (Christophe.Geuzaine@advalvas.be)
-
+Christophe Geuzaine <geuz@geuz.org>
diff --git a/Master/texmf-dist/doc/latex/directory/directory.pdf b/Master/texmf-dist/doc/latex/directory/directory.pdf
index 77d2a1b8bee..97683cee73a 100644
--- a/Master/texmf-dist/doc/latex/directory/directory.pdf
+++ b/Master/texmf-dist/doc/latex/directory/directory.pdf
diff --git a/Master/texmf-dist/doc/latex/directory/directory.tex b/Master/texmf-dist/doc/latex/directory/directory.tex
index c5a2fd5f96f..287b18b0275 100644
--- a/Master/texmf-dist/doc/latex/directory/directory.tex
+++ b/Master/texmf-dist/doc/latex/directory/directory.tex
@@ -1,7 +1,7 @@
 %% directory.tex
-%% Copyright 1999-2000 Christophe Geuzaine
+%% Copyright 1998-2004 Christophe Geuzaine <geuz@geuz.org>
 %
-% Last Mod by Christophe on Sun Aug 27 21:04:05 2000
+% $Id: directory.tex,v 1.32 2004/09/22 21:05:18 geuzaine Exp $
 %
 % This program can be redistributed and/or modified under the terms
 % of the LaTeX Project Public License distributed from CTAN
@@ -10,91 +10,81 @@
 %
 % 'directory' user's guide and example file
 % 
-% Christophe.Geuzaine@advalvas.be
-%
-% The parts you may want to customize are labeled with "CUSTOM"
-%
-% The lines beginning with %%tth: are used by TTH (TeX->HTML translator)
-%
+% The parts you may want to customize are labeled with "CUSTOM:". The lines
+% beginning with "%%tth:" are used by TTH (a LaTeX to HTML translator).
 
 \documentclass[10pt]{article}
-\addtolength{\textheight}{6pt}
 
-% CUSTOM  try e.g. \usepackage[split]{directory} 
-\usepackage[split]{directory} 
+\usepackage[break,longdates]{directory} 
 
-% CUSTOM  uncomment only one of these
-% \directorystyle{email-html}
+% CUSTOM: uncomment one of the following:
 % \directorystyle{email}
 % \directorystyle{phone}
 % \directorystyle{birthday}
 % \directorystyle{letter}
 % \directorystyle{address-html}
+% \directorystyle{email-html}
+% \directorystyle{address-vcard}
+% \directorystyle{address-ldif}
 \directorystyle{address}
 
-% CUSTOM  here is how I customized the directory for this document
-\renewcommand{\dirsymbol}{\raisebox{1ex}{\tiny\textit{(cf.\ section~\ref{dir})}}}
+% CUSTOM: here is how I customize the directory for this user's guide:
+\renewcommand{\dirsymbol}{\raisebox{1ex}{\tiny{[see \S\ref{sec:output}]}}}
 \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}}}
 
-% CUSTOM  here is how I handle pdf output
 \ifx\pdfoutput\undefined\else
   \usepackage[colorlinks=true,urlcolor=blue]{hyperref}
   \newcommand\MyURL{\begingroup\Url}
   \renewcommand{\Diremail}[1]{\href{mailto:#1}{\MyURL{#1}}}
   \renewcommand{\Dirurl}[1]{\href{#1}{\MyURL{#1}}}
 \fi
+\def\baselinestretch{0.98}
 
-% 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.}}
+  \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\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.}}
+%%tth: \def\LaTeX{LaTeX}
+%%tth: \def\BibTeX{BibTeX}
 
 \pagestyle{headings}
 
 \begin{document}
 
-%%tth:\special{html:<BODY TEXT="#000000" BGCOLOR="#ffffff">}
+\title{\texttt{directory}: address books with \LaTeX\ and \BibTeX}
 
-\title{\TitleTT{directory} 1.15 User's Guide}
-
-% CUSTOM  try \author{\wdir{c.geuzaine}} with \directorystyle{letter}
+% CUSTOM: try e.g. \author{\wdir{c.geuzaine}} with \directorystyle{letter}
 \author{\dir{c.geuzaine}}
 
-%%tth:\special{html:<H3 align=center>Christophe Geuzaine</H3>}
+%%tth: \special{html:<H3 align=center>Christophe Geuzaine</H3>}
 
-\date{August 27, 2000}
+\date{Version 1.20, 22 September 2004}
 
 \maketitle
 
-%%tth:\section*{Download}
-%%tth:The current archive of the package is available
-%%tth:\href{http://www.geuz.org/directory/directory-1.15.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}. 
+%%tth: \section*{Download}
+%%tth: The current distribution of \texttt{directory} is 
+%%tth: \href{http://www.geuz.org/directory/src/directory-1.20.tgz}{directory-1.20.tgz}.
+%%tth: This distribution contains both a
+%%tth: \href{http://www.geuz.org/directory/directory.ps}{PostScript}
+%%tth: and a \href{http://www.geuz.org/directory/directory.pdf}{PDF}
+%%tth: version of the documentation. The separate files are also available
+%%tth: through the \href{http://www.ctan.org/}{CTAN} sites in the 
+%%tth: \href{http://www.ctan.org/tex-archive/biblio/bibtex/contrib/directory/}
+%%tth: {biblio/bibtex/contrib/directory/} subdirectory. Older versions are
+%%tth: still available \href{http://www.geuz.org/directory/src/}{here}.
+%%tth: Any questions, comments or suggestions? Send me an 
+%%tth: \href{mailto:geuz@geuz.org}{e-mail}. 
 
 \tableofcontents
 
@@ -105,59 +95,61 @@ 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 \LaTeX\ style file \texttt{directory.sty}. According to
+conjunction with the \LaTeX\ style file \texttt{directory.sty}. Depending on
 the bibliographical style used, the package has two main applications:
 
 \begin{enumerate}
 \item
-the construction of a list of informations (address, phone number, etc.)
+the construction of a list of information (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.
+the inclusion of a selected piece of information 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.
+bibliographical styles: while standard bibliographical styles handle data
+concerning books, articles, proceedings, etc., \texttt{directory} handles
+data 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{sec:output}. The first four \BibTeX\ files provide
+several ways to handle this data.
 
 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. 
+\sloppypar
+Four special \BibTeX\ style files (\texttt{address-html.bst},
+\texttt{email-html.bst}, \texttt{address-vcard.bst} and
+\texttt{address-ldif.bst}) are also provided for an easy generation of HTML,
+vCard and LDIF 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: 
+The package is included by the usual \verb'\usepackage{directory}' command
+at the top of the document. Four options are available:
 \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.
+\item[\textmd{\texttt{break}:}] allows the directory fields to be broken
+  across pages;
+\item[\textmd{\texttt{german}:}] creates directories in German;
+\item[\textmd{\texttt{french}:}] creates directories in French;
+\item[\textmd{\texttt{longdates}:}] prints birthday dates using month names
+  instead of numbers.
 \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}
+\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. 
+included, a comma separating the different file names.
 
 \subsection{Making a citation}
 
@@ -206,36 +198,103 @@ or \verb'\wdir{'\emph{key}\verb'}') command prints the name and the private
 
 \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. 
+\texttt{directory} defines three entry types: \verb'@person{}',
+\verb'@company{}' and \verb'@place{}'. In all these types, \texttt{name} is
+the only mandatory field, since it serves as a key for sorting the entries.
+Here are all the available fields that can be defined for each entry:
 
-\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.cellular}, \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.cellular}, \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.cellular}, \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{cellular}, \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{cellular}, \texttt{fax} and \texttt{note}.
-\end{description}
+\begin{verbatim}
+@person{key,
+  name = "Full name(s), in standard BibTeX format",
+  nickname = "Nickname(s)",
+  birthday = "Birthday date(s), in numeric 'day month' format",
+  birthyear = "Birth year(s)",
+
+  p.street = "Street of private residence",
+  p.city = "City of private residence",
+  p.zip = "ZIP code of private residence",
+  p.state = "State of private residence",
+  p.country = "Country of private residence",
+  p.phone = "Private phone number",
+  p.cellular = "Private mobile phone number",
+  p.fax = "Private fax number",
+  p.email = "Private e-mail address",
+  p.url = "Private home page",
+  p.account = "Private bank account",
+
+  r.street = "Street of alternative residence",
+  r.city = "City of alternative residence",
+  r.zip = "ZIP code of alternative residence",
+  r.state = "State of alternative residence",
+  r.country = "Country of alternative residence",
+  r.phone = "Alternative phone number",
+  r.cellular = "Alternative mobile phone number",
+  r.fax = "Alternative fax number",
+  r.email = "Alternative e-mail address",
+  r.url = "Alternative home page",
+  r.account = "Alternative bank account",
+
+  w.name = "Work organization name",
+  w.title = "Job title",
+  w.street = "Street of work organization",
+  w.city = "City of work organization",
+  w.zip = "ZIP code of work organization",
+  w.state = "State of work organization",
+  w.country = "Country of work organization",
+  w.phone = "Work phone number",
+  w.cellular = "Work mobile phone number",
+  w.fax = "Work fax number",
+  w.email = "Work e-mail address",
+  w.url = "Work home page",
+  w.account = "Work bank account",
+
+  note = "Additional notes about the person",
+}
+\end{verbatim}
 
+\begin{verbatim}
+@company{key,
+  name = "Company name",
+  street = "Company street",
+  city = "Company city",
+  zip = "Company ZIP code",
+  state = "Company state",
+  country = "Company country",
+  phone = "Company phone number",
+  cellular = "Company mobile phone number",
+  fax = "Company fax number",
+  email = "Company e-mail address",
+  url = "Company home page",
+  account = "Company bank account",
+  note = "Additional notes about the company",
+}
+\end{verbatim}
+
+\begin{verbatim}
+@place{key,
+  name = "Place name",
+  street = "Place street",
+  city = "Place city",
+  zip = "Place ZIP code",
+  state = "Place state",
+  country = "Place country",
+  phone = "Place phone number",
+  cellular = "Place mobile phone number",
+  fax = "Place fax number",
+  note = "Additional notes about the place",
+}
+\end{verbatim}
+
+Multiple names, nicknames or birthday dates should be be separated with
+``\texttt{and}''. For backward compatibility, or if an unconventional
+address formatting is needed, the \texttt{street}, \texttt{city},
+\texttt{state}, \texttt{zip} and \texttt{country} fields (and their
+\texttt{p.}, \texttt{r.} and \texttt{w.}  equivalents) can be replaced by
+generic \texttt{address}, \texttt{p.address}, \texttt{r.address} or
+\texttt{w.address} fields. As soon as an \texttt{address} field is defined,
+any \texttt{street}, \texttt{city}, \texttt{state}, \texttt{zip} or
+\texttt{country} field definition is ignored, and the formatting in the
+\texttt{address} field is kept as is.
 
 \section{Customization}
 \label{sec:custom}
@@ -256,40 +315,46 @@ and \verb'\dirparindent') and the amount of space between two entries
 If you want to explicitly introduce a new paragraph in a field, you
 should use the \verb'\dirbreak' command.
 
+A fourth dimension (\verb'\dirtablewidth') sets the width of the table used
+to display fields in when the \texttt{letter} style is selected. The default
+value is:
+\begin{quote}
+\begin{verbatim}
+\setlength{\dirtablewidth}{0.5\textwidth}
+\end{verbatim}
+\end{quote}
+
+
 \subsection{Flags and formats}
+\label{sec:flagsformats}
 
 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: 
+commands summarized in table~\ref{tab:commands} at the end of this user's
+guide (page~\pageref{tab:commands}).
+
+For example, to produce nicely formatted address booklets, you could
+redefine the \verb'\Dirheader' command as
 \begin{quote}
 \begin{verbatim}
-\renewcommand{\dirsymbol}
-  {\raisebox{1ex}{\tiny\textit{(cf.\ section~\ref{dir})}}}
-\renewcommand{\Dirlabel}[1]{{#1}}
+\pagestyle{headings}
+\renewcommand{\Dirheader}[1]
+ {\newpage\markboth{\MakeUppercase{#1}}{\MakeUppercase{#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:
+(which will split the directory across pages, with the first letter used in
+the sorting algorithm in the header of each page) or
 \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}}
+\renewcommand{\Dirheader}[1]
+  {\item\hspace{-\dirindent}\textbf{\MakeUppercase{#1}}}
 \end{verbatim}
 \end{quote}
+(which will produce inline headings).
 
-\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
+When a field type appears multiple times 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.
 
@@ -330,40 +395,6 @@ rest of the bibliography processing. Remember that changing the directory
 
 \section{Generating directories with hypertext links}
 
-\subsection{Direct HTML output}
-
-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;|.
-
-\subsection{Using the \texttt{hyperref} package}
-
 You can use the \texttt{hyperref} package along with \texttt{directory}. For
 example, adding the following lines in the preamble of your document and
 using \texttt{pdflatex} will produce a PDF version of your directory, with
@@ -380,8 +411,52 @@ working links for the \verb'email' and \verb'url' fields.
 \end{verbatim}
 \end{quote}
 
+\section{Generating HTML, vCard or LDIF directories}
+
+Four special \BibTeX\ style files (\texttt{address-html},
+\texttt{email-html}, \texttt{address-vcard} and \texttt{address-ldif}) allow
+the easy generation of HTML, vCard and LDIF 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;
+\item[\textmd{\texttt{address-vcard}:}] 
+full listing in the vCard directory of all fields corresponding to the
+\emph{key} entry.
+\item[\textmd{\texttt{address-ldif}:}] 
+full listing in the LDIF directory of all fields corresponding to the
+\emph{key} entry.
+\end{description}
+
+Since \BibTeX\ directly outputs a \texttt{bbl} file in HTML, vCard or LDIF
+format, no additional program is needed to make the HTML/vCard/LDIF
+conversion. The \texttt{bbl} file directly contains the HTML/vCard/LDIF
+code, ready to be included in a HTML document or to be imported in a
+vCard/LDIF-aware application (Apple Address Book, Microsoft Outlook, Mozilla
+Mail, etc.).
+
+This method presents nevertheless a little drawback: after \BibTeX'ing your
+\LaTeX\ file, running \LaTeX\ on the same file (even with another
+\verb|\directorystyle|) will produce errors, since the \texttt{bbl} file is
+not understandable by \LaTeX. You have to either 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/vCard/LDIF directories is
+also somewhat problematic: 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;|. The vCard style assumes an ISO Latin 1 encoding of the
+directory. If a special encoding is used in the \texttt{bib} file, the LDIF
+output will need to be converted to UTF8. See the comments in the \BibTeX\
+style files for more information.
 
 \section{Example}
+\label{sec: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
@@ -391,9 +466,6 @@ people, companies or places, as in the example shown in this document:
 \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 \LaTeX\ class \texttt{letter.cls} with the
@@ -420,32 +492,33 @@ Here are four \texttt{bib} entries (taken from \texttt{family.bib} and
   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/",
+  p.email    = "geuz@geuz.org",
+  p.url      = "http://www.geuz.org",
+  w.title    = "Postdoctoral Scholar",
+  w.name     = "Caltech, Applied and Computational Mathematics",
+  w.url      = "http://www.acm.caltech.edu",
+  w.street   = "1200 E California Blvd",
+  w.city     = "Pasadena",
+  w.state    = "CA",
+  w.zip      = 91125,
+  w.country  = "USA",
+  w.phone    = "1 626 395 4552",
 }
 
 @Person{d.d.knu,
-  name       = "Knudson, Daffy Duck and Bunny, Bugs and Pluto",
+  name       = "Knudson, Daffy Duck and Bunny, Bugs and Mr. 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.street   = "Haight Street 512",
+  r.zip      = 80214,
+  r.city     = "Novosibirsk",
+  r.country  = "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,
@@ -461,70 +534,87 @@ Here are four \texttt{bib} entries (taken from \texttt{family.bib} and
 \end{verbatim}
 
 \subsection{Output}
-\label{dir}
+\label{sec:output}
 
 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
+% CUSTOM: try e.g. citing just some of the entries
 \nodir{*}
 
-% CUSTOM  this has the same effect: \directory[bbl]{family,business}
+% CUSTOM: this has the same effect as \directory[bbl]{family,business}
 \directory{family,business} 
 
-%%tth:directory generated with \href{directory.html.address}{address-html.bst}
-%%tth:and with \href{directory.html.email}{email-html.bst}.
+%%tth: \par directory generated with \href{directory-address.html}{address-html.bst},
+%%tth: \href{directory-email.html}{email-html.bst}, 
+%%tth: \href{directory-address.vcf}{address-vcard.bst} and
+%%tth: \href{directory-address.ldif}{address-ldif.bst}.
 
 \section{Contributors}
 
-Many thanks to Bernd Schandl, Robert Walker Sumner and Thomas Ruedas for their
-suggestions and corrections.
+Many thanks to Bernd Schandl, Robert Walker Sumner, Thomas Ruedas and
+J\"urgen G\"obel for their suggestions and corrections.
 
 \section{Versions}
 
 \begin{description}
-\item[0.95] 
+\item[0.95] (Jan 8, 1998)
 First distributed version. 
-\item[0.96] 
+\item[0.96] (Jan 9, 1998)
 New documentation. Introduction of customization commands. New alignment
 mechanism in the \texttt{addressbook} and \texttt{phonebook} environments.  
-\item[0.97] 
+\item[0.97] (Jan 26, 1998)
 Entries \texttt{ccp} and \texttt{p.ccp} changed to \texttt{account} and
 \texttt{p.account}.
-\item[0.98] 
+\item[0.98] (Feb 9, 1998)
 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]
+\item[0.99] (Feb 12, 1998)
 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]
+\item[1.00] (Mar 26, 1998)
 New HTML styles (\texttt{address-html.bst} and \texttt{email-html.bst}). 
-\item[1.01]
+\item[1.01] (Oct 26, 1998)
 Minor corrections.
-\item[1.10]
+\item[1.10] (May 6, 1999)
 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]
+\item[1.11] (May 7, 1999)
 Introduction of \verb'\dirparindent'. 
-\item[1.12]
+\item[1.12] (May 11, 1999)
 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] 
+\item[1.13] (Jun 21, 1999)
 Fixed bug for long entries without blank spaces (e.g.\ in \texttt{url}
 fields).
-\item[1.14] 
+\item[1.14] (Jun 21, 2000)
 More flexible definition of \verb|\Dirheader|.
-\item[1.15] 
+\item[1.15] (Aug 28, 2000)
 Added fields for cellular phones (suggested by Stefano Ferrari). Added
 section explaining how to use \texttt{hyperref} to generate PDF documents
 with hyperlinks. Updated web site address.
+\item[1.16] (Feb 5, 2002) 
+Added \verb'\dirtablewidth' to set the width of the fields when the
+\texttt{letter} style is selected. Suppressed the \texttt{split} option
+(redefining the \verb'\Dirheader' command makes it possible to achieve the
+same result: see section~\ref{sec:flagsformats}).
+\item[1.17] (Dec 15, 2002)
+Revised documentation.
+\item[1.18] (Sep 13, 2003)
+Added vCard and LDIF support.
+\item[1.19] (Sep 15, 2003)
+Split \texttt{address} into \texttt{street}, \texttt{city}, \texttt{state},
+\texttt{zip} and \texttt{country}.
+\item[1.20] (Sep 22, 2004)
+Fixed small vcard export bug when using the old \texttt{address} fields;
+new \texttt{german}, \texttt{french} and \texttt{longdates} options.
 \end{description}
 
 
@@ -542,7 +632,7 @@ Command & Arg. & Explanation & Default \\
 
 \verb'\dirand' & 0 &
 \DbleQuote{anding} string &
-\verb*'and' \\
+\verb*'\normalfont{and}' \\
 
 \verb'\dirbirthday' & 0 &
 Birthday field flag &
@@ -574,11 +664,11 @@ Address fields flag &
 
 \verb'\dirphone'$^*$ & 0 &
 Phone fields flag &
-\verb*'phn: ' \\
+\verb*'tel: ' \\
 
 \verb'\dircellular'$^*$ & 0 &
 Cellular phone fields flag &
-\verb*'gsm: ' \\
+\verb*'mobile: ' \\
 
 \verb'\dirfax'$^*$ & 0 &
 Fax fields flag &
@@ -608,18 +698,15 @@ Name field flag &
 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'\Dirheader' & 1 & 
+Command issued for each new starting letter in the directory (the arg.\ is
+the first letter used in the sorting algorithm) & 
+\verb*'{}' \\
 
 \verb'\Dirbirthday' & 2 &
 \raggedright Birthday format (the first arg.\ is the day, the second
 is the month) & 
-\verb*'{\number#1}/{\number#2}' \\
+\verb*'{\number#2}/{\number#1}' \\
 
 \verb'\Dirbirthyear' & 1 &
 \raggedright Birth year format when a \texttt{birthday} field exists &
@@ -631,7 +718,7 @@ is the month) &
 
 \verb'\Dirnickname' & 1 &
 Nickname format &
-\verb*'(aka {#1})' \\
+\verb*'(aka \emph{#1})' \\
 
 \verb'\Diraddress'$^*$ & 1 &
 Address format &
@@ -680,10 +767,7 @@ Note format &
 $^*$\,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}').
+\verb'\dirrphone' and \verb'\dirwphone').
 \end{table}
 
 \end{document}
-