[TxMt] Including .bib files in Latex

[Charilaos Skiadas]

Hi Kjell,

Since you are new to LaTeX, I'll first explain a couple of things on  
how compiling LaTeX works, and hopefully someone more knowledgeable  
can correct me.

You of course already know the principal player, the .tex file, where  
all your LaTeX code works. When you call the Typeset command, it runs  
on the background a command line tool, which is typically "pdflatex",  
but it could be "latex" or a host of other programs, but let's keep  
it simple. For the purposes of this discussion, we care about a file  
called .aux. This is the "auxilliary" file, where LaTeX keeps  
information it needs as it moves on. For instance if you set a label  
at some point in your text, via \label, that information is stored in  
that file. Then later on in the run LaTeX can look for that label in  
that .aux file whenever you ask it to via something like \ref.

Now, LaTeX does a single pass through the document, meaning that if  
you make a reference to a label that is created further down, LaTeX  
doesn't know about it yet, but it will know about it once it is done  
with the entire file, and that information is kept in this .aux file.  
The second time that you run LaTeX, it now can find the information  
in this aux file, since it's stored it there. This is how LaTeX deals  
with future references. One needs typically more than one runs to get  
it right.

Which brings us to the mechanism for dealing with .bib files.  
The .bib file is a separate file keeping your bibliographies, and I  
agree that BibDesk is a wonderful program to use for handling that  
file (kudos to the developers). In fact, our "insert citation ..."  
command might break if the bib file is not saved in the same format  
that BibDesk saves it in, so I would strongly encourage you to  
continue using it.

Now, LaTeX doesn't know anything about this .bib file. It has a \cite  
command that looks for "citations", and its way of dealing with  
citations is by \bibitem entries later on in the file. This works  
exactly like the \ref-\label pairs above.

Now it is really ugly to create \bibitem entries manually, and much  
harder to maintain, and that's where BibTeX and the .bib file come  
in. In the .tex document you would have a command like \bibliography 
{filename}, which takes care of the task of creating those \bibitem  
entries for us. But the problem remains how to get the information  
out of  the .bib file and into the .aux file, where \cite can get  
hold of it. So what happens when you run LaTeX is that it stores in  
the .aux file the fact that it needs the citekeys referred to by the  
\cite commands. Then you need to run BibTeX, which reads that .aux  
file, finds those citekeys in the appropriate .bib file that you've  
told it about via the \bibliography command, and then adds the  
information from those citekeys in the form of \bibitem commands in  
a .bbl file. When you now run LaTeX again, it finds those \bibitems  
and adds them to the resulting pdf file as well as to the .aux file.  
But this happens at the end of the document, so all the \cite  
commands previously don't know about it yet, so you need yet another  
LaTeX run to get those right.

So overall we have:

latex/pdflatex
bibtex
latex
latex



And all this brings us to the suggestion on that web page, which is  
probably not the right place to look for it. If you read the LaTeX  
help (Bundles -> LaTeX -> Help), you will find a section about using  
latexmk.pl. This is a perl script that takes care of all the above,  
only doing it if it is necessary, and more that I did not mention  
(namely indexes). If you follow the instructions about enabling it  
there, then all you have to do is use the standard Typeset command,  
and it will do all the necessary BibTeX work for you.

Otherwise I would suggest simply to run the BibTeX command whenever  
you feel the need to, i.e. whenever new citations have been added to  
the text, and just the compile command as it currently stands,  
instead of always doing the four steps described above (which is not  
always needed, for instance if nothing has changed in the bib file).  
Incidentally, (always performing the four steps described above is  
what the script you linked to does, so you end up typesetting three  
times each time, when you could most of the time have typeset only  
once).

Ok hoping this was not extremely long, I know it was too long. Let me  
know if you have problems using latexmk.pl

Welcome to both TextMate and LaTeX!

Haris Skiadas
Department of Mathematics and Computer Science
Hanover College


On Mar 8, 2007, at 10:01 AM, Refsvik Kjell Are wrote:

> Hi,
>
> Being new to both TextMate and Latex, I find myself in the middle  
> of a fairly steep learning curve, in addition to starting as a  
> graduate student.
>
> This is my setup: http://home.online.no/~refsvik/TextMate_Latex.jpg
>
> ...and as I am using Mac OS X, I have found that BibDesk is a  
> splendid way of collecting and maintaining bibliography and  
> publications.
>
> Compiling my main.tex works out fairly ok (with a few warnings),  
> tying together most of my files, but what lacks is the Bibliography/ 
> References entry. There is simply no Bibliography entry at all in  
> the final .pdf file, and the compiler is telling me this:
>
> Typesetting: ./4_methodology.tex
>  LaTeX Warning: Citation `Jones:1992' on page 4 undefined on input  
> line 5.
>
>
> Trying to understand this, I have had a look at this:
> http://article.gmane.org/gmane.editors.textmate.general/8789/ 
> match=bibtex
>
> ...but still struggle to understand the following:
>
> 1. Do the "Bibtex full run" need to be set up for every single  
> latex project in any way?
>
> 2. What does happen to my .bib (bibtex) file in this process? How  
> is a bibtex file compiled (if that is the correct term) and is it  
> converted to latex in some way?
>
> I would be very grateful if someone could post a small recipe on  
> the total amount of things to set/do in order to get this to work:
>
> 1. The appropriate actions in the bundle editor
> 2. Setting environment variables accoring to what is needed in the  
> "Run Bibtex copy" command
>
> Best regards,
>
> Kjell Are Refsvik
> Norway