Bibhtml

Bibhtml consists of a Perl script and a BibTeX style file, which together allow you to compile a bibliography for a collection of HTML files. The references in the text are linked directly to the corresponding bibliography entry, and if a URL is defined in the entry within the BibTeX database file, then the generated bibliography entry is linked to this.

This page is http://purl.org/nxg/dist/bibhtml

This documentation describes bibhtml, version 1.2, 2005 September 19.

Contents

Bibhtml consists of a Perl script and a number of BibTeX style files, which together allow you to compile a bibliography for a collection of HTML files. The references in the text are linked directly to the corresponding bibliography entry, and if a URL is defined in the entry within the BibTeX database file, then the generated bibliography entry is linked to this.

The BibTeX style files are plainhtml.bst and alphahtml.bst, which are derived from the standard files plain.bst and alpha.bst. As well, there are .bst files which produce their output in date order (see below). You can specify these to bibhtml using either the -s option or the processing instructions described below.

The BibTeX style files distributed as part of this package are also of considerable use in isolation.

Usage

The BibTeX database

Bibhtml works with a standard BibTeX database -- it is intended to be compatible with a database used in the standard way with LaTeX. The BibTeX style files distributed with this package define an additional url field: if this is present, then the generated entry will contain a link to this URL. They also define an eprint field -- if you do not use the LANL preprint archive, this will be of no interest to you.

TeX features such as ~ and -- are translated to corresponding HTML entities (controlled with the +3 switch, see below), but other TeX constructions will make their way into the generated HTML, and look a little odd. I might try to deal with these in future versions.

Preparing the text

You prepare your text simply by including links to the bibliography file (the default is bibliography.html), followed by a fragment composed of the BibTeX citation key. Thus, you might cite [grendel89] with

<a href="bibliography.html#grendel89">(Grendel, 1989)</a>

(of course, the link text can be anything you like). That's all there is to it. When you run bibhtml, it generates an .aux file which makes BibTeX produce references for exactly those keys which appear in this way.

Preparing the bibliography file -- processing instructions supported

The bibliography file is an ordinary HTML document (which may itself have citations within it), distinguished only by having two processing instructions within it. Bibhtml replaces everything between <?bibhtml start ?> and <?bibhtml end ?> (which should be on lines by themselves) with the formatted bibliography. It leaves those instructions in place, naturally, so once this file is set up, you shouldn't have to touch it again. Older versions of bibhtml used the magic comments <-- bibhtml start --> and <-- bibhtml end -->: these are still supported, but are deprecated and may disappear in a future version.

Alternatively, you may include the processing instruction <?bibhtml insert?>. This acts broadly like the start and end processing instructions, except that the line is completely replaced by the inserted bibliography. This is useful if the file being processed is a generated file (perhaps the output of a separate XML tool-chain, for example), which will not therefore have to be rescanned in future.

You can specify the bibliography database and style file either on the command line (see below) or using the <?bibhtml bibdata bibfile?> and <?bibhtml bibstylestylefile?> instructions. The value of `bibdata' is cumulative, and appends to any value specified on the command line. A value of `bibstyle' specified on the command line, in contrast, overrides any value in the file.

As a special case, bibhtml also replaces the line after a comment <?bibhtml today ?> with today's date.

Summary of processing instructions:

<?bibhtml start?> and <?bibhtml stop?>
Bracket the bibliography -- any text between these PIs is replaced when bibhtml is next run.
<?bibhtml insert?>
This PI is replaced by the bibliography when bibhtml is next run. This PI is always removed, irrespective of the presence or absence of the --strip option.
<?bibhtml bibdata bibfile?>
Specify the bibliography database to be used. This is the analogue of a \bibliography{bibfile} command in a LaTeX file; see also the -b command-line option.
<?bibhtml bibstyle stylefile?>
Specify the bibliography style to be used. This is the analogue of \bibliographystyle{stylefile} command in a LaTex file; see also the -s command-line option.
<?bibhtml today?>
Replace the following line by today's date.

BibTeX style files

bibhtml depends on several BibTeX style files. plainhtml.bst, plainhtmldate.bst and plainhtmldater.bst are derived from the standard plain.bst. All produce HTML, but the latter two sort the output by date and reverse date, rather than by author. alphahtml.bst and friends were derived from the standard alpha.bst, and contributed to the package, by Franz G. Fischer, Franz.Fischer@lpr.e-technik.tu-muenchen.de, to whom thanks are due.

These style files support an additional entry type, @webpage, and two additional fields on all entry types, url and lastchecked, which give the URL associated with the reference, and the date at which the URL was last verified to be still present. See also the urlbst package, which performs a different role, but implements the same BibTeX extensions.

Although these style files are distributed as part of bibhtml they are also useful in isolation, as part of a larger system which generates HTML.

Running bibhtml -- options

Usage

% bibhtml [options...] filename...
% bibhtml --merge file.bbl file.html

The filename argument is the name of a file to be scanned.

Bibhtml takes a list of HTML files as argument (though see below for a two-pass variant). It creates an .aux file, runs BibTeX, and merges the resulting .bbl file (if it exists) into bibliography.html, or whatever has been specified as the bibliography file name.

There are several options:

-3, +3
Set this to +3 if you want ~ translated to &nbsp;, and -- to &enspace;. Or set it to -3 (the default) if you don't.
-a
If this option is set, bibhtml won't bother scanning any files at all, and will generate references for all the entries in your database. This is equivalent to \nocite{*} in LaTeX.
-b bibdata
The name of your BibTeX database file, as it would be specified in a \bibliography{} command in LaTeX. Unless you happen to keep all your references in a file called bib.bib, you'll probably want to change this. Or you can use the <?bibhtml bibdata xxx?> processing instruction.
-c configfile
Specifies a configuration file which contains a single line of options, which are inserted in the command line at that point.
--merge
In this special case, bibhtml takes two arguments, a .bbl file and an .html file, merges the first into the second, and nothing else. It's intended to be used when you have generated a .bbl file by a separate run of BibTeX, and simply wish to merge the results into your bibliography file. As such, it will most likely be useful as part of a script, or other post-processing system.
-r rootname
Specify this and you'll create rootname.html, rootname.aux and so on. Why not just stick with the default `bibliography'...?
-s bibstyle
The name of the BibTeX bibliography style you want to use, as it would be specified for the \bibstyle command in LaTeX. If you want to have a different layout for your HTML bibliographies, please don't change the file plainhtml.bst distributed with bibhtml. Instead, make a copy of plainhtml.bst under a different name, edit it as much as you like, and use this option of bibhtml to use the modified version instead of the default. Or you can use the <?bibhtml bibstyle xxx?> processing instruction.
--strip
If this option is set, then strip all processing-instruction lines from the output file. This means that the resulting file cannot be processed again by bibhtml, and so is appropriate when the file is the output of a separate tool-chain.
-V, --version
Bibhtml prints the version information and exits.
-v, -q
Do you want the program to be verbose or quiet? The default is -v, verbose.

The defaults for the various parameters are unlikely to be helpful, so you're likely to want to set one or more of them every time you run the program. It is for this reason, and because you're likely to want the same set of options every time you create the bibliography for a set of files in a directory, that you can put a collection of options in a configuration file. This can be specified on the command line with the option -c configfilename. If this option is not given, then bibhtml looks for a file named bibhtml.config. For example, the configuration file might contain:

-b mybib +3 -r refs

Installation

Nothing to it.... On Unix, for example, put bibhtml somewhere in your path and make it executable (chmod u+x bibhtml), and put *.bst somewhere BibTeX will find it (this means either looking at the environment variable BSTINPUTS, or running the command kpsepath bst, if you have it). If you want to use the two-pass variant of the program, then make a symbolic link with ln -s bibhtml bibhtml2.

If you wish, you may change the distributed BibTeX style files (see above) to the extent of changing the `eprint' mirror site from the master xxx.lanl.gov to a more local mirror. If you don't use the LANL preprint archive, this will be of no interest to you.

Two-pass bibhtml

You might sometimes have a need to invoke the two phases separately. If you make a symbolic link to the program via ln -s bibhtml bibhtml2, then you can generate an aux-file alone by giving the command bibhtml2 *.html, say; and you can merge a bbl-file into the bibliography file with the command bibhtml2 bibliography.bbl. The command line option --merge above may be more suitable if you are calling this code from a script, as it requires you to specify both the .bbl and the .html file it is being merged with, (and so it is more robust, and more flexible).

On Unix, this works because the program is able to detect the name it was invoked under. This may be more difficult on other platforms. If so, please get in touch, with suggestions.

Example

There are multiple sources of advice for how to cite electronic documents. The most formal are an ISO standard [ISO 690-2], and the American Psychological Association's guidance ([APA 2003]. As well, there are older, but still useful discussions in Walker and Emory.

We also include here a test entry, which has some odd characters in the title and URL.

This file was processed with the command bibhtml -r bibhtml bibhtml.html to produce the document you are reading now.

References

[apa03] American Psychological Society.
APA style: Electronic references. [Online, cited September 2005].
[test] A. N. Experimenter.
bibhtml tests - how do we handle odd ( &) characters?. This is a test entry.
[iso690] ISO 690-2.
ISO 690-2, bibliographic references to electronic documents (excerpts). [Online, cited September 2005].
[emory95] libsf@web.cc.emory.edu.
Citation formats. [Online].
[walker95] Janice R Walker.
MLA-style citations of electronic sources. Technical Report 4/95, Department of English, University of South Florida, January 1995. Endorsed by the Alliance for Computers and Writing.

See also the documentation for the urlbst package, which generates BibTeX style files for ordinary LaTeX output (which also supports a @webpage entry type, and url and lastchecked fields), and which contains a similar list of references concerned with citing online sources.

Distribution

Changes

1.2, 2005 September 19
1.2b2, 2005 August 30
1.2b1, 2005 August 19

Obtaining bibhtml

Bibhtml is available on CTAN at biblio/bibtex/contrib/bibhtml/, and at purl.org/nxg/dist/bibhtml.

Download the distribution: bibhtml-1.2.tar.gz.

Do let me know if you use this stuff. I'd be grateful for any bug reports, and bug fixes, and also for any comments on the clarity or otherwise of this documentation.

Licence

This software is copyright, 1999, 2005, Norman Gray. It is released under the terms of the GNU General Public Licence. See the copyright declaration at the top of file bibhtml, and the file LICENCE for the licence conditions. You can find an online copy of the GPL at http://www.gnu.org/copyleft/gpl.html.

Norman
2005 September 19