path: root/biblio/bibtex/ms-dos/kempson/btxguide.tex

\documentstyle[11pt,draft]{article}

%
%-----------------------------------------------------------------------
%	SET UP THE PAGE LAYOUT FOR A4 PAPER
%-----------------------------------------------------------------------
\topmargin 0 pt
\textheight 46\baselineskip
\advance\textheight by \topskip
\oddsidemargin 0in
\textwidth 6.3 in 
\def\textfraction{0.1}
\def\floatpagefraction{0.7}
%
%-----------------------------------------------------------------------
%	DEFINE SOME USEFUL MACROS
%-----------------------------------------------------------------------
\newcommand{\BT}{{\rm B\kern.05em{\sc i\kern-.025em b}\kern-.08em
    T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}
\newcommand{\TC}{Turbo C}
\newcommand{\VV}{{\tt VAX/VMS}}
\newcommand{\UX}{{\tt UNIX}}
\newcommand{\PSCL}{{\tt PASCAL}}
\newcommand{\WEB}{{\tt WEB}}
\newcommand{\WIIC}{{\tt WEB2C}}
\newcommand{\FTN}{{\tt FORTRAN}}
\newcommand{\DOS}{{\tt MS-DOS}}
\newcommand{\us}{{\tt \char '137}}		% a real underscore in \tt font
\newcommand{\bs}{\char '134}			% a backslash in \tt font
\let\_=\us					% map \_ -> {\tt \us}
\title{An Implementation of \BT{} for \DOS{}}
\author{Niel Kempson}
\date{19 June 1989}

\begin{document}
\maketitle
\tableofcontents
\listoftables
{\def\thepage{\mbox{}}\clearpage}
\pagenumbering{arabic}
%
%-----------------------------------------------------------------------
%	INTRODUCTION
%-----------------------------------------------------------------------
\section{Introduction}
This document describes an implementation of \BT{} for the IBM 
PC running the \DOS{} operating system. It does not describe the creation of
bibliographic databases and their use by \LaTeX{}; this is covered in detail
in references~\cite{latexbook,btxdoc,btxhak}.

%-----------------------------------------------------------------------
\subsection{Background}
Over the last year, I have seen numerous requests (including my own) for
a public domain \DOS{} implementation of \BT{} v0.99, but no
responses.\footnote{Arbortext provide an implementation of \BT{} v0.99
as part of their \LaTeX{} package for the IBM  PC. This implementation
is, of course, copyrighted and costs money.}  I needed such a version
for the preparation of my PhD thesis, so I decided to produce one
myself. 

I have never used \PSCL{} and I don't have a \PSCL{} compiler for the IBM
PC, so a \WEB{} change file was not a practical  proposition.  I do have
some experience of C and a C compiler, so I decided to translate the
original \WEB{} source of \BT{} into C.\footnote{I'm a \FTN{} man really,
but translating \BT{} into \FTN{} didn't sound like a very good idea.}
The target compiler is Borland Turbo C v2.0, which is cheap, draft ANSI
compatible and in my possession.

Initially, I tried to use Tim Morgan's excellent \WIIC{} system which 
translates the \PSCL{} produced from the \WEB{} into C.  A test translation 
was soon compiled and tested on a Sun 3/50 with no problems whatsoever;
porting the C source to \DOS{} was rather more difficult.  Like the \PSCL{} 
code produced by most \WEB{} programs, the C code is rather monolithic and 
is greatly dependent on a large number of global variables.

\TC{} is restricted by the limitations of \DOS{} and the segmented 
architecture of the Intel 8086 family; arrays must normally be less than 
64kB in size, as must areas of common (global) variables.  After many 
iterations, the code was finally split up into enough small sections to 
allow compilation and linking, but the program crashed the operating system!

Enough was enough, I decided to start again with a manual translation of the
\WEB{} source into C.  The code is designed to be compiled with the \TC{} 
compiler and run under the \DOS{} operating system, but conditional 
compilation switches allow the code to be compiled and run on a \VV{} 
system. The \VV{} implementation allows me to test my version against the
proven \VV{} \BT{} \WEB{} implementation and to use the excellent debugging
facilities available under \VV{}.\footnote{The large memory requirements of
\BT{} mean that after loading the \TC{} debugger, there isn't enough free 
memory to load and run \BT{}.}


%-----------------------------------------------------------------------

\subsection{Acknowledgements}
\BT{} was created by Oren Patashnik in consultation with Leslie Lamport.  I 
have indexed my C code to the sections of his original \WEB{} source, and 
have made verbatim copies of most of the comments therein.  If this version 
of \BT{} doesn't work, it will be my fault since the version I copied 
{\em does \/} work.  Oren Patashnik has also provided some extra
documentation for \BT{} users~\cite{btxdoc,btxhak}; the \LaTeX{} sources
are included in this distribution.

Tim Morgan should be congratulated on creating the excellent \WIIC{}
system which is a real boon for \UX{} systems with grotty \PSCL{}
compilers. It's a shame that \DOS{} is too primitive to cope with large
programs. 

Thanks to PKware for creating the  \verb|ZIP| archiving utility which is used
to pack the files in this distribution.

Finally, my thanks to the people who volunteered to test my first version 
of \BT{}, especially Tim Hoverd \verb|<tim%uucp.logcam@uk.ac.ukc>| who
discovered a bug!

%-----------------------------------------------------------------------

\subsection{System requirements}
An IBM PC or compatible with at least 384kB of memory running \DOS{} or
\verb|PC-DOS| version 3.0 or later.

\subsubsection{Free Memory}\label{subsubsec:free-memory}
Before the program is run, there should be at least 242kB of free
memory. This can be checked with the \DOS{} program \verb|CHKDSK|. If 
\verb|CHKDSK| reports less than 248,000 free bytes of memory, \BT{} will
fail with one of the messages below:

\begin{verbatim}
    Fatal error: Couldn't allocate xxxxxx bytes for array `aaaaaa'

    Fatal error: Insufficient memory to allocate dynamically sized arrays.
\end{verbatim}

\noindent where \verb|`xxxxxx'| is a decimal number and \verb|`aaaaaa'| is 
the name of one of \BT{}'s work arrays.

Although \BT{} will run with only 242kB of free memory, its capacity will
be severely limited if there is less than 287kB free, and a warning message
will be issued of the form:

\begin{verbatim}
    Warning: Memory limitations have restricted BibTeX's processing capability.
             (MAX_CITES = xxxx, MAX_ENT_STRS = xxxx, MAX_FIELDS = xxxxx)
\end{verbatim}
See section~\ref{subsubsec:dynmem} for an explanation of the message.

\subsubsection{Disk Space}
To install \BT{}, at least 300kB of free disk space is permanently required,
with up to 1MB required for installation.  If \BT{} is to be built from
source code, 1MB will be required permanently, and up to 2.5MB required for
installation.

\subsubsection{C Compiler}
This implementation of \BT{} was developed using the Borland \TC{} v2.0 
compiler.  The compiler is only required if you wish to build \BT{} from the
source code.  The code should be portable to other ANSI C compilers 
({\em e.g.\/} Microsoft C v5) with only minor changes.  If you do port this 
implementation of \BT{} to another \DOS{} C compiler, please let me know so 
that I can include the code modifications in the distribution.  My contact 
address is given in section~\ref{sec:contact-address}.

%-----------------------------------------------------------------------

\subsection{Files distributed}
This implementation of \BT{} is distributed as two \verb|ZIP| archives,
namely:

\begin{tabular}{lp{4.8in}}
 & \\
{\tt BIBTEX.ZIP} & All you need to get \BT{} up and running.  Contains 
		    the \BT{} program, style files and documentation. \\
{\tt SOURCES.ZIP} & The source code for \BT{}. \\
 & \\
\end{tabular}

\noindent To extract the files from the archive, you need the program
\verb|PKUNZIP|.

%
%-----------------------------------------------------------------------
%	USING BIBTEX
%-----------------------------------------------------------------------
\section{Using \BT{}}


\subsection{Invoking \BT{}}\label{subsec:invoking}
The format of the \BT{} command is:\footnote{{\tt MS-DOS>} is used to 
represent the \DOS{} prompt string.}

\begin{verbatim}
    MS-DOS> BIBTEX [aux-file]
\end{verbatim}
where the optional parameter \verb|aux-file| is the name of the \verb|AUX| 
file {\em without\/} the \verb|AUX| extension added.  If \verb|aux-file| is 
not specified, \BT{} will prompt for it:

\begin{verbatim}
    MS-DOS> BIBTEX
    This is BibTeX version 0.99c (MS-DOS Turbo C Release 1.00, 14 June 1989)
    Please type input file name (no extension)--
\end{verbatim}
Assuming that \BT{} is invoked with the command:

\begin{verbatim}
    MS-DOS> BIBTEX btxdoc
\end{verbatim}

\noindent \BT{} will read \verb|btxdoc.aux| and, if all goes well, will
create 2 new files:

\begin{tabular}{lp{4.8in}}
 & \\
{\tt btxdoc.bbl}    & the formatted bibliography information generated by
			\BT{} and read by \LaTeX's \verb|\bibliography| 
			command. \\
{\tt btxdoc.blg}    & \BT's log file containing a transcript of everything 
		 	written to the terminal during the \BT{} run. \\
& \\
\end{tabular}

\noindent This implementation of \BT{} should then behave just like
other versions of \BT{}! 

\subsection{Features of this implementation}
This implementation attempts to emulate as closely as possible the original  
\WEB{} source so that subsequent changes to the \BT{} \WEB{} source can be 
implemented as readily as possible.  Features of this implementation that 
should be noted are listed below.

%-----------------------------------------------------------------------

\subsubsection{Output Files}
\BT{} creates the (\verb|BBL| and \verb|BLG|) output files by appending the
appropriate extension to the \verb|aux-file| command line argument.  If you
tell \BT{} to process a file in the current default directory, the output
files will be there too.  The command:

\begin{verbatim}
    MS-DOS> BIBTEX btxdoc
\end{verbatim}
will create \verb|btxdoc.bbl| and \verb|btxdoc.blg| in the current
default directory. If, however, you specify an explicit file path for the
input file, for example with the command:

\begin{verbatim}
    MS-DOS> BIBTEX \latex\report\btxdoc
\end{verbatim}
the output files will be \verb|\latex\report\btxdoc.bbl| and
\verb|\latex\report\btxdoc.blg|. I consider this to be bad behaviour, in
that output files should always be written to the current default directory,
but it has been preserved because I wanted to mimic the \WEB{} source as
closely as possible.

%-----------------------------------------------------------------------

\subsubsection{\DOS{} Environment Variables}\label{subsubsec:dos-env-vars}
\BT{} normally requires 3 types of input files, each of which may be
located in a different area of your system.  They are:


\begin{tabular}{lp{5.1in}}
 & \\
{\tt AUX} files	&    	\LaTeX{} output which is processed by \BT{}. These
			files are normally in the current default
			directory. \\
{\tt BIB} files	&   	Your \BT{} reference databases used by \BT{} to 
			resolve the \verb|\cite| command references in your 
			\LaTeX{} source file.  These files are often kept in 
			a separate directory as they are common to many 
			documents. \\
{\tt BST} files	&	The \BT{} style files that tell \BT{} how to 
			format the citations. These files are often kept with 
			the \LaTeX{} style files. \\
 & \\
\end{tabular}


\noindent When \BT{} tries to open an input file and fails, the string
specified by an appropriate \DOS{} environment variable is prepended to the
file name and the file opening retried. The environment variables supported
are:


\begin{tabular}{lp{4.8in}}
 & \\
{\tt TEXINPUTS}		& 	Used to locate {\tt BST} files \\
{\tt TEXBIB}		& 	Used to locate {\tt BIB} files \\
 & \\
\end{tabular}

\noindent
The value of these environment variables must be suitable for prepending to
a file name  ({\em i.e.\/} it must contain only one path, not a list of
paths separated by semicolons). An example of setting these
environment variables for use by \BT{} is:

\begin{verbatim}
    MS-DOS> SET TEXINPUTS=c:\tex\inputs
    MS-DOS> SET TEXBIB=d:\latex\bibtex\
\end{verbatim}
It does not matter whether you specify a trailing backslash after the path
element.

If, for example, the environment variables had been set as above and the
\verb|alpha| bibliography style had been specified, \BT{} would attempt to
open \verb|alpha.bst| and if that failed, the file 
\verb|c:\tex\inputs\alpha.bst| would be tried.

%-----------------------------------------------------------------------

\subsubsection{Dynamic Memory Allocation}\label{subsubsec:dynmem}
The \WEB{} source of \BT{} declares many large arrays which are used to hold
the information contained in the style and bibliography database files.  The
total storage required by these arrays considerable, with one array of
nearly 300kB.

Under virtual memory operating systems ({\em e.g.\/} \UX, \VV), there is not
normally a problem allocating memory; the array sizes can be predetermined
and memory allocated statically by the compiler.

If the array sizes were predetermined and allocated by the compiler (as in 
the \WEB{} source), \BT{}'s capacity would have to be limited to support IBM
PCs with limited memory, or maximized and support only IBM PCs with 
sufficient memory installed.  An alternative would be to produce several 
versions of \BT{} for different memory sizes.

I want \BT{} to be usable by as many PC users as possible, so at 
startup, \BT{} determines how much memory is available and adjusts its 
processing capacity accordingly.  The algorithm used is arbitrary, adjusting
the size of the following constants declared in the \WEB{} source of \BT{}:

\begin{tabular}{lp{4.7in}}
 & \\
{\tt MAX\_CITES} & the maximum number of {\tt \bs cite} commands allowed in 
		   the \LaTeX{} source.\\
{\tt MAX\_ENT\_STRS} & the maximum total number of string fields allowed in the 
		       bibliographic database(s).\\
{\tt MAX\_FIELDS} & the maximum total number of fields allowed in the 
		    bibliographic database(s).
\end{tabular}

\noindent The size of these arrays is tabulated against the free memory
available before running \BT{}:

\begin{center}
\begin{tabular}{|c|r|r|r|}
\hline
{\bf Free Memory} & {\tt MAX\_CITES} & {\tt MAX\_ENT\_STRS} & 
			{\tt MAX\_FIELDS}\\
\hline
242kB &   0\hspace*{1.5em} &     0\hspace*{1.5em} &      0\hspace*{1.2em} \\
250kB &  17\hspace*{1.5em} &    68\hspace*{1.5em} &    391\hspace*{1.2em} \\
287kB & 100\hspace*{1.5em} &   400\hspace*{1.5em} &  2,300\hspace*{1.2em} \\
300kB & 128\hspace*{1.5em} &   512\hspace*{1.5em} &  2,944\hspace*{1.2em} \\
350kB & 240\hspace*{1.5em} &   960\hspace*{1.5em} &  5,520\hspace*{1.2em} \\
400kB & 352\hspace*{1.5em} & 1,408\hspace*{1.5em} &  8,096\hspace*{1.2em} \\
450kB & 464\hspace*{1.5em} & 1,856\hspace*{1.5em} & 10,672\hspace*{1.2em} \\
500kB & 576\hspace*{1.5em} & 2,304\hspace*{1.5em} & 13,248\hspace*{1.2em} \\
550kB & 688\hspace*{1.5em} & 2,752\hspace*{1.5em} & 15,824\hspace*{1.2em} \\
577kB & 750\hspace*{1.5em} & 3,000\hspace*{1.5em} & 17,250\hspace*{1.2em} \\
\hline
\end{tabular}
\end{center}

\noindent \BT{} will refuse to run if the free memory available is less
than 242kB, and will issue warnings if the calculated value of
\verb|MAX_CITES| is less than 100.  The warning message will be of the form:

\begin{verbatim}
    Warning: Memory limitations have restricted BibTeX's processing capability.
             (MAX_CITES = xxxx, MAX_ENT_STRS = xxxx, MAX_FIELDS = xxxxx)
\end{verbatim}
If sufficient memory is available ({\em e.g.\/} when running 
under certain \DOS{} `extenders'), \BT{} will set the array 
sizes to those in the \WEB{} source, {\em i.e.\/} \verb|MAX_CITES|=750, 
\verb|MAX_ENT_STRS|=3000 and \verb|MAX_FIELDS|=17250.


%
%-----------------------------------------------------------------------
%	INSTALLING BIBTEX
%-----------------------------------------------------------------------
\section{Installing and Testing \BT{}}

%-----------------------------------------------------------------------

\begin{table}[htbp]
\begin{tabular}{|l|p{5in}|}
\hline
{\bf File} & {\bf Description} \\
\hline
{\tt BIBTEX.EXE}& the \BT{} program \\
{\tt ABBRV.BST} & the {\tt abbrv} \BT{} bibliography style \\
{\tt ALPHA.BST} & the {\tt alpha} \BT{} bibliography style \\
{\tt PLAIN.BST} & the {\tt plain} \BT{} bibliography style \\
{\tt UNSRT.BST} & the {\tt unsrt} \BT{} bibliography style \\
{\tt BTXDOC.TEX}& the \LaTeX{} source for~\cite{btxdoc} \\
{\tt BTXHAK.TEX}& the \LaTeX{} source for~\cite{btxhak}\\
{\tt BTXDOC.BIB}& the \BT{} database used by ~\cite{btxdoc} and 
		   \cite{btxhak}\\
{\tt BTXAMPL.BIB}& the \LaTeX{}  of a test document which references every 
		   entry in the {\tt XAMPL.BIB} database\\
{\tt XAMPL.BIB}	& an example \BT{} database which illustrates many of the 
		  entry types allowed\\
{\tt BTXAMPL.XUA}& a reference version of the {\tt BTXAMPL.AUX} file which is 
		  used for testing \BT{}\\
{\tt BTXAMPL.LBB}& a reference version of the {\tt BTXAMPL.BBL} file which is 
		  used for testing \BT{}\\
{\tt BTXDOC.XUA}& a reference version of the {\tt BTXDOC.AUX} file which is 
		  used for testing \BT{}\\
{\tt BTXDOC.LBB}& a reference version of the {\tt BTXDOC.BBL} file which is 
		  used for testing \BT{}\\
{\tt BTXHAK.XUA}& a reference version of the {\tt BTXHAK.AUX} file which is 
		  used for testing \BT{}\\
{\tt BTXHAK.LBB}& a reference version of the {\tt BTXHAK.BBL} file which is 
		  used for testing \BT{}\\
\hline
\end{tabular}
\caption{Contents of the {\tt BIBTEX.ZIP} archive}%
\label{table:bibtex}
\end{table}

%------------------------------------------------------------------------

\subsection{Files required and where to put them}\label{subsec:where}
All of the files required to get \BT{} up and running are contained in the
archive \verb|BIBTEX.ZIP| and are listed in
table~\ref{table:bibtex}. Use \verb|PKUNZIP| to unpack the archive
\verb|BIBTEX.ZIP|.  It is recommended that you create a temporary directory
for this, then once installation is complete, the directory and its contents
can be safely deleted.

On my system, all \TeX{} related programs are kept in the directory
\verb|c:\tex\bin|, style and macro files in \verb|c:\tex\inputs|, the
common bibliographical databases in \verb|d:\latex\bibtex| and the \BT{}
documentation in \verb|c:\tex\doc|.  Assuming that the archive
\verb|BIBTEX.ZIP| is on a floppy disk in drive \verb|A:|, the following
\DOS{} commands could be used to extract and install the \BT{} files and then
set the \DOS{} environment variables appropriately:

\begin{verbatim}
    MS-DOS> MD \BTXTMP
    MS-DOS> CD \BTXTMP
    MS-DOS> PKUNZIP A:BIBTEX

    MS-DOS> COPY *.exe  c:\tex\bin
    MS-DOS> COPY *.bst  c:\tex\inputs
    MS-DOS> COPY *.bib  d:\latex\bibtex
    MS-DOS> COPY btx*.* c:\tex\doc

    MS-DOS> CD \
    MS-DOS> DEL \BTXTMP
    MS-DOS> RD \BTXTMP

    MS-DOS> SET PATH=c:\dos;c:\bin;c:\util;c:\tex\bin
    MS-DOS> SET TEXINPUTS=c:\tex\inputs
    MS-DOS> SET TEXBIB=d:\latex\bibtex
\end{verbatim}


%-----------------------------------------------------------------------

\subsection{Building \BT{} from sources}
Use \verb|PKUNZIP| to unpack the archive \verb|SOURCES.ZIP|; this will create 
the \BT{} source files listed in table~\ref{table:sources}.  The source code
has been split into many parts to ensure that each module is less than 64kB in
size and is thus able to be compiled  and edited in the \TC{} integrated
development environment.

To generate the \BT{} program \verb|BIBTEX.EXE|, simply use the \verb|MAKE| 
program supplied with \TC{} by executing the command:

\begin{verbatim}
    MS-DOS> MAKE bibtex
\end{verbatim}
The executable program \verb|BIBTEX.EXE|  will be created in the current 
working directory.

\begin{table}[htbp]
\begin{tabular}{|l|p{5in}|}
\hline
{\bf File} & {\bf Description} \\
\hline
{\tt MAKEFILE}		& \TC{} makefile for building \BT{}. \\
{\tt BIBTEX.PRJ} 	& \TC{} project file for building \BT{} from
			  within the integrated development environment. \\
{\tt TCCONFIG.TC} 	& \TC{} configuration file for the integrated 
		   	  development environment. \\
 & \hfill \\
{\tt BIBTEX.H} 		& header file defining the macros used in the \BT{} 
			  \WEB{} source. \\
{\tt DATATYPE.H} 	& header file defining the data types used. \\
{\tt EXTVARS.H} 	& header file declaring the external global 
			  variables. \\
{\tt GBLPROCS.H} 	& header file containing declaring all of the global
			  functions used. \\
{\tt GBLVARS.H} 	& header file declaring and allocating space for 
			  global variables. \\
{\tt SYSDEP.H} 		& header file declaring system dependent items. \\
 & \hfill \\
{\tt BIBTEX.C} 		& the main module of \BT{} containing system 
			  dependent functions. \\
{\tt PART1.C} 		& {\raggedright
			  source module containing \BT{} functions from \\
			  {\tt aux\_err\_stuff\_after\_right\_brace}
			  to {\tt bst\_integers\_command}.} \\
{\tt PART2.C} 		& {\raggedright
			  source module containing \BT{} functions from
			  {\tt build\_in} to \\
			  {\tt enough\_text\_chars}.} \\
{\tt PART3.C} 		& {\raggedright
			  source module containing \BT{} functions from 
			  {\tt execute\_fn} to \\
			  {\tt get\_bib\_command\_or\_entry}.} \\
{\tt PART4.C} 		& {\raggedright
			  source module containing \BT{} functions from \\
			  {\tt get\_bst\_command\_and\_process} 
			  to {\tt pop\_whole\_stack}.} \\
{\tt PART5.C} 		& {\raggedright
			  source module containing \BT{} functions from \\
			  {\tt pre\_def\_certain\_strings}
			  to {\tt scan\_balanced\_braces}.} \\
{\tt PART6.C} 		& {\raggedright 
			  source module containing \BT{} functions from
			  {\tt str\_eq\_buf} to \\
			  {\tt x\_add\_period}.} \\
{\tt PART7.C} 		& {\raggedright
			  source module containing \BT{} functions from
			  {\tt x\_change\_case} to \\
			  {\tt x\_num\_names}.} \\
{\tt PART8.C} 		& source module containing \BT{} functions from
			  {\tt x\_plus} to {\tt x\_write}. \\
\hline
\end{tabular}
\caption{Contents of the {\tt SOURCES.ZIP} archive}%
\label{table:sources}
\end{table}


%-----------------------------------------------------------------------

\subsection{Testing \BT{}}
The \LaTeX{} source file \verb|btxdoc.tex| for the \BT{} 
documentation~\cite{btxdoc} is provided as part of this distribution.  If it
is  processed with \LaTeX{} and \BT{} using the following commands:

\begin{verbatim}
    MS-DOS> LATEX btxdoc
    MS-DOS> BIBTEX btxdoc
    MS-DOS> LATEX btxdoc
    MS-DOS> LATEX btxdoc
\end{verbatim}
the files \verb|btxdoc.aux| and \verb|btxdoc.bbl| will be created (amongst 
others).  Reference versions of these files (\verb|btxdoc.xua| and 
\verb|btxdoc.lbb| respectively) are provided as part of the distribution, 
and they should be identical to the files created as a result of the above 
commands.  The files can be compared using the \DOS{} utility \verb|COMP| 
with the commands:

\begin{verbatim}
    MS-DOS> COMP btxdoc.aux btxdoc.xua
    MS-DOS> COMP btxdoc.bbl btxdoc.lbb
\end{verbatim}

\noindent\verb|COMP| should report that no differences were found.  This procedure 
should be repeated with the provided files \verb|btxhak| and \verb|btxampl|.
If, in all cases, no differences are found, you may be confident that your 
new version of \BT{} has been installed correctly.

%
%-----------------------------------------------------------------------
%	PROBLEMS
%-----------------------------------------------------------------------
\section{Problems}
If you believe that \BT{} is behaving incorrectly, I'd like to hear from you!
Before reporting a bug, I'd be grateful if you would follow a few steps to 
help isolate the problem.

A bug is usually suspected as the result of \BT{} issuing an error message 
or by the production of unexpected results.  Either of these can be 
caused by a real bug in the \BT{} implementation, or the correct behaviour 
in response to misuse.  It is assumed that you have read the \BT{} 
documentation~\cite{latexbook,btxdoc}.

%-----------------------------------------------------------------------
\subsection{Unexpected Results}
Sometimes the output generated by \BT{} is not what you expect, especially:
\begin{itemize}
  \item formatting of names and initials
  \item the sorting of the references
\end{itemize}
Check the bibliography style file, which should describe how the citations 
are supposed to be formatted.

%-----------------------------------------------------------------------
\subsection{Error Messages}
\BT{} will generate warning, error and fatal messages under several 
circumstances, including:
\begin{itemize}
  \item \BT{} refuses to run, or reports restricted processing capacity due 
	to memory limitations.  See sections~\ref{subsubsec:dynmem} 
	and~\ref{subsubsec:free-memory}.
  \item \BT{} couldn't open a file.  The offending file name is reported.  
	Check that the file exists and is in the current working directory 
	or in the directory referenced by the appropriate \DOS{} environment
	variable.  See section~\ref{subsubsec:dos-env-vars}.
  \item errors in the bibliographic database.  The offending file and line 
	number are usually identified.  Check the bibliographic database 
	against the documentation~\cite{latexbook,btxdoc}.
  \item one of \BT{}'s internal capacity limits has been exceeded. The error
	message will detail which limit has been exceeded.    See 
	section~\ref{subsubsec:dynmem}.
  \item errors in the bibliographic style file detected by \BT{}. The errors
	are characterized by the message {\tt *Please notify the bibstyle 
	designer*}.  If the style file used was provided with this 
	implementation, consider it a bug.  If you are using style files 
	from another source, note that the style file must have been 
	designed for \BT{} v0.99 or later.  Style files designed for \BT{} 
	v0.98 or earlier {\em will not\/} work with \BT{} v0.99.
  \item internal errors detected by \BT{}. These errors are characterized by
	the message {\tt *Please notify the BibTeX maintainer*}.  This is 
	definitely the result of a bug.
\end{itemize}


%-----------------------------------------------------------------------

\subsection{Bug Reports}
If you have access to another implementation of \BT{} ({\em e.g.\/} on a 
\UX{} or \VV{} system), try processing the same files with that 
implementation and compare results.  If that implementation produces 
satisfactory results where the \DOS{} implementation does not, you can be 
reasonably sure that you've found a bug.  I have tested the \DOS{} version 
against the \VV{} implementation, but there are bound to be errors which
haven't been detected.

Once you're fairly sure that this implementation of \BT{} is at fault,
I'd like to hear from you so that I can fix the problem.  To help me
diagnose the fault, please supply the following information with your bug 
report:

\begin{itemize}
  \item	a description of the problem
  \item	the {\tt AUX} and {\tt BIB} input files that caused the problem
  \item	the {\tt BBL} and {\tt BLG} output files produced by \BT{}
  \item if possible, the {\tt BBL} and {\tt BLG} output files produced by 
	another implementation of \BT{}.
\end{itemize}

\noindent Please send the bug report to me, preferably at the e-mail
address given in section~\ref{sec:contact-address} below.  Please {\em do
not\/} send bug reports to Oren Patashnik as any fault is almost bound to
be in my translation from the original \WEB{} source.
%
%-----------------------------------------------------------------------
%	CONTACT ADDRESSES
%-----------------------------------------------------------------------
\section{Contact Address}\label{sec:contact-address}
If you have any suggestions or (constructive) criticisms, I would welcome 
your comments, preferably to the e-mail address below.

\begin{tabular}{@{}ll}
 & \\
{\bf Name}	&	Niel Kempson\\
{\bf Mail} 	&	School of Electrical Engineering and Science,\\
		&	Royal Military College of Science,\\
		&	Shrivenham,\\
		&	SWINDON\\
		&	SN6 8LA\\
		&	United Kingdom \\
		& \\
{\bf Phone}	&	Swindon (0793) 785687 (UK)\\
		&	+44-793-785687        (International)\\
		& \\
{\bf E-mail}	&  
    \begin{tabular}[t]{@{}ll}
	{\tt JANET} & {\tt tex@uk.ac.cranfield.rmcs}\\
	{\tt INTERNET} & {\tt tex\%uk.ac.cranfield.rmcs@nsfnet-relay.ac.uk}\\
	{\tt BITNET/EARN} & {\tt tex\%uk.ac.cranfield.rmcs@ukacrl}\\
	{\tt UUCP} & {\tt \{mcvax|uunet|ukc\}!rmcs.cranfield.ac.uk!tex}
    \end{tabular}
\end{tabular}


%
%-----------------------------------------------------------------------
%	BIBLIOGRAPHY (Included here so that this guide can be printed 
%		      BEFORE installing BibTeX)
%-----------------------------------------------------------------------
\addcontentsline{toc}{section}{References}
\begin{thebibliography}{99}
  \bibitem{latexbook}
  Leslie Lamport.
  \newblock {\em {\LaTeX \rm:} {A} Document Preparation System}.
  \newblock Addison-Wesley, 1986.

\bibitem{btxdoc}
  Oren Patashnik.
  \newblock {{\BT ing}}.
  \newblock Documentation for general {\BT} users, 8~February 1988.
  \newblock {\bf Note:~} the \TeX{} source for this document is in the 
		file {\tt BTXDOC.TEX}

\bibitem{btxhak}
  Oren Patashnik.
  \newblock Designing {\BT} styles.
  \newblock The part of \BT's documentation that's not meant for general
    users, 8~February 1988.
  \newblock {\bf Note:~} the \TeX{} source for this document is in the 
		file {\tt BTXHAK.TEX}\end{thebibliography}

\end{document}