\title {The \textsf{Custom-Bib} Package}

\author{Patrick W. Daly\\
Max-Planck-Institut f\"ur Aeronomie\\
D-37189 Katlenburg-Lindau, Germany\\
\texttt{daly@linmpi.mpae.gwdg.de}}

\begin{Article}

\section{Introduction}
This article\footnote{%
Based on the \texttt{README} file distributed with version 3.7 of the
package, dated  February 1, 1996}
describes the \package{custom-bib} package for generating customized
\BibTeX\ bibliography styles from a generic file by means of Frank
Mittelbach's \package{docstrip} program.
Many authors are frustrated at the wide range of bibliographic styles
demanded by journals and publishers, and at the limited number
available with standard
\LaTeX\ and \BibTeX. This is not \BibTeX's fault, but rather
shows the lack of any bibliographic standards in the English
language. Often the differences are trivial~--- comma or colon, date
in brackets or parentheses; but the normal user does not want to tackle
the task of making up his own \texttt{.bst} file (no normal human
would!).

For this reason, I set out to produce a generic \texttt{.bst} file
that could have
features and options selected by means of the
\package{docstrip} program, which is now part of the standard \LaTeX{}
installation.
I found over 50 different \texttt{*.bst} files and compared their
outputs just for article: they were all different. They served as part
of my input as to which features were needed. I knew of a few extra
that were not covered by these~50.

I also discovered \texttt{btxbst.doc}, Oren Patashnik's source for the four
standard \texttt{.bst} files, as well as a file \texttt{physics.bst}, for
extracting \texttt{.bst} files for a number of physics journals. Both of these
do precisely what I had set out to accomplish; however, they require the
C~preprocessor, or something similar. It is really a simple matter to convert
the preprocessor commands into \package{docstrip} equivalents.

Nevertheless, neither of these really met all of my needs, so I continued to
develop \texttt{genbst.mbs} 
   (\underline{GEN}eric-\underline{B}ib\underline{ST}.%
       \underline{M}aster\underline{B}ib\underline{S}tyle).  
It soon became obvious that the sheer number of options necessary made any kind
of customizing a difficult chore. Hence, the next step: the program
\textsf{makebst} takes menu information out of the selected \texttt{.mbs} file
and presents the user with descriptive choices as menus. From the answers, it
writes a \textsf{docstrip} batch job (extension \texttt{.dbj}) which when
\TeX'ed, creates the desired \texttt{.bst} file out of the \texttt{.mbs} one.
The \texttt{.dbj} file may even be hand edited if one wants to alter only one
or two options.

Since I first released this system in November 1993, I have received
many suggestions and requests for additions. I have tried to
incorporate as many as possible. The original 50 options have grown to over
100. The rate at which suggestions are sent to me has decreased considerably,
so one can hope that the system is becoming stable.

The second version of \texttt{genbst.mbs} allowed other languages to
be included. However, since the method had considerable overhead per
language, I was unsatified with it. A parallel version called
\texttt{babel.mbs} (which was really \texttt{genbst.mbs} version~2)
has been available for some time, supporting English, French, German,
and Esperanto, as well as a generic language called Babel.

I have now modified \textsf{makebst} to allow more than one
\texttt{.mbs} file to be used as input for any given \texttt{.bst}
output. This means that the language support can be
contained in separate files, one per language, and does not need to
burden the main file. The new issue of this main file, version~3, is
now called \texttt{merlin.mbs}, to emphasize its magical powers.

\section{Installation and Use}
To install the package you need to have \texttt{docstrip.tex} and
\texttt{doc.sty}; if you do not have the former, you cannot use
the package anyway. Both are now part of the standard \LaTeX\ (2e)
distribution from 1994 June~1.

The steps for installing are:
%
\begin{enumerate}\setcounter{enumi}{-1}
\item (Optional, for connoisseurs.) \LaTeX\ \texttt{makebst.dtx} to get
the   documentation. This also extracts \texttt{makebst.ins} from
      \texttt{makebst.dtx}, if it does not already  exist.

\item Run \TeX\ (or \LaTeX) on \texttt{makebst.ins} (to generate
      \texttt{makebst.tex})

\item Run \TeX\ (or \LaTeX) on \texttt{makebst.tex} to start customizing
     your own  \texttt{.bst} file. You may select the master file as
     either
     \texttt{merlin} (default), or one of the older genbst and babel, 
     if you have them.

\item
      Answer the questions that then arise; for \texttt{merlin}, you will  
      also be asked which language support file you want (default is merlin
      itself, meaning English or the pseudo-language Babel). You will also be
      asked if you want to add a file defining short-hand designations for
      various journals; such files are included (\texttt{physjour.mbs},
      \texttt{photjour.mbs}, \texttt{geojour.mbs}) for journals in physics, 
      optics, and geophysics, but you could create your own. 

\item The menus that appear may not be informative
      enough for you. More information can be obtained by reading the
      documentation (on the options) contained in the \texttt{.mbs} files
      themselves. This documentation can be printed out by running \LaTeX\ on
      the \texttt{.mbs} files. 

\item The \textsf{makebst} program only produces
      a \textsf{docstrip} batch job to generate the \texttt{.bst} file. The
      last question it asks is whether that job should be run right away. You
      can always run it again yourself by running \TeX\ or \LaTeX\ on this
      \texttt{.dbj} file. (The \texttt{.dbj} file can also be manually edited
      if you want to play around with the various options it includes.)

\end{enumerate}

\section{Note on Author--Year Citations}

Author--year style citations are not supported by standard \LaTeX\ and
\BibTeX. However, there exist a large number of bibliography styles for this,
all of which need some interface package to run properly. I have
identified 5 different interfaces, plus a 6th one that I use myself
(see the \package{natbib} package in a parallel directory). I have made up
\texttt{merlin.mbs} to be able to produce \texttt{.bst} files for
all~6. If one selects author--year style, then one is asked which
interface package is to be used. (Incidentally my \package{natbib} package
is capable of interpreting all~6!)

\section{The Pseudo Language Babel}

If one selects the language to be Babel, all explicit words in the resulting
\texttt{.bst} file are replaced by commands. For example, `editor' is replaced
by \verb|\bbleditor|. The translations of these commands are to be found in a
file named \texttt{babelbst.tex}, which can be extracted from
\texttt{merlin.mbs} with the \package{docstrip} option \textsf{bblbst}, albeit
only for English. My original idea was that one could edit this file as one
pleases for other languages, or that it could be incorporated into the
\textsf{babel} multilingual system. However, this needs further development.


\section{Selected Features of \texttt{merlin.mbs}}

\begin{itemize}

\item
List all options in the \texttt{dbj} file.

The \textsf{makebst} program writes to the \texttt{.dbj} file all the
\package{docstrip} options that were offered in the interactive session, with
all but the selected ones commented out. This makes editing afterwards much
easier. Often one wants to experiment with some of these options, but only
wants to run the \package{makebst} program once.

This feature (suggested by Frank Mittelbach) is available when the
\texttt{makebst.tex} file is extracted from \texttt{makebst.dtx} with
the `\textsf{optlist'} option;
without it, only the selected options are listed in the \texttt{.dbj}
file. Edit the \texttt{makebst.ins} file accordingly; by default, this
feature is included.

\item Allow multiple input \texttt{.mbs} files.
The \texttt{.dbj} file is now so constructed that \verb|\generateFile|
can read in more than one input  \texttt{.mbs} file for a single
output  \texttt{.bst} file. The main \texttt{.mbs} file must
have its menu coding arranged to take advantage of this. Older
\texttt{.mbs} files
(like \texttt{genbst.mbs} and \texttt{babel.mbs}) will still work just
as well with this version of \package{makebst}. Similarly,
\texttt{merlin.mbs} can be used with older versions of
\package{makebst}, but without any additional input files.


\item Name formatting:  can also have reversed full names, as Smith,
John George.  (Previously reversed names could only be initials.)
Thus the follwing forms are allowed:
\begin{quote}
   John George Smith\\
   Smith, John George \\
   J. G. Smith\\
   Smith, J. G.\\
   Smith, J. G. and F. M. Jones \\
   Smith, J G\\
   Smith, JG \\
   Smith J G
\end{quote}

Editors' names (in collections) for surname-first styles, may now be
formatted    exactly as the authors'. (Previously they would never be
reversed.)
It is also possible to have
\begin{quote}\raggedright
In: B. G. James (editor) Booktitle  \\
                          In: B. G. James, editor, Booktitle\\
                          In: Booktitle, edited by B. G. James\\
                          In: Booktitle (edited by B. G. James)
\end{quote}

\item
ISBN numbers can optionally be included, if they're present in the database.

\item
Volume, number has more possibilities:

\begin{tabular*}{\linewidth}{l@{\extracolsep{\fill}}l@{\extracolsep{\fill}}l@{\extracolsep{\fill}}l@{\extracolsep{\fill}}l@{\extracolsep{\fill}}l}
  34(2) &  34 (2)    &  34, 2 &  34, no. 2 &
   34, \verb|#|2  &  34
\end{tabular*}

The following page number can be separated by colon, colon space,
   semi-colon and space, comma and space. It is even possible to add
   to \texttt{number} to the page specification:
   34, (2)234--(2)254.


\item
Date: year coming just after authors may have colon and space following.
      Date may appear as `1994 Jul', with or without a dot.
      Date may be part of journal specification, something that is
      common in medical journals.
      Date may be bold.


\item
      Journal names: the periods in abbreviations may be removed, so
      Phys.\ Rev.\  becomes Phys~Rev  (no change to database necessary).
    Name of journal can be in normal font, not only italic.

\item
      Author names in may be italic, small caps, or bold.
       The word `and' can be in the regular text font, 
       not in the author font.
     The font style may be
      different in the citations and list of references.

\item
      If the number of authors exceeds a certain limit, then only
      so many are listed, followed by \emph{et~al.} Both these maximum and
      minumum numbers can be set. Default is that all authors are listed.

\item
      The page numbers in edited works can have `pages' or `pp' suppressed.

\item
     It is possible to have the names sorted by ignoring the `von' part, so
     that  della Robbia comes after Rabin.

\item
    Publisher's address may come before name, as New York: New Press
    (required by some psychology journals).

\item
    The extra labels added to years (as 1995a) are grouped in braces
    to avoid some problems with \package{natbib} when this extra label is more
    than one letter. The font of this extra label can also be selected.

\item
    For author-year systems, both full and abbreviated author lists are 
    possible in the citations.

\item
  Journals can have date between volume and pages, as:
       J.\ Geophys.\ Res.\ {\bf 34} (1994) 333--338

\item
  Technical Reports can have titles treated like books
(default is like article).

\item  Can sort by year and then authors.

\item Can include more than one file with prestored journal names.

\item
   The \package{named} format for \verb|\bibitem| now included.

\item
   Blocks can be separated by colons as well as commas or periods.


\item
   Pages in books may be in parentheses.



\item
  Authors in the list may separated by semi-colons instead of
    by commas.
\end{itemize}

\section{Package files}

The package contains the following files:
\begin{filedesc}
\item[merlin.mbs]
   A master \BibTeX\ style file for producing customized
   styles (numerical or author-year) with docstrip. It is
     self-documenting: simply latex it to produce its
   description.

\item[english.mbs] A sample language support file for English, to act
as a   model for hacking others.

\item[esperant.mbs]  A language support file for Esperanto.
\item[finnish.mbs]  A language support file for Finnish.
\item[french.mbs]  A language support file for French.
\item[german.mbs]  A language support file for German.
\item[italian.mbs]  A language support file for Italian.
\item[norsk.mbs]  A language support file for Norwegian.
\item[spanish.mbs]  A language support file for Spanish.
\end{filedesc}

\noindent
(Further contributions and corrections are welcome.)

\begin{filedesc}
\item[physjour.mbs]
 A support file to add the names of common Physics journals
  in shorthand form, for example `pr' for Physical Review, or
  Phys. Rev., depending on whether abbreviations chosen.

\item[photjour.mbs]
  A contributed file containing names of optics journals.

\item[geojour.mbs]
  A contributed file containing names of geophysics journals.
\end{filedesc}

\noindent
(Contributions for other fields are welcome.)

The \texttt{.mbs} files can only be used effectively with the
\textsf{makebst} `program', which is included in documented source form.

\begin{filedesc}
\item[makebst.dtx] the documented source file; \LaTeX{}ing this file
produces the manual and optionally a documentation of the
coding. Requires \class{ltxdoc} class from the \LaTeXe\ distribution.

Current version is 3.0; the documentation requires
\LaTeXe\ (1994/06/01). The program itself only requires \TeX.

\item[makebst.ins] \package{docstrip} batch job to extract from
\texttt{makebst.dtx} the program file \texttt{makebst.tex}. (This file
is actually included  within \texttt{makebst.dtx}; it is extracted
when the \texttt{.dtx} file is processed under \LaTeXe.)
\end{filedesc}
\end{Article}

