BibliographyPlugin < System

---+!! !BibliographyPlugin
<!--
One line description, required for extensions repository catalog. %JQREQUIRE{"chili"}%
   * Set SHORTDESCRIPTION = Cite bibliography in one topic and get a references list automatically created.
-->
%SHORTDESCRIPTION%

%TOC%

---++ Description

The Bibliography Plugin manages citations inside a Foswiki topic, and can generate an References List at the end of the topic. This should be every usefull for writing conference papers, journal articles, ellaborated 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 rows with two columns: the first one contains a key, that will identify that entry (and __must__ be unique, without relying on whitespace or capitalisation variations). The second column contains the bibliography reference for that entry.

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

| *Key* | *Description* |
| big | Jass, Hugh. _A big paper_. The journal of big papers, 7991, volume MCMXCVII. %ICON{note}% |
| 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/>CITEINLINE{<em>theKey</em>}%= to reference samething that is not in the references.
     Useful to cite URL's, for example. =theKey= will be used both as key *and* text dislayed in
     references listing. %BR%
     __Warning:__ be sure to not use keys present in bibliography with
     <code>%<nop/>CITEINLINE{}%</code>: this can have unpredicted results.
	* =%<nop/>BIBLIOGRAPHY{...}%= to get a 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. | DEFAULTHEADER setting (see below). |
     | =referencesTopic= | indicates the topic bibliography must be taken from. Can be a comma-separated list of topics. | DEFAULTBIBLIOGRAPHYTOPIC setting (see below). |
     | =order= | in which order the references should appear. Accepted values are =citation= (references appear in citation order) and =alpha= (references appear in alphabetical order). | DEFAULTSORTING 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 names <nop/>MinhaBibliografia and to list the references in citation order.  |||

---++ Example

<table border='1'>
  <tr>
    <th> You type ...
    </th>
    <th> ... and you get (if installed):
    </th>
  </tr>
  <tr>
    <td>
<!-- you type: -->
<pre class="tml">
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{Smal l}%. You might
accidentally reference a non-existent 
%<nop/>CITE{non-existent}% reference.

With %<nop/>CITEINLINE% you can reference things
that are not in your bibliography
%<nop/>CITEINLINE{http://foswiki.org/Extensions/BibliographyPlugin}%.

%<nop/>BIBLIOGRAPHY%
</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{Smal l}%. You might accidentally
reference a non-existent %CITE{non-existent}%
reference.

With %<nop/>CITEINLINE% you can reference things
that are not in your bibliography
%CITEINLINE{http://foswiki.org/Extensions/BibliographyPlugin}%.

%BIBLIOGRAPHY%
    </td>
  </tr>
</table>

---++ Plugin Settings

Plugin settings are stored as preferences values. To change the setting you need to overwrite them in %WIKIPREFSTOPIC%. Changing them here will have no effect! This allows you to upgrade the plugin without having worry about loosing your settings.

	* Default topic to get references from:
	   * Set BIBLIOGRAPHYPLUGIN_DEFAULTBIBLIOGRAPHYTOPIC = %SYSTEMWEB%.BibliographyPlugin

	* Default sorting for references:
	   * Set BIBLIOGRAPHYPLUGIN_DEFAULTSORTING = alpha

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

---++ Installation Instructions

You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in =configure=, then you can still install manually from the command-line. See http://foswiki.org/Support/ManuallyInstallingExtensions for more help.


---++ Plugin Info

|  Plugin Author(s): | Foswiki:Main.PaulHarvey, Foswiki:Main.AndrewJones |
|  Previous Author(s): | Foswiki:Main.AntonioTerceiro |
|  Copyright: | &copy; 2010, Paul Harvey, &copy; 2009 - 2010, Andrew Jones, &copy; 2004, Antonio Terceiro |
|  License: | [[http://www.gnu.org/licenses/gpl.html][GPL (Gnu General Public License)]] |
|  Plugin Release: | 2.2.2 |
|  Plugin Version: | 11925 (2011-06-15) |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  15 Jun 2011 | 2.2.2: Foswikitask:Item10882 - Fix for Foswiki installations using UTF-8, international charsets %BR%\
                                              - ignore HTML tags in cite keys -- Foswiki:Main.PaulHarvey |
|  05 Dec 2010 | 2.2.1: Foswikitask:Item10113 - Fix incorrect use of Foswiki 1.1 API |
|  23 Jun 2010 | 2.2: Foswikitask:Item9182 - Be more tolerant of whitespace/capitilisation variations\
                                             -- Foswiki:Main.PaulHarvey |
|  22 Jun 2010 | 2.1: Foswikitask:Item9178 - Fix mod_perl/fastcgi problems; improve handling of cite keys\
                                             using ',",& etc. punctuation chars -- Foswiki:Main.PaulHarvey |
|  18 Jun 2010 | 2.0: Foswikitask:Item8394 - Made citation [refs] hyperlinks -- Foswiki:Main.PaulHarvey <br/>\
                 2.0: Foswikitask:Item8459 - Convert plugin from =commonTagsHandler= to =registerTagHandler=\
                                             and general code cleanup; Added Foswiki 1.1 compatibility; Minor\
                                             performance improvements; Added inline alerts to aid user when\
                                             citing missing references or using missing reference topics\
                                             -- Foswiki:Main.PaulHarvey |
|  29 Jan 2010 | 1.1: Foswikitask:Item8440 - Expand Macros in References -- Foswiki:Main.AndrewJones |
|  17 Mar 2009 | 1.0: Foswikitask:Item1251 - Initial release for Foswiki -- Foswiki:Main.AndrewJones |
|  28 Aug 2005: | Adhering to official handlers in TWiki:Codev/DakarRelease. Added <code>%<nop/>CITEINLINE{...}%</code>. |
|  23 Aug 2004: | Added multiple references sources support |
|  17 Jun 2004: | Initial version |
|  Dependencies: | <table class="foswikiTable" border="1"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">HTML::Entities</td><td align="left">&gt;=1.25</td><td align="left">Required. Available from [[http://cpan.uwinnipeg.ca/search?query=HTML%3A%3AEntities&mode=dist][CPAN]].</td></tr></table> |
|  Plugin Home: | http://foswiki.org/Extensions/%TOPIC% |
|  Development: | http://foswiki.org/Development/%TOPIC% |
|  Support: | http://foswiki.org/Support/%TOPIC% |

__Related Topics:__ %SYSTEMWEB%.DefaultPreferences, %USERSWEB%.SitePreferences, [[%SYSTEMWEB%.Plugins][Plugins]]

<!-- Do _not_ attempt to edit this topic; it is auto-generated. Please add comments/questions/remarks to the Development topic on foswiki.org instead. -->
This topic: System > BibliographyPlugin
Topic revision: 29 Aug 2005, ProjectContributor (raw view)
Copyright © CC-BY-SA by the contributing authors. All material on this collaboration platform is copyrighted under CC-BY-SA by the contributing authors unless otherwise noted.
Ideas, requests, problems regarding Foswiki? Send feedback