NAME

Text::BibTeX::BibStyle - Format Text::BibTeX::Entry items using .bst

DESCRIPTION

Text::BibTeX::BibStyle is a module that can format Text::BibTeX::Entry objects by interpreting a bibstyle (.bst) file such as ieeetr.bst. In this way, Perl can use the same bibliographic style files that bibtex does.

For a large collection of .bst files, see http://www.math.utah.edu/pub/tex/bibtex/index.html.

SYNOPSIS

  $bibstyle = Text::BibTeX::BibStyle->new(%options);

  $ENV{BSTINPUTS} = "my/bstfiles/";
  $bibstyle->read_bibstyle("bibstyle");
       OR
  $bibstyle->replace_bibstyle($bibstyle_def);

  $ENV{BIBINPUTS} = "my/bibfiles/";
  $bibstyle->execute([qw(bibfile1 bibfile2)]);
       OR
  $bibstyle->execute([qw(bibfile1 bibfile2)], \@ref_list);

  @warnings = $bibstyle->warnings;

  $output = $bibstyle->get_output();
  $output = $bibstyle->convert_format(Text::BibTex::BibStyle::html);
       OR
  $output = $bibstyle->get_output(\%options);

METHODS

new [(%options])

Class method. Creates a new Text::BibTeX::BibStyle object with the options specified in the optional option='value'> arguments.The following options are understood:

debug

Turns on debugging messages during execute.

nowarn

Turns off warnings from certain sanity checks, such as the existence of a unique ENTRIES and READ statement within the bibstyle.

convert_format ($text, \%options)

Method. Converts a LaTeX bibliography in $text into some other format using the options specified by %options and returns the result. This method can also be used to convert a standard BibTeX output to a different format.

Assuming that $text contains a LaTeX bibliography (e.g., the contents of a .bbl file), the following option packages may be useful for the options hash reference:

$Text::BibTeX::BibStyle::HTML

Produces HTML code to render the formatted bibliography. Exportable.

$Text::BibTeX::BibStyle::LATEX

Outputs LaTeX code identical to bibtex (specifies (wrap => 1)). Exportable.

$Text::BibTeX::BibStyle::RST

Produces reStructuredText code. Exportable.

The following options are supported, if you want to write your own translation package:

character

Reference to a subroutine to call for special characters. The subroutine is called with the arguments ($bst, $latex, [$unicode], $char, [$accent]), where $bst is the Text::BibTeX::BibStyle object, $latex is the original latex for the special character, $unicode is the equivalent unicode character (if it exists), $char is the special character(s), and $accent is the latex accent code to be applied (if specified). It should return the string to be substituted.

command

Reference to a subroutine to call for LaTeX commands. The subroutine is called with the arguments ($bst, $cmd, @args), where $bst is the Text::BibTeX::BibStyle object, $cmd is the name of the LaTeX command and @args is the array of arguments (including optional arguments) to the command. At a minimum, the subroutine should handle the following commands: \begin{thebibliography}, \bibitem[label]{key}, \cite{ref}, \end{thebibliography}, \mbox{text}, \newblock. It should return the string to be substituted.

delete_braces

Boolean to delete from the output any braces that are not backslash-quoted.

init

Reference to a subroutine to call before processing the output. The subroutine is called with the argument ($bst), which is the Text::BibTeX::BibStyle object.

math

Reference to a subroutine to call for latex math. The subroutine is called with the arguments ($bst, $latex, $math), where $bst is the Text::BibTeX::BibStyle object, $latex is the original latex and $math is the part that actually translates to math. It should return the string to be substituted.

postprocess

Reference to a subroutine to call to post-process the output. The subroutine is called with the arguments ($bst, $text), where $bst is the Text::BibTeX::BibStyle object and $text contains the text of the entire formatted bibliography. It should return the final formatted bibliography.

prologue

A string or reference to a subroutine to call to produce any pre-bibliography definitions needed by the format.

style

Reference to a subroutine to call for different font styles. The subroutine is called with the arguments ($bst, $latex, $style, $text), where $bst is the Text::BibTeX::BibStyle object, $latex is the original latex, $style is one of rm, em, bf, it, sl, sf, sc, or tt indicating the font style, and $text is the text to be output in that style. It should return the string to be substituted.

substitute_newcommand

Boolean to process and do substitutions for any \newcommand definitions in the output.

wrap

Boolean to force the standard bibtex wrapping on the output.

execute [(\@bibfiles[, \@cites])]

Method. Executes the current bibstyle interpreter on a set of cited references passed in @cites looking in a set of .bib files passed in @bibfiles. If the @cites argument is undefined, uses all the references in all the bibfiles. The files in @bibfiles should be without the ".bib" extension. The search path for bibfiles is taken from the BIBINPUTS environment variables if it is defined. The @bibfiles argument is not needed if the bibstyle interpreter does not contain a READ command. Croaks if a bibstyle interpreter has not been defined using either the read_bibstyle or replace_bibstyle method.

get_output [(\%options)]

Method. Returns the output produced by write$ commands in the .bst file. The options are listed under the convert_format method, which it calls.

num_warnings

Method. Returns the number of warning messages generated during execution.

read_bibstyle ($bibstyle)

Method. Replaces the bibstyle interpreter with a new one obtained by reading the file $bibstyle.bst. The search path for the bibstyle file is taken from the BSTINPUTS environment variable if it is defined.

replace_bibstyle ($string[, $filename])

Method. Replaces the bibstyle interpreter by parsing $string. The optional $filename argument is used for warning messages. Written primarily for testing purposes; most users will call it only indirectly through the read_bibstyle method.

warnings

Method. Returns an array of the warning messages generated during execution.

ENVIRONMENT

The following environment variables are used:

BIBINPUTS

The search path for bibliography (.bib) files.

BSTINPUTS

The search path for bibstyle (.bst) files.

LIMITATIONS

The $Text::BibTeX::BibStyle::HTML output filter has the following limitations:

Math mode

The math mode interpretation depends upon using Text::ASCIIMathML to convert to MathML. ASCIIMathML accepts most, but not all, LaTeX constructs. In order to render correctly in some browsers, it will need to use xhtml and put the appropriate MathML entity definitions in the header.

latex2e symbols

Extended symbols defined by latex2e are not supported.

COPYRIGHT & LICENSE

Copyright 2007 Mark Nodine, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.