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,
48 the cmapx option is superfluous since SVG supports linking
49 natively and Graphviz converts "href" attributes appropriately
50 transform - the name of a transformation applied to SVG output; this must
51 match an entry in the TRANSFORMS dictionary defined in the Parser
52 class; by default, only "notugly" is supported, for which the
53 DIAGRAM_TOOLS_PATH must be defined appropriately in the parser
54 file, referencing the directory containing the notugly.xsl file;
55 other transformations may be added as required
56
57 To embed a visualisation of a graph in a Wiki page, using the dot filter and
58 providing a client-side imagemap (the filter=dot and format=png options are
59 redundant since those are the defaults for this parser), try the following:
60
61 {{{#!graphviz
62 //filter=dot
63 //format=png
64 //cmapx=DocumentationMap
65 digraph DocumentationMap {
66 FrontPage [href="FrontPage", root=true];
67 HelpOnEditing [href="HelpOnEditing"];
68 SyntaxReference [href="SyntaxReference"];
69 WikiSandBox [href="WikiSandBox", color="grey"];
70 MoinMoin [href="http://moinmo.in"];
71 FrontPage -> WikiSandBox;
72 FrontPage -> MoinMoin;
73 WikiSandBox -> HelpOnEditing;
74 WikiSandBox -> SyntaxReference;
75 SyntaxReference -> FrontPage;
76 };
77 }}}
78
79 As noted above, for SVG output an imagemap definition need not be used, since
80 SVG as a format supports hyperlinks.
81
82 Known Issues
83 ------------
84
85 * The parser could benefit from being checked for potential methods of
86 injecting arbitrary HTML into the page output, even though the formatter
87 interface is being used to generate the output.
88
89 * The parser only be useful or compatible with HTML rendering, although the
90 generic formatter interface is used to format the output and could support
91 any page format that can present images and objects in a similar fashion.
92
93 * The code may not use all of the MoinMoin interfaces properly. Particularly
94 the manipulation of attachments might be better done through any
95 Moin-level abstractions instead of at the file level.
96
97 * Comments must start at the beginning of the graphviz block and at the
98 beginning of their respective lines. They must also not contain any extra
99 whitespace surrounding the = sign. It would arguably be better if the
100 configuration of images were done using the argument notation employed by
101 other parsers.
102
103 * SVG image sizing can only be done by extracting the dimensions from an
104 uncompressed ("svg" format, not "svgz" format) output representation.
105 Moreover, the extraction process assumes that the "width" and "height"
106 attributes appear in an "svg" start tag of a particular form.
107
108 * Beyond SVG size detection there is no support for determining the size of
109 output representations that cannot be inserted into a page as an image.
110 Thus, most of the supported output formats may cause inappropriately sized
111 objects to appear in a page because the browser has not been able to
112 determine the size of the object in advance.
113
114 Recommended Software
115 --------------------
116
117 See the "Dependencies" section below for essential software.
118
119 The moinsetup tool is recommended for installation since it aims to support
120 all versions of MoinMoin that are supported for use with this software.
121
122 See the following page for information on moinsetup:
123
124 http://moinmo.in/ScriptMarket/moinsetup
125
126 Dependencies
127 ------------
128
129 The graphviz parser has the following basic dependencies:
130
131 Packages Release Information
132 -------- -------------------
133
134 graphviz Tested with 2.16
135 Source: http://www.graphviz.org/
136
137 SVG output can be transformed using XSL transformations, and the parser can
138 make use of the diagram-tools notugly.xsl stylesheet to improve the appearance
139 of graphs. See the resources directory for a copy of this stylesheet provided
140 for convenience. The repository for diagram-tools can be found at the
141 following location:
142
143 https://github.com/vidarh/diagram-tools.git
144
145 Contact, Copyright and Licence Information
146 ------------------------------------------
147
148 See the following Web page for more information about this work:
149
150 http://moinmo.in/ParserMarket/graphviz
151
152 The author of this packaging of the original work can be contacted at the
153 following e-mail address:
154
155 paul@boddie.org.uk
156
157 Copyright and licence information can be found in the docs directory - see
158 docs/COPYING.txt and docs/LICENCE.txt for more information.
159
160 New in GraphvizParser 0.3 (Changes since GraphvizParser 0.2.3)
161 --------------------------------------------------------------
162
163 * Added some support for XSL transformations to the Graphviz SVG output.
164 * Added close_fds usage for XSLT processor subprocesses.
165
166 New in GraphvizParser 0.2.3 (Changes since GraphvizParser 0.2.2)
167 ----------------------------------------------------------------
168
169 * Fixed graph attachment detection where no dimension attributes are
170 specified.
171
172 New in GraphvizParser 0.2.2 (Changes since GraphvizParser 0.2.1)
173 ----------------------------------------------------------------
174
175 * Removed request.flush usage where the method does not exist (in Moin 1.9).
176
177 Release Procedures
178 ------------------
179
180 Update the parsers/graphviz.py __version__ attribute.
181 Change the version number and package filename/directory in the documentation.
182 Update the release notes (see above).
183 Tag, export.
184 Archive, upload.
185 Update the ParserMarket and ParserMarket/graphviz page.