1.1 --- a/README.txt Sat Jan 14 19:17:36 2012 +0100
1.2 +++ b/README.txt Sat Jan 14 20:40:47 2012 +0100
1.3 @@ -1,7 +1,27 @@
1.4 +Introduction
1.5 +------------
1.6 +
1.7 +The graphviz parser module allows descriptions of graphs suitable for
1.8 +interpretation by the Graphviz suite of tools to be embedded within Wiki
1.9 +pages.
1.10 +
1.11 +Installation
1.12 +------------
1.13 +
1.14 +First, make sure that the BINARY_PATH setting in the graphviz.py module (found
1.15 +in the parsers directory) is suitable for your system. Then, copy the
1.16 +graphviz.py module into your Wiki's parsers directory.
1.17 +
1.18 +With moinsetup and a suitable configuration file (see "Recommended Software"
1.19 +below), you can perform this last step as follows, with $GVDIR referring to the
1.20 +GraphvizParser distribution directory:
1.21 +
1.22 + python moinsetup.py -f moinsetup.cfg -m install_parsers $GVDIR/parsers
1.23 +
1.24 Basic Usage
1.25 -----------
1.26
1.27 -Embed a visualization of a graph in a wiki page:
1.28 +To embed a visualisation of a graph in a Wiki page, try the following:
1.29
1.30 {{{#!graphviz
1.31 digraph G {
1.32 @@ -14,23 +34,23 @@
1.33
1.34 This parser will check the first lines of the Graphviz data for C++ style
1.35 comments instructing it to use a different filter (dot, neato, twopi, circo,
1.36 -or fdp - see http://graphviz.org/ for more info), use a different format for
1.37 -the output (see the FORMATS list in the Parser class), or to generate and pass
1.38 -a client-side image map.
1.39 +or fdp - see http://graphviz.org/ for more information), use a different
1.40 +format for the output (see the OUTPUT_FORMATS list in the Parser class), or to
1.41 +generate and pass a client-side imagemap.
1.42
1.43 Options:
1.44
1.45 filter - the filter to use (see Parser.FILTERS)
1.46 -format - the output format (see Parser.FORMATS)
1.47 -cmapx - the map name to use for the client-side image map; this must match
1.48 +format - the output format (see Parser.OUTPUT_FORMATS)
1.49 +cmapx - the map name to use for the client-side imagemap; this must match
1.50 the graph name in the graph definition and shouldn't conflict with
1.51 any other graphs that are used on the same page; for SVG images, the
1.52 cmapx option is superfluous since SVG supports linking natively and
1.53 Graphviz converts "href" attributes appropriately
1.54
1.55 -Embed a visualization of a graph in a wiki page, using the dot filter and
1.56 -providing a client-side image map (the filter=dot and format=png options are
1.57 -redundant since those are the defaults for this parser):
1.58 +To embed a visualisation of a graph in a Wiki page, using the dot filter and
1.59 +providing a client-side imagemap (the filter=dot and format=png options are
1.60 +redundant since those are the defaults for this parser), try the following:
1.61
1.62 {{{#!graphviz
1.63 //filter=dot
1.64 @@ -50,16 +70,73 @@
1.65 };
1.66 }}}
1.67
1.68 -Known Bugs
1.69 -----------
1.70 +As noted above, for SVG output an imagemap definition need not be used, since
1.71 +SVG as a format supports hyperlinks.
1.72 +
1.73 +Known Issues
1.74 +------------
1.75 +
1.76 + * The parser could benefit from being checked for potential methods of
1.77 + injecting arbitrary HTML into the page output, even though the formatter
1.78 + interface is being used to generate the output.
1.79 +
1.80 + * The parser only be useful or compatible with HTML rendering, although the
1.81 + generic formatter interface is used to format the output and could support
1.82 + any page format that can present images and objects in a similar fashion.
1.83 +
1.84 + * The code may not use all of the MoinMoin interfaces properly. Particularly
1.85 + the manipulation of attachments might be better done through any
1.86 + Moin-level abstractions instead of at the file level.
1.87 +
1.88 + * Comments must start at the beginning of the graphviz block and at the
1.89 + beginning of their respective lines. They must also not contain any extra
1.90 + whitespace surrounding the = sign.
1.91 +
1.92 + * SVG image sizing can only be done by extracting the dimensions from an
1.93 + uncompressed ("svg" format, not "svgz" format) output representation.
1.94 + Moreover, the extraction process assumes that the "width" and "height"
1.95 + attributes appear in an "svg" start tag of a particular form.
1.96 +
1.97 + * Beyond SVG size detection there is no support for determining the size of
1.98 + output representations that cannot be inserted into a page as an image.
1.99 + Thus, most of the supported output formats may cause inappropriately sized
1.100 + objects to appear in a page because the browser has not been able to
1.101 + determine the size of the object in advance.
1.102
1.103 - - Hasn't been thoroughly checked for potential methods of injecting
1.104 - arbitrary HTML into the output.
1.105 - - Only compatible with HTML rendering
1.106 - - May not use all of the MoinMoin interfaces properly - this is a
1.107 - quick hack based on looking at an example and digging through the
1.108 - MoinMoin source. The MoinMoin development docs haven't been
1.109 - consulted (yet).
1.110 - - Comments must start at the beginning of the graphviz block, and at the
1.111 - beginning of their respective lines. They must also not contain
1.112 - any extra whitespace surrounding the = sign.
1.113 +Recommended Software
1.114 +--------------------
1.115 +
1.116 +See the "Dependencies" section below for essential software.
1.117 +
1.118 +The moinsetup tool is recommended for installation since it aims to support
1.119 +all versions of MoinMoin that are supported for use with this software.
1.120 +
1.121 +See the following page for information on moinsetup:
1.122 +
1.123 +http://moinmo.in/ScriptMarket/moinsetup
1.124 +
1.125 +Dependencies
1.126 +------------
1.127 +
1.128 +The graphviz parser has the following basic dependencies:
1.129 +
1.130 +Packages Release Information
1.131 +-------- -------------------
1.132 +
1.133 +graphviz Tested with 2.16
1.134 + Source: http://www.graphviz.org/
1.135 +
1.136 +Contact, Copyright and Licence Information
1.137 +------------------------------------------
1.138 +
1.139 +See the following Web page for more information about this work:
1.140 +
1.141 +http://moinmo.in/ParserMarket/graphviz
1.142 +
1.143 +The author of this packaging of the original work can be contacted at the
1.144 +following e-mail address:
1.145 +
1.146 +paul@boddie.org.uk
1.147 +
1.148 +Copyright and licence information can be found in the docs directory - see
1.149 +docs/COPYING.txt and docs/LICENCE.txt for more information.