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