.\" $Id: bib2xhtml.man 1.13 2004/07/01 22:17:49 dds Exp $
.TH BIB2XHTML L "01 July 2004"
.SH NAME
bib2xhtml \- BibTeX bibliography to XHTML converter
.SH SYNOPSIS
.B bib2xhtml
[
.B \-a
] [
.B \-b
.I bibtex-options
] [
.B \-c
] [
.B \-i
] [
.B \-d
.I delimiter
] [
.B \-h
.I heading
] [
.B \-m
.I macro file
] [
.B \-r
]
.B \-s
.I style
] [
.B \-t
] [
.B \-v
] [
.B \-u
]
.I sourcefile
[
.I htmlfile
]
.SH DESCRIPTION
.LP
.B bib2xhtml
converts a bibtex-format bibliography file to XHTML.
.I sourcefile
may be either a BibTeX-format bibliography
.RB ( .bib )
file or a LaTeX-fomatted bibliography auxillary file
.RB ( .aux ).
.I htmlfile
will often be just part of a larger
XHTML file;
.B bib2xhtml
attempts to update the XHTML file in place.  It does this
by searching
.I htmlfile
for two special strings, which delimit
the bibliography part of the file.
These strings are the XHTML comments
.IP
<!-- BEGIN BIBLIOGRAPHY
.I delimiter
-->
.IP
<!-- END BIBLIOGRAPHY
.I delimiter
-->
.P
If these delimiters are found, the old bibliography between them is
replaced with the new bibliography.
Otherwise the new bibliography, with the appropriate delimiters,
is appended to the end of
.IR htmlfile ,
and it will be necessary to move it to the proper location by hand.
Note that it is possible for
.I htmlfile
to contain any number of bibliographies, and they may be updated
independently.
If no
.I htmlfile
is specified, the bibliography is written to standard output.
.P
The tag of each BibTeX bibliography entry is converted into a name
anchor (<A NAME="tag">) in
.IR htmlfile ,
and may be used to construct a link to this particular entry.
.P
By default the contents of the bibliography are determined by
the contents of the
.IR sourcefile .
It is also possible to specify the contents of the bibliography in the
.I htmlfile
itself by setting the
.B \-i
option and using two special strings to delimit
the citations to be used for generating the bibliography.
These strings are the XHTML comments
.IP
<!-- BEGIN CITATIONS
.I delimiter
-->
.IP
<!-- END CITATIONS
.I delimiter
-->
.P
If these delimiters are found, the contents between them are searched for
XHTML comments containing the citations (one citation per line), for example
.IP
<!-- BEGIN CITATIONS
.I delimiter
-->
.IP
.br
<!-- \\citation{knuth:1997}
.br
    \\citation{knuth:1984} -->
.br
.IP
<!-- END CITATIONS
.I delimiter
-->
.P
These citations are then used for choosing the bibliography entries from
the
.IR sourcefile .
.SS Special Field Processing
.P
Several BibTeX fields are treated specially.  The filenames specified
in the
.BR postscript ,
.BR pdf ,
and
.B dvi
fields are relative to the
.I htmlfile
directory.  In addition,
.B bib2xhtml
recognizes compressed or gzipped files
(those with filenames ending in
.BR .Z ,
.BR .gz ,
or
.BR .z ).
.TP
.B url
If the
.B url
field exists, a link (``A'' tag) is created.  The destination
of the link is the
.B url
tag's value.
The bibliography entry's title is the source of the link.
This can be used to create a link to a XHTML version of the paper,
or to a version that is available by ftp.
.TP
.B mailto
If the
.B mailto
field exists, a link (``A'' tag) is created.  The destination
of the link is the
.B mailto
tag's value.
The bibliography entry's author name is the source of the link.
.TP
.B postscript
If the
.B postscript
field exists, its value is used as the name of a PostScript file.
.B bib2xhtml
creates a link to the file.
, and updates
.I htmlfile
with the number of pages and size of the PostScript file.
.TP
.B doi
If the
.B doi
field exists, its value is used as the designation of a digital
object identifier.
.B bib2xhtml
creates a link to the object through http://dx.doi.org and updates
.I htmlfile
with the
.B doi
as a hyperlink.
The
.B doi
should normally be in a canonical form like the following:
.I doi:10.1145/363347.363387.
However,
if the
.B doi
designator is formed as an HTTP hyperlink, it will be converted to the
canonical form by replacing the HTTP protocol designation and the host
name of the hyperlink with the
.I doi:
literal string.
.TP
.B pdf
If the
.B pdf
field exists, its value is used as the name of a PDF (portable document
format) file.
.B bib2xhtml
creates a link to the file and updates
.I htmlfile
with the size of the PDF file.
.TP
.B dvi
If the
.B dvi
field exists, its value is used as the name of a TeX DVI file.
.B bib2xhtml
creates a link to the file and updates
.I htmlfile
with the number of pages and size of the DVI file.
.TP
.BR author , " keywords"
The full
.B author
and
.B keywords
fields of each BibTeX entry are included in
.I htmlfile
as XHTML comments, and may be used by CGI scripts (such as
.BR bibsearch ,
which is supplied) to select only certain entries.
.SS Hints
.BR bib2xhtml 's
LaTeX to XHTML conversion is not very smart.
If something isn't being converted correctly, try doing it in a different way.
.P
.B bib2xhtml
does not currently understand \fI\\verb\fR.
To get a tilde into a filename or URL, use \fI\\~{}\fR.
.SH OPTIONS
.TP
.B \-a
Include the BibTeX file's abstract field in the bibliography.
.TP
.BI \-b " bibtex-options"
Provide the specified options to the BibTeX program.
.TP
.B \-c
Sort chronologically.  Normally, the bibliography is ordered first by
author and then by year.  With this option, the bibliography is
ordered by year and then author.
.TP
.BI \-i
The citations are included in the
.IR htmlfile .
When this option is set, the
.I sourcefile
must be a .bib file.
.TP
.BI \-d " delimiter"
Specify the delimiter that sets the bibliography off from the rest
of the XHTML file.  The default delimiter is the name of the bibliography
file with the
.B .bib
extension stripped.
.TP
.BI \-h " heading"
Use the string
.I heading
instead of the default title when creating a new
.IR htmlfile .
If updating an existing
.IR htmlfile ,
this option is ignored.
.TP
.BI \-m " macro file"
Specify a BibTeX macro file to supply to BibTeX when processing the
bibliography file.
Macro files typically contain local abbreviations and other macro
definitions.
.TP
.B -r
Reverse the chronological sorting order.  Normally, the bibliography
is sorted from the earliest entry to the latest entry.  With this
option, the order is reversed.
Note that to obtain a bibliography ordered by chronological order you
must also specify the
.B \-c
option.
.TP
.BI \-s " style"
Create a
.IR style \-style
bibliography.  Supported styles are
.B empty
(the default),
.BR plain ,
.BR alpha ,
.BR named ,
.BR unsort ,
and
.BR unsortlist .
An
.B empty
bibliography is a bulleted list.  A
.B plain
bibliography is a numbered list.
.B unsort
is like
.B plain
except that the entries in the XHTML file are in the same order as
as they are in the source file.
.B unsortlist
is like
.B unsort
but entry labels are bullets instead of numbers.
An
.B alpha
bibliography has labels that are in the BibTeX alpha style.  A
.B named
bibliography has labels of the form [name, year].
.TP
.B \-t
Write a timestamp with the date at which the bibliography was
updated to
.IR htmlfile .
.TP
.B \-v
Report version number on stderr.
.TP
.B \-u
Convert LaTeX special characters into the corresponding
Unicode characters, and output XML coded in UTF-8.
The output produced by this option may be easier to parse and validate
with some XML parsers.
By default LaTeX special characters are converted into HTML character entities.
.SH FILES
.PD 0
.TP 14
.B html-a.bst
alpha XHTML BibTeX style file
.TP
.B html-n.bst
named XHTML BibTeX style file
.TP
.B html-u.bst
unsort XHTML BibTeX style file
.TP
.BR html-aa.bst ", " html-na.bst ", " html-ua.bst
versions of the above style files with abstracts
.TP
.B bibsearch
a CGI script for performing bibliography searches
.PD
.SH SEE ALSO
.BR perl (L),
.BR bibtex (L).
.br
.ne 8
.SH BUGS
.LP
The LaTeX to XHTML translation, while decent, is not perfect.
.LP
Requires bibtex and perl.  However, I think that most
sites that would want to convert BibTeX to XHTML will already
have both programs installed.
.LP
Relies on dviselect to count the number of pages in a DVI file.
.SH AUTHORS
David Hull
while at the University of Illinois at Urbana-Champaign.
.LP
Diomidis Spinellis
.RI ( dds@aueb.gr ),
Athens University of Economics and Business.

.SH HISTORY
The program was originally written as
.B bib2html
by David Hull in 1996, who
maintained it until 1998 (version 1.33).
In 2002, due to the lack of visible updates on the web,
the program was adopted for maintenance, distribution, and further evolution
by Diomidis Spinellis.
Changes made by him include support for XHTML 1.0 and documentation bug fixes.
The first public release of the maintenance effort was in 2004 (version 2.1).
On March 2004 the program was renamed into
.B bib2xhtml
to avoid confusion with projects using the name
.B bib2html .
Panos Louridas
.RI ( louridas@aueb.gr )
added the functionality for including the citations in the
.I htmlfile .
.LP
See
.I http://www.spinellis.gr/sw/textproc/bib2xhtml
for the latest version.
This is free software, and may be modified or redistributed under
the terms of the GNU Public License.