Difference between revisions of "XML Primer"

From MircWiki
Jump to navigation Jump to search
 
Line 1: Line 1:
MIRC uses extensible markup language (XML) to encode configuration data, indexed information, and MIRCdocuments themselves. To use MIRC, an understanding of XML is not necessary, but administrators may find it helpful. To assist readers who are new to XML, the following description will provide enough background to understand the XML in the MIRC documentation.
+
MIRC uses extensible markup language (XML) to encode configuration data, indexed information, and MIRCdocuments themselves. To use MIRC, an understanding of XML is not necessary, but administrators may find it helpful. To assist readers who are new to XML, the following description will provide enough background to read and understand the XML in the MIRC documentation.
  
An XML document is typically a text file, although it can also be a text stream obtained from a server via a network. Content in an XML document is contained in XML elements. An XML element is identified by a name enclosed in  __< >__ brackets. For example, an element called __MIRCdocument__ is coded as __<MIRCdocument>__. The notation __<elementname>__ is called a tag. Every element tag must be paired with a tag that defines its end. The end tag for __<MIRCdocument>__ is coded as __</MIRCdocument>__. The value of an element is the content between the element tag and its end tag.
+
An XML document is typically a text file, although it can also be a text stream obtained from a server via a network. Content in an XML document is contained in XML elements. An XML element is identified by a name enclosed in  <b>< ></b> brackets. For example, an element called <b>MIRCdocument</b> is coded as <b><MIRCdocument></b>. The notation <b><elementname></b> is called a tag. Every element tag must be paired with a tag that defines its end. The end tag for <b><MIRCdocument></b> is coded as <b></MIRCdocument></b>. The value of an element is the content between the element tag and its end tag.
  
 
An element may contain attributes. An attribute is coded within the element tag itself. An attribute consists of a name, an equals sign, and an attribute value. The attribute value is enclosed in quotes. The following is an example of an element with an attribute:
 
An element may contain attributes. An attribute is coded within the element tag itself. An attribute consists of a name, an equals sign, and an attribute value. The attribute value is enclosed in quotes. The following is an example of an element with an attribute:
  
{code:none}
+
<pre>
 
<MIRCdocument docref="http://www.somewhere.edu/mydocument.xml">
 
<MIRCdocument docref="http://www.somewhere.edu/mydocument.xml">
 
This text is the value of the element.
 
This text is the value of the element.
 
</MIRCdocument>
 
</MIRCdocument>
{code}
+
</pre>
  
 
An element may be empty, meaning that it has no element value (although it may have attributes). Such an element is usually coded as:
 
An element may be empty, meaning that it has no element value (although it may have attributes). Such an element is usually coded as:
  
{code:none}
+
<pre>
 
<element attribute="attribute value"/>
 
<element attribute="attribute value"/>
{code}
+
</pre>
  
 
(note the slash before the >), although the form:
 
(note the slash before the >), although the form:
  
{code:none}
+
<pre>
 
<element attribute="attribute value"></element>
 
<element attribute="attribute value"></element>
{code}
+
</pre>
  
 
is equally acceptable.
 
is equally acceptable.
Line 29: Line 29:
 
The value of an element may contain other elements, thus allowing the nesting of elements in an XML document. A well-formed XML document must have exactly one top-level, or root, element, within which all other content is contained, and every element must be paired with its end tag within the value of which it is a part. For example, the following is well-formed:
 
The value of an element may contain other elements, thus allowing the nesting of elements in an XML document. A well-formed XML document must have exactly one top-level, or root, element, within which all other content is contained, and every element must be paired with its end tag within the value of which it is a part. For example, the following is well-formed:
  
{code:none}
+
<pre>
topelement>
+
<topelement>
 
<p>This is a paragraph.</p>
 
<p>This is a paragraph.</p>
 
<p>This is another paragraph.</p>
 
<p>This is another paragraph.</p>
 
</topelement>
 
</topelement>
{code}
+
</pre>
  
 
The following is not well-formed, and is rejected by XML parsers:
 
The following is not well-formed, and is rejected by XML parsers:
  
{code:none}
+
<pre>
 
<topelement>
 
<topelement>
 
This text is one paragraph.
 
This text is one paragraph.
Line 44: Line 44:
 
This is another paragraph.
 
This is another paragraph.
 
</topelement>
 
</topelement>
{code}
+
</pre>
  
 
The last example is a common sloppy use of HTML. When including HTML within XML elements, it is imperative to provide an end tag for each HTML element.
 
The last example is a common sloppy use of HTML. When including HTML within XML elements, it is imperative to provide an end tag for each HTML element.
Line 50: Line 50:
 
The following document is also not well-formed:
 
The following document is also not well-formed:
  
{code:none}
+
<pre>
 
<topelement>
 
<topelement>
 
<element1> …
 
<element1> …
Line 57: Line 57:
 
</element2>
 
</element2>
 
</topelement>
 
</topelement>
{code}
+
</pre>
  
because __<element2>__, which is within __<element1>__, is not closed within the value of __<element1>__.
+
because <b><element2></b>, which is within <b><element1></b>, is not closed within the value of <b><element1></b>.
  
Whenever editing an XML file, it is imperative that it remain well-formed. An easy way to check that a document is well-formed is to open it in a web browser that parses XML documents. One such browser is Microsoft's Internet Explorer.
+
Whenever an XML file is edited, it is imperative that it remain well-formed. An easy way to check that a document is well-formed is to open it in a web browser that parses XML documents. One such browser is Microsoft's Internet Explorer.

Revision as of 21:39, 30 June 2006

MIRC uses extensible markup language (XML) to encode configuration data, indexed information, and MIRCdocuments themselves. To use MIRC, an understanding of XML is not necessary, but administrators may find it helpful. To assist readers who are new to XML, the following description will provide enough background to read and understand the XML in the MIRC documentation.

An XML document is typically a text file, although it can also be a text stream obtained from a server via a network. Content in an XML document is contained in XML elements. An XML element is identified by a name enclosed in < > brackets. For example, an element called MIRCdocument is coded as <MIRCdocument>. The notation <elementname> is called a tag. Every element tag must be paired with a tag that defines its end. The end tag for <MIRCdocument> is coded as </MIRCdocument>. The value of an element is the content between the element tag and its end tag.

An element may contain attributes. An attribute is coded within the element tag itself. An attribute consists of a name, an equals sign, and an attribute value. The attribute value is enclosed in quotes. The following is an example of an element with an attribute:

<MIRCdocument docref="http://www.somewhere.edu/mydocument.xml">
	This text is the value of the element.
</MIRCdocument>

An element may be empty, meaning that it has no element value (although it may have attributes). Such an element is usually coded as:

<element attribute="attribute value"/>

(note the slash before the >), although the form:

<element attribute="attribute value"></element>

is equally acceptable.

When XML documents are processed, whitespace is often insignificant. For example, multiple elements and their contents may appear on one line, and multiple spaces, tabs, and newline characters are sometimes reduced to a single space.

The value of an element may contain other elements, thus allowing the nesting of elements in an XML document. A well-formed XML document must have exactly one top-level, or root, element, within which all other content is contained, and every element must be paired with its end tag within the value of which it is a part. For example, the following is well-formed:

<topelement>
	<p>This is a paragraph.</p>
	<p>This is another paragraph.</p>
</topelement>

The following is not well-formed, and is rejected by XML parsers:

<topelement>
	This text is one paragraph.
	<p>
	This is another paragraph.
</topelement>

The last example is a common sloppy use of HTML. When including HTML within XML elements, it is imperative to provide an end tag for each HTML element.

The following document is also not well-formed:

<topelement>
	<element1> …
		<element2> …
	</element1>
		</element2>
</topelement>

because <element2>, which is within <element1>, is not closed within the value of <element1>.

Whenever an XML file is edited, it is imperative that it remain well-formed. An easy way to check that a document is well-formed is to open it in a web browser that parses XML documents. One such browser is Microsoft's Internet Explorer.