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.
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.
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.
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.
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 bibstyle
stylefile?>
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?>
<?bibhtml insert?>
--strip
option.<?bibhtml bibdata
bibfile?>
\bibliography{
bibfile}
command in a
LaTeX file; see also the -b
command-line option.<?bibhtml bibstyle
stylefile?>
\bibliographystyle{
stylefile}
command in a LaTex file; see also the -s
command-line option.<?bibhtml today?>
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.
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:
~
translated to
, and --
to
&enspace;
. Or set it to -3 (the default) if you
don't.\nocite{*}
in LaTeX.\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..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.rootname.html
,
rootname.aux
and so on. Why not just stick with the default
`bibliography'...? \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.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
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.
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.
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.
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.
.bst
style files, adding
@webpage
entry type, and lastchecked
field
to all entry types./usr/bin/env perl
at the top of the
script, rather than /usr/bin/perl
; this should be more
portable.<?bibhtml start?>
, rather than magic comments (the
old behaviour is still temporarily supported).<?bibhtml insert?>
inserts the bibliography in-place.--help
and --strip
options.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.
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
.