docs-mini/README.xmlsyntax

   1 XML IN FIFTEEN MINUTES OR LESS
   2
   3 Written by David Megginson, david@megginson.com
   4 Last modified: $Date$
   5
   6 This document is in the Public Domain and comes with NO WARRANTY!
   7
   8
   9 1. Introduction
  10 ---------------
  11
  12 FlightGear uses XML for much of its configuration.  This document
  13 provides a minimal introduction to XML syntax, concentrating only on
  14 the parts necessary for writing and understanding FlightGear
  15 configuration files.  For a full description, read the XML
  16 Recommendation at
  17
  18   http://www.w3.org/TR/
  19
  20 This document describes general XML syntax.  Most of the XML
  21 configuration files in FlightGear use a special format called
  22 "Property Lists" -- a separate document will describe the specific
  23 features of the property-list format.
  24
  25
  26 2. Elements and Attributes
  27 --------------------------
  28
  29 An XML document is a tree structure with a single root, much like a
  30 file system or a recursive, nested list structure (for LISP fans).
  31 Every node in the tree is called an _element_: the start and end of
  32 every element is marked by a _tag_: the _start tag_ appears at the
  33 beginning of the element, and the _end tag_ appears at the end.
  34
  35 Here is an example of a start tag:
  36
  37   <foo>
  38
  39 Here is an example of an end tag:
  40
  41   </foo>
  42
  43 Here is an example of an element:
  44
  45   <foo>Hello, world!</foo>
  46
  47 The element in this example contains only data element, so it is a
  48 leaf node in the tree.  Elements may also contain other elements, as
  49 in this example:
  50
  51   <bar>
  52    <foo>Hello, world!</foo>
  53    <foo>Goodbye, world!</foo>
  54   </bar>
  55
  56 This time, the 'bar' element is a branch that contains other, nested
  57 elements, while the 'foo' elements are leaf elements that contain only
  58 data.  Here's the tree in ASCII art (make sure you're not using a
  59 proportional font):
  60
  61   bar +-- foo -- "Hello, world!"
  62       |
  63       +-- foo -- "Goodbye, world!"
  64
  65 There is always one single element at the top level: it is called the
  66 _root element_.  Elements may never overlap, so something like this is
  67 always wrong (try to draw it as a tree diagram, and you'll understand
  68 why):
  69
  70   <a><b></a></b>
  71
  72 Every element may have variables, called _attributes_, attached to
  73 it.  The attribute consists of a simple name=value pair in the start
  74 tag:
  75
  76   <foo type="greeting">Hello, world!</foo>
  77
  78 Attribute values must be quoted with '"' or "'" (unlike in HTML), and
  79 no two attributes may have the same name.
  80
  81 There are rules governing what can be used as an element or attribute
  82 name.  The first character of a name must be an alphabetic character
  83 or '_'; subsequent characters may be '_', '-', '.', an alphabetic
  84 character, or a numeric character.  Note especially that names may not
  85 begin with a number.
  86
  87
  88 3. Data
  89 -------
  90
  91 Some characters in XML documents have special meanings, and must
  92 always be escaped when used literally:
  93
  94   <  &lt;
  95   &  &amp;
  96
  97 Other characters have special meanings only in certain contexts, but
  98 it still doesn't hurt to escape them:
  99
 100   >  &gt;
 101   '  &apos;
 102   "  &quot;
 103
 104 Here is how you would escape "x < 3 && y > 6" in XML data:
 105
 106   x &lt; 3 &amp;&amp; y &gt; 6
 107
 108 Most control characters are forbidden in XML documents: only tab,
 109 newline, and carriage return are allowed (that means no ^L, for
 110 example).  Any other character can be included in an XML document as a
 111 character reference, by using its Unicode value; for example, the
 112 following represents the French word "cafe" with an accent on the
 113 final 'e':
 114
 115   caf&#233;
 116
 117 By default, 8-bit XML documents use UTF-8, **NOT** ISO 8859-1 (Latin
 118 1), so it's safest always to use character references for characters
 119 above position 127 (i.e. for non-ASCII).
 120
 121 Whitespace always counts in XML documents, though some specific
 122 applications (like property lists) have rules for ignoring it in some
 123 contexts.
 124
 125
 126 4. Comments
 127 -----------
 128
 129 You can add a comment anywhere in an XML document except inside a tag
 130 or declaration using the following syntax:
 131
 132   <!-- comment -->
 133
 134 The comment text must not contain "--", so be careful about using
 135 dashes.
 136
 137
 138 5. XML Declaration
 139 ------------------
 140
 141 Every XML document may begin with an XML declaration, starting with
 142 "<?xml" and ending with "?>".  Here is an example:
 143
 144   <?xml version="1.0" encoding="UTF-8"?>
 145
 146 The XML declaration must always give the XML version, and it may also
 147 specify the encoding (and other information, not discussed here).
 148 UTF-8 is the default encoding for 8-bit documents; you could also try
 149
 150   <?xml version="1.0" encoding="ISO-8859-1"?>
 151
 152 to get ISO Latin 1, but some XML parsers might not support that
 153 (FlightGear's does, for what it's worth).
 154
 155
 156 6. Other Stuff
 157 --------------
 158
 159 There are other kinds of things allowed in XML documents.  You don't
 160 need to use them for FlightGear, but in case anyone leaves one lying
 161 around, it would be useful to be able to recognize it.
 162
 163 XML documents may contain different kinds of declarations starting
 164 with "<!" and ending with ">":
 165
 166   <!DOCTYPE html SYSTEM "html.dtd">
 167
 168   <!ELEMENT foo (#PCDATA)>
 169
 170   <!ENTITY myname "John Smith">
 171
 172 and so on.  They may also contain processing instructions, which look
 173 a bit like the XML declaration:
 174
 175   <?foo processing instruction?>
 176
 177 Finally, they may contain references to _entities_, like the ones used
 178 for escaping special characters, but with different names (we're
 179 trying to avoid these in FlightGear):
 180
 181   &chapter1;
 182
 183   &myname;
 184
 185
 186 Enjoy.