<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!DOCTYPE document PUBLIC "-//CNX//DTD CNXML 0.5//EN" "http://cnx.rice.edu/cnxml/0.5/DTD/cnxml_plain.dtd">
<document xmlns="http://cnx.rice.edu/cnxml" xmlns:md="http://cnx.rice.edu/mdml/0.4" xmlns:bib="http://bibtexml.sf.net/" id="m9000">

  <name>Using Basic CNXML in Edit-In-Place</name>
  <metadata>
  <md:version>1.2</md:version>
  <md:created>2006/12/05 12:17:59 US/Central</md:created>
  <md:revised>2007/03/20 12:10:46.817 GMT-5</md:revised>
  <md:authorlist>
      <md:author id="lizzardg">
      <md:firstname>Elizabeth</md:firstname>
      
      <md:surname>Gregory</md:surname>
      <md:email>elizabeth.gregory@gmail.com</md:email>
    </md:author>
  </md:authorlist>

  <md:maintainerlist>
    <md:maintainer id="lizzardg">
      <md:firstname>Elizabeth</md:firstname>
      
      <md:surname>Gregory</md:surname>
      <md:email>elizabeth.gregory@gmail.com</md:email>
    </md:maintainer>
  </md:maintainerlist>
  
  <md:keywordlist>
    <md:keyword>CNXML</md:keyword>
    <md:keyword>Connexions</md:keyword>
    <md:keyword>content</md:keyword>
    <md:keyword>document</md:keyword>
    <md:keyword>markup</md:keyword>
    <md:keyword>namespace</md:keyword>
    <md:keyword>tag</md:keyword>
    <md:keyword>XML</md:keyword>
  </md:keywordlist>

  <md:abstract>This document introduces simple CNXML tags that are easy to use in Edit-in-Place.</md:abstract>
</metadata>
  
  <content>
    <note type="Please Note">This module also contains information derived from <cnxn document="m9007">The Advanced CNXML</cnxn> by <link src="http://cnx.org/member_profile/rars">Ricardo Radaelli-Sanchez</link>.</note><section id="sec1">
      <name>Starting with CNXML</name>
      <para id="element-410">To create the bare bones of content in Connexions, the author interface provides a variety of creation tools: the Document Importer, Edit-In-Place, and even a full-source editor.  However, a basic knowledge of our markup language can help make small edits into tremendous enhancements to your material!  </para><para id="intro"><link src="http://cnx.org">The Connexions Project</link>
	uses the <term>Connexions Markup Language</term> (<term>CNXML</term>) as its primary
	language for marking up and storing documents.  CNXML is lightweight <link src="http://en.wikipedia.org/wiki/XML">XML</link> for
	marking up educational content. Unlike the well-known HTML, the goal of CNXML is to convey
	the <emphasis>content</emphasis> of the material and not a particular presentation.  For example, say you have the following sentence: I like cupcakes very much.  However, you feel that you enthusiasm for cupcakes has not been fully expressed.  In HTML, you would use bold, underline, italic, etc.; in CNXML, you would use the <cnxn target="emphasis">emphasis</cnxn> <term>tag</term>.</para>
    </section>
    <section id="Inline_tags">
	  <name>Inline Tags</name>
	  <para id="inline_tags_para">Inline tags, such as emphasis, are used to embed content and functionality inside the structural tags, such as paragraphs.  Some of the more commonly used tags are discussed below.
	  </para>

	  <section id="emphasis">
	    <name>Emphasis</name>
	    <para id="emphp1">As mentioned <cnxn target="intro">previously</cnxn>, the <code type="inline">emphasis</code> tag is used to
	      accent certain text.  Note that this refers to <emphasis>semantic</emphasis>
	      emphasis and not a typeface.  Different <term>stylesheets</term>
	      can render emphasis with different typefaces.
	    </para>
	    <example id="emphexamp">
	      <code type="block"><![CDATA[<para id='intro'>
  Gardenias are my absolute <emphasis>favorite</emphasis> flower.  
  Their petals are soft, and their bloom has an absolutely 
  <emphasis>heavenly</emphasis> scent.
</para>]]>     
</code><para id="element-877">The above markup will display as:</para><para id="element-443">Gardenias are my absolute <emphasis>favorite</emphasis> flower.  Their petals are soft, and their bloom has an absolutely <emphasis>heavenly</emphasis> scent.</para>
	    </example>
	  </section>

	  <section id="term">
	    <name>Term</name>
	    <para id="termp1">The <code type="inline">term</code> tag is used to mark
	      words or phrases which are being defined.  However, its
	      use is confined to either a <cnxn document="m14395" target="para">para</cnxn> or <cnxn document="m9006" target="definition">definition</cnxn> tag.  The <code type="inline">term</code> tag has one optional
	      <term>attribute</term>: <code type="inline">src</code> - a URL
		  specifying the source or definition of the
		  term.</para>
	    <example id="termexamp">
	      <code type="block"><![CDATA[<para id='gardenia'>
  <term src="http://en.wikipedia.org/wiki/Gardenia">Gardenias</term> 
  can be tricky to maintain.  The soil around the roots of a 
  <term>gardenia</term> must remain moist always, but too much water 
  can damage the plant.  Also, <term>gardenias</term> enjoy the sun, 
  but if the <emphasis>foliage</emphasis> gets wet to bring the 
  gardenia into the shade.
</para>]]>      </code><para id="element-424">The above markup will display as:</para><para id="element-130"><term src="http://en.wikipedia.org/wiki/Gardenia">Gardenias</term> 
  can be tricky to maintain.  The soil around the roots of a 
  <term>gardenia</term> must remain moist always, but too much water 
  can damage the plant.  Also, <term>gardenias</term> enjoy the sun, 
  but if the <emphasis>foliage</emphasis> gets wet to bring the 
  gardenia into the shade.</para>
	    </example>
	  </section>
	  
	  <section id="note">
	    <name>Note</name>
	    <para id="notep1">The <code type="inline">note</code> tag creates an "out
	      of line" note (which could be a warning,
	      point of interest, etc.) to the reader.  The <code>type</code> of note is specified
	      by an optional <code type="inline">type</code> attribute.  If a <code>type</code> is not specified, the default is <code>Note</code>.
	    </para>
	    <example id="notexamp">
	      <code type="block"><![CDATA[<para id='pollen'>
  Receiving flowers is, on the whole, a wonderful thing.  
  However, sometimes pollen from the flowers can cause 
  problems.  In particular, the clean up of a bit of 
  pollen can be tricky.  <note type="Important">Do not 
  use water when cleaning up pollen!  This can lead to 
  counter-top and clothing stains!</note>  Your best bet 
  is to use a dry method of cleaning with a paper-towel.
</para>]]>      </code>
	      <para id="notep2">
		The above markup will display as: 
	      </para>
	      <para id="notep3">Receiving flowers is, on the whole, a wonderful thing.  However, sometimes pollen from the flowers can cause problems.  In particular, the clean up of a bit of pollen can be tricky.  <note type="Important">Do not use water when cleaning up pollen!  This can lead to counter-top and clothing stains!</note>  Your best bet is to use a dry method of cleaning, with a paper-towel, for example.</para>

	    </example>
	  </section>
	  
	  <section id="cnln">
	    <name>CNXN and Link</name>
	    <para id="cnlnp1">The <code type="inline">cnxn</code> and <code type="inline">link</code> tags are 
	      used for linking to other documents.  The <code>cnxn</code> tag is specifically used for linking to
	      other documents in the Connexions system, while the <code>link</code> tag is
	      used for linking to general documents on the internet.
	    </para>
	    <para id="cnxn">The <code type="inline">cnxn</code> tag has four
	      attributes:
	      <list id="cnxnlist"><item>
		  <code type="inline">target</code> - targets a
		specific tag within a document</item>
		<item>
		  <code type="inline">document</code> - targets a
		specific document by its ID </item>
		<item>
		  <code type="inline">version</code> - targets a
		specific version of a document
		</item>
		<item>
		  <code type="inline">strength</code> - designates the
		  degree to which the linked information is related to
		  the current document
		</item>
	      </list>
	      The <code type="inline">version</code> attribute is
	      optional.  When not specified the cnxn will default the
	      link to the most current version of the document.  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.  On the other hand, you will not see any updated information in that document if you specify the version.
	    </para>
	    <para id="cnxn2">The <code type="inline">target</code> and <code type="inline">document</code> attributes can be used
	      together or alone.  If both are used then you will link
	      to a particular place in another document.  If only <code type="inline">document</code> is used, you will link to
	      a document as a whole.  If only <code type="inline">target</code> is used, you will link to a
	      particular tag within the current document.
	    </para>
	    <para id="cnxn2b">The <code type="inline">strength</code> attribute is
	      optional and can give the reader an indication of how
	      related the additional information is to the current
	      discussion.
	    </para>

	    <example id="cnxn_info">
	      <name>CNXN Example</name>

	      <para id="cnxn_info_para">The cnxn tag does not have to have a description of
		the destination in order to be used. For example,
		say you want to link to a figure. You could you
		use a cnxn similar to the one below:
		<code type="block"><![CDATA[    <cnxn target='tbonefig' document="m10278"/>]]></code>	
	      </para>
              <para id="midpara2">
                The above markup will display as:
              </para>
              <para id="midpara"><cnxn target="tbonefig" document="m10278"/>
              </para><para id="element-584">Notice how the display says "(Reference)".  When you point to something that it not within the document, this will be the display.  However, pointing to a tag within the document has a different display:</para><code type="block"><![CDATA[    <cnxn target="element-852"/>]]></code><para id="element-374"><cnxn target="element-852"/></para><figure id="element-852"><media type="image/jpeg" src="alb_jul_flo_1.jpg"/>
<caption>Picture taken by Jennifer Drummond (CC Attribution).</caption></figure><para id="element-33">Using an empty cnxn tag like this is an easy way to point to a specific part of a document; all the numbering is done for you, and if you need to insert a new figure in the middle of the document, the numbering will change automatically.</para>
	    </example>
            <example id="cnxnex2"><name>CNXN example</name>
              <para id="Whenyouuse">Also, you can use your own text instead of the autogenerated text:
		<code type="block"><![CDATA[<cnxn target='element-852'>Momosa Picture</cnxn>]]></code>
	      </para><para id="element-983">The above markup will display as:</para><para id="element-708"><cnxn target="element-852">Momosa Picture</cnxn></para>
	    </example>
	    
	    <para id="link">The <code type="inline">link</code> tag, on the other
	      hand, has only a required <code type="inline">src</code>
	      tag which contains a URL for the target online document.
	    </para>
	    <example id="cnlnexamp"><name>Link Example</name>
	      <code type="block"><![CDATA[<para id='moretips'>
  For more gardening tips, see 
  <link src="http://www.bhg.com/bhg/gardening/index.jhtml">Better 
  Homes and Gardens' Garden Section</link>.  
</para>]]>   </code>
	      <para id="noteex10a">
		The above markup will display as: 
	      </para>
	      <para id="noteex10b">For more gardening tips, see <link src="http://www.bhg.com/bhg/gardening/index.jhtml">Better Homes and Gardens' Garden Section</link>.  </para>

	    </example>
	  </section>

	  <section id="cite">
	    <name>Cite</name>
	    <para id="citep1">The <code type="inline">cite</code> tag is used to refer
	      to non-electronic materials within a document, and primarily
	      contains the title, the author, and/or a page number of a work.  
	    </para><example id="element-511"><name>Cite Example</name>
<code type="block"><![CDATA[Finally, a good resource is the <cite>Garden Lover's 
Cookbook -- William M. Rice; Paperback</cite>.]]>
</code>
<para id="citelike">
The above markup will display as:
</para>
<para id="finally">Finally, a good resource is the <cite>Garden Lover's Cookbook -- William M. Rice; Paperback</cite>.
</para></example>
	  </section>

	  <section id="quote">
	    <name>Quote</name>
	    <para id="quote_para">The <code type="inline">quote</code> tag is used to
	      denote that some text directly quotes another
	      source. The quote tag has a <code type="inline">type</code> attribute which denotes
	      whether the quote is <code type="inline">inline</code>
	      or <code type="inline">block</code>.
	    </para>
	    <example id="quote_example"><name>Quote Example</name>
	      <para id="quote_para_example"><code type="block"><![CDATA[<para id='steakquote'>
  Every plant needs a different amount of water in order to grow 
  well. <quote>"If you water each plant the same, you will always 
  water too much and too little."</quote>  Also, remember the words 
  of Lou Erickson: 
  <quote type='block'>"Gardening requires lots of water - most of 
  it in the form of perspiration."</quote>
</para>]]></code>
		Every plant needs a different amount of water in order to grow well.  <quote>"If you water each plant the same, you will always water too much and too little."</quote>  Also,
  remember the words of Lou Erickson: <quote type="block">"Gardening requires lots of water - most of it in the form of perspiration."</quote></para>
	    </example>
	  </section>
	  
	  <section id="foreign">
	    <name>Foreign</name>
	    <para id="foreign_para">The <code type="inline">foreign</code> tag is used to
	      denote that a word or phrase foreign to the language of the document is being used.
	    </para>
	    <example id="foreign_example"><name>Foreign Example</name>
	      <para id="foreign_para_example"><code type="block"><![CDATA[<para id='steakquote2'>
  All flowers have a scientific name, often derived from latin.  
  <foreign>Gardenia augusta</foreign> is the name of a type of 
  gardenia found in Japan.
</para>]]></code>
		 All flowers have a scientific name, often derived from latin.  <foreign>Gardenia augusta</foreign> is the name of a type of gardenia found in Japan.
	      </para>
	    </example>
	  </section>
<section id="code">
      <name>Code</name>
      <para id="codelp1">The <code>code</code> tag is used to insert example computer
	output/input as either inline text within a paragraph or as a
	block of text.  The <code>code</code> tag has a <code>type</code>
	attribute with two possible values:
	<list id="code_list">
	  <item>
	    <code>inline</code> (default) - used to specify code that
	    is inline.</item>
	  <item>
	    <code>block</code> - used to specify code that should be
	    in a separate block of text.</item>
	</list>
      </para>

      <example id="codelexamp"><name>Inline Code Example</name>
	<para id="element-872">For now, take a look at what the inline code looks like:</para><code type="block"><![CDATA[
<para id='copy'>
  In a unix terminal the command to copy a file is 
  <code type='inline'>cp original copy</code>.
</para>]]>
	</code>
	<para id="copy">
	  In a unix terminal the command to copy a file is <code type="inline">cp original copy</code>
	</para>
      </example><para id="element-592">You will see more about code blocks in <cnxn target="code" document="m14395">Advanced CNXML using Edit-In-Place</cnxn>.</para>
    </section>

	</section>
  </content>
</document>
