+
+Entities and Parameterisation:
+
+ The westley producer parser supports XML entities. An example:
+
+ <?xml version="1.0"?>
+ <!DOCTYPE westley [
+ <!ENTITY msg "Hello world!">
+ ]>
+ <westley>
+ <producer id="producer0">
+ <property name="mlt_service">pango</property>
+ <property name="text">&msg;</property>
+ </producer>
+ </westley>
+
+ If you are embedding another XML document into a property value not using
+ a CNODE section, then any DOCTYPE section must be relocated before any of
+ the xml elements to be well-formed. See demo/dvg.westley for an example.
+
+ Entities can be used to parameterise westley! Using the above example, the
+ entity declared serves as the default value for &msg;. The entity content
+ can be overridden from the resource property supplied to the westley
+ producer. The syntax is the familiar, url-encoded query string used with
+ HTTP, e.g.: file?name=value&name=value...
+
+ There are a couple of rules of usage. The Miracle LOAD command and inigo
+ command line tool require you to preface the URL with "westley:" because
+ the query string destroys the filename extension matching peformed by
+ Fezzik. Also, inigo looks for '=' to tokenise property settings. Therefore,
+ one uses ':' between name and value instead of '='. Finally, since inigo
+ is run from the shell, one must enclose the URL within single quotes to
+ prevent shell filename expansion, or similar.
+
+ Needless to say, the ability to parameterise westley XML compositions is
+ an extremely powerful tool. The above example is avialable in
+ demo/entity.westley for you to try out. Override the message from inigo:
+ inigo 'westley:entity.westley?msg:Amazing!'
+
+ Technically, the entity declaration is not needed in the head of the XML
+ document if you always supply the parameter. However, you run the risk
+ of unpredictable behviour without one. Therefore, it is safest and a best
+ practice to always supply an entity declaration. It is improves the
+ readability as one does not need to search for the entity references to
+ see what parameters are available.
+