Customizing Bibliographic Style Files
Patrick W. Daly
This paper describes program makebst
version 4.0-beta1 from 1999/08/26∗
(including additions by Arthur Ogawa, ogawa@teleport.com)
1
Introduction
This TEX program is meant to be used together with generic bibliographic style
files to produce customized .bst files for running with BibTEX. The generic,
or master file, can be processed by docstrip with selected options to achieve the
desired bibliographic style. To this end, a docstrip batch job should be made up.
However, because of the large number of options available, an interactive, dialogue
system would be more convenient.
This program, makebst, accomplishes this goal. It defines macros to establish
such a docstrip batch job file, and to organize a menu of options. The menu information is contained, however, in the master file itself, since the two are intimately
related. Thus different master files with totally different option structures may be
accommodated.
The batch job could in fact be made up with an editor without calling makebst,
but this program does simplify the task.
Incidentally, the docstrip run can only be carried out by means of a batch job.
Running docstrip interactively inserts default pre- and postambles in the text, the
latter including an \endinput command that BibTEX will not understand.
2
The Master File
The master file is a BibTEX bibliographic style file containing alternative coding
depending on docstrip options. The options are selected when docstrip is run,
either interactively or through a batch job.
Suppose that one of the options is called xyz. Then the following alternatives are
possible:
∗ Work
on custom-bib 4.00 was supported by the American Physical Society
1
CUSTOMIZING BIBLIOGRAPHIES
2
% one line of coding
includes the single line of coding;
% one line of coding
excludes the single line;
%
several lines of coding
%
includes all the bracketed lines;
%
several lines of coding
%
excludes all the bracketed lines.
Options may be logically combined: the symbol | is a logical or, & a logical and,
! a logical not; parentheses ( and ) may be used to group options.
2.1
Using with docstrip
(The docstrip command syntax shown here is that for version 2.4 and later, released
December, 1996.)
In order to generate a true BibTEX style file with selected options from the master
file, it is necessary to run a docstrip batch job. Suppose that the master file is
named master.mbs, the resulting BibTEX style file is to be silly.bst, and the
batch job file itself is called silly.dbj. To produce this with options, say, xyz
and abc, the batch job would look something like:
\input docstrip
\preamble
This is for Journal of Silly Results
\endpreamble
\postamble
End of customized bst file
\endpostamble
\keepsilent
\askforoverwritefalse
CUSTOMIZING BIBLIOGRAPHIES
3
\generate{\file{silly.bst}{\from{master.mbs}{xyz,abc}}}
\endbatchfile
A preamble is not necessary, although it is advisable to include some statement
about the application of the bibliographic style. A postamble is vital, otherwise
the default will add \endinput at the end of the file, something that BibTEX will
not understand. The \keepsilent is optional and just suppresses docstrip output
during processing. Similarly the \askforoverwritefalse suppresses the warning
that a file of the same name is to be overwritten.
2.2
The Menu File
This program, makebst, simplifies the creation of the batch job file. To do that,
it needs information on the available options. This information must be stored in
a special format, in the master file itself. Alternatively, that information may be
extracted and stored in a file with the same root name but extension .opt. This
feature is not recommended since it can lead to inconsistencies! The format of the
menu information is illustrated below in Section 4.
In the master file, this information must be enclosed within docstrip options
% . . . % and must be ended by an \endoptions command.
It may also include any number of comments. The rest of the file must be enclosed
within % . . . % to exclude it when the menu information
is extracted with docstrip.
A sample menu in the master file to select one or none of options xyz or zyx
would look thus:
%
\mes{Select one of these}
\optdef{f}{xyz}{Option forword}{to do forward stuff}
\optdef{r}{zyx}{Option reverse}{to do reverse stuff}
\optdef{*}{}{None of the above}{}
\getans
\endoptions
%
%
. . . . . .
%
An explanation of these commands is to be found in Section 4.
The menu information may be extracted from the master file by means of docstrip
and stored in a file with extension .opt. If this file is present, makebst offers to
read it instead of the master file, although this is not recommended, as explained
above.
CUSTOMIZING BIBLIOGRAPHIES
3
3.1
4
The Program makebst
Installing makebst
The makebst program comes as a documented source file named makebst.dtx,
which needs to be processed by docstrip to extract the actual ‘program’ file
makebst.tex. The easiest way to do this is simply to process the installation
batch file makebst.ins with TEX or LATEX, as
tex makebst.ins
or
latex makebst.ins
There are in fact three variants of makebst that may be extracted: the basic
one lists by default only those options that have been selected; the more refined
one (and the default) lists all options offered with the rejected ones commented
out; the third version also adds more detailed comments. Even in the first two
versions, the user will be asked interactively if s/he wants the additional features
of the others.
One can select the variant by editing makebst.ins.
Another choice that can be made is whether the .dbj files are to conform to
docstrip version 2.4 syntax or not. By default, makebst.ins tests the current
version and automatically configures makebst.tex to write the correct syntax.
This too may be overridden by editing makebst.ins. (Note that the older syntax
is still understood by the newer version of docstrip.)
Reminder: the older syntax requires \def\batchfile{hfilenamei} as the first line
in a docstrip batch job, where filename is the name of the batch file itself. The
newer syntax does not need this line, but requires \endbatchfile at the very end
instead. The advantage of the new syntax is that one can edit and rename such
a file without having to change its name in the first line. The old syntax leads to
great frustration if one forgets to change filename.
Another difference in the syntaxes (actually introduced in version 2.3 in June,
1996) is the use of the command \generate instead of \generateFile. Its advantage is that it permits multiple files to be extracted in one pass, something
that is not exploited at all by makebst.
3.2
Running makebst
This is actually a TEX program, although it will also run under LATEX. In that
sense, it is like docstrip itself. Thus run the program with (something like)
tex makebst
or
latex makebst
CUSTOMIZING BIBLIOGRAPHIES
5
The program first asks for the name of the master file. This is the file containing all
possible bibliographic style commands, with docstrip options for selective output.
A default name is offered, as well as a default extension (.mbs).
Next, the program asks for the name of the output file, the .bst file. The extension
here is optional, defaulting to .bst. This name also determines the name of the
batch job file, which will have the same root name with the extension .dbj, for
the docstrip batch job.
The actual interrogation then begins. All the information for the menus is contained in the master bibliographic style file. The reason for this is that the menu
information must conform to the available options in the master file, so it makes
sense that one file should contain both. The master file is only read up to the
\endoptions command.
Finally, the batch job file is closed, and the user is asked if it should be run. If he
does not take up this offer, or if he later edits the batch job, then it may be run
manually with (something like)
tex bstname.dbj
4
The Menu Information
The set of questions in the interrogation must fit the available options in the
master file. For this reason, the menu information is contained in the master file
itself. The program makebst supplies the macros that are used in the menu file
to simplify writing and processing menu information.
\mes
To print a message to the terminal, use \mes{htexti}. A new line may be forced
within text by means of ^^J.
\ask
To interrogate the user for a response, use \ask{\com}{htexti}, which writes text
to the terminal, and puts the response in the command \com.
\optdef
Almost all interrogations will consist of a list of mutually exclusive options, one
of which is the default. For each item in the list, one must specify the keyboard
response that is to select it, the actual name of the docstrip option that realizes
it, and two pieces of explanatory text. For example,
\optdef{a}{abr}{Abbreviations}{of such words}
means that abr is the true docstrip option name that is selected by typing a. The
two explanatory texts are written to the terminal immediately as part of the menu,
but only the first text is echoed when the selection is made (for confirmation) and
is also written to the batch job file (as comment).
The default option must have the response *.
A menu is written to the terminal, first with a \mes command to state the subject
matter, and then with a sequence of \optdef statements, each of which also
CUSTOMIZING BIBLIOGRAPHIES
\getans
6
writes the texts to the terminal. The response is then read in and processed with
\getans, which writes the reply to the command \ans and writes the appropriate
docstrip option to the batch job file. If the response does not correspond to any
of those in the menu list, it is set to *; if there is no * in the list, then \ans is set
to the last entry. The command \ans is still available afterwards for any extra
testing that might be needed.
An example menu appears as follows:
\mes{^^JJOURNAL VOLUME NUMBER:}
\optdef{*}{}{Volume plain}{as vol(num)}
\optdef{i}{vol-it}{Volume italic}%
{as {\string\em\space vol}(num)}
\optdef{b}{vol-bf}{Volume bold}%
{as {\string\bf\space vol}(num)}
\optdef{d}{vol-2bf}{Volume and number bold}%
{as {\string\bf\space vol(num)}}
\getans
\beginoptiongroup
Further structure for the interrogation is provided by the \beginoptiongroup
. . . \endoptiongroup sequence, which should act as a container for the \mes
. . . \optdef . . . \getans commands described above. For example:
\beginoptiongroup{JOURNAL VOLUME NUMBER:}{}
\optdef{*}{}{Volume plain}{as vol(num)}
\optdef{i}{vol-it}{Volume italic}%
{as {\string\em\space vol}(num)}
\optdef{b}{vol-bf}{Volume bold}%
{as {\string\bf\space vol}(num)}
\optdef{d}{vol-2bf}{Volume and number bold}%
{as {\string\bf\space vol(num)}}
\getans
\endoptiongroup
presents the same effect as the previous example. The virtue of the option group
is in providing a single markup for all interrogations and having a consistent
appearance in the generated file.
This feature has been added with version 4.0 of makebst.
5
More Complex Batch Jobs
Version 3.0 of makebst allows the master file to define more sophisticated batch
jobs, such as additional master files with their own options. This is made possible
because the options are not written directly in the \generate command, as in earlier versions, but to a command \MBopts. The batch file then contains something
like:
CUSTOMIZING BIBLIOGRAPHIES
7
\def\MBopts{\from{hsource.exti}{%
lines from menu session
}}
\generate{\file{houtput.exti}{\MBopts}}
Normally the lines from menu session contain just the docstrip options. However,
the master file could add other things to the definition of \MBopts, even closing
it and starting a new definition. It just has to make sure that the braces are
balanced.
\MBaskfile
A number a macros are provided, which are used by makebst itself, to simplify
making complex menus. To ask for the name of a file interactively,
\MBaskfile{hPrompting texti}(hroot.exti){hioi}\fname
may be given, where root.ext is the default name of the file, io is i (for input)
if the file must already exist, and \fname is the command that receives the file
name. The root name will be in \froot, the extension in \fext.
\wr
Text is written to the batch job file with
\wr{htexti}
Any commands in text that are to be written literally must be preceded by
\string.
\MBswitch
Since any braces in text must be balanced, something special must be done to
permit them to be printed as normal characters. The command \MBswitch accomplishes this; the parentheses ( ) replace { } as the delimiters. This should
always be given within \begingroup . . . \endgroup.
As an example, suppose the master file contains only half the coding for the .bst
file, the other half being in one of several other master files. We must prompt
for this second file, include it for its options, and make sure that \MBopts knows
about it. The following code in the master file will do this.
\MBaskfile{Name of second master file}(aa.mbs)i\xfile
\begingroup\MBswitch
\wr(\string\MBopta})
\wr(\string\from{\xfile}{\string\MBoptb}})
\wr(\string\def\string\MBopta{\pc)
\endgroup
regular menu information for first file
\begingroup\MBswitch
\wr(}\string\def\string\MBoptb{\pc)
\endgroup
\input\xfile\relax
\begingroup\MBswitch
\wr({\pc)
CUSTOMIZING BIBLIOGRAPHIES
8
\endgroup
\endoptions
The resulting .dbj file contains
\def\MBopts{\from{first.mbs}{%
\MBopta}
\from{second.mbs}{\MBoptb}}
\def\MBopta{%
first set of options
}\def\MBoptb{%
second set of options
{%
}}
\generate{\file{sample.bst}{\MBopts}}
6
Coding
This section presents and explains the actual coding of the macros. It is nested
between % and %, which are indicators to docstrip that this
coding belongs to the program file.
6.1
Preliminaries
The first thing is to open up i/o devices for communicating with the terminal and
files. (Some of this has been borrowed from docstrip.) The terminal input and
output are \ttyin and \ttyout respectively, while the output file if \outfile.
h∗programi
\newwrite\outfile
3 \newread\ttyin
4 \newread\infile
5 \newwrite\ttyout
1
2
\mes
\wr
\umes
The commands for outputting text are defined: \mes writes to the terminal, \wr
writes it argument directly to the output file, while \umes writes to the terminal
and adds its argument as a comment to the output file.
\def\mes{\immediate\write\ttyout}
\def\wr#1{\immediate\write\outfile{#1}}
8 \def\umes#1{\mes{^^J#1}\wr{\pc#1}}%
6
7
To assist inserting new lines in the middle of text, define a newline symbol.
9
\newlinechar=‘\^^J
CUSTOMIZING BIBLIOGRAPHIES
\MBswitch
9
There are times when we need to write a line of code to the output file with
unbalanced braces in that line. (They are balanced in another line.) Such lines
are written with \wr{...}. If the braces in the argument are not balanced, then
there will be trouble. To get around this, change the category codes of the braces
to ‘other’ and let parentheses take their place.
10
11
\def\MBswitch{\catcode‘\{=12 \catcode‘\}=12
\catcode‘\(=1 \catcode‘\)=2\relax}
The way to employ this is as
\begingroup\MBswitch
\wr(..{..)
\endgroup
\ask
To get a response from the terminal, use \ask. However, there are some complications here. If only carriage-return is pressed, then the response command is equal
to \par; for anything else, a typed-in text includes a trailing blank. We must test
for \par and remove the blank if it is there.
\def\defpar{\par}
\def\remblk#1 @@{#1}
14 \def\ask#1#2{\mes{#2}\read\ttyin to #1\ifx#1\defpar\def#1{}\else
15
\edef#1{\expandafter\remblk#1@@}\fi}
12
13
\getroot
\getext
To parse the name of a file into root and extension, use commands \getroot and
\getext.
16
17
18
19
\MBaskfile
\def\groot#1.#2@@{#1}
\def\getroot#1{\expandafter\groot#1.@@}
\def\gext#1.#2.#3@@{#2}
\def\getext#1{\expandafter\gext#1..@@}
Several times it is necessary to ask for a file name interactively, and maybe test if
it exists. This might even be done in the .mbs file, so provide a macro to simplify
this task. The syntax is
\MBaskfile{hPrompting texti}(hroot.exti){hioi}\fname
where root.ext is the default name for the file sought, and \fname is the command
that contains the final file name. The commands \froot and \fext will contain
the root and extensions of the file name, if they are needed for further parsing. If
io=i (for input), then the resulting file must already exist, else the macro loops
again. If root is blank, then only the extension is given as default, but a file root
name must be entered.
20
21
\def\MBaskfile#1(#2.#3)#4#5{%
\loop
CUSTOMIZING BIBLIOGRAPHIES
10
\def\ans{#2.#3}
\if!#2!
24 \if!#3!\ask{#5}{#1}\fi
25
\ask{#5}{#1 (default extension=#3)}\else
\ask{#5}{#1 (default=\ans)}
26
27 \fi
28
\ifx#5\empty \edef#5{\ans}\fi
29
\edef\froot{\getroot#5}
30
\edef\fext{\getext#5}
31
\ifx\fext\empty \def\fext{#3}\fi
32
\edef#5{\froot.\fext}
33 \if#4i
34
\def\temp{Cannot find file ‘#5’}
35
\openin\infile#5\relax
\ifeof\infile \def\ans{}\fi \closein\infile
36
37 \else
38 \def\temp{There is no default}
39 \ifx\froot\empty \def\ans{}\fi
40 \fi
41
\ifx\ans\empty \mes{*** \temp}
42 \repeat}
22
23
\pc
\pcpc
\spsp
Now for some special commands to simplify outputting % signs and double spaces
to the output file.
{\catcode‘\%=12
\gdef\pc{%}
45 \gdef\pcpc{%% }
46 }
47 \def\spsp{\space\space}
43
44
\Now
In order to date-and-time-stamp the resulting batch job file, we need macros to
produce the current date and time. (In TEX there is no \today command.)
\newcount\hours
\newcount\minutes
50 \def\SetTime{\hours=\time
51
\global\divide\hours by 60
\minutes=\hours
52
53
\multiply\minutes by 60
54
\advance\minutes by-\time
55
\global\multiply\minutes by-1 }
56 \SetTime
57 \def\now{\number\hours:\ifnum\minutes
