Connexions

You are here: Home » Content » CNXML Reference Extensions
Content Actions

CNXML Reference Extensions

Module by: Adan Galvan

Summary: A module describing the use of bibtexml with cnxml, as well as as introduction to the glossary tag.

Introduction

As an author/editor, you will often times need a way to include additional information in a document that does not actually appear in the flow of text. This information may include a glossary, and bibliographic references. There are many ways to include this type of information, but for our purposes, we have chosen to create a new CNXML tag named glossary, and have chosen to use an xml language called bibteXML for references. The two are described below. I have also included the glossary and bibteXML file examples in the source of this document. Scroll to the bottom of the page to see how these examples would be rendered.

BibteXML

"BibteXML is a bibliography DTD for XML that expresses the content model of BibTeX, the bibliographic system for use with LaTeX. It provides conversion tools for tagging your bibliographic data in XML, or export it to HTML or native BibTeX syntax, saving typing time." [source]
In plain language, this means that bibtexml is an XML version of the popular and widely accepted latex extension bibtex. One can markup references in their document using semantic tags such as author and editor. More info will be provided below.

The 'Glossary' Tag

Often in textbooks there will be a list of definitions included at the end of the book. In the same way, the glossary tag will contain a list of definitions that will be included at the end of a module. One can link to these definitions using the term tag (see Example 2).

Including a Glossary

It is very easy to include a glossary in your CNXML document. In the Basic CNXML Tutorial it is stated that the structure usually resembles the following:
    Document
  • name
  • metadata(optional)
  • content
When one wishes to add a glossary the structure will change to match the following:
    Document
  • name
  • metadata(optional)
  • content
  • glossary
Inside of the glossary tag one can add as many definitions as one wishes. For more information on the definition tag, see the CNXML 0.5 specification.
Example 1: Glossary Example 
Following is an example of the code necessary to add a glossary with one definition. 
<glossary>
  <definition id='quardef'>
    <term>quarter</term>
    <meaning><name>Meaning Name</name>One fourth of something.</meaning>
    <example id='def'>
      <para id='par'>
	"He cut the pie into quarters and gave all four people a
	piece."
      </para>
    </example>
    <meaning>25 cents, a quarter of a dollar.</meaning>
    <example id='def2'>
      <para id='par2'>
	"The drink cost a quarter."
      </para>
    </example>
    <example id='def3'>
      <para id='par3'>
	"She picked up a roll of quarters so that she could do
	laundry."
      </para>
    </example>
  </definition>
</glossary>
Example 2: Linking to Definitions in a Glossary 
Often, one will need to refer to a definition in the glossary. To do this, one can use the term tag. By putting the src attribute in the term tag, one can link to a definition. Simply set the value of the src attribute to the id of the definition in the glossary, and that term will automatically become a link to the definition in the glossary. Shown below is an example of the term tag being used to link to the definition in the definition example: 
	    <term src='#quardef'>quarter</term>

Including BibteXML

It is very easy to include a bibteXML reference section in your CNXML document. In the Basic CNXML Tutorial it is stated that the structure usually resembles the following:
    Document
  • name
  • metadata(optional)
  • content
When one wishes to add a bibteXML reference section the structure will change to match the following:
    Document
  • name
  • metadata(optional)
  • content
  • glossary
  • file
Note: It is possible to include either a glossary or a bibteXML file or both. The only restriction is that if you include both the glossary must precede the bibteXML file.
The file tag is the root tag of the bibteXML language. Inside of the file tag one will add other tags that correspond to the different type of bibliographical references. An example of a bibliography is given below:
Example 3: BibteXML Example 
<bib:file>
  <bib:entry id="esbensen">
    <bib:book>
      <bib:author>Kim Esbensen; Tonje Midtgaard; Suzanne Schonkopf</bib:author>
      <bib:title>Multivariate Analysis in Practice</bib:title>
      <bib:publisher>Camo AS</bib:publisher>
      <bib:year>1994</bib:year>
      <bib:address>Trondheim</bib:address>
    </bib:book>
  </bib:entry>

  <bib:entry id="martens.nes">
    <bib:book>
      <bib:author>Harald Martens; Tormod Nas</bib:author>
      <bib:title>Multivariate Calibration</bib:title>
      <bib:publisher>John Wiley &amp; Sons Ltd.</bib:publisher>
      <bib:year>1989</bib:year>
      <bib:address>Chichester</bib:address>
    </bib:book>
  </bib:entry>
</bib:file>
Note: Each tag in the example code begins with a namespace prefix. In the case of bibteXML, the prefix is bib:.
Example 4: Linking to Bibliography 
You will want to refer to an entry in the bibliography. To do this, one can use the cite tag. By putting the src attribute in the cite tag, one can link to a bibliographic entry. Simply set the value of the src attribute to the id of the bib:entry, and that reference will automatically become a link to the bibliographic entry. Shown below is an example of the cite tag being used to link to the bibliography in Example 3: 
	    <cite src='#esbensen'>Multivariate Analysis in Practice</cite>

BibteXML Tags

By looking at Example 3 one can see the types of tags that are available for use in bibteXML. Below I will attempt to give a brief explanation on the use of some of the bibteXML tags. For more information and the complete specification please see BibteXML Homepage.

File

The file tag is the root tag of the bibteXML language. It denotes the beginning of the bibliography.
Children The file tag must contain one or more entry tags.

Entry

The entry tag denotes the beginning of an individual bibliographical reference.
Children The entry must contain one of the following containers:
  • article
  • book
  • booklet
  • manual
  • techreport
  • mastersthesis
  • phdthesis
  • inbook
  • incollection
  • proceedings
  • inproceedings
  • conference
  • unpublished
  • misc

Containers

Each of the possible children of entry (article, book, booklet, etc.) are containers for metadata on that specific type of entry.
Children Every container tag must contain a different combination of bibteXML metadata tags. For more information on exactly which children a specific container may possess, please see the BibteXMLHomepage.

BibteXML Metadata Tags

Every child listed as a possible child of entry can contain metadata tags. These metadata tags are now listed.
    Metadata Tag List
  • address
  • author
  • booktitle
  • chapter
  • edition
  • editor
  • howpublished
  • institution
  • journal
  • month
  • note
  • number
  • organization
  • pages
  • publisher
  • school
  • series
  • title
  • type
  • volume
  • year
Children Every metadata tag can contain unicode text.

Glossary

quarter:
1. Meaning Name: One fourth of something.
Example:  
"He cut the pie into quarters and gave all four people a piece."
2. 25 cents, a quarter of a dollar.
Example:  
"The drink cost a quarter."
Example:  
"She picked up a roll of quarters so that she could do laundry."
References
  1. Kim Esbensen; Tonje Midtgaard; Suzanne Schonkopf. (1994). Multivariate Analysis in Practice. Trondheim: Camo AS.
  2. Harald Martens; Tormod Nas. (1989). Multivariate Calibration. Chichester: John Wiley & Sons Ltd.

Comments, questions, feedback, criticisms?

Discussion forum

Send feedback