Getting Started with custom-bib:
An introduction for for SWP users
August 25, 2000
The typeset appearance of a BibTeX bibliography is governed by the
“bibliography style” (.bst) file, which you choose when you insert the
Bibliography item from SWP’s Typeset Field toolbar. One of the most frequently
asked questions about these bibliographies is: How do I get it into the format
that journal X requires? While it is sometimes possible to hack an existing .bst
file, there is a much better solution: use Patrick Daly’s custom-bib package to
generate a bibliography style file set up just the way you need it. Once you install
the system, you’ll find that custom-bib is astonishingly easy to use, and
the .bst files can be created consistent with standard LaTeX citation
modes, with the Harvard system (package) or with Daly’s own Natbib
This note explains how to set up and use custom-bib. I use “SWP” as an
abbreviation for both Scientific Word and Scientific WorkPlace; but since
custom-bib requires a TeX/LaTeX system, Scientific Notebook is not supported.
These instructions are geared to the directory structure of SWP3.0+; SWP2.5
users will need to make adjustments, but the package will almost certainly work
for them too.
The most important thing to understand is that you do not use
custom-bib within SWP: you will need to use the stand-alone TrueTeX formatter
(initex32.exe). Of course, nothing depends on this particular formatter: any
TeX formatter, like MikTeX’s latex.exe, will do just as well. But first, let’s get
the package and set it up.
2 Getting custom-bib
The simplest way to get the latest files is to browse to the excellent CTAN
lookup facility at
- In the Search CTAN For a File box, enter custom-bib
- Press the Submit Query button
- There will probably be several responses. You want the one marked
- To the right of this text is an option to get the entire directory as a
.zip file. Click on it, and save the file to disk.
3 Installing custom-bib
You can install the package anywhere in your SWP LaTeX tree, ie in any
subdirectory under swp-dir\tcitex\tex\latex , where swp-dir is your
top-level SWP directory, typically something like c:\swp35 or c:\sw30. However,
the standard location is in the contrib\supported tree, so I suggest you install
(It’s a long way down, but that is the standard place). I’ll refer to this as your
custom-bib directory. So now unpack all the files to your chosen location. If you
use WinZip and want the standard location, type
into the Extract to dialog box. Click All files, make sure that Use Folder Names is
checked, and then click the Extract button.
4 Setting up custom-bib
You now need to create the custom-bib system, and you do this using the
stand-alone TrueTeX formatter. Here’s how:
- Start the formatter by clicking on Start -> Programs -> Scientific
Workplace -> TrueTeX Formatter.
- The formatter starts, and you get the Open TeX File dialog.
- In the File Name field type *.ins and hit the Return key
- Now navigate to your custom-bib directory.
- Select makebst.ins
- Click Open. The formatter runs briefly.
- Start the formatter again, and this time (you will still be in the
custom-bib directory) type merlin.mbs into the File Name field, and click
Open. The formatter again runs briefly.
- Open the Formatter once more. This time merlin.mbs will already be
displayed in the File Name dialog, so just click Open. The formatter runs
again, and you’ve now created the documentation, merlin.dvi.
Before you use the system you should look at (and probably print) the
documentation file, to get some idea of what the package can do, and the way it
is organized. You can do this in either of two ways, using the stand-alone
- Click Start -> Programs -> Scientific Workplace -> TrueTeX Previewer.
When the Previewer starts, click File -> Open and navigate to
your custom-bib directory, and open merlin.dvi.
- Use the Windows Explorer to go your custom-bib directory, then
double-click on merlin.dvi. This should start the Previewer and
load merlin.dvi file, if SWP was correctly installed and you’ve done
nothing to alter the association it created.
5 Running custom-bib
Now that you’ve installed the system and read the documentation, you probably
want to make a .bst file for journal X. It’s a good idea to have a copy of journal
X handy, to help you decide how to answer custom-bib’s questions: remember,
you’re making an entire bibligraphy style file. Then:
- Start the stand-alone formatter by clicking on Start -> Programs ->
Scientific Workplace -> TrueTeX Formatter.
- Navigate to your custom-bib directory
- Find the file makebst.tex
- Select it, then click Open
At this point, you start a dialog with custom-bib, beginning with the question
Do you want a description of the usage (No)
The \yn asks for a response from you (though there may be no obvious prompt,
like a blinking cursor, visible on your screen), and the (No) tells you the default.
To select the default, just hit Return or type n; otherwise type Y or y. The next
question asks about the MASTER file: unless you know what you are
doing, you should probably take the default (merlin.mbs) here. This is
followed by the name of the style file you’d like to create; note that if you
give the name of an existing file, that file will be over-written without
A few questions later you will probably see something like
INTERNAL LANGUAGE SUPPORT (if no language file)
(*) English words ...
(b) Babel .....
Here the text in parentheses tells you the allowable responses, which in this
case are * for the English words option or b for Babel. Note that (*)
always indicates the default, and if you want this, just hitting Return is
equivalent to typing *. After you’ve made your selection, custom-bib prints a
message beginning You have selected telling you what it thinks you have
There’s no way to go back and correct an error, but there is a simple way of
making corrections, as we’ll see. If you really want to quit and start over, you can
simply close the formatter in the normal Windows ways, for example by hitting
The remainder of the run is a series of questions from custom-bib and
answers from you. It’s fairly straightforward; when in doubt, I recommend
accepting the default, since you can change things later.
At the end of the session, custom-bib tells you that the “batch job” has
been written to a .dbj file, whose name is the one you supplied at the
beginning of the run; and the final question is Shall I now run this batch
job?. The default is No; I recommend that you go ahead and run it by
replying y at the prompt. If you do, you will see a message that it is
generating your .bst file; and the TrueTeX formatter closes. You’re
If you elect not to run the job at the end of the question-and-answer session,
you need to run it yourself. To do this:
- Start the TrueTeX formatter as before.
- Navigate to your custom-bib directory.
- In the formatter’s File Name field, type *.dbj and hit Return. You see
a list of .dbj files in the directory.
- Select the one you want to process and hit Open. The formatter runs,
processes the file, and closes. As before, the result is the new .bst file.
Note that the “batch job” referred to here is not a batch file in the DOS (.bat)
sense: it is a file which must be processed by the LaTeX docstrip utility. This is
what happens when you run the formatter.
6 Using your custom-bib file with SWP
The custom-bib package creates a standard BibTeX style file with extension
.bst. To make it available to SWP, all you need to do is copy it to the directory
where the system stores the rest of these files, typically swp-dir\bibtex\bst.
SWP will recognize it the next time you need to insert a bibliography. Note, for
the reason explained in the next section, you probably do not want to move the
file (which implies deleting it from the original directory): a copy is what you
want to place in your SWP directory.
7 Fixing errors
Chances are, when you typeset with your new .bst file, you’ll realize
that you made a few mistakes in your selections. You could go back and
re-run the entire question-and-answer session, but there’s often an easier
The .dbj file which was created by custom-bib contains not only a complete
record of your responses but also a full list of the options presented to you.
This file is a plain ASCII file; if you look through it you’ll see that it
contains the questions themselves: these are the lines which begin with
material in CAPITAL LETTERS. The answers follow, and their structure is very
- A non-selected answer will have a LaTeX comment character (%) in
- The answer you actually gave will have no comment character there.
So all you have to do to correct the .bst file is
- Open the .dbj file in a text editor. (NB: not in a word-processor, and
not in SWP).
- Comment out the wrong responses you made by putting a % in column
1. It is vital that it appear in the first column, or else the docstrip
system will not process it correctly.
- Uncomment the right ones by erasing the column-1 comment.
- Save the .dbj file and re-run it through the TrueTeX formatter, just
as if you had told the system not to run the batch job at the end of
the original session (see the end of section 5).
Important: manual editing like this is appropriate only when you made a wrong
“independent” choice. For example, I wouldn’t recommend it if you if you want
to make a fundamental change, like changing from Numerical to Author-Year
citations, since this choice enables several sub-options. The file itself usually
provides a clue to what depends on what; for example one line is ORDERING OF
REFERENCES (if author-year citations)which says that this option is
presented to you only if you previously selected the author-year system. I’d
restrict my fix-ups to questions which do not depend on a prior answer. But
there’s no harm in experimenting, as long as you make a copy of the original file
Alternatively, since you now understand the structure of a .dbj file, you print
it out (though it’s about 500 lines long) and use the print-out as a guide to what
you said before when you repeat the entire session.
Good luck! Let me know if you found this useful, and also if you have corrections,
or suggestions for improvements.