From: david Date: Tue, 26 Mar 2002 17:19:23 +0000 (+0000) Subject: Renamed README.xml to README.xmlsyntax, so that it wouldn't look like X-Git-Url: https://git.mxchange.org/?a=commitdiff_plain;h=6ca7d9ae00fab9cb98a4730b48f84de76334ddb1;p=flightgear.git Renamed README.xml to README.xmlsyntax, so that it wouldn't look like an XML file itself. --- diff --git a/docs-mini/README.xml b/docs-mini/README.xml deleted file mode 100644 index 6c55c1969..000000000 --- a/docs-mini/README.xml +++ /dev/null @@ -1,186 +0,0 @@ -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: - - - -Here is an example of an end tag: - - - -Here is an example of an element: - - Hello, world! - -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: - - - Hello, world! - Goodbye, world! - - -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): - - - -Every element may have variables, called _attributes_, attached to -it. The attribute consists of a simple name=value pair in the start -tag: - - Hello, world! - -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: - - < < - & & - -Other characters have special meanings only in certain contexts, but -it still doesn't hurt to escape them: - - > > - ' ' - " " - -Here is how you would escape "x < 3 && y > 6" in XML data: - - x < 3 && y > 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é - -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: - - - -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 -"". Here is an example: - - - -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 - - - -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 so on. They may also contain processing instructions, which look -a bit like the XML declaration: - - - -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. diff --git a/docs-mini/README.xmlsyntax b/docs-mini/README.xmlsyntax new file mode 100644 index 000000000..6c55c1969 --- /dev/null +++ b/docs-mini/README.xmlsyntax @@ -0,0 +1,186 @@ +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: + + + +Here is an example of an end tag: + + + +Here is an example of an element: + + Hello, world! + +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: + + + Hello, world! + Goodbye, world! + + +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): + + + +Every element may have variables, called _attributes_, attached to +it. The attribute consists of a simple name=value pair in the start +tag: + + Hello, world! + +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: + + < < + & & + +Other characters have special meanings only in certain contexts, but +it still doesn't hurt to escape them: + + > > + ' ' + " " + +Here is how you would escape "x < 3 && y > 6" in XML data: + + x < 3 && y > 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é + +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: + + + +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 +"". Here is an example: + + + +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 + + + +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 so on. They may also contain processing instructions, which look +a bit like the XML declaration: + + + +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.