You type

%CITE{BahrSimpson02}%

The text within the citation is dictated by the results of the %BIBTEXREF% declaration in the topic (see below).

Note: The %CITE% macro is also defined by the TWiki:Plugins.BibliographyPlugin. If both plugins are installed, one must use the alternate declaration, %BIBCITE{...}%, to access the BibtexPlugin functionality.

Syntax

• %BIBTEX{<attributes>}% - render a set of bibtex files attached to some topic
• %STARTBIBTEX{<attributes>}% ... %STOPBIBTEX% - render an inline-bibtex database
• %CITE{key}% (or %BIBCITE{key}%) - generate an hyperlink to a bibtex entry
• %BIBTEXREF{key, topic}% - generate a list of references based on the declared CITE keys

Attributes

All attributes for %BIBTEX% and %STARTBIBTEX% are optional. The attributes topic and bibfile are not valid in the %STARBIBTEX% tag as the bibtex database is given inline and not as an attachment. %CITE% has one obligatory attribute, that is key refering to the bibtex entry that is to be cited. topic is optional here and defaults to the recently used bibtex database location in a %BIBTEX% tag on the same topic (see Tips).

Citations and Automated Reference Lists

As of release v1.3, the BibtexPlugin has functionality similar to the TWiki:Plugins.BibliographyPlugin. Specifically, if a topic has %CITE{key}% declarations through out, the use of %BIBTEXREF{...}% will generate a list of references based on the citations declared. The output of the reference list is dictated by BibTeX. Thus, the HTML output can use all of the flexibility of bibtex, including custom bibtex style templates and string macros.

The citation keys must refer to the output key produced by this plugin, which may differ from the entries in the associated .bib files according to the bibtool resource file in use. Simply use the output key produced by BibtexPlugin search template query results.

Again, if both the TWiki:Plugins.BibliographyPlugin and TWiki:BibtexPlugin are installed, one must use %BIBCITE{...}% inplace of %CITE% for the BibtexPlugin functionality to work.

Example

You type

<table border=1><tr><td>
     %BIBTEXREF{bibstyle="alpha"}%
</table>

you get

(simulated)

(if installed)

The Query Language

The information here is extracted from the bibtex2html manual (section 3.2: Filter conditions) and might be incomplete or outdated. Please see here for more information. Anyhow here's a version matching the naming conventions that we use here (filter conndition = query).

A query is a boolean expression that is evaluated against a BibTeX entry to decide whether this entry should be selected. A query is either:

• a comparison between two expressions, written as e1 op e2
• a matching of a field name with respect to a regular expression, written as field : regexp
• a conjunction of two conditions, written as c1 and c2
• a disjunction of two conditions, written as c1 or c2
• a negation of a condition, written as not c (or ! c)
• a test of existence of a field, written as exists f (or ? f) where f is a field name

where an expression is either:

• a field name
• a string constant between single quotes
• an integer constant
• the special ident $key which corresponds to the key of an entry.
• the special ident $type which corresponds to the type of an entry (ARTICLE, INPROCEEDINGS, etc.). Notice that an entry type is always written in uppercase letters.
• comparison operators are the usual ones: , <, >, <, >= and <>

The field names are any sequences of lowercase or uppercase letters (but no distinction is made between lowercase and uppercase letters).

Regular expressions must be put between single or double quotes, and must follow the GNU syntax of regular expressions, as for example in GNU Emacs. Any character other than $^.*+?[] matches itself, see the following table for the meaning of the special characters:

Customizing Look & Feel

The BibtexPlugin is customizable in several ways:

• manipulate the cascading style sheets sitewide or derived on one topic
• implementing an different BibtexSearchTemplate used with the form attribute of the %BIBTEX% command
• rewriting the bibtool resourcefile shipped with the BibtexPlugin

Cascading Stylesheets

Here's the list of used styles:

BibtexPlugin search templates

The BibteXPlugin search templates provide an interactive query interface to the bibtex files present on a wiki. As an example of their use, one can declare

   %BIBTEX{form="only"}%

• Available search templates
  • BibtexSearchTemplate - verbose .bib file query form
  • BibtexSimpleSearchTemplate - BibTeX key query form
  • BibtexSelectTemplate - query .bib files using bib2bib 'select' syntax

Bibtool Resource Files

Actually this is an art for itself. The author has taken care to give you a quite reasonable resource file for bibtool. This contains an own (default) style of citation keys. You might have a look at the bibtool manual page and dig into the bibtoolrcs file yourself.

Examples

• %BIBTEX%
  Render all bibtex entries in the bibtex files attached to the DEFAULTWEB.=DEFAULTTOPIC= in the DEFAULTSTYLE with the DEFAULTSORT.

• %BIBTEX{web="Sandbox" topic="BibTest" file="cite.bib" select="author : 'Einstein'"}%
  Use cite.bib which is attached in Sandbox under the topic BibTest as the BibTeX file. Embeds all of the references from the BibTeX file which have Einstein in the author field

• %BIBTEX{file="cite.bib" select="author : 'Einstein|Fermi' and year=2003"}%
  • Use cite.bib which is attached to the DEFAULTWEB under the topic DEFAULTTOPIC as the BibTeX file
  • Embeds all of the references from the BibTeX file which have Einstein or Fermi in the author field and 2003 in the year field
  • Format the embedded text as DEFAULTSTYLE

• Selecting entries of a given year
  • select only entries that appeared in 1999 : select="year=1999"
  • select references appearing after and/or before a given year, e.g. references after 1997:
    select="year>1997"
  • references between 1990 and 1995:
    select="year>=1990 and year<=1995"

• Selecting references of a given author
  • select only entries whose (co)author is Donald Knuth:
    select="author : 'Knuth'"
  • if you would like to have only the references whose author is Knuth only, you may try:
    select="author : '^\(Donald \(E. \)?Knuth\|Knuth, Donald \(E.\)?\)$'"
  • or equivalently but missing the possible E.:
    select="author = 'Donald Knuth or author = 'Knuth, Donald'"

• Other examples
  • extract the references that appeared since 1995 and have lambda-calculus in their title, with anything between "lambda" and "calculus":
    select="year >= 1995 and title : 'lambda.*calculus'"
  • select entries for Wolfgang Menzel since year 2000:
    select="author : 'Wolfgang Menzel' or author = 'Menzel, Wolfgang' and year>=2000"

Tips

• Setting the current bibtex database for citations:
  Having a set of citations %CITE{keyA}% ... %CITE{keyZ}% refering to the same database is achievable in several ways:
  • by attaching all your bibtex files at a common place and set the DEFAULTTOPIC in the Global Settings section to that topic, or
  • by declaring the current database in the first %CITE% tag: %CITE{"keyA" topic="Main.BibtexDatabase"}, or
  • by setting the current database with %BIBTEX{topic="BibtexDatabase" display="off"}%, or
  • by specifying the bibtex database in every %CITE% tag (not seriously)
• Merging bibtex databases from different sources:
  If there are lots of databases all over your twiki site, you might want to merge them or extend them with some extra entries you don't want in the main database. Example: the main database contains all publications of your division but not the crossrefering presentation slides. You might want to keep them separate on your home-topic. You do that by nesting one or several %;BIBTEX{...bibstyle="raw"...}% commands inside a %STARBIBTEX% ... %STOPBIBTEX% section.

      %STARTBIBTEX%
      %BIBTEX{select="author:'YourName'" bibstyle="raw"}%
      @Misc{YourName02Slides,
         crossref = {YourName02},
         note = {slides of oral presentation},
      }
      %STOPBIBTEX%

• Manipulating the Cascading Style Sheet:
  You possibly don't like the default stylesheet for bibtexing installed on your twiki site. Or you just want to render a bibtex database differently on a single topic. Then add a stylesheet section in the topic: <style type="text/css"> ... </style>. Section Customizing Look & Feel lists the styles used. Here's a small example of how to get a different look easily. Just put it on some topic and see:

      <style type="text/css">
      .bibtex {
        background:transparent;
        border:0px;
      }
      .bibtex dd {
        margin-left:30px;
        margin-right:30px;
      }
      </style>

Global Settings

• One line description, shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Embeds BibTeX entries in a TWiki page

• Default topic name for BibTeX files:
  • Set DEFAULTTOPIC = BibtexPlugin

• Default search template
  • Set DEFAULTSEARCHTEMPLATE = BibtexSearchTemplate

Plugin Installation Instructions

• Download the .zip or .tgz file from twiki.org (see below)
• Extract the plugin files in your twiki installation directory. Content:

  File:	Description:
  data/TWiki/BibtexPlugin.txt	Plugin topic
  data/TWiki/BibtexSearchTemplate.txt	default query template
  data/TWiki/BibtexSimpleSearchTemplate.txt	simple query template
  data/TWiki/BibtexSelectTemplate.txt	expert query template
  lib/TWiki/Plugins/BibtexPlugin.pm	Plugin Perl module
  lib/TWiki/Plugins/BibtexPlugin/BibSearch.pm	Plugin Perl module
  lib/TWiki/Plugins/BibtexPlugin/Config.spec	Configure spec file
  pub/TWiki/BibtexPlugin/sample.bib	Plugin sample BibTeX file
  pub/TWiki/BibtexPlugin/style.css	default style definitions
  pub/TWiki/BibtexPlugin/bibtoolrsc	bibtool resource file
  bin/bibsearch	cgi query script
  tools/render.sh	bibtex to html/raw rendering script

• Modify the tools/render.sh script to point to the installed versions of bibtool, bib2bib, bibtex2html, and bibtex.
• Run configure and set the {Plugins}{BibtexPlugin}{render} setting to the full path to render.sh

If TWiki access control is managed at the web-server level, be sure to add bibsearch to the authorization list. E.g., for Apache, add the following lines to the .htaccess file:

<Files "bibsearch">
       require valid-user
</Files>

Plugin Info

Related Topics: BibtexPlugin, BibtexSearchTemplate, BibtexSelectTemplate, BibtexSimpleSearchTemplate, TWikiPlugins