The Basic CNXML

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. Connexions 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)Title Metadata Section Content Section The document tag has one required attribute: id - a unique ID given to the document. This is automatically assigned.

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, but all can possess an id. The tags requiring an id are listed below: document para equation list rule definition exercise table div section subfigure example footnote problem solution block quotes media meaning proof list preformat block code figure block notes 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'. Be aware that in CNXML 0.6 ids will be generated automatically, but you are still permitted to specify you own ids if you wish. Here is an example of a couple of paras containing a user generated ids.


	      
<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>

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

. 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. The document tag should also contain the metadata namespace xmlns:md="http://cnx.rice.edu/mdml/0.4", the bibtex namspace xmlns:bib="http://bibtexml.sf.net/", and the question markup language xmlns:q="http://cnx.rice.edu/qml/1.0".



	  This what the document tag should look like.  <document xmlns="http://cnx.rice.edu/cnxml" 
xmlns:m="http://www.w3.org/1998/Math/MathML" 
xmlns:md="http://cnx.rice.edu/mdml/0.4" 
xmlns:bib="http://bibtexml.sf.net/" 
xmlns:q="http://cnx.rice.edu/qml/1.0" id="m9000" module-id="" cnxml-version="0.6">
	    
	   Be aware that the you document id can not be the same as this example. Each module will have its own unique id.



      TitleThe title tag can be used with
	  many CNXML tags to hold the name of its parent.  This tag
	  can only contain information in ASCII text or MathML. 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).
	

	
	  <title>Grilling a Good Steak</title>
	
	
	Please see the CNXML tag list in Edit-In-Place 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. 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.
	    
	    
	      

<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 optional first child tag,
	      title.
	    
	    
	      
<section id='ingredsec'>
  <title>Ingredients</title>
    <list> ... </list>
</section>
<section id='marinadesec'>
  <title>Marinade</title>
  <para id='marinate'> ... </para>
    <list id='marinade'> ... </list>
  <para id='tobecontinued'> ... </para>
</section>
<section id='grillingsec'>
  <title>Grilling</title>
  <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.
	    
	    
	      

<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 several optional
	      attributes:
	      
		url - a URL
		  specifying the source or definition of the
		  term.
window - contains the possible values "replace" which results in the associated url opening in the present window, and "new" which result in the associated url opening in a new window or tab.
document - the id of another Connexions module or collection.
target-id - the id of a specific element (such as a para or section) in the current or another Connexions document.
resource - This reference points to a file that is associated with the term in question. The resource could be a pdf, text file, or any other supplementary resource.
version - The version of a Connexions module or collection. This attribute is used in conjunction with the document attribute.
id - A unique identifier, whose value must begin, with a letter and contain only letters, numbers, hyphens, underscores, colons, and/or periods (no spaces).
	      
	    
	    
	      
<para id='marinade'>
  To ensure the best flavor possible, it is necessary to marinate the
  beef.  A steak <term url='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 a note to the reader, which could be a warning, tip, etc. There are five allowed types of note: note
aside
warning
tip
important
.  The type of note is specified by an optional type attribute.
	    
	    
	      

<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.  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.
	      

	    
	  
	  
	  Link
	    
	    The link tag is
	      used to provide a quick link to other Connexions modules, collections or external websites. The link tag can contain the following attributes.
	    
	    
	    strength - The Strength attribute can contain the values 1, 2, or 3 (with 3 being the strongest) specifying the relevance of the link. 

		url - a URL
		  specifying the source or definition of the
		  term.
window - contains the possible values "replace" which results in the associated url opening in the present window, and "new" which result in the associated url opening in a new window or tab.
document - the id of another Connexions module or collection.
target-id - the id of a specific element (such as a para or section) in the current or another Connexions document.
resource - This reference points to a file that is associated with the term in question. The resource could be a pdf, text file, or any other supplementary resource.
version - The version of a Connexions module or collection. This attribute is used in conjunction with the document attribute.
id - A unique identifier, whose value must begin, with a letter and contain only letters, numbers, hyphens, underscores, colons, and/or periods (no spaces).
	      
	      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.
	    
	    

	    
	    
	    
	    
	  

	  
	    Cite
	    The cite tag is used to refer
	      to non-electronic materials within a document, primarily
	      containing the title of a work.  Cite has several optional attributes:
url - a URL
		  specifying the source or definition of the
		  term.
window - contains the possible values "replace" which results in the associated url opening in the present window, and "new" which result in the associated url opening in a new window or tab.
document - the id of another Connexions module or collection.
target-id - the id of a specific element (such as a para or section) in the current or another Connexions document.
resource - This reference points to a file that is associated with the term in question. The resource could be a pdf, text file, or any other supplementary resource.
version - The version of a Connexions module or collection. This attribute is used in conjunction with the document attribute.
id - A unique identifier, whose value must begin, with a letter and contain only letters, numbers, hyphens, underscores, colons, and/or periods (no spaces).
	      
	    
	  

	  
	    Quote
	    The quote tag is used to
	      denote that some text is a direct quote from some other
	      source. The quote tag has a display attribute which denotes
	      whether the quote is inline
	      or block. Quote can also contain all of the attributes associated with cite.
	    
	    
	      
		<para id='steakquote'>
  Everyone has an opinion on how a steak should be cooked. <quote
  display='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. Foreign can also contain all of the attributes associated with cite.
	    
	    
	    
	      
		<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'>  
      <title>Grilling a Good Steak</title>

      <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 <link document='m9006'
	    >The Intermediate CNXML</link> which focuses on more
	    advanced CNXML tags.  For more marinades see the <link
	    url='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" encoding="utf-8"?> , and must not be preceeded by any
	blank lines or whitespace.  CNXML 0.6 only uses one schema, so there is no need to specificy specific DTDs. Below is an example of a correct CNXML 0.6 document tag containing the proper namespaces.
      
	<document xmlns="http://cnx.rice.edu/cnxml" 
xmlns:m="http://www.w3.org/1998/Math/MathML" 
xmlns:md="http://cnx.rice.edu/mdml/0.4" 
xmlns:bib="http://bibtexml.sf.net/" 
xmlns:q="http://cnx.rice.edu/qml/1.0" 
id="m9000" module-id="" cnxml-version="0.6">

	 
      
      

      
    
    
    
      Conclusions
      Remember that when composing documents it is always best to
	consult the
	CNXML Tag List 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.