\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}