This is still under development, but nevertheless usable!


*** CREDITS/REQUIREMENTS ***

First of all you'll need an account at:
- del.icio.us, which is a social bookmark service

These tools are the minimum requirements to get Graphiclious work for you:
- The Ruby interpreter (Graphiclious is implemented in the Ruby programming language)
- Rubygems, the Ruby package manager
- Rubilicious, which makes the del.icio.us-API availiable within Ruby applications
- RGL: The Ruby Graph Library

Note that the Rubygems package manager will automatically ask for
installation of Rubilicious and RGL when installing the Graphiclious gem.

To get the most ut of Graphiclious you'll further need:
- FXRuby, which makes the FOX gui toolkit availiable for Ruby applications
- RMagick, a wrapper ImageMagick, which is a tool for image processing
- Graphviz, a tool for generating nicely layouted graphs
- Piggy, a FTP-Browser written in Ruby

Developers will need Rake, the Ruby make tool, too.

FXRuby and RMagick are availiable as Rubygems. You'll need a FXRuby version >= 1.2
and RMagick might need further installation steps as described on the RMagick
homepage http://rmagick.rubyforge.org/. Graphviz is easy to install, just follow the instructions
at http://www.graphviz.org/.

Note that some of these requirements, e. g. Rubygems and FXRuby, might be contained in your Ruby
installation.

*** GEM INSTALLTION ***

gem install Graphiclious


*** RUNNING GRAPHICLIOUS WITH GEM INSTALLATION ***

Depending on your Ruby installation, it might be enough to run:

graphiclious --gui

On Windows, create a shortcut and set
- the working directory to a directory of your choice (output will be generated into this directory)
- the command:

C:\ruby\bin\graphiclious.cmd --gui --user <your-delicious-name>


*** COMMAND LINE OPTIONS ***

Graphiclious has some useful options, the most mentionable options are:

--help/-h will display a help text containing all options
--gui/-g will start a graphical user interface
--user/-u specify a del.icio.us user (its name will be used as output directory, too)
--password/-p specify password for given user
--version/-v prints actual version

Without gui option you'll need to specify user and password.


*** RUNNING GRAPHICLIOUS WITHOUT GEM INSTALLATION (TYPICAL CASE FOR DEVELOPERS) ***

In general it shoud work to
1. Open a console window
2. Go to the graphiclious library directory (e.g. "cd ~/graphiclious/lib" or "cd C:\graphiclious\lib")
3. Run graphiclious.rb with options of your choice (we recommend option --gui)

Note that there are better ways to run it, but this one is easy to describe and quite platform independent.

On WINDOWS create a shortcut which runs in the directory you want to generate output in
(e. g. C:\homepage\graphiclious) and executes the following command:

C:\ruby\bin\ruby.exe -rubygems -I "C:\graphiclious\lib" -Ilib "C:\graphiclious\bin\graphiclious" --gui

To analyse errors, it might be useful to keep a console open. Try something like this:

C:\WINNT\system32\CMD.EXE /k <command as described above> || pause

On Debian unstable the following works if you have installed the package
libfox-ruby:

1. Go to the graphiclious root directory (e. g. cd ~/graphiclious)
2. Run the following command:

ruby -rubygems -Ilib bin/graphiclious --gui


*** RUNNING THE TESTS ***

Go to the graphiclious installation directory and run rake.


*** USAGE HINTS/KNOWN ISSUES ***

- Downloading all links may take some time if you have lots of tags.
Be patient or better: use the quicker update mode "update recent"!
We try to avoid unnecessary updates by writing a timestamp. If you really
need a second run, delete the file delicious.time before running the program.
Note that the update mode won't use this timestamp.
It is not possible to delete links with the update mode.

- We locally fixed a bug in Rubilicious 1.5 by overriding Rubilicious#all.

- The number of generated files can be very large, it can become something like
3*(b + 2) + n + n*n where n is the number of tags and b is the number of bundles;
there will be no further warning about that.

- Avoid spaces in the working directory you run Graphiclious in.

- Avoid tags that could not be used as a filename
(depends on file system and operation systems, therefore our substitutions might not
cover every possible situation, also substitutions might cause overwrites if tags
only differ in special characters)

- In general, if you use a new feature of del.icio.us: Make sure it is
correctly supported by Graphiclious before making the generated pages public
availiable.

- Html output will be overwritten. Old output will not be deleted so you
need to take care of obsolete files yourself. Note that old files might
contain private links if you once included them and later decided to
ignore them. Delete the whole output and regenerate in this case.