.\" $Id: bib2xhtml.man 1.25 2010/12/08 19:02:34 dds Exp $
.TH BIB2XHTML L "5 December 2010"
.SH NAME
bib2xhtml \- BibTeX bibliography to XHTML converter
.SH SYNOPSIS
.B bib2xhtml
[
.B \-a
] [
.B \-b
.I bibtex-options
] [
.B \-c
] [
.B \-D
.I mappings
] [
.B \-d
.I delimiter
] [
.B \-e
.I extended-information
] [
.B \-h
.I heading
] [
.B \-i
] [
.B \-k
] [
.B \-m
.I macro-file
] [
.B \-n
.I author-name
] [
.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
.IP
.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 () 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
.IP
.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
.IP
.br
.br
.IP
.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
.I 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 an embedded URL, use \fI\\~{}\fR.
On the other hand, entries containing \fIURL\fR fields or
\fI\\url{}\fR commands,
are correctly converted into hyperlinks.
Leave such hyperlinks as they are;
do not embed any LaTeX commands in them.
.P
The lists that
.B bib2xhtml
generates contain CSS hooks of the class \fIbib2xhtml\fR.
You can therefore modify the appearance of the lists
by adding style entries like the following in the web page's header.
.ft C
.nf
.fi
.ft P
.P
The value of the named attributes can contain arbitrary HTML markup commands,
and can thus be used for substituting the text with icons.
For example, the following Unix command can be used for creating stand-alone
PDF icons.
.ft C
.nf
perl bib2xhtml -e 'nosize,nopages,PDF:' example.bib example.html
.fi
.ft P
Unser the Windows shell the corresponding command would be.
.ft C
.nf
perl bib2xhtml -e "nosize,nopages,PDF:" example.bib example.html
.fi
.ft P
A couple of PDF icons and the conditions for their use are available
at
.I http://www.adobe.com/misc/linking.html#pdficon .
.P
To display the number of pages in local PDF files, the Perl module
\fIPDF::API2\fP must be installed on the system where
.B bib2xhtml
is running.
A command like the following will accomplish this.
.ft C
.nf
perl -MCPAN -e "install PDF::API2"
.fi
.ft P
.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 date. With this option, the bibliography is
ordered by year, month, day, and then by author.
.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 \-D " mappings"
Define URL to directory mappings.
The \fImappings\fP argument contains a sequence of comma-separated
values.
Each value contains a local file path and the corresponding URL,
separated by an \fI@\fP sign.
The resulting URL is used for linking the various paper file format types.
.TP
.BI \-e " extended-information"
Specify how an entry's extended information will be displayed.
The extended information is specified as a series of comma-separated
attributes.
The following plain attributes are supported.
.RS
.TP
.B notype
Do not display the file's type (PDF, Postscript, DVI).
.TP
.B nosize
Do not display the file's size in bytes.
.TP
.B nopages
Do not display the file's number of pages.
.TP
.B nocompression
Do not display the file's compression type.
.TP
.B nodoi
Do not display the file's DOI.
.TP
.B nobrackets
Do not enclose the DOI link or the file's extended information in brackets.
.RE
.LP
A number of valued attributes allow the specification of the text
to display for various file types.
These are written as a \fIname\fP:\fIvalue\fP pair.
The following names are supported for valued attributes.
.RS
.IP \(bu
PostScript
.IP \(bu
PDF
.IP \(bu
DVI
.IP \(bu
DOI
.RE
.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 \-i
The citations are included in the
.IR htmlfile .
When this option is set, the
.I sourcefile
must be a .bib file.
.TP
.B -k
In labeled styles
.BR "" ( alpha ,
.BR named ,
.BR plain ,
and
.BR unsort )
append to the label of each entry its BibTeX key.
Thus, the label of each entry will consist of the original label,
followed by an em-dash, followed by the BibTeX key.
.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
.BI \-n " author name"
Specify an author name to highlight.
Any bibliography entry author names that match the name specified as a regular
expression will be set in HTML \fIstrong\fP tags and will therefore
be displayed in a bold (or similar) font.
.TP
.B -r
Reverse the chronological sorting order. Normally, the bibliography
is sorted (by year; BibTeX ignores the month)
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 paragraph ,
.BR unsort ,
and
.BR unsortlist .
An
.B empty
bibliography is a bulleted list. A
.B plain
bibliography is a numbered list.
.B paragraph
produces just paragraphs (no bullets).
.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.