Skip to content Skip to navigation

Connexions

You are here: Home » Content » The Basic CNXML

Navigation

Lenses

What is a lens?

Definition of a lens

Lenses

A lens is a custom view of the content in the repository. You can think of it as a fancy kind of list that will let you see content through the eyes of organizations and people you trust.

What is in a lens?

Lens makers point to materials (modules and collections), creating a guide that includes their own comments and descriptive tags about the content.

Who can create a lens?

Any individual member, a community, or a respected organization.

What are tags? tag icon

Tags are descriptors added by lens makers to help label content, attaching a vocabulary that is meaningful in the context of the lens.

This content is ...

Affiliated with (What does "Affiliated with" mean?)

This content is either by members of the organizations listed or about topics related to the organizations listed. Click each link to see a list of all content affiliated with the organization.
  • CNX Documentation display tagshide tags

    This module is included inLens: Connexions Documentation
    By: Connexions

    Click the "CNX Documentation" link to see all content affiliated with them.

    Click the tag icon tag icon to display tags associated with this content.

Recently Viewed

This feature requires Javascript to be enabled.

Tags

(What is a tag?)

These tags come from the endorsement, affiliation, and other lenses that include this content.
 

The Basic CNXML

Module by: Ricardo Radaelli-Sanchez, Brent Hendricks. E-mail the authors

Summary: This is a basic introduction to the CNXML language. It includes a description on how to begin a CNXML module and also examples of the basic tags needed to start writing in CNXML.

Note: You are viewing an old version of this document. The latest version is available here.

Starting with CNXML

CNXML is a lightweight XML markup language for marking up educational content. The goal of CNXML is to convey the content of the material and not a particular presentation. The Connexions Project uses the Connexions Markup Language (CNXML) as its primary language for storing documents. Now let's get started!

CNXML Tags

Document

All CNXML documents have as their root the document tag. Everything about the document including it's metadata and content are contained within the document tag. It is important that you understand the basic structure for a CNXML document. The structure is as follows:

Document (root tag)

  • Name (required)
  • Metadata Section (optional)
  • Content Section (required)

Warning:

There is some additional information that is required for the document to validate. This is explained under the section titled Other Required Stuff.

The document tag has one required attribute:

  • id - a unique ID given to the document (usually assigned to you by the Connexions project)

ID Requirements

One major difference between CNXML and other markup languages is the id attribute requirement. Certain tags require that you include the id attribute. These tags are listed below:

  • document
  • para
  • equation
  • rule
  • definition
  • exercise
  • list
So, if you are going to use any of the above tags, be sure to add the id attribute and give it a unique 'id'. An example of this is shown below.

Example 1

	      
<para id='uniqueid1'>
  This is an example to illustrate the use of the <code>id</code> attribute.
</para>
<para id='uniqueid2'>
  This paragraph has a different id than the last.
</para>
note:
Any tag can contain an id attribute. This is useful if you want to link to the information contained in a particular tag.

Namespaces

The document tag should also contain any namespace declarations. Namespaces allow us to easily use other mark-up languages within CNXML without having to worry about whether tag name collision will occur. For simple documents using only CNXML, you need to include the CNXML namespace attribute xmlns='http://cnx.rice.edu/cnxml'. Any additional languages need to be declared as well and should be given their own prefixes. For example, to associate the MathML namespace with the prefix "m", include the following attribute: xmlns:m='http://www.w3.org/1998/Math/MathML'. This states that any tag with a prepended "m" will be interpreted as a MathML tag while any tag without a prefix will be interpreted as CNXML.

Example 2

<document id='doc1' xmlns='http://cnx.rice.edu/cnxml'>

Name

The name tag can be used with many CNXML tags to hold the name of its parent. This tag can only contain information in ASCII text. I mention it here to allow you to put in the name of the module (since I mentioned that it was the first required tag in the document tag).

Example 3

<name>Grilling a Good Steak</name>

note:

Please see the CNXML 0.5 specification to see if a tag can be named.

Content

Now that you have the document tag set up with an id and namespace info, the next thing to do with your document is add content. By 'content' I mean the text that will make up the bulk of your document.

note:

Strictly speaking the metadata should precede information about content, but we will leave this until later.
All of this content is conveniently placed in the content tag. Every CNXML document will have one content tag. The body of the document will be here inside the content tag.

Structural tags are the tags which are used inside of the content tag to give structure to the document. These tags are discussed below.

Structure Tags

Some of the structure tags are section, para, document, and content.

We have already discussed the document and content tags, so we will proceed with a short description and examples of the other other tags listed.

Para

Text can be inserted into documents by using the para tag. Each para has a required id which must be unique within the document.

Example 4


<para id='intro'>
  I have eaten many steaks in my life and none have been more satisfying
  than the backyard-grill cooked steak.  Maybe this is because of the
  relaxing nature of drinking a beer, being outside, and lounging that
  accompanies the grilling procedure.  Maybe it is because of the aroma
  of the grill and the beef perfectly seasoned to your taste.  Either
  way, this document shows how a good steak can be prepared.
</para>
Section

As often is the case in textbooks, chapters are divided into smaller sections. Because it is often necessary to segment text for better understanding and coherence, CNXML has included a section tag.

The section tag has one required attribute, id, and a required first child tag, name.

Example 5

		
<section id='ingredsec'>
  <name>Ingredients</name>
    <list> ... </list>
</section>
<section id='marinadesec'>
  <name>Marinade</name>
  <para id='marinate'> ... </para>
    <list id='marinade'> ... </list>
  <para id='tobecontinued'> ... </para>
</section>
<section id='grillingsec'>
  <name>Grilling</name>
  <para id='prepgrill'> ... </para>
  <para id='grilling'> ... </para>
</section>

Obviously ellipses would be replaced by appropriate text.

Inline Tags

Inline tags are used to embed content and functionality inside of the structural tags. Some of the more commonly used tags are discussed below.

Emphasis

The emphasis tag is used to emphasize text in a CNXML document where emphasis in text would be needed or desired. It is important to note that this refers to semantic emphasis and not a typeface, although many stylesheets may choose to render it visually with a different typeface.

Example 6


<para id='intro'>
  I have eaten many steaks in my life and none have been more satisfying
  than the backyard-grill cooked steak.  Maybe this is because of the
  relaxing nature of drinking a beer, being outside, and lounging that
  accompanies the grilling procedure.  Maybe it is because of the aroma
  of the grill and the beef <emphasis>perfectly</emphasis> seasoned to
  your taste.  Either way, this document shows how a good steak can be
  prepared.
</para>
Term

The term tag is used to mark words or phrases which are being defined. However, its use is confined to either a para or definition tag. The term tag has one optional attribute:

  • src - a URL specifying the source or definition of the term.

Example 7


<para id='marinade'>
  To ensure the best flavor possible, it is necessary to marinate the
  beef.  A steak <term src='http://marinade.com'>marinates</term> when
  left to sit in a prepared sauce, or <term>marinade</term>, where it
  will absorb the flavors of the ingredients.  Marinating may take as
  little as 15 minutes or as long as 6 hours and should
  <emphasis>always</emphasis> be done in the refrigerator and
  <emphasis>not</emphasis> at room temperature.
</para>
Note

The note tag creates an "out of line" note to the reader, which could be a warning, point of interest, etc. The type of note is specified by an optional type attribute.

Example 8


<para id='intro'>
  I have eaten many steaks in my life and none have been more
  satisfying than the backyard-grill cooked steak.  Maybe this is
  because of the relaxing nature of drinking a beer, being outside,
  and lounging that accompanies the grilling procedure.  <note
  type='warning'>Excessive drinking or fun may result in overcooked or
  burned steak.</note> Maybe it is because of the aroma of the grill
  and the beef <emphasis>perfectly</emphasis> seasoned to your taste.
  Either way, this document shows how a good steak can be prepared.
</para>

The above markup will display as:

I have eaten many steaks in my life and none have been more satisfying than the backyard-grill cooked steak. Maybe this is because of the relaxing nature of drinking a beer, being outside, and lounging that accompanies the grilling procedure.

Warning:
Excessive drinking or fun may result in overcooked or burned steak.
Maybe it is because of the aroma of the grill and the beef perfectly seasoned to your taste. Either way, this document shows how a good steak can be prepared.

CNXN and Link

The cnxn and link tags are the two tags in CNXML used for linking to other documents. The difference in the two tags are that cnxns are used for linking to other documents in the Connexions system while links are used for linking to general documents on the internet.

The cnxn tag has four attributes

  • target - targets a specific tag
  • document - targets a specific document by its ID
  • version - targets a specific version of a document
  • strength - designates the degree to which the linked information is related to the current document
The version attribute is optional. When not specified the cnxn will default the link to the most current version of the document. It may seem pointless, but it is actually quite useful. If you specify a specific version of a document, it will never change, meaning important parts, such as paragraphs or figures, will not disappear without warning.

The target and document attributes can be used together or alone. If both are used then you will link to a particular tag in another document. If only document is used, you will link to another document. If only target is used, you will link to a particular tag within the current document.

The strength attribute is optional. It can give the reader an indication of how related the additional information is to the current discussion.

Example 9: CNXN Example

The cnxn tag does not have to have a description of the destination in order to be used. For example, let's say you want to link to a figure inside the page but are unsure what to name the cnxn. You could you use a cnxn similar to the one below: 


		  
		<cnxn target='figure1'/>
When you use a cnxn such as the example above, a substitution will be made since no text was inserted into the tag. So, the above example would render as: Figure 1 or Reference depending on whether or not the system was able to find a suitable substitution. In most cases you can use text in the cnxn to describe the destination as in: 

		  
		<cnxn target='figure1'>Steak Figure</cnxn>

Example 10

		
<para id='tobecontinued'>
  I'll be adding to this document in <cnxn document='m9006' >The
  Intermediate CNXML</cnxn> which focuses on more advanced CNXML tags.
  For more marinades see the <link src='http://www.2eatcab.com'>Angus
  Beef website</link>.  Finally, a good resource is the <cite>Steak
  Lover's Cookbook -- William Rice; Paperback</cite>.
</para>

The above markup will display as:

I'll be adding to this document in The Intermediate CNXML which focuses on more advanced CNXML tags. For more marinades see the Angus Beef website. Finally, a good resource is the Steak Lover's Cookbook -- William Rice; Paperback.

Cite

The cite tag is used to refer to non-electronic materials within a document, primarily containing the title of a work. See Example 10.

Quote

The quote tag is used to denote that some text is a direct quote from some other source. The quote tag has a type attribute which denotes whether the quote is inline or block.

Example 11

<para id='steakquote'>
  Everyone has an opinion on how a steak should be cooked. <quote
  type='inline'>"A good steak should be pink in the middle and black
  on the outside."</quote> Although this may sound reasonable many
  remember the words of George Washington: <quote type='block'>"In any
  free country a man should have the ability to purchase a nice rare
  steak."</quote>
</para>
Everyone has an opinion on how a steak should be cooked. "A good steak should be pink in the middle and black on the outside." Although this may sound reasonable many remember the words of George Washington:
"In any free country a man should have the ability to purchase a nice rare steak."

Foreign

The foreign tag is used to denote that a foreign word or phrase is being used.

Example 12

<para id='steakquote2'>
  In many latin american countries steak is called <foreign>carne
  asada</foreign>.
</para>
In many latin american countries steak is called carne asada.

Document Example Code

Below is an example of what your document could look like if you included all the tags above to make a document about making a steak. 


	
      <document id='meat'
	xmlns='http://cnx.rice.edu/cnxml'
	>  
      <name>Grilling a Good Steak</name>

      <content>    

        <section id='intro'>
          <para id='intro'>
	    I have eaten many steaks in my life and none have been more
	    satisfying than the backyard-grill cooked steak.  Maybe this is
	    because of the relaxing nature of drinking a beer, being
	    outside, and lounging that accompanies the grilling procedure.
            <note type='warning'>Excessive drinking or fun may result in
	    overcooked or burned steak.</note> Maybe it is because of the
	    aroma of the grill and the beef <emphasis>perfectly</emphasis>
	    seasoned to your taste.  Either way, this document shows how a
	    good steak can be prepared.
          </para>
        </section>

        <section id='marinate_section'>	      
          <para id='marinate'>
	    To ensure the best flavor possible, it is necessary to marinate
	    the beef.  A steak <term>marinates</term> when left to sit in
            <term>marinade</term>, or prepared sauce, where it will absorb
	    the flavor of the ingredients.  Marinating may take as little as
	    15 minutes or as long as 6 hours and should
            <emphasis>always</emphasis> be done in the refrigerator and
            <emphasis>not</emphasis> at room temperature.
          </para>
        </section>

        <section  id='tobecontinued_section'>	      
          <para id='tobecontinued'>
	    I'll be adding to this document in <cnxn document='m9006'
	    >The Intermediate CNXML</cnxn> which focuses on more
	    advanced CNXML tags.  For more marinades see the <link
	    src='http://www.2eatcab.com'>Angus Beef website</link>.
	    Finally, a good resource is the <cite>Steak Lover's Cookbook --
	    William Rice</cite>.
          </para>
        </section>

      </content>
      </document>

See how Connexions would render this example.

Other Required Stuff

The first line in any XML file should be the XML declaration. (Strictly speaking, this is optional, but it's a good practice to follow). The XML declaration looks like this: <?xml version="1.0" standalone="no"?> , and must not be preceeded by any blank lines or whitespace. After this we declare what Document Type Definition (DTD) we'll be using for this document. (Strictly speaking, this is optional too. However, we must include it if we want to validate our document as CNXML). For flexibility, Connexions has made several DTDs available to allow authors to combine other markup languages with CNXML within a document. The DTD you specify will depend on which languages you wish to use in your document. For simple documents using only CNXML, the declaration is:

Example 13


	  
<!DOCTYPE document PUBLIC "-//CNX//DTD CNXML 0.5//EN" 
	  "http://cnx.rice.edu/cnxml/0.5/DTD/cnxml_plain.dtd">

For CNXML with MathML the declaration would be:

Example 14


	  
<!DOCTYPE document PUBLIC "-//CNX//DTD CNXML 0.5 plus MathML//EN" 
	  "http://cnx.rice.edu/cnxml/0.5/DTD/cnxml_mathml.dtd">

Conclusions

Remember that when composing documents it is always best to consult the CNXML Spec for any questions regarding the exact usage of CNXML tags. For more advanced topics see The Intermediate CNXML or The Advanced CNXML, which concludes the cooking lesson.

Content actions

Download module as:

PDF | More downloads ...

Add module to:

My Favorites (?)

'My Favorites' is a special kind of lens which you can use to bookmark modules and collections. 'My Favorites' can only be seen by you, and collections saved in 'My Favorites' can remember the last module you were on. You need an account to use 'My Favorites'.

| A lens I own (?)

Definition of a lens

Lenses

A lens is a custom view of the content in the repository. You can think of it as a fancy kind of list that will let you see content through the eyes of organizations and people you trust.

What is in a lens?

Lens makers point to materials (modules and collections), creating a guide that includes their own comments and descriptive tags about the content.

Who can create a lens?

Any individual member, a community, or a respected organization.

What are tags? tag icon

Tags are descriptors added by lens makers to help label content, attaching a vocabulary that is meaningful in the context of the lens.

| External bookmarks