Difference between revisions of "Wgraph:Fundamentals"

Revision as of 12:37, 15 August 2007

Wgraph -- The Idea

There are many situations where a small picture can help more than a long piece of text. Note that picture in this context does not mean 'photo' or 'image' but graphical visualization of connections. So we better talk about 'diagrams' or graphs.

Wgraph provides a language to define graphs. In accordance with wiki philosophy it is NOT Wysiwyg, but offers a simple text notation instead. So be prepared to express the structure of your graph as a piece of text.

Why would one want to do this? There are so many painting tools out there...

First

• First, there is no media gap. You can stay within the wiki text editor and define your graph right there.
• As your graph source is part of the wiki document it can never get lost.
• For the same reason versioning goes automatically along with your article.
• Second, you do not loose time with tossing pixels around. We dare say that it is significantly more efficient to define a graph in WGL notation than to draw the same graph using interactive drawing tools.
• It is easy to translate the text labels of a WGL graph into another language. You can use a normal text editor.
• The graph can contain hyperlinks to wiki articles without the need to specify complex href attributes or to define clickable map areas.

Second

• A strong argument in favor of Wydiwyg ("What you define is what you get") is the use of macros.
• You can define common properties for many graphs in a separate (template) document.
• You can define common properties for certain nodes or egdes by defining 'nodetypes' and 'edgetypes'. You can use semantically meaningful names' for these types. This makes your graph definitions much more readable. Type definitions can be concentrated in (template) documents and thus support multiple graphs with similar semantics.
• You can put your node and edge declarations into separate documents and generate several views on the same set of nodes. This sounds strange but can be very useful for big graphs.
• In general: The more graphs you have the more advantages a textual notation will have.

Third

• The strongest argument is that WGL code can not only be written by hand but can also be produced as the result of a program, possibly another mediawiki extension.
• You can map wiki concepts like categories to WGL concepts like nodetypes. You can visualize things that are already defined in some syntactically recognizable form in your wiki without any manual effort. The combination of two mediawiki extensions (Wgraph and Dynamic Page List) makes it possible to visualize aspects of your wiki as a graph. Something you may have dreamt of for a long time ;-).

Wgraph -- The Implementation

Writing a graph layouter is a complex task. There is only a handful of applications on the globe which do a good job in this area. So the concept was to build a wiki interface layer on top of one of them.

Product Selection

The author of Wgraph (Gero Scholz) opted for aiSee based on some good experiences with test samples and impressed by the competence shown on the aiSee website. Also, the licensing conditions of aiSee seemed more favourable than (e.g.) Tom Sawyer. The most important point was that aiSee accepts a well-defined textual graph definition as input (GDL = graph definition language). It can be used in batch mode for background image generation and there is a rich client available, which allows to view a graph, fold edges and regions and produce a multi-page print etc.

aiSee is a commercial product. People creating brilliant software should be able to earn their living somehow, shouldn´t they? So, if you want to use Wgraph, make sure that you comply to the licensing conditions of AbsInt (the company behind aiSee). Fortunately, with aiSee coming out of the academic area, there is free licensing for non-commercial usage.

Evolution of Wgraph

Wgraph started as a simple, very thin interface layer between the mediawiki engine and aiSee. During the development it proved useful to make some changes and add some features. So Wgraph became 'thicker' and grew to a full parser for a separate language which was called WGL. Of course WGL is still very close to GDL, but there are some differences:

WGL syntax is much more tolerant than GDL

• you can use ':' or '=' between keywords and their values but you need not. Spaces around ":" or "=" are allowed. (GDL requires a ":" and does not accept a space between the property name and the ":").

splines : yes is the same as splines=yes or simply splines yes

• you can use space or comma to separate several property assignments

splines=yes, xspace=100 is the same as splines yes xspace 100

• optional keywords 'from' and 'to' in edge definitions for those who like it more verbose
• boolean properties accept 'true' and 'yes', resp. 'false' and 'no' as values
• if a command expects a list of types or nodes, the names can be separated by comma or semicolon; spaces after the comma or semicolon will be ignored. So region{ sources "a,b, c" } is equivalent to region { sources a;b;c }

Quoting literals is more flexible

• literals need only be quoted if they contain space or comma
• single and double quotes can be used
• you can concatenate quoted strings by simply putting them behind each other (using the same type of quotes)

Wiki like syntax

• two or three single quotes can be used for italic an bold texts
• <u> provides underlining
• markups can be nested (which is not the case in GDL)
• Wgraph is implemented as a parser function; this allows to use other template calls within the Wgraph call.

common sense notation for colors

• you can use 32 pre-defined color names
• you can use #000000 .. #ffffff notation for individual colors (Wgraph creates a color registry and keeps track of it).

alias names for properties

• font= as an alias for fontname=
• icon= as an alias for iconfile=
• align= as an alias for textmode=
  • values are 'left' ('left_justify), 'center', 'right' ('right_justify')
• layout= as an alias for layoutalgorithm=

Flexible treatment of undefined nodes

• nodes can be used in edges before they are defined
• even if a node is not defined at all, a correct graph will be produced.
• undefined nodes are automatically assigned to the type undefined node
• You can define special layout attributes for this nodetype if you want; you can change its color, shape, visibility or you can even modify its label via the %% replacement symbol

multi-dimensional type concept

• WGL allows you to assign a node or an edge to a number of nodetypes/edgetypes in the same way wiki articles can be assigned to many categories.
• properties that are applicable for nodes can be assigned to nodetypes as well
• properties that are applicable for edges can be assigned to edgetypes as well
• nodetypes and edgetypes live in two separate namespaces.
• attributes of all types to which a node/edge belongs will be transferred to the individual node/edge - as long as they do not ovwerwrite previously defined properties.
• the sequence in which nodetype/edgetype properties are searched can be influenced:
  • normally the sequence in which nodetypes are defined, is taken
  • you can define a precedence list on type level; this gives you control over the sequence in which type properties are assigned to individual nodes or edges
• GDL has a concept which allows to assign an edge to one class. Wgraph generates GDL-edgeclasses which correspond to Wgraph's edgetypes and assigns every edge to one class (if the edge is assigned to one or more edgetypes within Wgraph). Wgraph takes the edgetype with the highest weight an edge is assigned to. Edgetypes are implicitly weighed by the sequence in which they are listed in the WGL code (The first edgetype has weight 100, the next one 99 and so on.) The property "weight" allows to specify weights which change that order.

Property merging

• It is permitted to give multiple definitions for the same node.
• In principle, all property settings for a node are merged. Previous definitions of the same properties will be overwritten.
• Type assignments, however, accumulate.
• Special rules apply to labels: Newer label texts overwrite older label texts. But the symbol %% within the newer text acts like an include for the previously defined contents.
• When nodetype properties are merged with node properties, there will be no overwriting, i.e. type-related properties always act as defaults.
• The special rule for labels also applies to nodetypes.

Example:

node x { label hello       type B    color green                } 
node x { label '%% world'  type A                 shape ellipse }
node x { label "%%!"       type C    color red                  }
nodetype A {label %%\nHere_we_are.   color blue                 }

produces a red ellipse with the text "hello world!Here we are.", because

• red overwrites green
• blue does not overwrite red (blue is on type level)
• node x belongs to types A,B and C (type assignments cumulate)
• label texts of the three node definitions are merged via the %% substitution
• "Here we are." is appended because node x belongs to type A.

Consistent edge hiding

• hiding edges is more consistent than in GDL: if you hide an edge its label and the arrow symbols will be hidden as well (color white). This is not the case in GDL.
• edgetypes in WGL are mapped to "classname" and "class" attributes in GDL; this means that you can use them within the rich client software for interactive filtering.

Filtering

• you can define filters based on nodetypes and edgetypes
• a filter can hide nodes or edges; this means that they are still present in the layout but invisible; thus the layout remains stable if you "hide" nodes/edges
• a filter can eliminate nodes/edges; since they are completely ignored the layout will be constructed based on the remaining nodes/edges only
• a filter can select nodes/edges for display. In this case all other nodes/edges are eliminated.

continue with Wgraph:Architecture ...