Referees-0.0.0: README.org

#+TITLE: README for Referees v0.0.0
#+AUTHOR: Pablo Couto
#+EMAIL: pablo@infty.in

* Overview

/Referees/ is a tool for computing distributions, among reviewers, of material to review.

It takes into consideration the areas of expertise of the referees, the number of items that they accept for review, the languages they understand, and the minimum and maximum number of copies we may want to distribute per each item to review.

/Referees/ is distributed according to the terms and conditions of the [[https://www.gnu.org/copyleft/gpl.html][GNU GPL v3]] license.

* Example of use

The program reads two CSV files, one for referees and the other for proposals. Each line in these files must have the following format:

: Name,Capacity,Language;…;Language,Area,Subarea;…;Subarea

The =Area= field can be empty but must be present; =Subarea= is also optional.
Note that different =Subarea= (and =Language=) values are separated by =;= within only one field.

=Capacity= and =Language= fields are optional. If only one
of them is included, the program will detect which one on the basis of whether
it contains digits.

If there are many areas (and corresponding subareas) for some =Name=, these go
in different lines, as in the following example:

#+BEGIN_SRC
RefereeA,3,Spanish,Metaphysics,Identity
RefereeA,Greek,Aesthetics
RefereeB,1,PoliticalPhilosophy,State;Justice
RefereeC,Catalan,PhilosophyOfMind,Perception
#+END_SRC

Let’s say we have, then, two files in that format: =referees.csv= and =proposals.csv=. These are the options we have at the command line, as would be shown by passing the =-?= flag:

#+BEGIN_SRC
  referees [OPTIONS] <referees> <proposals>

            --ca=<integer>    Default capacity for referees with none
                              assigned. [default: 1]
            --maxc=<integer>  Number of minimum copies per proposal to
                              distribute. If this value is higher than --maxc,
                              or no --maxc is given, it will also be set as the
                              maximum number of copies to distribute.
                              [default: 0]
            --minc=<integer>  Number of maximum copies per proposal to
                              distribute. [default: 1]
  -l=<text>                   Default language for referees with none
                              assigned. Providing a default language is
                              optional.
  -?        --help            Display help message
#+END_SRC

So, for distributing a minimum of 2 copies and a maximum of 3 per each proposal among the referees, each of them accepting at most 1 proposal, while setting English as /lingua franca/, we would write:

: $ referees "referees.csv" "proposals.csv" --minc=2 --maxc=3 --ca=1 -l=English

This will print a distribution, if any is found – or an informative message if that wasn’t possible.

* Installation

To install Referees, simply use Cabal:

: $ cabal install Referees

You may need to acquire Cabal first with your package manager of choice.

This program relies on [[https://www.gnu.org/software/glpk/][GNU GLPK]], so please make sure you also have it installed.