Monotone Browser Files

mtn-browse Version 1.20
=======================

mtn-browse is an application for browsing Monotone VCS databases without the
need of a workspace. The interface allows one to:

    * Easily select a revision from within a branch.
    * Find a revision using complex queries.
    * Navigate the contents of a revision using a built in file manager.
    * Display file contents, either using the internal viewer or an external
      helper application.
    * Graph revision histories.
    * Compare the changes between different revisions or versions of a file
      either using the internal difference viewer or an external application.
    * Find files within a revision based on detailed search criteria.
    * Display file annotations and easily refer back to the corresponding
      change documentation.
    * Save files to disk.

For further details on Monotone see http://monotone.ca. For further details on
mtn-browse see http://www.coosoft.plus.com/software.html.


DEPENDENCIES
------------

This program requires these modules and libraries:

    * Perl 5.8.5 or later
    * Gnome and Gtk2
    * The following Perl CPAN modules:
          - Glib (1.144) *
          - Gnome2 (1.040) *
          - Gnome2-Canvas (1.002) *
          - Gnome2-VFS (1.080) *
          - Gtk2 (1.146) *
          - Gtk2-GladeXML (1.006) *
          - Gtk2-SourceView (1.000) *
          - libintl-perl (1.16)
          - Monotone::AutomateStdio (1.02 or later)

Please note that the Gtk2 CPAN bundle will probably satisfy all of the
dependencies marked with * at the end of the line.

Older versions of Perl may work but these have not been tested at this point in
time.

Monotone::AutomateStdio Library
-------------------------------

This library module is a Perl interface to Monotone's automate stdio interface
and is heavily used by mtn-browse. As such it is probably best to upgrade this
library each time you upgrade Monotone itself. For this reason you may decide
to just install this library as a part of mtn-browse. If you need to upgrade
the library then all you need do is just copy the new version into place.

The installation process will, by default, install a copy of this library in
mtn-browse's lib directory.


INSTALLATION
------------

Using Makefile.PL
-----------------

Simply unpack the tar file and use Makefile.PL by doing:

    tar xvpzf mtn-browse-<Version Number>.tgz
    cd mtn-browse-<Version Number>
    perl Makefile.PL
    make
    make test
    make install

To install to a custom location use:

    perl Makefile.PL PREFIX=<PATH>

To configure the software to run in a custom location but have the installation
location prepended by an additional path (useful for package maintainers) use:

    perl Makefile.PL PREFIX=<PATH> DESTDIR=<PATH>

Those of you familiar with CPAN will recognise the above as the standard
mechanism for installing Perl modules (or libraries). However, there does not
seem to be a standard way of installing a Perl application. Since Perl is
largely platform independent, the ./configure; make; make install approach of
automake does not seem right. So I have decided to write a custom Makefile.PL
script that supports some basic installation capability.

In fact Makefile.PL simply calls the installer script, passing any arguments
through to it. The installer script supports some additional options that can
also be specified via Makefile.PL, meaning that the full list of arguments are:

    perl Makefile.PL PREFIX=<PATH> DESTDIR=<PATH> LIBDIR=<PATH> \
                     GLOBS_FILE=<PATH> GRAPHVIZ_DOT=<PATH> \
                     FILE_COMPARISON=<PATH> HTML_VIEWER=<PATH> \
                     NO_USE_DISTS_MAS=1 USE_LABELS=1

For further information on what these options mean please run:

    ./linux-installer -m

PREFIX equates to --prefix, DESTDIR equates to --destdir, LIBDIR equates to
--libdir, GLOBS_FILE equates to --globs-file, GRAPHVIZ_DOT equates to
--graphviz-dot, HTML_VIEWER equates to --help-viewer, NO_USE_DISTS_MAS equates
to --no-use-dists-mas and USE_LABELS equates to --use-labels.

Alternatively one can run the installer directly. See the next subsection.

Using linux-installer
---------------------

As root simply unpack the tar file and run the installer by doing:

    tar xvpzf mtn-browse-<Version Number>.tgz
    cd mtn-browse-<Version Number>
    chmod +x linux-installer
    ./linux-installer -i

and then follow the prompts.

If you wish to do an automated install then all of the options can be specified
on the command line. To get more information on what options are available do:

    ./linux-installer --man

In particular, package maintainers may find the following useful:

    ./linux-installer --prefix=/opt/mtn-browse --destdir=/tmp/install-dir

This tells the installer to configure the installation as if it were going
under /opt/mtn-browse but actually installs it under /tmp/install-dir (i.e. the
application can be found at /tmp/install-dir/opt/mtn-browse/bin/mtn-browse).

The Use Gtk2::Labels Installer Option
-------------------------------------

So what is this option all about then? Well when drawing graph histories,
mtn-browse has two options when it comes to writing text on the graph. It can
either use the method that comes with the main drawing widget, known as a Gnome
Canvas, or the method that is used to display text everywhere else in the
application, Gtk2::Labels.

Gnome Canvas text, to my knowledge, always works perfectly and gives pleasing
results, but because you can do fancy things with it (which I do not make use
of) it can be slow.

Gtk2::Labels on the other hand are more basic and hence much faster, but they
are not really supposed to be used inside canvases and so can behave oddly or
not at all depending on what version of Gtk2 you have and the associated Perl
bindings. This odd behaviour sometimes manifests itself as spidery text or
simply not displaying the text at all at the bottom of very tall history
graphs.

Because I cannot predetermine what will work best for your setup, I give you
the choice of which mechanism to use during installation. Defaulting to the
most reliable but the slowest. Life is never simple!

In order to determine whether you can successfully use Gtk2::Labels in history
graphs, I have set up a little test branch in my public database that can be
used to generate very tall graphs that will test the Gtk2::Label approach.

To test whether Gt2k::Labels will work for your system do the following:
- Install mtn-browse into a test location using ./linux-installer -i. When you
  get to the use Gtk2::Labels question answer yes.
- Optionally create a local copy of the test branch in a database by doing
  something like:
    $ mtn --db=test.mtn db init
    $ mtn --db=test.mtn pull mtn://code.monotone.ca/mtn-browse?net.venge
    .monotone.contrib.mtn-browse.test.long-graph
  (Please note that here is no white space in the above URL, it was just broken
   up to fit nicely into this text file.)
- Run up your test mtn-browse application and then either open your local test
  database or connect to mtn://code.monotone.ca/mtn-browse.
- Select the net.venge.monotone.contrib.mtn-browse.test.long-graph branch.
- Generate a history graph for it.
- Since all revisions were added in a matter of minutes the entire branch's
  history should be graphed but if you want to absolutely make sure, call up
  the change history graph dialog window and remove the time range restriction.
- Scroll to the very bottom of the history graph. Do you see any text inside
  the little coloured boxes? If you do and things seems to be drawn correctly
  then you can probably use Gtk2::Labels without any real issues. If no text
  appears or there are fundamental drawing issues try another test installation
  but this time answer no to the above use Gtk2::Labels question.

For example, with my older RHEL 4.2 system with Perl bindings that I compiled
myself, all works fine using Gtk2::Labels. On my Debian 5 machine it does not
work, but it does on Debian 6.

If you determine that using Gtk2::Labels works markedly better than not using
them on a particular system then I would be interested to know the details.
Please include details of the operating system, where you got the Perl bindings
from and any other relevant libraries, along with their versions. If like
Debian or Ubuntu the packages came from a standard repository then just say so.


COPYRIGHT AND LICENCE
---------------------

Copyright (c) 2007 Anthony Edward Cooper <aecooper@coosoft.plus.com>.

This library is free software; you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the Free
Software Foundation; either version 3 of the License, or (at your option) any
later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along
with this library; if not, write to the Free Software Foundation, Inc., 59
Temple Place - Suite 330, Boston, MA 02111-1307 USA.