posts/BibTeX.mdwn

   1 [[!meta  title="BibTeX"]]
   2
   3 [BibTex][] is system (tools and file format) for managing references
   4 in [[LaTeX]] documents.  Forget about formatting your bibliography (is
   5 it “publisher (year)” or “publisher: year”?), just add entries for the
   6 works you're referencing, and drop in a `\cite{key}`.  I also use my
   7 [[entrez]] script to pull nicely detailed citations off [PubMed][] and
   8 its related databases.  Once you've added the citation to your
   9 database the first citation, you can reuse that data in any future
  10 paper just by reusing your BibTeX database.  It's wonderful.
  11
  12 Basic usage
  13 ===========
  14
  15 At some point in your LaTeX document:
  16
  17     \bibliographystyle{prsty} % Phys. Rev. style
  18
  19 other syles include `abbrv`, `alpha`, `plain`, `unsrt`, ...
  20 In your LaTeX document where you want the bibliography:
  21
  22     \bibliography{wtk} % wtk.bib is the name of the database
  23
  24 compile (using `latex` for example) with:
  25
  26     $ latex example
  27     $ bibtex example
  28     $ latex example
  29     $ latex example
  30
  31 Formatting names
  32 ================
  33
  34 There are many possible author name formats, but the least ambiguous
  35 is `von Last, Jr., First Middle`.  If the `von` is capitalized
  36 (e.g. "Emanuela Di Cola"), use `\uppercase`:
  37
  38     @String{EDCola = "{\uppercase{d}}i Cola, Emanuela"}
  39
  40 See [Tame the BeaST][TTB] for details.
  41
  42 Natbib
  43 ======
  44
  45 I don't actually use LaTeX's `\cite{key}` command as I claimed above.
  46 That works, but the [Natbib][] package adds support for other citation
  47 styles & link formats.  I actually use `\citep{key}` (parenthetical
  48 citations), `\citet{key}` (textual citations), and other more
  49 specialized Natbib commands.  That way I don't have to worry about
  50 misspelling author names or remembering “et al.” when I cite a source
  51 in the text.
  52
  53 [Natbib]: http://www.ctan.org/tex-archive/help/Catalogue/entries/natbib.html
  54
  55 Makebst
  56 =======
  57
  58 Customize bibliography with Makebst (`latex makebst`, from
  59 [custom-bib][]), makes `.bst` (bib-style) format files according to
  60 your specifications.
  61
  62 Cross-references (more like sub-references)
  63 ===========================================
  64
  65 [Don't repeat yourself][DRY]!  BibTeX lets you piggyback low level
  66 references (`@inbook`, `@inproceedings`) underneath higher level
  67 references (`@book`, `@proceedings`) without duplicationg information
  68 from the parent entry (via `crossref`).  However, this can be a bit
  69 tricky.
  70
  71 Like a number of TeX tools, BibTeX tries to accomplish as much as
  72 possible with a single pass through your data.  This makes things more
  73 memory efficient (if you really can't spare that extra MB ;), but it
  74 also makes for some odd errors.  While working on my [[thesis]], I ran
  75 into:
  76
  77     $ bibtex root
  78     …
  79     Database file #9: root.bib
  80     Warning--string name "nist:esh" is undefined
  81     --line 1175 of file root.bib
  82     A bad cross reference---entry "NIST:gumbel"
  83     …
  84
  85 The problem is due to the `@inbook` entries occuring after the `@book`
  86 they reference:
  87
  88     @book{ NIST:ESH,
  89       …
  90     }
  91
  92     @inbook{ NIST:gumbel,
  93       crossref = {NIST:ESH},
  94       …
  95     }
  96
  97 When it's reading your bibliography, BibTeX hits the `@book` entry
  98 (`NIST:ESH`), and says to itself, “Hmm, it doesn't look like anyone's
  99 referencing `NIST:ESH`.  I'll save some memory by forgetting I've seen
 100 it.”  Then when BibTeX hits the `@inbook` entry (`NIST:gumbel`), it
 101 says, “Ahh, this references `NIST:ESH`.  I'd better keep an eye out
 102 for that.”  Unfortunately, this is too late, because it's already past
 103 that entry.  BibTeX hits the end of the database without finding a
 104 (second) `NIST:ESH` definition, and complains about the missing
 105 reference.
 106
 107 The solution is just to order your `@inbooks` (and other `crossref`
 108 consumers) so they occur before the entry they reference:
 109
 110     @inbook{ NIST:gumbel,
 111       crossref = {NIST:ESH},
 112       …
 113     }
 114
 115     @book{ NIST:ESH,
 116       …
 117     }
 118
 119 Embarassingly, this information is spelled out on [Wikipedia's BibTeX
 120 page][wikipedia]:
 121
 122 > The referred entry must stand below the referring one.
 123
 124 That's the kind of thing you'll only remember after you've been bitten
 125 by it ;).  Hopefully putting the `bad cross reference` error message
 126 in the surrounding text will help the rest of you searching for
 127 solutions.
 128
 129 It looks like [Matěj Cepl][MC] (who has also
 130 [contributed][MC-rss2email] to [[rss2email]]) ran into [the same
 131 issue][lyx-2000-11-07] back in 2000.  It's a small world ;).
 132
 133 References
 134 ==========
 135
 136 There are a number of good resources to get you going:
 137
 138 * [very basic tutorial](http://cmtw.harvard.edu/Documentation/TeX/Bibtex/Example.html)
 139 * really awesome explanation of how BibTeX works: [Tame the
 140   BeaST][TTB]
 141 * [process overview](http://www.andy-roberts.net/misc/latex/latextutorial3.html)
 142 * [entry types reference](http://newton.ex.ac.uk/tex/pack/bibtex/btxdoc/node6.html)
 143 * [fields reference](http://newton.ex.ac.uk/tex/pack/bibtex/btxdoc/node7.html)
 144 * [entry and fields reference](http://en.wikipedia.org/wiki/BibTeX),
 145   but with little discussion
 146 * [examples](http://www.cs.stir.ac.uk/~kjt/software/latex/showbst.html)
 147   of assorted styles
 148 * [assorted tools](http://liinwww.ira.uka.de/bibliography/Bib.Format.html)
 149 * Nelson Beebe's
 150   [list of bibliographies](http://www.math.utah.edu/~beebe/bibliographies.html)
 151 * Nelson Beebe's
 152   [GNU bibliography](http://www.math.utah.edu/pub/tex/bib/gnu.html)
 153
 154 [BibTeX]: http://www.bibtex.org/
 155 [PubMed]: http://www.ncbi.nlm.nih.gov/pubmed/
 156 [TTB]: http://www.ctan.org/tex-archive/info/bibtex/tamethebeast/
 157 [Natbib]: http://merkel.zoneo.net/Latex/natbib.php
 158 [custom-bib]: http://www.ctan.org/tex-archive/help/Catalogue/entries/custom-bib.html
 159 [DRY]: http://en.wikipedia.org/wiki/Don%27t_repeat_yourself
 160 [wikipedia]: https://en.wikipedia.org/wiki/BibTeX#Cross-referencing
 161 [MC]: http://luther.ceplovi.cz/blog/
 162 [MC-rss2email]: http://search.gmane.org/?query=&author=Cepl&group=gmane.mail.rss2email&sort=relevance&DEFAULTOP=and&xFILTERS=Gmail.rss2email-Acepl---A
 163 [lyx-2000-11-07]: http://www.mail-archive.com/lyx-users@lists.lyx.org/msg07511.html
 164
 165 [[!tag tags/latex]]
 166 [[!tag tags/programming]]
 167 [[!tag tags/tools]]