| Teamwork |
-------------------------->
is the key to |
Victory |
Mediawiki is the software used by the popular
Wikipedia. It allows humans very easily to
create, maintain and improve documents in shared environments.
One of the strengths of the software is that the content is seperated from the
layout. This means that the source of a document/page/article specifies the
structure of the information, but usually not how the information is finally
rendered in the browser.
Today you can easily enter text (headlines, paragraphs, lists etc),
tables, lists and even mathematical formulas.
What is missing, however, is an easy way to describe flow graphs like
network plans, flow charts,
organizational diagrams and similiar things.
This project changes this.
This extension is quite stable and works good - have a look at the "graphic"
at the top of this page :)
However, some features still need to be implemented, and of course, bugs to be fixed.
Currently the development goes in the following directions:
- Improve the underlying graph package to deal with:
- more complicated descriptions (nested graphs etc.)
- more complicated graphs/layouts
- Improve the HTML/CSS output to generate slants for diamonds, triangles etc.
- Improve the Graphviz and SVG output
- Improve the integration into the Mediawiki software (user preferences, caching)
- Add animation support
Read more
details
about the current limitations in the underlying graphing package.
These limitations will be overcome when the software behind the scenes
improves. However, the software already works quite good. If you
find anything missing or encounter bugs, please file a bug report at
rt.cpan.org.
This project has a few goals:
- KISS (Keep It Simple, Stupid - sometimes less is more)
- Simple syntax. Just like the media wiki table syntax is much easier
than HTML tables, the graph text descriptions should be human
readable and human maintainable, while still easily
machine parsable.
- Do away with grafics and dependecies on external software. Creating
graphs in Gimp or any other external program (Viseo etc) has some
serious drawbacks. They are either awkward to use (creating complex
graphs manually takes time and skill) and/or the result is not easily
changeable (you need software and time and skill again).
- Seperate content from layout - the actual layout will
be done automatically. This makes changes much easier because you do not need
to worry about to fit the graph.
- Seperate content from style - changing the overall style (colors,
borders etc) will be easier (think: HTML + CSS) if these are not
intermingled
- Make the output look good.
The last point is quite difficult to define, and without definition of what looks
good we cannot achive that goal. However, there are a few rules we should
obey:
- Elements should not stick together. There should always be space between text
and borders, as well as lines and text, even if it are only 2 pixels.
- Things should not cross into other. This means especially labels, which should
never be inside a line, border or other text.
- No pixelations. Rectangles look good, as well as antialiased text. Circles
without antialiasing do not. Edges that are not straight are not good, either.
- For artistic and stylish reasons hinting should be implemented, giving the
user the ability to influence the layout (edge directions and node placement).
This would allow for specific designs, were not only the graph contents, but
the graph layout itself is part of the artwork. Thing for instance graphs laid out
like a big star, fish, box, spiral etc.
| Textual description |
------> |
Parser |
------> |
Layouter |
------> |
Output (ASCII/HTML/SVG etc) |
The Mediawiki extension takes text between <graph> and
</graph> and feeds it to an external program. This uses a Perl
module named Graph-Easy to
render the graph description either as ASCII art, as pretty HTML,
as Scalable Vector Graphic (SVG) or a graphviz code, which can be fed to dot
to render PNG files.
The graph text syntax is modelled after an easy mnemonic
("[ Bonn ] --> [ Berlin ]" looks already like the final graph will be typically
rendered, two boxes connected by an arrow)
and the most important feature is ease-of-use and simplicity (for both
human and machine). The language is (almost completely) white-space,
newlines and order invariant, and supports full Unicode.
This means you can move objects around, insert white-space and
newlines to make the source more readable, without accidentily
changing the resulting graph or layout.
The language also separates style from content by allowing all objects
to have a class and attributes to be set class-wide, thus enabling
quick style changes of everything with little edit effort.
Please see the online manual for many examples and
explanations.
You can see the Mediawiki integration at work at this
Mediawiki graph test page.
Mediawiki-POD
Top -^
The Mediawiki-POD extension
also uses Graph::Easy to parse graph paragraphes embedded into POD to
generate HTML documents such as
this perl atlas.
Graph::Easy has no dependencies itself (except
Perl v5.8.1 or better), but to integrate it into Mediawiki, you need
the following additional Perl modules (and/or
graphviz):
The following optional packages can be used to get more output options:
If http://search.cpan.org is down, you can also look
here for the Perl modules.
You can either install these Perl modules into your system (this needs usually
administrator rights), or install them locally into a directory.
The latter step is explained in detail in the mediawiki-graph extension's INSTALL
file.
To install the Perl modules in your system, you can use CPAN for this:
su
perl -MCPAN -e 'shell'
> install Graph::Easy
> install Digest::SHA1
> install Config::Tiny
> install Graph::Easy::As_svg
This will install all dependencies, too. If the automatic install fails,
for most Perl modules out there you can use the following sequence:
untar Some-Perl-Module-0.01.tar.gz
chdir Some-Perl-Module
perl Makefile.PL
make test
sudo make install
If unsure, a file called INSTALL or README in each of these modules will have further info.
Then unpack the mediawiki-graph-0.21.tar.gz
file and integrate it into Mediawiki by following the instructions in the
README (it's easy :-). Afterwards it should work like in the screenshots below.
The Graph::Easy distribution contains also a script called graph-easy, which
is installed into your system so you can use it from the any prompt.
This script parses and outputs the various graph formats and thus allows
conversion between the formats as well as rendering either via Graph::Easy
or dot et al. For more information see the
graph-easy online help
or type graph-easy --help.
There is also a page with screenshots.
Here is a short list of things to do regarding the Wikimedia integration:
- Find out how to get the parameters after
<graph ...> to
graphcnv - this lets us deal will multiple HTML graphs in
one page.
Currently the gid: 123; syntax inside the
<graph> must be used to make more than one graph with
different styles work properly.
- A way to insert a page with options into the user preferences must be found.
Currently the user will always get HTML output and can only choose a
different output style like ASCII by editing the graph syntax and inserting
output: ascii;.
The underlying software package, Graph::Easy,
also needs a lot of work. Please see the
TODO list and the
Graph::Easy limitations.
Contact and Bugreports
If you have questions, feel free to send me an email
(Gnupg key).
Bugreports should go to rt.cpan.org.
I would like to thank the following people (in alphabetic order):
- Evstyugov-Babaev, Alexander A. - for specs and information about
GDL
- Beuker, Scott - for the highly interesting discussions and pushing me to improve ASCII output
- Biggi - layout/text critics of these pages
- Bortzmeyer, Stéphane - for bug reports and example files
- Boswell, Phil - IE testing and bug reports for the manual CSS
- Coffman - for the competition :)
- the Graphviz development team - for the competition :)
- Hietaniemi, Jarkko - for the Graph module, even though I no longer use it
- Jenkins, Nick - for much feedback, bug reports and generally being nice :)
- Lindner, Florian - For countless bug reports, testing and feature suggestions
- Mutante - for prodiving feedback and the first installion on a live wiki
- O Love - HTML and CSS help, Opera & IE testing
- Omega - early beta tests, first to notice broken links =)
- Voss, Jakob - for the idea of adding links
See also the
Wikimedia Graphviz extension
and
WikiSophia.
The following sites (list is not complete) already use this extension or Graph::Easy: