Introduction
------------

The graphviz parser module allows descriptions of graphs suitable for
interpretation by the Graphviz suite of tools to be embedded within Wiki
pages.

Installation
------------

First, make sure that the BINARY_PATH setting in the graphviz.py module (found
in the parsers directory) is suitable for your system. Then, copy the
graphviz.py module into your Wiki's parsers directory.

With moinsetup and a suitable configuration file (see "Recommended Software"
below), you can perform this last step as follows, with $GVDIR referring to the
GraphvizParser distribution directory:

  python moinsetup.py -f moinsetup.cfg -m install_parsers $GVDIR/parsers

Basic Usage
-----------

To embed a visualisation of a graph in a Wiki page, try the following:

{{{#!graphviz
digraph G {
    A -> B;
};
}}}

Advanced Usage
--------------

This parser will check the first lines of the Graphviz data for C++ style
comments instructing it to use a different filter (dot, neato, twopi, circo,
or fdp - see http://graphviz.org/ for more information), use a different
format for the output (see the OUTPUT_FORMATS list in the Parser class), or to
generate and pass a client-side imagemap.

Options:

filter  - the filter to use (see Parser.FILTERS)
format  - the output format (see Parser.OUTPUT_FORMATS)
cmapx   - the map name to use for the client-side imagemap; this must match
          the graph name in the graph definition and shouldn't conflict with
          any other graphs that are used on the same page; for SVG images, the
          cmapx option is superfluous since SVG supports linking natively and
          Graphviz converts "href" attributes appropriately

To embed a visualisation of a graph in a Wiki page, using the dot filter and
providing a client-side imagemap (the filter=dot and format=png options are
redundant since those are the defaults for this parser), try the following:

{{{#!graphviz
//filter=dot
//format=png
//cmapx=DocumentationMap
digraph DocumentationMap {
    FrontPage [href="FrontPage", root=true];
    HelpOnEditing [href="HelpOnEditing"];
    SyntaxReference [href="SyntaxReference"];
    WikiSandBox [href="WikiSandBox", color="grey"];
    MoinMoin [href="http://moinmo.in"];
    FrontPage -> WikiSandBox;
    FrontPage -> MoinMoin;
    WikiSandBox -> HelpOnEditing;
    WikiSandBox -> SyntaxReference;
    SyntaxReference -> FrontPage;
};
}}}

As noted above, for SVG output an imagemap definition need not be used, since
SVG as a format supports hyperlinks.

Known Issues
------------

  * The parser could benefit from being checked for potential methods of
    injecting arbitrary HTML into the page output, even though the formatter
    interface is being used to generate the output.

  * The parser only be useful or compatible with HTML rendering, although the
    generic formatter interface is used to format the output and could support
    any page format that can present images and objects in a similar fashion.

  * The code may not use all of the MoinMoin interfaces properly. Particularly
    the manipulation of attachments might be better done through any
    Moin-level abstractions instead of at the file level.

  * Comments must start at the beginning of the graphviz block and at the
    beginning of their respective lines. They must also not contain any extra
    whitespace surrounding the = sign. It would arguably be better if the
    configuration of images were done using the argument notation employed by
    other parsers.

  * SVG image sizing can only be done by extracting the dimensions from an
    uncompressed ("svg" format, not "svgz" format) output representation.
    Moreover, the extraction process assumes that the "width" and "height"
    attributes appear in an "svg" start tag of a particular form.

  * Beyond SVG size detection there is no support for determining the size of
    output representations that cannot be inserted into a page as an image.
    Thus, most of the supported output formats may cause inappropriately sized
    objects to appear in a page because the browser has not been able to
    determine the size of the object in advance.

Recommended Software
--------------------

See the "Dependencies" section below for essential software.

The moinsetup tool is recommended for installation since it aims to support
all versions of MoinMoin that are supported for use with this software.

See the following page for information on moinsetup:

http://moinmo.in/ScriptMarket/moinsetup

Dependencies
------------

The graphviz parser has the following basic dependencies:

Packages                    Release Information
--------                    -------------------

graphviz                    Tested with 2.16
                            Source: http://www.graphviz.org/

Contact, Copyright and Licence Information
------------------------------------------

See the following Web page for more information about this work:

http://moinmo.in/ParserMarket/graphviz

The author of this packaging of the original work can be contacted at the
following e-mail address:

paul@boddie.org.uk

Copyright and licence information can be found in the docs directory - see
docs/COPYING.txt and docs/LICENCE.txt for more information.

New in GraphvizParser 0.2.3 (Changes since GraphvizParser 0.2.2)
----------------------------------------------------------------

  * Fixed graph attachment detection where no dimension attributes are
    specified.

New in GraphvizParser 0.2.2 (Changes since GraphvizParser 0.2.1)
----------------------------------------------------------------

  * Removed request.flush usage where the method does not exist (in Moin 1.9).

Release Procedures
------------------

Update the parsers/graphviz.py __version__ attribute.
Change the version number and package filename/directory in the documentation.
Update the release notes (see above).
Tag, export.
Archive, upload.
Update the ParserMarket and ParserMarket/graphviz page.
