SoundSoftware Code Site

h1. Bibliography Plugin Documentation

We're developing a Plugin to manage project's and user's bibliographical entries. In the issue tracker it is named _feature_36_.

* [[BibliographyOngoingReviewNotes|Ongoing miscellaneous review notes]] from testing during development

* [[BibliographyPluginAlphaVersion|Plugin's Alpha Version Requisites and Notes]]

h2. Objective and Philosophy

Projects hosted on code.soundsoftware.ac.uk are usually associated with academic publications (papers, articles, etc). These often offer a strong theoretical background to the code that's being hosted on this site, and many times are the only way users can understand what's happening under the hood for a specific project. On the other hand many researchers are now adopting a "reproducible research" philosophy, in which they not only publish the paper/article itself, but also the code and/or data that supports such publication.

The main idea behind this module is to be able to provide a service that ties both features together, making it easy for researchers to make their source code and publications available on the same platform.

Since Redmine is a project-oriented platform, it makes sense that the publications can only be *created, edited, deleted, etc* in the project's scope. 

h2. Plugin Architecture

h3. Permissions

The following permissions were created: 

* view

* add

* edit

* delete  

h3. Models

h4. Publications

h4. Bibtex_Entries

h4. Authors

h4. Authorships

Model that "ties" the authors and publications models together. It contains relation-specific information: 

* @name_on_paper@: author's name on that specific publication;

* @order@: author's order in that publication;

* @institution@: author's institution when the publication was published;

* @email@: author's email on that specific publication.

h3. Relationships

NOTE: upload the class UML. 

h3. Tying it all togheter

This is the complete documentation used to create the plugin:

http://www.redmine.org/projects/redmine/wiki/Hooks

h3. Views

There should be two main ways to browse publications:

# General

# Project 

h4. General Publications View

All the publications published in the website.

h4. Project Publications View

All the publications related to a specific project.

h4. My Publications

In the My Page, there should be a "box" with a list of all the publications added by the user and/or publications where the user is an author

h2. Bibtex Parsing: necessary gems

* Bibtex parsing: *bibtex-ruby* (https://github.com/inukshuk/bibtex-ruby)

* Bib entries formatting: *citeproc-ruby* (https://github.com/inukshuk/citeproc-ruby)

** needs nokogiri gem: http://nokogiri.org/tutorials/installing_nokogiri.html

*** need to have @libiconv@ installed

h3. Installation instructions (tested on eclectus, as root)

<pre>

  gem install bibtex-ruby

  apt-get install libxslt-dev libxml2-dev

  apt-get install ruby1.8-dev ruby1.8 ri1.8 rdoc1.8 irb1.8

  apt-get install libreadline-ruby1.8 libruby1.8 libopenssl-ruby

  gem install nokogiri

  gem install citeproc-ruby 

</pre>

h2. Deployment notes

h3. Migrations 

<pre>

  rake db:migrate:plugin NAME=redmine_bibliography VERSION=version

</pre>

After running the migrations, you need to seed the publication types:

<pre>

  rake redmine:plugins:redmine_bibliography:seed_bibtex_entry_types

</pre>