[[PageOutline(2-5,Contents,pullout)]]
= A !BibTex Cite Plugin =

== Description ==
[http://en.wikipedia.org/wiki/BibTeX BibTex] is for formatting lists of bibliographic references.

The aim of this plugin is to provide the ability to cite from common bibtex (*.bib) files.

The plugin can use bibtex files out of 
 * a repository (svn, git, mercurial)
 * a wiki page
 * a Wiki-Attachment
 * or an external website.

If a wiki page called !BibTex exists, the page is loaded automatically by ''!BibRef()'' and used as standard library.

Make sure to put bibtex entries into a Code Block when you use them from a wiki page.

The command structure is inspired by the reference and bibtex system in latex. This should make it easy to make this plugin compatible with existing trac - latex plugins.

== Bugs/Feature Requests == 

Existing bugs and feature requests for TracBibPlugin are 
[query:status!=closed&component=TracBibPlugin&order=priority here].

If you have any issues, create a 
[/newticket?component=TracBibPlugin&owner=Amfortas new ticket].

== Download and Source ==

Download the [download:tracbibplugin zipped source], check out from [/svn/tracbibplugin using Subversion], or [source:tracbibplugin browse the source] with Trac.

== Install ==
{{{
#!sh
easy_install http://trac-hacks.org/svn/tracbibplugin/0.10/
easy_install http://trac-hacks.org/svn/tracbibplugin/0.11/
easy_install http://trac-hacks.org/svn/tracbibplugin/0.12/
easy_install http://trac-hacks.org/svn/tracbibplugin/1.0/
}}}

== Requirements ==
 [http://www.geocities.com/fiolj/bibtexparse.html bibtexparser], a modified version is already included in the plugin.

== News ==
 * The new default citation style is an IEEE-like style
 * !BibTeX files can be loaded from external websites
 * Extensionpoint 'IBibRefFormatter' for custom citation styles introduced
 * Extensionpoint 'IBibSourceProvider' for custom !BibTeX loaders introduced
 * Wiki pages can be used as bibliograpy. The Entries must be inside a code block.
 * The attachments can now be loaded fom any page in the wiki
 * A special page "!BibTex" will be loaded automatically if this page exists, like in [http://trac.edgewall.org/wiki/BadContent BadContent].

== Usage ==

=== Configuration Settings ===

You can add a '''bibtext''' config section in trac.ini. In this section you can change the heading of the References and you can add other sources that should always be loaded:
{{{
#!ini
[bibtex]
heading= Literatur # default: References
auto= source:mybib.bib, wiki:BibTexBlub # default: wiki:BibTex
}}}

=== Load Bibtex Entries ===
The way how to invoke a bibtex file has substantially changed:
{{{
[[BibAdd(source:path/to/file[@rev])]]    # add a file from source 
[[BibAdd(attachment:[wikipage/]file)]]   # add a file from a wiki attachment        
[[BibAdd(wiki:page)]]                    # use a wiki page 
[[BibAdd(http://www.external.page.com)]] # use a bibtex file from everywhere
}}}

==== Examples ====
{{{
[[BibAdd(source:bib.bib@2)]]
[[BibAdd(source:trunk/bib.bib@latest)]]
[[BibAdd(source:bib.bib)]]
[[BibAdd(attachment:fiol.bib)]]
[[BibAdd(attachment:test/lala.bib)]]
[[BibAdd(http://www.external.page.com/bibtex.bib)]]
}}}

=== Cite an article ===

==== Macros ====
{{{
[[BibCite(key)]]
[[BibCite(key,page)]]
}}}

==== Wiki Syntax ====
{{{
cite:key
cite:key:page
}}}

=== Add an article without citation ===
{{{
[[BibNoCite(key)]]
}}}

=== Inserting the bibliography ===
This renders all cited entries:
{{{
[[BibRef]]
}}}

This renders all loaded entries:
{{{
[[BibFullRef]]
}}}

If you also want to render all entries from the special page '!BibTex' you can write
{{{
[[BibFullRef(auto=true)]]
}}}

=== URL/DOI Fields ===
'''url''' and '''doi''' fields in !BibTex files will be rendered to links if possible.

=== Full Example ===
{{{
= Welcome =

[[BibAdd(source:mybib.bib)]]

I am citing here [[BibCite(small)]] and someone said "hello world" [[BibCite(wiki,123)]] and 
cite:small:123-124 is important. finally the BibTex entry with the key 'big' is not cited but 
will appear in the references because of tho '!BibNoCite' macro. 

[[BibNoCite(big)]]
[[BibRef()]]
}}}

This looks rendered like that:

[[Image(tracbib2.png)]]

== Related ==
 * Ticket [ticket:453]
 * Ticket [ticket:5175]
 * [wiki:CiteMacro CiteMacro]



== Recent Changes ==

[[ChangeLog(tracbibplugin, 3)]]

== Author/Contributors ==

'''Author:''' [wiki:Amfortas] [[BR]]
'''Maintainer:''' [wiki:Amfortas] [[BR]]
'''Contributors:''' abeld