Back to Computer Support     Back to PAV Home Page     Email to PAV    


Getting Started with custom-bib:
An introduction for for SWP users

Philip A. Viton

August 25, 2000

Contents

1 Introduction

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 setup.

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

http://www.ctan.org/search/

then:

  • 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

    tex-archive/macros/latex/contrib/supported/custom-bib
  • 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 to

swp-dir\tcitex\tex\latex\contrib\supported\custom-bib

(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

swp-dir\tcitex\tex\latex\contrib\supported\

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 TrueTeX previewer:

  • 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)
 \yn

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 warning.

A few questions later you will probably see something like

 INTERNAL LANGUAGE SUPPORT (if no language file)
 (*) English words ...
 (b) Babel .....
 
 Select:\ans=

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 chosen.

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 Alt+F4.

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 done.

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 way.

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 simple:

  • A non-selected answer will have a LaTeX comment character (%) in column 1.
  • 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 first.

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.

8 Conclusion

Good luck! Let me know if you found this useful, and also if you have corrections, or suggestions for improvements.