SoundSoftware Code Site

h1. Bibliography Plugin Documentation

{{>toc}}

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>

h2. Tests

Running test files directly using the rails runner:
<pre>
script/rails r plugins/redmine_bibliography/test/unit/publication_test.rb
</pre>