[[PageOutline(2-5,Contents,pullout)]]

= Produce simple-minded graphical images of the structure of XML Schema files

== Description

This plugin produces a graphical depiction of the data structure defined by an [https://en.wikipedia.org/wiki/XML_Schema_(W3C) XML Schema (XSD)] file.

Input files can be source files in an SVN repository, attachements to tickets or placed in the Trac server file system.

Output is as indicated in this example:

[[Image(trac-hacks-example_1.1.png,width=300)]]


== !Bugs/Feature Requests

Existing bugs and feature requests for TracXsdPlotMacro are 
[report:9?COMPONENT=TracXsdPlotMacro here].

If you have any issues, create a 
[/newticket?component=TracXsdPlotMacro new ticket].

[[TicketQuery(component=TracXsdPlotMacro&group=type,format=progress)]]

== Download

Download the zipped source from [export:tracxsdplotmacro here].

== Source

You can check out TracXsdPlotMacro from [/svn/tracxsdplotmacro here] using Subversion, or [source:tracxsdplotmacro browse the source] with Trac.

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

Requirements:
 * `ImageMagick` must be installed.
 * `ElementTree` must be installed for XSD parsing.

Enable the plugin as follows in your `trac.ini` file:

{{{#!ini
[components]
tracxsdplot.* = enabled
}}}

Tested with Trac 1.0.6 on Linux. Older Trac versions cannot access specific source file revisions.

== Configuration

 
{{{#!ini
[tracxsdplot]
file.prepath = /relative/entry/directory
file.preurl = http://example.com/entrydir
png-density=600
colour.element = #D3D3D3
colour.complextype = #B3B3B3
colour.container = #FFFFFF
colour.stroke = #2F4F4F
}}}

|| file.prepath || Path prefix for local files ||
|| file.preurl || URL prefix ||
|| png-density || pixel density for generated PNG images (used as parameter to `ImageMagick`) ||
|| colour.element || RGB colour used for <xs:element> ||
|| colour.complextype || ... for <xs:complexType> ||
|| colour.container || ... for <xs:sequence>, <xs:all>, <xs:choice> ||
|| colour.stroke || ... for box frames ||

The plugin contains functionality that allows command-line usage as well:

{{{#!sh
/path/to/plugin/xsd2svg XSDFILE --outfile=OUTFILE
}}}

== Usage

{{{
[[XsdPlot(schema.xsd,width=400,page=100,caption="Page 100 from Book Example")]]
[[XsdPlot(source:repo/schema.xsd@10,width=600,caption="SVG-image from repository in version 10")]]
[[XsdPlot(ticket:1:schema.xsd)]]
}}}

== Possible trac links for input files/resources:

||= Trac link =||= Alternatives =||= Comment              =||
|| wiki:        ||  !JustPageName || Wiki page attachment ||
|| ticket:      ||  !#1           || Ticket attachment    ||
|| source:      ||  browser,repos || File stored in subversion ||
|| file:        ||                || Local file. Path prefix read from `file.prepath` in trac.ini  ||


== XSD layout selectiveness control parameters:
||= Parameter =||= Value                 =||= Default =||
|| top-element || select specific top XSD element of plot || assumes file to contain '''exactly one''' XSD root element. Otherwise the first element encountered will be plotted. ||
|| depth       || maximum depth counted in elements || infinity ||
|| stop-list   || Pipe-separated list of XSD element names where recursive descent shall stop || empty ||


== Other parameters:
||= Parameter =||= Value                 =||= Default =||= Note =||
|| img-type    || 'png' or 'svg'          || svg       || case INsensitive ||
|| width       || width in pixel          || 600       || must be absolute value ||
|| caption     || Caption under image     || ''none''  ||       ||
|| label       || anchor to link to       ||           ||       ||
|| cache       || build once or each time || True      || time consumption or changing vector graphics  ||
|| align       || left|right              || nothing   ||       ||


== Recent Changes

[[ChangeLog(tracxsdplotmacro, 3)]]

== !Author/Contributors

**Author:** [wiki:thenor] [[BR]]
**Maintainer:** [[Maintainer]] [[BR]]
**Contributors:**

== Credits

Thanks to [wiki:ursaw] for most of the macro argument parsing and trac infrastructure that is taken from PdfImagePlugin.