Convention for documenting XML

Eclipse Style of documenting extensions is used.

The markup used to describe the XML document tree is based on used by Eclipse to describe its Extension Point Schema.

This Mark up define the elements and attributes for the element element.

<!ELEMENT element (subelement, subelementA?, subelementB*, subelementC+, @ADDITIONAL) >
<!ATTRIBUTE element
    attrib  #REQUIRED
    attribB #IMPLIED 
    @ADDITIONAL #IMPLIED>

where element, subelement, , subelementA, subelementB, subelementC, attrib and attribB are the names of the element or attribute. @ADDITIONAL is a special tag introduced by GenericFX to signify that additional elements or attribute can be used.

The first markup ELEMENT describe the elements inside element. Items in bracket “()” are the subelements. Subelements are separated by commas. They can end with ?+* as count modifier:

• No modifier : exactly one instance required (subelement)
• ? : none or one (subelementA)
• * : none, one or more (subelementB)
• + : one or more (subelementC)

A special element “#PCDATA” is used to describe text element.

If @ADDITIONAL specified, implementations that require additional element will use the markup

<!ELEMENT element @ADDITIONAL (subelementZ, ..)>

to specify additional elements (subelementZ).

The second markup ATTRIBUTE describe the attributes for element. It defines one attribute per line. Each attribute line starts with the attribute name (attrib and attribB), followed by whether is it a compulsory element (#REQUIRED) or optional (#IMPLIED).

If @ADDITIONAL specified, implementations that require additional attribute will use the markup

<!ATTRIBUTE element  @ADDITIONAL 
  subelementZ #IMPLIED
  subelementY #REQUIRED

to specify additional elements (subelementZ/subelementY and their IMPLIED|REQUIRED status.

<person firstName="Cinly" lastName="Ooi">
  <gender code="M" />
  <address>Brain Mapping Unit, University of Cambridge</address>
  <address>Barnwell, Cambridge UK</address>
  <marital status="Single" />
  <parents>
    <father name="XXX" />
    <mother name="YYY" />
  </parents>
</person>
 
<person firstName="Charles" lastName="Windsor">
  <gender code="M" />
  <address>High Grove, UK</address>
  <title saluation="HRH" />
  <parents>
    <father name="Philip" />
    <mother name="Elizabeth" note="Queen Of Great Britain" />
  </parents>
</person>

Mark Up:

<!ELEMENT person (gender, address+, title?, parents) >
<!ATTRIBUTE person
    firstName  #REQUIRED
    secondName #REQUIRED >

<!ELEMENT gender () >
<!ATTRIBUTE gender>
    code #REQUIRED >

<!ELEMENT address (#PCDATA) >

<!ELEMENT title () >
<!ATTRIBUTE title
  salutation #REQUIRED >

<!ELEMENT parents (father, mother) >

<!ELEMENT father ()>
<!ATTRIBUTE father
  name #REQUIRED
  note #IMPLIED >


<!ELEMENT mother ()>
<!ATTRIBUTE mother
  name #REQUIRED
  note #IMPLIED >

For details of XML description see http://www.google.co.uk/url?sa=U&start=1&q=http://www.w3.org/XML/&e=14911

You can see this as a crash course for XML.

For a XML document:

<? xml ?>
<elementName attrib1="attribvalue1" attrib2="attribvalue2">''
   <subelement attrib3="myattrib1" attrib4="myattrib2">pure text</subelement>''
   <subelementB />
</element>

<? xml ?> is a marker telling the computer that this is an XML document.

Anything enclosed between a < and a > is a tag.

In most cases < and > is the only reserved characters. To denote < and > in an XML document, you need to use < and > respectively.

elementName, subelement and subelementB are known as Element. <elementName> denotes the start of element with name elementName and </elementName> denotes the end of the element. They are sometimes known as start tag and end tag respectively. <subelementB /> denote that the start and end tag is the same tag.

Elements can contain other elements, attributes (see later). Attributes are defined in the start tags. Elements must be completely defined within the start and end tag of its parent element. A line of text, e.g. “pure text” above, is known as a text node.

The can be multiple elements with the same name.

attrib1, attrib2, attrib3 and attrib4 are known as Attributes and have the values attribvalue1, attribvalue2, attribvalue3 and attribvalue4 respectively. Unlike element, it is an error to have more than one attribute with the same name.

The discussion above merely show the structure of an XML document. It is a tree-like structure. It is up to the implementers to decide what name to give to elements and attributes and the final structure of the tree.