%META:TOPICINFO{author="AntonioTerceiro" date="1093299300" format="1.0" version="1.2"}%
---+ %TOPIC%

BibliographyPlugin manages citations inside a TWiki topic, and can generate a References List. 
This should be very useful for writing conference papers, journal articles, elaborated news, etc.

---++ Syntax Rules

First of all, you must have a topic with a list of bibliography entries. 
Each entry must consist of a table row with two (or three) columns: 
The first column contains a key, that will identify that entry (and __must__ be unique). 
The second column contains the bibliography reference for that entry.
The third column contains an optional set of "key=value" pairs used to link to other sites.
Keys that are formatted (bold, italics, etc) are ignored.

For example, a bibliography list might look like this 
(from a <nop/>BibTex [[http://shelah.logic.at/eindex.html][example]] 
found with [[http://www.google.com][Google]]):

| *Key* | *Description* | *Optional Info* |
| big | Jass, Hugh. _A big paper_. The journal of big papers, 7991, volume MCMXCVII. | PUBMED=12345 |
| small | Freely, I.P. _A small paper_. The journal of small papers, 1997. (to appear). |

Then, in the topic where you want to reference and get a references list, you can use:

	* =%<nop/>CITE{<em>theKey</em>}%= to reference the entry with key _theKey_.
	* =%<nop/>CITEFULL{<em>theKey</em>}%= to insert the full reference for key _theKey_.
	* =%<nop/>BIBLIOGRAPHY{...}%= to get a list of references used in this topic. 
	* =%<nop/>BIBLIOGRAPHYFULL{...}%= to get a full list of references. 
	
	=%<nop/>BIBLIOGRAPHY{...}%= accepts the following arguments:
	  | *Argument* | *Description* | *Default value* |
	  | =header= \
	  | the header for the references list (like "---+ References", "---+ Referências" (in portuguese), and so on. \
	    If there are no references, the header is suppressed. \
	  | DEFAULTHEADER setting (see below). |
	  | =keyLink= \
	  | where a link to a key topic should appear. \
	    Accepted values are =cite= (citation number is a link), \
	    and =end= (details link appears at end of reference). \
	  | DEFAULTKEYLINK setting (see below). |
	  | =optionString= \
	  | text that can be combined with an optional value in the bibliographic list, \
	    usually to create a link to an external site. \
	    For each entry in the bibliographic list, \
	    BibliographyPlugin checks each optional =key/value=. \
	    If an =optionString= contains a =key=, the =key= is replaced with the =value=, \
	    and the resulting string is appended to the bibliographic entry. \
	    Can be a comma-separated list of strings, and can be repeated. \
	    Here are some sample =optionString= values: %BR%\
		=" ([<nop/>[http://www.amazon.com/gp/product/ISBN][Amazon]]) "= %BR%\
		=" ([<nop/>[http://isbndb.com/search-isbn.html?isbn=ISBN][ISBN]]) "= %BR%\
		=" ([<nop/>[http://portal.acm.org/citation.cfm?id=ACM][ACM]]) "= %BR%\
		=" ([<nop/>[http://www.pubmedcentral.gov/articlerender.fcgi?artid=PUBMED][PubMed]]) "= %BR%\
		=" ([<nop/>[http://search.barnesandnoble.com/booksearch/isbnInquiry.asp?isbn=ISBN][B&N]]) "= \
	  | DEFAULTOPTIONSTRINGS setting (see below). |
	  | =order= \
	  | the order in which references should appear. \
	    Accepted values are =alpha= (references appear in alphabetical order), \
	    =citation= (references appear in citation order), \
	    and =key= (references appear in key order). \
	  | DEFAULTSORTING setting (see below). |
	  | =referencesTopic= \
	  | the topic(s) bibliography must be taken from. \
	    Can be a comma-separated list of topics, and can be repeated. \
	  | DEFAULTBIBLIOGRAPHYTOPIC setting (see below). |
	  | *Usage example:* |||
	  | =%<nop/>BIBLIOGRAPHY{header="---++ Referências" referencesTopic="<nop/>MinhaBibliografia" order="citation"}%= %BR% \
	  The above usage tells BibliographyPlugin to use "Referências" (in portuguese) \
	  as the title of the references list, to take bibliography from a topic named \
	  <nop/>MinhaBibliografia and to list the references in citation order.  |||

---++ Example

<table border='1'>
  <tr>
	 <th> You type ...
	 </th>
	 <th> ... and you get:
	 </th>
  </tr>
  <tr>
	 <td>
<!-- you type: -->
<pre>
You start writing, and then cite a
small paper %<nop/>CITE{small}%. Further,
you reference a big paper %<nop/>CITE{big}%.
You can even reference the small
 paper again %<nop/>CITE{small}%.

%<nop/>BIBLIOGRAPHY{referencesTopic="TWiki.Bibliography2Plugin"}%
</pre>
	 </td>
	 <td>
<!-- you get: -->
You start writing, and then cite a small paper %CITE{small}%. Further, you reference a big paper %CITE{big}%. You can even reference the small paper again %CITE{small}%.

%BIBLIOGRAPHY{referencesTopic="TWiki.Bibliography2Plugin"}%
	 </td>
  </tr>
</table>

---++ Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write ==%<nop>&lt;plugin&gt;_&lt;setting&gt;%==, i.e. ==%<nop>INTERWIKIPLUGIN_SHORTDESCRIPTION%==

	* One line description, is shown in the %TWIKIWEB%.TextFormattingRules topic:
		* Set SHORTDESCRIPTION = cite bibliography in one topic and get a references list automatically created.

	* Debug plugin: (See output in =data/debug.txt=)
		* Set DEBUG = 0

	* Default topic to get references from:
		* Set DEFAULTBIBLIOGRAPHYTOPIC = TWiki.BibliographyPlugin

	* Default header for the references list:
		* Set DEFAULTHEADER = ---++ References

	* Default key link:
		* Set DEFAULTKEYLINK =
	
	* Default option string:
		* Set DEFAULTOPTIONSTRINGS = 
		
	* Default sorting for references:
		* Set DEFAULTSORTING = alpha

---++ Plugin Installation Instructions

__Note:__ You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running. 

	* Download the ZIP file from the Plugin web (see below)
	* Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
	  | *File:* | *Description:* |
	  | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
	  | ==data/TWiki/%TOPIC%.txt,v== | Plugin topic repository |
	  | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
	* Test if the installation was successful: see above at [[#Example]]

---++ Plugin Info

|  Plugin Author: | TWiki:Main/AntonioTerceiro |
|  Plugin Version: | 23 Aug 2004  |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  08 Jun 2006: | Multiple enhancements by TWiki:Main/ClifKussmaul |
|  23 Aug 2004: | Added multiple references sources support |
|  17 Jun 2004: | Initial version |
|  CPAN Dependencies: | none |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  TWiki:Plugins/Benchmark: | %TWIKIWEB%.GoodStyle 97%, %TWIKIWEB%.FormattedSearch 99%, %TOPIC% 97% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |

__Related Topics:__ %TWIKIWEB%.TWikiPreferences, %TWIKIWEB%.TWikiPlugins

-- TWiki:Main/AntonioTerceiro - 17 Jun 2004