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