bib2html Documentation
by Kiri Wagstaff


Introduction/Overview

Many researchers make use of bibTeX for maintaining a comprehensive bibliography which they can then draw on at will when writing papers.

bib2html is a handy utility that converts bibTeX files into HTML format. You can use it to easily maintain an updated online bibliography. In addition, it is possible to specify, for each bibfile entry, a URL that indicates where the document can be found online. Entries with associated URLs are linked to their respective destinations.

The output is (pretty much) in the format used by the ACL for their papers, because it seems fairly general and because I like it.

For ease of use, be sure to read section 2 on the format bib2html expects from your bibfile.

Disclaimer: I've come across mention of other bib2html programs. This program is in no way related to any of them. For the curious, it was implemented using flex, bison, and C.

1. How to run bib2html

2. The bibfile format expected by bib2html

3. What it can handle / Bugs

4. What it can't handle

5. Example output

6. Contributors and bug reporters


1. How to run bib2html

bib2html takes one argument: the name of the bibfile you wish to process, e.g.

 [wkiri@astra]$ bib2html wkiri.bib

The output is written to the same filename with 'bib' replaced by 'html'. In this example, the output goes to wkiri.html.


2. bibfile format

While bib2html is generally quite permissive, there are a few things to be aware of when using it for the first time.

2.1 Header

bib2html scans the beginning of the bibfile for important header information. It looks for a contiguous block of lines that each start with a single % followed by a space. This is best illustrated with an example:

 % Name: Kiri Wagstaff
 % Title: Research Bibliography
 % URL: http://www.cs.cornell.edu/home/wkiri
 % Email: wkiri%cs.cornell.edu
The Name field contains the owner's name. Title refers to the title you would like the HTML document to have. URL and Email are self-explanatory, but NOTE that you must replace the '@' in your email address with a '%'. This is because bibTeX gets confused by lines with '@' in them, even if the line is commented out. bib2html will convert the '%' to a '@' in the HTML output.

The field names are not case-sensitive.

While it is to your advantage to include all four lines, they are not required. In their absence, bib2html makes a guess for each value.

2.2 Table of Contents

bib2html will generate a table of contents for your bibfile that appears at the beginning of the HTML output. You can indicate section headings by including comments in your bibfile in the following format:

 %%% Section Heading %%%

(Any other kind of comment will be ignored, as comments tend to be.) Since the order of items in your bibfile is preserved in the output, you can use these headings to indicate sections within the HTML output. The table of contents is represented by an HTML table with three columns. I am considering making the number of columns a command-line argument. If you think this would be useful, please let me know.

2.3 Each entry

To be recognized by bib2html, each entry must begin with an '@', immediately followed by the type of entry it is (see the list of recognized entry types), immediately followed by a '{'. It will then process the fields you've specified for that entry until it hits the closing '}' (see the list of recognized fields). The format then looks something like this:

  @entrytype{authorname:concept,
    fieldname1 = "Contents",
    fieldname2 = {Contents},
    fieldname3 = contents,
    ...
  }

Three types of field contents are valid, as shown here. In fieldname1, the contents are enclosed in quotes; in fieldname2 they are enclosed in curly braces, and in fieldname3 there are no surrounding characters. The third type is often used to specify pre-defined string values, and any value specified in this way will be compared to the list of @strings you've defined for a possible match (if there is a match, it will be expanded out to the full value of the @string).

Any amount of whitespace can come between the fieldname and the '=', or between the '=' and the contents. In addition, bib2html can handle nested {}'s in the contents of a field.

2.4 How to specify a URL for an entry

Since the bibTeX format is expandable (it ignores any additional fields you may wish to add), bib2html takes advantage of this by allowing you to specify a url field. For example:

  @article{authorname:concept,
    author = "Lastname, F.",
    year = 2000,
    title = "Title of the paper",
    journal = "Journal name",
    pages = {1--10},
    url = "http://some.url/directory/paper.ps"
  }

This results in an entry in the HTML output that is automatically linked to the proper location, e.g.

Lastname, F. 2000. Title of the paper. Journal name, 1-10.

bibTeX ignores field names it does not recognize. bib2html also permits custom fields, but it will print a note indicating that the field has not been recognized.


3. What it can handle

3.1 Entry types

bib2html recognizes the following bibliography entry types (these are not case-sensitive):

I welcome requests to support other entry types. If there's something you use that I haven't included, let me know.

3.2 Field types

bib2html recognizes the following bibliography field types (these are not case-sensitive):

If a fieldname is prefixed with OPT, it will be ignored. Again, requests that involve other field types are welcome.

3.3 @strings

Like bibTeX, bib2html also handles arbitrary @string definitions, which can be used in any entry field, e.g.

 @string{acl = "Association for Computational Linguistics"}
 ...
 publisher = acl


4. What it can't handle / Bugs

bib2html will not handle the following properly: I'm interested in hearing about your experiences. Is there anything I've omitted that would be useful?


5. Example output

The bib2html distribution comes with test.bib. Run `make test` and observe the output. If the diff reports anything at all, either the build failed or there is a bug. You can submit a bug report at:

http://www.litech.org/~wkiri/bib2html

To see a 'real' example of bib2html's output, you can view my HTML bibfile online at:

http://www.litech.org/~wkiri/Papers/wkiri.html


6. Contributors and Bug reporters

I would like to thank the following people for generously taking the time to point out bugs, suggest improvements, or send me bib2html patches. Many thanks to:


Kiri Wagstaff < Email : wkiri@cs.cornell.edu >
Last modified: Mon Jul 1 01:20:18 EDT 2002