Understanding XML terminology

What are XML and CNXML?

XML stands for eXtensible Markup Language, and is a way to surround text to convey information about its content or format. CNXML is the particular brand of XML used in Connexions. Here is an example of some markup in CNXML:

Example 1

<para>
  This is a paragraph in <term>CNXML</term>.
  Notice that the markup contains tags that 
  express the meaning of it.
</para>

What is a Tag?

Tags are the markers used to enclose the text they define. In the above example, para and term are the tags being used. In XML, the opening (first) tag is surrounded by angle brackets (< and >) and the closing (second) tag is also surrounded by angle brackets, but the name of the tag is preceded by a slash (/). Also, the closing tag never contains any attribute information.

What is an Attribute?

Sometimes in XML, the tag name is not sufficient to contain all the information one might want to convey. For example, in CNXML, there are two types of code tags: 'inline' (the code is included in the current line of text) or 'block' (it is set apart from the text). This information can be included in attributes, which are nestled between the name of the opening tag and its 2nd angle bracket (>), as in the example below:

Example 2

<para>
  This is a paragraph written in 
  <code display="inline">CNXML</code>.  
  In the output, the word 'CNXML' would not 
  be offset from the rest of the text.
</para>

In this example, display is the attribute name and inline is the attribute value. The attribute name is always followed by the equal sign (=) and the attribute value is always surrounded by double or single quotes (" or '). In CNXML, the attributes one can use for a given tag are strictly defined.

What is a Child/Parent?

In XML, tags are contained inside other tags. In the above example, a code tag is nested inside a para tag. It can be said that code is a child of para and that para is a parent of code. In XML, it is not valid to write tags that do not properly nest, such as in this example, where the emphasis tag ends before its child, foreign, also ends:

Example 3: Invalid nesting

It is <emphasis><foreign>muy</emphasis> 
importante</foreign> that you write proper XML.

However, "siblings" nested inside a single tag are allowed:

Example 4

<para>
  Shakespeare wrote both <cite>MacBeth</cite>
  and <cite>Hamlet</cite>.
</para>

In CNXML, the children that a given tag can contain are strictly defined.

What is escaping?

Escaping allows one to write certain characters that would otherwise be parsed by XML processors for another purpose. For example, if you want to use the "less than" symbol, you would have to write it in XML as <, since that angle bracket (<) is parsed by the processors to mark the beginning of an opening or closing tag. The following characters should be escaped:

& (escaped by writing &)
< (escaped by writing <)
> (escaped by writing >)

What is CDATA?

If the text of your paragraph or code block uses a lot of characters that otherwise would need to be escaped, you might find it convenient to use CDATA, or (Unparsed) Character Data, to eliminate the need to transform each character in need of escaping. This is accomplished by beginning the section in question with <![CDATA[ and ending it with ]]>, as highlighted in this example:

Example 5

<code display="block">
<![CDATA[
<html>
  <title>This is an HTML document</title>
  <body>This is its body text</body>
</html>
]]>
</code>

In CNXML, failing to add the highlighted lines in the above code will result in a validation error. The validator would interpret the html tag as unknown CNXML inside the code tag.

What are table summaries?

When inserting a table into your document, a table summary is required. The table summary should describe the main purpose of the table, explain its overall structure, and can serve one or more of the following functions:

Summaries can be read by screen readers to help convey the information presented in the table. This is incredibly useful as it adds an accessibility option for those with visual or cognitive disabilities. The contents of the summary will not show on the screen, but can be used to help visually impaired readers that are listening to the content understand the table.
Summaries are a useful way to organize your data to be more easily read by search engines and indexed.
In more complex tables, such as tables with multiple column and/or row headers, the table summary can help the user quickly understand and make sense of the information the table is trying to convey to the user.

Example 6

In the following example, to place a summary for a table showing the number of petition signatures two students obtained over the course of a five day week, we set the "summary" attribute of the table tag, or add it in the "Description" textarea for tables in Edit-in-Place.

<table id="signatures" summary="This table shows the 
  number of petition signatures both Jon and Mary 
  collected each day of the weekend. Jon collected a 
  total of 41 signatures while Mary collected 72.">
  <title>
    Number of Signature Collected Over the Weekend
  </title>
  <tgroup cols="4">
    <thead>
      <row>
        <entry/>
        <entry>Friday</entry>
        <entry>Saturday</entry>
        <entry>Sunday</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>Jon</entry>
        <entry>7</entry>
        <entry>15</entry>
        <entry>19</entry>
      </row>
      <row>
        <entry>Mary</entry> 
        <entry>34</entry>
        <entry>7</entry>
        <entry>31</entry>
      </row>
    </tbody>
  </tgroup>
</table>