1 Introduction
2 ------------
3
4 The graphviz parser module allows descriptions of graphs suitable for
5 interpretation by the Graphviz suite of tools to be embedded within Wiki
6 pages.
7
8 Installation
9 ------------
10
11 First, make sure that the BINARY_PATH setting in the graphviz.py module (found
12 in the parsers directory) is suitable for your system. Then, copy the
13 graphviz.py module into your Wiki's parsers directory.
14
15 With moinsetup and a suitable configuration file (see "Recommended Software"
16 below), you can perform this last step as follows, with $GVDIR referring to the
17 GraphvizParser distribution directory:
18
19 python moinsetup.py -f moinsetup.cfg -m install_parsers $GVDIR/parsers
20
21 Basic Usage
22 -----------
23
24 To embed a visualisation of a graph in a Wiki page, try the following:
25
26 {{{#!graphviz
27 digraph G {
28 A -> B;
29 };
30 }}}
31
32 Advanced Usage
33 --------------
34
35 This parser will check the first lines of the Graphviz data for C++ style
36 comments instructing it to use a different filter (dot, neato, twopi, circo,
37 or fdp - see http://graphviz.org/ for more information), use a different
38 format for the output (see the OUTPUT_FORMATS list in the Parser class), or to
39 generate and pass a client-side imagemap.
40
41 Options:
42
43 filter - the filter to use (see Parser.FILTERS)
44 format - the output format (see Parser.OUTPUT_FORMATS)
45 cmapx - the map name to use for the client-side imagemap; this must match
46 the graph name in the graph definition and shouldn't conflict with
47 any other graphs that are used on the same page; for SVG images, the
48 cmapx option is superfluous since SVG supports linking natively and
49 Graphviz converts "href" attributes appropriately
50
51 To embed a visualisation of a graph in a Wiki page, using the dot filter and
52 providing a client-side imagemap (the filter=dot and format=png options are
53 redundant since those are the defaults for this parser), try the following:
54
55 {{{#!graphviz
56 //filter=dot
57 //format=png
58 //cmapx=DocumentationMap
59 digraph DocumentationMap {
60 FrontPage [href="FrontPage", root=true];
61 HelpOnEditing [href="HelpOnEditing"];
62 SyntaxReference [href="SyntaxReference"];
63 WikiSandBox [href="WikiSandBox", color="grey"];
64 MoinMoin [href="http://moinmo.in"];
65 FrontPage -> WikiSandBox;
66 FrontPage -> MoinMoin;
67 WikiSandBox -> HelpOnEditing;
68 WikiSandBox -> SyntaxReference;
69 SyntaxReference -> FrontPage;
70 };
71 }}}
72
73 As noted above, for SVG output an imagemap definition need not be used, since
74 SVG as a format supports hyperlinks.
75
76 Known Issues
77 ------------
78
79 * The parser could benefit from being checked for potential methods of
80 injecting arbitrary HTML into the page output, even though the formatter
81 interface is being used to generate the output.
82
83 * The parser only be useful or compatible with HTML rendering, although the
84 generic formatter interface is used to format the output and could support
85 any page format that can present images and objects in a similar fashion.
86
87 * The code may not use all of the MoinMoin interfaces properly. Particularly
88 the manipulation of attachments might be better done through any
89 Moin-level abstractions instead of at the file level.
90
91 * Comments must start at the beginning of the graphviz block and at the
92 beginning of their respective lines. They must also not contain any extra
93 whitespace surrounding the = sign. It would arguably be better if the
94 configuration of images were done using the argument notation employed by
95 other parsers.
96
97 * SVG image sizing can only be done by extracting the dimensions from an
98 uncompressed ("svg" format, not "svgz" format) output representation.
99 Moreover, the extraction process assumes that the "width" and "height"
100 attributes appear in an "svg" start tag of a particular form.
101
102 * Beyond SVG size detection there is no support for determining the size of
103 output representations that cannot be inserted into a page as an image.
104 Thus, most of the supported output formats may cause inappropriately sized
105 objects to appear in a page because the browser has not been able to
106 determine the size of the object in advance.
107
108 Recommended Software
109 --------------------
110
111 See the "Dependencies" section below for essential software.
112
113 The moinsetup tool is recommended for installation since it aims to support
114 all versions of MoinMoin that are supported for use with this software.
115
116 See the following page for information on moinsetup:
117
118 http://moinmo.in/ScriptMarket/moinsetup
119
120 Dependencies
121 ------------
122
123 The graphviz parser has the following basic dependencies:
124
125 Packages Release Information
126 -------- -------------------
127
128 graphviz Tested with 2.16
129 Source: http://www.graphviz.org/
130
131 Contact, Copyright and Licence Information
132 ------------------------------------------
133
134 See the following Web page for more information about this work:
135
136 http://moinmo.in/ParserMarket/graphviz
137
138 The author of this packaging of the original work can be contacted at the
139 following e-mail address:
140
141 paul@boddie.org.uk
142
143 Copyright and licence information can be found in the docs directory - see
144 docs/COPYING.txt and docs/LICENCE.txt for more information.
145
146 New in GraphvizParser 0.2.2 (Changes since GraphvizParser 0.2.1)
147 ----------------------------------------------------------------
148
149 * Removed request.flush usage where the method does not exist (in Moin 1.9).
150
151 Release Procedures
152 ------------------
153
154 Update the parsers/graphviz.py __version__ attribute.
155 Change the version number and package filename/directory in the documentation.
156 Update the release notes (see above).
157 Tag, export.
158 Archive, upload.
159 Update the ParserMarket and ParserMarket/graphviz page.