XML
XML or Extensible Markup Language (XML), is basically a specification for writing formats used by other software programs. It is used in FlightGear for many things, and the files can be edited in plain text.
Most XML files in FlightGear are based on the so called "PropertyList" format and follow the corresponding structure: PropertyList XML File. PropertyList encoded XML files map nested XML tags to FlightGear properties and only use a well-defined subset of XML.
<position>
<altitude-ft>10000</altitude-ft>
<latitude-deg>-117.00</latitude-deg>
<longitude-deg>35</longitude-deg>
</position>
This markup specifies three "child" properties named "altitude-ft", "latitude-deg" and "longitude-deg". These are all children of the "position" group.
In FlightGear, these nested tags would then map to properties like this:
- /position/altitude-ft
- /position/latitude-deg
- /position/longitude-deg
This can be imagined like a directory structure, with "position" being a toplevel directory and the three child nodes being child nodes (sub directories or files).
It is generally a good idea to add a type attribute to all tags, describing the type of property to be specified.
Examples include joystick or CDU configuration files. Some details on the XML used for the CDU can be found on the CDU development page.
PropertyList-encoded XML files can be easily processed directly by FlightGear, by both, core C++ source code, as well as Nasal scripts, but also by using so called fgcommands (savexml/loadxml). In addition, it is easily possible to include other PropertyList-encoded XML files by using the include attribute for a tag:
<colors include="colors.xml"/>
README.xmlsyntax
NOTE: This is a straight copy-paste from $FGDATA/Docs/README.xmlsyntax
XML IN FIFTEEN MINUTES OR LESS
Written by David Megginson, david@megginson.com Last modified: $Date$
This document is in the Public Domain and comes with NO WARRANTY!
Introduction
FlightGear uses XML for much of its configuration. This document provides a minimal introduction to XML syntax, concentrating only on the parts necessary for writing and understanding FlightGear configuration files. For a full description, read the XML Recommendation at
http://www.w3.org/TR/
This document describes general XML syntax. Most of the XML configuration files in FlightGear use a special format called "Property Lists" -- a separate document will describe the specific features of the property-list format.
XML Validation
XML is very persnickety about its formatting, and FlightGear often gives terse or uninformative messages--or no message at all--when your XML fails to validate. Whenever you are editing an XML file, it is wise to use an outside method to validate it, before sending it to FlightGear.
A simple way to validate an XML file is simply to open it in Firefox.
Another way is to use an XML validation service such as W3 Schools or XMLValidation.com.
Any of these methods will identify the exact line and character where your file fails to validate.
Elements and Attributes
An XML document is a tree structure with a single root, much like a file system or a recursive, nested list structure (for LISP fans). Every node in the tree is called an _element_: the start and end of every element is marked by a _tag_: the _start tag_ appears at the beginning of the element, and the _end tag_ appears at the end.
Here is an example of a start tag:
<foo>
Here is an example of an end tag:
</foo>
Here is an example of an element:
<foo>Hello, world!</foo>
The element in this example contains only data element, so it is a leaf node in the tree. Elements may also contain other elements, as in this example:
<bar>
<foo>Hello, world!</foo>
<foo>Goodbye, world!</foo>
</bar>
This time, the 'bar' element is a branch that contains other, nested elements, while the 'foo' elements are leaf elements that contain only data. Here's the tree in ASCII art (make sure you're not using a proportional font):
bar +-- foo -- "Hello, world!"
|
+-- foo -- "Goodbye, world!"
There is always one single element at the top level: it is called the _root element_. Elements may never overlap, so something like this is always wrong (try to draw it as a tree diagram, and you'll understand why):
<a><b></a></b>
Every element may have variables, called _attributes_, attached to it. The attribute consists of a simple name=value pair in the start tag:
<foo type="greeting">Hello, world!</foo>
Attribute values must be quoted with '"' or "'" (unlike in HTML), and no two attributes may have the same name.
There are rules governing what can be used as an element or attribute name. The first character of a name must be an alphabetic character or '_'; subsequent characters may be '_', '-', '.', an alphabetic character, or a numeric character. Note especially that names may not begin with a number.
Data
Some characters in XML documents have special meanings, and must always be escaped when used literally:
< <
& &
Other characters have special meanings only in certain contexts, but it still doesn't hurt to escape them:
> > ' ' (in attribute values) " " (in attribute values)
Here is how you would escape "x < 3 && y > 6" in XML data:
<pre>x &lt; 3 &amp;&amp; y &gt; 6</pre>
Most control characters are forbidden in XML documents: only tab, newline, and carriage return are allowed (that means no ^L, for example). Any other character can be included in an XML document as a character reference, by using its Unicode value; for example, the following represents the French word "cafe" with an accent on the final 'e':
<pre>caf&#233;</pre>
By default, 8-bit XML documents use UTF-8, **NOT** ISO 8859-1 (Latin 1), so it's safest always to use character references for characters above position 127 (i.e. for non-ASCII).
Note that a double dash (--) will cause problems in a comment but cannot really be escaped.
Whitespace always counts in XML documents, though some specific applications (like property lists) have rules for ignoring it in some contexts.
Long sections of text that may contain a number of problem characters can be escaped using the CDATA method. This is often used for long sections of Nasal code within FlightGear XML files. Example:
<nasal>
<load>
<![CDATA[
print("Loading Sopwith Camel ", cmdarg().getPath
var thisNodeName = cmdarg().getPath();
var thisNode = props.globals.getNode(thisNodeName);
#etc . . . anywhere from a dozen to a few hundred lines of Nasal code
]]>
</load>
<nasal>
For more information about escaping sections of text with CDATA, see http://www.w3schools.com/xml/xml_cdata.asp
Comments
You can add a comment anywhere in an XML document except inside a tag or declaration using the following syntax:
<!-- comment -->
The comment text must not contain "--", so be careful about using dashes.
XML Declaration
Every XML document may begin with an XML declaration, starting with "<?xml" and ending with "?>". Here is an example:
<?xml version="1.0" encoding="UTF-8"?>
The XML declaration must always give the XML version, and it may also specify the encoding (and other information, not discussed here). UTF-8 is the default encoding for 8-bit documents; you could also try
<?xml version="1.0" encoding="ISO-8859-1"?>
to get ISO Latin 1, but some XML parsers might not support that (FlightGear's does, for what it's worth).
Other Stuff
There are other kinds of things allowed in XML documents. You don't need to use them for FlightGear, but in case anyone leaves one lying around, it would be useful to be able to recognize it.
XML documents may contain different kinds of declarations starting with "<!" and ending with ">":
<!DOCTYPE html SYSTEM "html.dtd">
<!ELEMENT foo (#PCDATA)>
<!ENTITY myname "John Smith">
and so on. They may also contain processing instructions, which look a bit like the XML declaration:
<?foo processing instruction?>
Finally, they may contain references to _entities_, like the ones used for escaping special characters, but with different names (we're trying to avoid these in FlightGear):
&chapter1;
&myname;
Enjoy.
Related content
External links
- http://www.w3schools.com/xml/default.asp
- http://www.w3.org/XML/
- http://xml.silmaril.ie/ The XML FAQ: Frequently-Asked Questions about the Extensible Markup Languag