=pod

=head1 graphcnv

Take textual graph descriptions and turn them into something that looks pretty.

This package is intended to integrate Graph::Easy into Wikimedia, the software
behind popular wikis like http://en.wikipedia.org/.

For instance this input:

	[ Bonn ] -> [ Berlin ]
	[ Berlin -> [ Frankfurt ] { border: 1px dotted black; }
	[ Frankfurt ] -> [ Dresden ]
	[ Berlin ] -> [ Potsdam ]
	[ Potsdam ] => [ Cottbus ]

would be rendered in ASCII as:

	+------+     +--------+      .............     +---------+
	| Bonn | --> | Berlin |  --> : Frankfurt : --> | Dresden |
	+------+     +--------+      .............     +---------+
	               |
	               |
	               v
	             +---------+     +---------+
	             | Potsdam | ==> | Cottbus |
	             +---------+     +---------+

The HTML output would look similiar except be more pretty :o)


=head1 Check the Signature

First you need to check the signature on the package to verify that
it is untampered and intact. To do this you have to:

=over 2

=item *

Install the Perl module Module::Signature from http://search.cpan.org

=item *

Get my key from http://bloodgate.com/tels.asc, import it into
GnuPG with:

	gpg --import tels.asc

You may also let the C<cpansign> utility fetch it automatically
from a keyserver, if that works for you.

=item *

Extract the package to a directory, change there and then:

=item *

Type on a console:

	cpansign --verify

inside the unpacked directory. 

=back

If the last step says "good signature" or "SIGNATURE VERIFIED OK",
everything is all right.

Note that if C<cpansign> let GnuPG download my key from a keyserver, it
might put a C<tels.asc> file in the package directory, and then afterward
complain that "tels.asc" is not in the MANIFEST:

 Not in MANIFEST: tels.asc
 ==> MISMATCHED content between MANIFEST and distribution files! <==

You can safely ignore this warning.

B<NOTE:> Please notify me immidiately if the signature
does not verify. In that case do B<NOT> install this software, your system
might get compromised!

=head1 Installation

Install the following Perl modules into your system:

	Heap
	Graph-Easy
	Graph-Easy-As_svg	(optional, for SVG output)

You can get these modules from C<http://search.cpan.org/>.

Afterwards, you should be able to run this on any command line:

	perl -MGraph::Easy\ 99

and it should report your installed Graph::Easy version (like v0.30).

	Graph::Easy version 99 required--this is only version 0.30.
	BEGIN failed--compilation aborted.

If it says something about "Graph::Easy" not being found, you need to
install it first as root (see above!).

Note: You do NOT need to install Graph::Simple (the former name of
Graph::Easy), nor Graph (formerly used by Graph::Easy). If they are already
installed, that will not do any harm, however.

=head2 Run the testsuite

Run in the directory of this package:

	perl Makefile.PL
	make test

All tests should pass. If not, please notify me.

Then place the contents of this mediawiki-graph.tar.gz file so that it
is a subdirectory named 'graph' of your wiki installation like this:

	http_docroot
		\ - cgi-bin			etc
		\ - wiki
			\ - graph		<-- here
			\ - math		etc

Make a backup of your wiki directory! I repeat, MAKE A BACKUP! You have been
warned!

Now copy B<all> the files from the C<extensions/> subdirectory of C<graph> to
to the extension dir of your wiki, like so:

	http_docroot
		\ - cgi-bin			etc
		\ - wiki
			\ - graph
				\ - extensions	<-- from here
			\ - extensions		<-- to here

At present this is only one file, C<Graph.php>.

Then include the following line in your C<LocalSettings.php>:

	include('extensions/Graph.php');

Now you should be able to edit any page of the wiki and insert:

	<graph>
	[ Bonn ] -> [ Berlin ]
	</graph>

and hit preview.

If you get error messages like:

	Error running graphcnv.

make sure that you can run manually (from your wiki directory):

	./graph/graphcnv '[ Bonn ] -> [ Berlin ]' 'utf-8' 'ascii'

and get a pretty ASCII art back.

For more information please see L<http://bloodgate.com/perl/graph/>
or send me an email.

=head1 SVG OUTPUT

To enable SVG output, you need to create a directory for the C<.svg>
files that will be generated for the graphs. (Inlining the SVG code in
the HTML page directly does not work, since no browser seesm to support
this properly at this time).

The C<.svg> files are currently written to C<./images/graph/> so you need
to make sure that this directory exists and is writable by the web server
process:

	http_docroot
		\ - cgi-bin			etc
		\ - wiki
			\ - images
				\ - graph	<-- create this directory
			\ - extensions		etc

=head1 AUTHOR

Copyright (C) 2004 - 2005 by Tels http://bloodgate.com/

Contact: <nospam-abuse@bloodgate.com> (literally :)

This library is free software; you can redistribute it and/or modify
it under the same terms of the GPL version 2.