\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|| 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}