1
0
Fork 0
flightgear/docs-mini
Thomas Geymayer 023021a879 Expose character-aspect-ratio and do some clean up
- Fix stupid memory corruption bug
 - Fix bounding box calculations
 - Fix docs
 - Fix text size
 - Expose setting background color
 - Expose trigger for updating elements
 - Untie nodes if deleting according element
 - Allow deleting canvas, text and group elements
 - Allow creating groups as children of groups
2012-05-31 22:04:19 +02:00
..
AptNavFAQ.FlightGear.html
FlightGear-FAQ.html Not using CVS anymore, removed dead link 2012-05-15 17:54:48 +01:00
Nasal.html
README.autoconf
README.canvas Expose character-aspect-ratio and do some clean up 2012-05-31 22:04:19 +02:00
README.commands
README.conditions
README.Cygwin
README.digitalfilters
README.effects
README.electrical
README.extensions
README.fgjs
README.gui
README.introduction
README.IO
README.IRIX
README.Joystick
README.JSBSim
README.jsclient
README.Linux
README.logging
README.MacOS
README.mingw
README.MSVC
README.multiplayer
README.multiscreen
README.plib
README.properties
README.protocol
README.running
README.SimGear
README.sound
README.src
README.submodels
README.tutorial
README.uiuc
README.Unix
README.Win32-X
README.xmlpanel
README.xmlparticles
README.xmlsound
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!


1. 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.


2. 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.


3. Data
-------

Some characters in XML documents have special meanings, and must
always be escaped when used literally:

  <  &lt;
  &  &amp;
  
Other characters have special meanings only in certain contexts, but
it still doesn't hurt to escape them:

  >  &gt;
  '  &apos;
  "  &quot;

Here is how you would escape "x < 3 && y > 6" in XML data:

  x &lt; 3 &amp;&amp; y &gt; 6

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':

  caf&#233;

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).

Whitespace always counts in XML documents, though some specific
applications (like property lists) have rules for ignoring it in some
contexts.


4. 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.


5. 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).


6. 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.