WikiTrust is an open-source MediaWiki extension that computes the
origin and author of every word of a wiki, as well as a measure of
text trust that indicates the extent to which text has been revised.
To use WikiTrust, you click on a special wiktrust tab added by the
extension.  In the resulting view, the portions of a page that changed
recently appear with orange background; the more intense the orange
color is, the less the change has been revised.  By clicking on any
word, you can determine who inserted the word, and you can examine the
precise context in which the word was inserted. 

There are three main ways of using WikiTrust: 

U1) As a MediaWiki extension, which analyzes the text of a wiki in
real-time, as edits are made.   This is what is described in this
README file. 

U2) As a Mediawiki extension, where the Mediawiki code, and the
WikiTrust code, are installed on separate servers, for scalability and
separation of concerns.  This is an advanced installation type; you
can find some instructions on README-WMF, but we are still working on
the documentation.  If you have just downloaded WikiTrust, this is
most likely not the mode of use that suits your needs.

U3) As a batch tool for analyzing large Wikipedia dumps, for extracting
statistical information, or to prepare for use U1) by analyzing in an
efficient way the past history of a Wikipedia.  This use is described
in more detail in README-batch. 

When used as a Mediawiki extension, WikiTrust can be added to an
existing wiki, or to a new one.  If the extension is added to a new
wiki, it will start computing reputations and trusts as soon as
someone makes an edit, or requests to view a trust-colored revision.
The reputation and trust computation takes some time, after which the
coloring is available.  If you switch the extension off, then on, the
extension will compute the missing reputation and trust values in a
self-healing, fault-tolerant fashion.


AUTHORS:

- Luca de Alfaro (luca@dealfaro.com)
- Ian Pye (ipye@gmail.com)
- Bo Adler (thumper@alumni.caltech.edu)

We also acknowledge the contributions of:

- Krishnendu Chatterjee (krish.chat@gmail.com)
- Vishwanath Raman (vishwa@soe.ucsc.edu)
- Gillian Smith
- Marco Faella (mfaella@na.infn.it)
- Jason Benterou


INSTALLATION PROCEDURE:

We describe in this README file the use of WikiTrust as a MediaWiki
extension.  For other uses of WikiTrust, see the other README files.


PREREQUISITES:

1) This step is not necessary to compile WikiTrust per se, or for uses
   U2), U3) above, but it is necessary if you want to use WikiTrust as a
   MediaWiki extension (use U1), and display the text trust coloring of
   revisions.

Install mysql and mediawiki.  In Ubuntu / Debian, you can install
the packages: 

     mediawiki
     php5-cli
     mysql-server
     mysql-client
     tidy

   In other distributions, follow the instructions at
   www.mediawiki.org.


================================================================

2) This step involves compiling WikiTrust from source code, and is of
   course always needed, for all usage modes U1), U2), and U3).

   First, use the package manager of linux to install the development
   library for mysql.  On Ubuntu or Debian, this is package
   libmysqlclient16-dev

2a) You need to install some packages for Ocaml.  There are two ways. 

   2a1) The best way is to use godi (http://godi.camlcity.org), as this
        provides a simple way to get all the packages you need, and it
	enables you to build everything in userspace.

        Get godi from http://godi.camlcity.org/godi/index.html and
        download godi. Follow the instructions to install it.  

	IMPORTANT: Remember to set the path correctly as instructed in
	the godi instructions, and remember to have it set correctly
	_before_ you install any additional Ocaml packages.
	Otherwise, the packages might get installed in the wrong places.

        Then, install the following Ocaml packages from godi (use
        godi_console to install them):

          godi-extlib
          godi-findlib
          godi-json-static
          godi-json-wheel
          godi-ocaml-mysql
          godi-ocamlnet
          godi-pcre
          godi-sexplib
          godi-type-conv
          godi-xml-light
          godi-zip

   2a2) If you do not wish to use godi, you can get the above packages
        either from their source, or from the linux distribution you
        are using.  For Ubuntu or Debian, you can use the following
        packages:

          ocaml (version 3.10.0 or greater)
          ocaml-base
          ocaml-native-compilers
          libextlib-ocaml-dev
          ocaml-findlib
          libjson-static-camlp4-dev
          libjson-wheel-ocaml-dev
          libmysql-ocaml
          libmysql-ocaml-dev
          python-mysqldb
          libocamlnet-ocaml
          libocamlnet-ocaml-bin
          libocamlnet-ocaml-dev
	      libpcre-ocaml-dev
          libsexplib-camlp4-dev
          libtype-conv-camlp4-dev
          libxml-light-ocaml-dev
          libzip-ocam
          libzip-ocaml-dev

2b) You need to obtain OcamlLdaLibs.  You can get it from 
    http://github.com/collaborativetrust/OcamlLdaLibs
    First, do:

        $ cd OcamlLdaLibs

    Then, there are various cases:

    - If you used godi:
        $ make all

    - If you can install Ocaml libraries without sudo rights: 
        $ make all

    - If you did not use godi, and you need sudo to install Ocaml libraries:
        $ make all-sudo

2c) Go in the extensions directory of MediaWiki, and get the WikiTrust
    code (as a tarball, or via git) from 
    http://github.com/collaborativetrust/WikiTrust
    You can compile the code with:

      $ cd WikiTrust
      $ make clean ; make all ; make allopt

    This creates an eval_online_wiki executable, which is what
    computes text trust and origin, and author reputation, in a wiki.
    The executable is called whenever someone edit the wiki, or wishes
    to see a trust-colored version of a page.

3) You should activate the extension by editing the file
   LocalSettings.php (part of the MediaWiki installation), adding the
   following lines:

$wgUseTidy = true;       // Enable Tidy
$wgUseAjax = true;       // Enable Ajax (needed for voting)
require_once( $IP . "/extensions/WikiTrust/WikiTrust.php" );
ini_set( 'memory_limit', '40M' );

   You can look in WikiTrust.php (located at WikiTrust/WikiTrust.php)
   for a list of all the configurable variables.  The defaults should
   be correct for most installations, but you can override
   values by placing assignments in your LocalSettings.php
   before the require_once() call for the WikiTrust extension.

   Some settings that you might like to use instead:

     $wgWikiTrustGadget = "gadget-WikiTrust";
   By default the trust tab is always visible.
   Set this as above to make it visible only to users opting in.

     $wgWikiTrustShowVoteButton = false;
   The default is to always show a "vote" button; disable this
   feature by setting it to false.

     $wgWikiTrustLog = "/tmp/{$wgDBname}-trust.log";
   This creates a log of the analysis of how useful each contribution to
   the wiki is, as well as a log of all user reputation changes.
   We advise you to create such a log: it contains very useful
   information, and it is likely that we will develop a variety of tools
   to extract the information present.  You don't want to miss out.  Note
   that you are responsible for rotating and compressing the log (e.g., via
   logrotate, or /etc/logrotate.conf or /etc/logrotate.d/


   As an example, we usually test with these lines added to
   our LocalSettings.php file:

$wgUseTidy = true;
$wgUseAjax = true;
global $wgWikiTrustShowVoteButton;
$wgWikiTrustShowVoteButton = false;
require_once( $IP . "/extensions/WikiTrust/WikiTrust.php" );


4) You need to make the installation readable from the web server. 

     $ chmod a+rX /var/lib/mediawiki/extensions/WikiTrust/*.php
     $ chmod -R a+rX /var/lib/mediawiki/extensions/WikiTrust/includes
     $ chmod -R a+rX /var/lib/mediawiki/extensions/WikiTrust/css
     $ chmod -R a+rX /var/lib/mediawiki/extensions/WikiTrust/js

   Be careful not to give access to the web server to the other files,
   as there may be obscure security issues associated with, for
   instance, your web server having access to the .git directory (if
   you got wikitrust via git).

5) You need to create the database tables that the trust coloring
   extension will use.  Assuming that the mediawiki database is called
   "wikidb" (this is the default name: you give a name to the database
   when you create the wiki instance during the MediaWiki installation
   process), proceed as follows:

     $ cd sql
     $ ./create_db.php "path_to_mediawiki" "mysql_root_user_name"

   where path_to_mediawiki is the path to the mediawiki installation.
   A typical command for Ubuntu is:
     $ ./create_db.php /usr/share/mediawiki root

   If you need to remove the tables first, then do instead:

     $ cd sql
     $ ./create_db.php "path_to_mediawiki" "mysql_root_user_name" remove
     $ ./create_db.php "path_to_mediawiki" "mysql_root_user_name"

6) If there are already revisions in the wiki, you should first
   analyze their trust, via (from the main WikiTrust directory):

     $ analysis/eval_online_wiki -db_user <username> -db_pass <pwd> -db_name <db_name>

   The above command analyzes all revisions in a single sweep.  You
   should expect a speed of between 10 to 60 revisions per second,
   depending on your hardware.  You can launch multiple
   eval_online_wiki in parallel, and they play nicely with each other.
   We fould that the performance increased up to 4 or 5 simultanous
   processes; beyond that, the database is the bottleneck.  This is
   however very hardware dependent.  If you prefer, you can limit each
   invocation of the command to a certain number of revisions, for
   example 1000, by doing:

     $ ./eval_online_wiki -n_events 1000 -db_user <username> -db_pass <pwd> -db_name <db_name>

   You can then give the command many times, until all the wiki is
   analyzed.  You can also slow down the processing via the
   -throttle_delay option, if you wish to limit the CPU or database
   load; for instance

      -throttle_delay 0.2

   will insert a 0.2-second delay between the analysis of revisions.
   eval_online_wiki has many options, of which only some are
   documented here.
   Typical values for database username and password are:

     username: wikiuser
     db_name: wikidb

   If you wish to redo the analysis from scratch, throwing away the
   results of previous analyses, you can use the option '-delete_all':

     $ ./eval_online_wiki -delete_all -db_user <username> -db_pass <pwd>  -db_name <db_name>

   Warning: the analysis can take a long time on very large wikis, so
   do not use the option '-delete_all' lightly!

7) You should now see a trust tab.  Click on it, or edit a revision, and
   the trust of all revision text, and the reputation of all authors,
   will be computed.

   The trust coloring is updated automatically whenever a user edits
   an article, or requests to view the trust informaton for a
   revision.  In particular, when a user edits an article, or when
   someone asks to view the trust information, WikiTrust computes the
   trust coloring not only for the newest revision, but for all past
   revisions of all wiki articles that have not been colored yet.