Introduction

Welcome to DrawShield and the world of Heraldry. The purpose of this section is to contain longer form explanations of the code that makes up DrawShield and some of the ideas behind it.

Before looking in detail at DrawShield it helps to have at lease a little understanding of Blazonry, the language of Heraldry.

There are lots of books on heraldry, both in print and on-line, or if you are just interested in learning the blazonry language that is implemented by DrawShield then there is a (currently incomplete) tutorial.

Operation Overview

The main phases of operation are as follows:

• Setting global options (in version.inc) and argument processing (in drawshield.php)

• Lexical analysis - breaking the input into tokens (parser/tokeniser.inc)

• Parsing - recognising the blazon and putting into an XML parse tree (parser/*)

• Analysis() - applying specialist knowledge to modify the parse tree (analyser/)

• Rendering - creating the SVG image from the parse tree (svg/*)

• Converting (optional) - reformat the SVG as jpg or png (drawshield.php)

Code Organisation Overview

The DrawShield code is organised into three sections which function as a pipeline:

The Parser - responsible for reading and understanding the blazon language, this produces a parse tree in an XML format conforming to a custom schema known as BlazonML.

The Analyser - this takes as input the parse tree XML and carries out additional processing such as adding links, resolving cross references and so on. Its output is in the same format but with additions to the XML content.

The SVG Renderer - this takes as input the XML parse tree from the analyser and produces an SVG representation of the blazon (the XML parse tree is included as meta-data within the SVG file).

The top level file, drawshield.php is responsible for processing arguments, calling each of the pipeline stages in turn, optionally calling ImageMagick to do image format conversion and outputting the final result.

Other Files

There are some additional files in the top level folder.

blazonML.XSD is an annotated XML Schema file for the BlazonML markup language. It was created in Oxygen Developer but is a standard XML schema file and can be opened in any XML aware editor.

shieldcommon.js Some example Javascript that uses AJAX to request a shield to be drawn and inserts the resulting SVG data into an existing web page.

There is additional information on the following subjects (in no particular order):