                              CUSTOM-BIB Package

**** INFO ******
Version 3.x now called  merlin.mbs   replacing genbst.mbs and babel.mbs
Current version is 3.8
*****************
Changes over 3.7: can now produce citations like those of ALPHA.BST
                  publishers can be in parentheses
                  can have no punctuation between `blocks'
                  can order author-year references by year, author, title
                  fix a bug that appears when titles are to be in quotes

This is the custom-bib package for generating customized BibTeX bibliography
styles from a generic file by means of Frank Mittelbach's 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 the fault of the latter, but rather of the lack
of any bibliographic standards in the English language. Often the differences
are so trivial (comma or colon, date in brackets or parentheses). The normal
user does not want to tackle the task of making up his own .bst file (no
normal human would!) 

For this reason, I set out to produce a generic .bst file that could have
features and options selected by means of Mittelbach's docstrip program. 
I found over 50 different *.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 XBTXBST.DOC, a minor modification of Patashnik's BTXBST.DOC,
as well as a file PHYSICS.BST, all of which are meant to do precisely what I
had set up to accomplish. However, they make use of the C Preprocessor
language. It is really a simple matter to convert the preprocessor commands
into docstrip equivalents. 

Nevertheless, none of these really met all of my needs, so I continued to
develop GENBST.mbs (GENeric-BibST.MasterBibSt). 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 MAKEBST takes menu information from
the selected .mbs file and presents the user with descriptive choices as
menus. From the answers, it writes a docstrip batch job (extension .dbj) which
when TeX'ed, creates the desired .bst file out of the .mbs one. The .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, but often the task is too complicated and I have to leave them out.

The second version of GENBST.mbs allowed other languages to be used. However,
since the method had considerable overhead per language, I was unsatified with
it. A parallel version called BABEL.mbs (which was really 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 MAKEBST to allow more than one .mbs file to be used as 
input for any given .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
MERLIN.mbs, to emphasize its magical powers.

To use the package: (I assume you have docstrip.tex and doc.sty; if you do not
  have the former, then you cannot use the package anyway; they are now part
  of the standard LaTeX (2e) distribution from 1994 June 1.)

0. (optional, for hackers) LaTeX makebst.dtx to get the documentation;
     This also extracts makebst.ins from makebst.dtx, if it does not already
     exist.
1. Run TeX (or LaTeX) on makebst.ins (--> makebst.tex)
2. Run TeX (or LaTeX) on makebst.tex to start customizing
     your own .bst file. You may select the master file as either merlin
     (default), or one of the older genbst and babel, if you have them.
3. Answer the questions that then arise; for 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 (physjour.mbs, photjour.mbs) for Physics and Optics 
     journals, but you could create your own.
4. 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 .mbs files themselves. This documentation can be printed
     out by running LaTeX on the .mbs files.
5. The makebst program only produces a docstrip batch job to generate the .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 .dbj file. (The .dbj file can also be manually edited if you want to
     play around with the various options it includes.)

NOTE ON AUTHOR-YEAR CITATIONS:-
Author-year style citations are not supported by standard LaTeX and BibTeX.
However, there exist a large number of bib 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 NATBIB package in a
parallel directory). I have made up merlin.mbs to be able to produce .bst
files for all 6. If one selects author-year style, then one is asked which
interface package is to be used. (Incidentally my natbib.sty is capable of
interpreting all 6!)

LIST OF ALL OPTIONS IN THE DBJ FILE (new to version 2.1 from 1994 Dec 29)
The makebst program writes to the .dbj file all the docstrip options
that were offered in the interactive session. This makes editing afterwards
much easier. Often one wants to experiment with some of these options, but
only wants to run the makebst program once.

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

ALLOW MULTIPLE INPUT .MBS FILES (new to version 3.0 from 1995 Mar 15)
The .dbj file is now so constructed that \generateFile can read in more than
one input .mbs file for a single output .bst file. The main .mbs file must
have its menu coding arranged to take advantage of this. Older .mbs files
(like genbst.mbs and babel.mbs) will still work just as well with this version
of makebst. Similarly, merlin.mbs can be used with older versions of makebst,
but without any additional input files.

NEW FEATURES OF MERLIN.MBS since genbst.mbs 1.7 and babel 2.5
Names formatting:  can also have reversed full names, as Smith, John George
                   (previously reversed names could only be initials)
   John George Smith
   Smith, John George  (v3.1)
   J. G. Smith
   Smith, J. G.
   (AGU style: first name reversed, rest normal, all with initials)
   Smith, J G
   Smith, JG   (v3.1)
   Smith J G   (v3.2)
   
Editors' names (in collections) for surname-first styles, may now be formatted
   exactly as the authors'. (Previously these would never be reversed.)

   Also possible to have  In: B. G. James (editor) Booktitle  
                          In: B. G. James, editor, Booktitle
                          In: Booktitle, edited by B. G. James
                          In: Booktitlte (edited by B. G. James)

ISBN numbers can optionally be included, if present in database

Volume, number has more possibilities: for volume=34, number=2:
  34(2)   34 (2)   34, 2   34, no. 2    34, #2    34  

The following page number can be separated by colon, colon space, 
   semi-colon and space, comma and space, or space only
(In v3.6, add number to page spec.) 34, (2)234-(2)254

Or even   34 (1994) 2, pp. 234-254  (v3.8)
   
Date: year coming just after authors may have colon and space following
      date may appear as `1994 Jul', with or without a dot (v3.2)
      date may be part of journal specification, something that is common
        in medical journals (v3.2)

Journal names: the periods in abbreviations may be removed, so Phys. Rev.
   becomes Phys Rev  (no change to database necessary)
   
Author names in citations (as opposed to list of references)
  may be italic, small caps, or bold (last two new)

The mininum number of authors' names before et al. has been raised from 
  5 to 6 (v3.2)

The page numbers in edited works can have `pages' or `pp' suppressed (v3.2)

It is possible to have the names sorted by ignoring the `von' part, so that
  della Robbia comes after Rabin (v3.2)

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

Refinements added to version 3.3: 
  - the extra labels added to years (as 1995a) are grouped in braces
    to avoid some problems with natbib when this extra label is more than
    one letter
    
  - when full author lists may be optional (for harvard and natbib formats)
    they are no longer included if they are identical to the short 
    author list

Refinements added to version 3.4:
  - journals can have date between volume and pages, as
       J. Geophys. Res. {\bf 34} (1994) 333-338
  - author block can be terminated with colon
  - if cited authors are in bold, italic, or small caps, then the word
      `and' can be in the regular text font, not in the author font.

Refinements added to version 3.5:
  - Technical Reports can have titles treated like books (default=article)
  - can sort by year then authors
  - can include more than one file with prestored journal names 
  - bug fixed for limited number of authors: sort only on those present
  - the `named' format for \bibitem now included.

Refinements added to version 3.6:
  - blocks can be separated by colons as well as commas or periods
  - name of journal can be in normal font, not only italic
  - pages in books may be in parentheses
  - can have `number' as part of page specification:  34, (2)234-(2)254
  - date may be bold
  - if authors in list have special font, then `and' and/or `et al.' 
    may be normal font

Refinements added to version 3.7:
  - an option to allow authors to be separated by semi-colons instead of
    by commas
  - fix bug in the option that removes periods from journal names when
    italicized

Refinements added to version 3.8:
  - fix a bug with titles in quotes
  - an option allows ALPHA style citations, of the form  ABD90. This
    is essentially a numerical system with some text replacing the number.
  - publishers and address can appear in parentheses 
  - punctuation between `blocks' can be suppressed, space only
  - ordering reference list by year is possible for author-year as well as
     numerical modes
  - can put date between volume and number
  - can add `pages' or `pp' to articles
  - cited names in a special font can have the `and' in regular font:
    previously this meant \rm, but now, with NFSS, only the one attribute is
    reset; thus  \textbf{\cite{james93}} yields
       \textbf{\textsc{James {\upshape and} Johns}, [1993]}
    so that `and' will be bold non-sc. (Actually, bold small caps does not
    exist in the CM fonts, so a substitution will be made.)

The package contains the following files:
  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. 
                   
  english.mbs  --  A sample language support file for English, to act as a
                   model for hacking others.
                   
  esperant.mbs --  A language support file for Esperanto 
  finnish.mbs  --  A language support file for Finnish 
  french.mbs   --  A language support file for French 
  german.mbs   --  A language support file for German 
  italian.mbs  --  A language support file for Italian 
  norsk.mbs    --  A language support file for Norwegian
  spanish.mbs  --  A language support file for Spanish 
(Further contributions and corrections are welcome)

  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.

  photjour.mbs --  A contributed file containing names of optics journals

  geojour.mbs  --  A contributed file containing names of geophysics journals

(Contributions for other fields are welcome)  

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

  makebst.dtx  --  the documented source file; LaTeXing this file produces
                   the manual and optionally a documentation of the coding.
                   Requires ltxdoc class from the LaTeX2e distribution.

                   This is version 3.0; the documentation requires 
                   LaTeX2e (1994/06/01). The program itself only requires TeX.

  makebst.ins  --  a docstrip batch job to extract from makebst.dtx the 
                   program file makebst.tex. (This file is actually included
                   within makebst.dtx; it is extracted when the .dtx file is
                   processed under LaTeX2e.)

1996 May 29
Patrick W. Daly
Max-Planck-Institut f\"ur Aeronomie
D-37189 Katlenburg-Lindau, Germany
E-mail: daly@linmpi.mpae.gwdg.de
