Connexions

You are here: Home » Content » Editing CNXML with Altova's Authentic
Content Actions

Editing CNXML with Altova's Authentic

Module by: Adan Galvan, Brent Hendricks, Mark Husband

Summary: The Authentic XML editor from Altova allows you to quickly and easily edit CNXML files.

Every Connexions module contains a CNXML file. It is generated by Connexions when you first create a module. This file is named index.cnxml and you can see it under the "Files" tab when you are editing a module. The file contains both metadata and content. The metadata is information about the file, for example, the document type, the author's name, creation date, revision date, and so on. The Connexions system inserts the metadata into the file based on the information you enter when you create or update a module. The content part of the file is the headings, text, links to images, and so on that you put into the file. If you want to change the metadata, you must make your changes on the "Metadata" tab when you are editing a module in Connexions.
The procedure for editing a CNXML file with Authentic consists of the following tasks:
  • Visit the Altova Web site and follow their instructions to install the Authentic XML editor on your computer.
  • Obtain a copy of the CNXML stylefile and associate it with the Authentic editor on your computer.
  • For new content, create a module in a Connexions workspace or workgroup. For existing, published content, check out the module to a Connexions workspace or workgroup.
  • Export the CNXML file from the module as an "XMLSpy/Authentic" file.
  • Launch Authentic, open the CNXML file, and make your edits.
  • Import the CNXML file back into the Connexions module as an "XMLSpy/Authentic" file.
Note: This module provides a basic description of using the Authentic XML editor to edit Connexions CNXML files. For a more comprehensive description of all the features of Authentic, see the documentation on the Altova Web site.

The Authentic XML Editor

Editing a CNXML file can be a complicated task if you are not familiar with XML and the CNXML markup language. CNXML contains many markup tags and some of the tags have different rules for applying them to your content. However, it is the CNXML markup tags that help to make Connexions a feature-rich resource for sharing knowledge. Among the many editing tools that are available to you, the author, is a third-party XML editor named Authentic®. Authentic is available free, on the Internet, from Altova®. Using Authentic, you can quickly and easily edit your CNXML files without being an expert in CNXML. Authentic is a "light" version of XMLSpy, which is a powerful, commercially-available XML editor from Altova.
To view the Altova Web site, click the following link: Display the Authentic product Web page and follow the instructions for downloading the Authentic XML editor (Desktop edition).
Note: Authentic has a Desktop edition and a Browser edition you can download. It is very important that you download the Desktop edition. You cannot perform the editing tasks mentioned in this document if you do not have the Desktop edition.

The Connexions Stylesheet (cnxml.sps)

Before you can edit a CNXML file with Authentic, you must first associate the stylesheet (cnxml.sps), which was specifically created for editing CNXML files with Authentic. This stylesheet enables Authentic to recognize CNXML tags and to insert them for you while you are editing. It also enables Authentic to validate, or check, that the CNXML markup tags are being applied correctly.

Downloading the Stylesheet

To obtain a copy of the cnxml.sps stylesheet, right-click the following link: Select the option to save the file to your desktop or any location where you can easily find it.

Associating the Stylesheet to Authentic

To associate the cnxml.sps stylesheet with Authentic, use the following steps:
  1. Launch the Authentic editor.
  2. Select File -> New... from the menu bar. The "Create new document" dialog box appears.
    altovasps.png
    Figure 1: The "Create new document" dialog box.
  3. Click the Browse... button. The "Open" dialog box appears.
    altovaopen.png
    Figure 2: The "Open" dialog box.
  4. Select the cnxml.sps file from the list of items on your desktop.
  5. Click Open and Authentic accesses the cnxml.sps file and opens a new CNXML file. Now the stylesheet is associated with Authentic. Close the new file and do not save it.
Note: Disregard the new file that was created when you associated the stylefile to Authentic. That file does not contain any Connexions metadata, which is required for the Connexions system. When you create a new module on Connexions, the system creates a CNXML file (index.cnxml) with the necessary metadata. The CNXML file exported from the module is the file you edit with Authentic.

Editing CNXML Files with Authentic

Different Views

Authentic provides two ways of looking at your CNXML file: the Authentic view and the Browser view. The Authentic view displays your file in an editing interface where you can add, change, or remove content. The Browser view displays your file as it would appear in an Internet browser. To change views, click one of the buttons on the bottom of the editing panel. An example of a CNXML file displayed in Authentic view is in Figure 3. An example of the same CNXML file displayed in Browser view is in Figure 4.
authenticview.png
Figure 3: The Authentic view of a CNXML file.
browserview.png
Figure 4: The Browser view of a CNXML file.

Displaying Tags

Displaying the markup tags while you edit shows the actual element boundaries in the flow of text. This enables you to correctly place your cursor and insert content where you want to place it. You can use one of the four tag buttons in the Authentic toolbar to show or hide the tags. Examples of the buttons are shown in the following figure and a brief description of each button appears after the figure.
Hide MarkupSmall MarkupLarge markupMixed markup
hidemarkup.pngsmallmarkup.pnglargemarkup.pngmixedmarkup.png
Subfigure 5.1:
Subfigure 5.2
Subfigure 5.3
Subfigure 5.4
Figure 5: The four Markup buttons in the toolbar.
A description of the action performed by each button appears in the following list:
  • Hide Markup - click this button to hide all the tags.
  • Small Markup - click this button to display small tags, which are triangle-shaped graphics without labels.
  • Large Markup - click this button to display large tags that have labels identifying them.
  • Mixed Markup - click this button to display a combination of the small and large tags. The small tags appear with inline elements, such as <emphasis> or <term>. The labeled tags appear with the block elements, such as <section> or <para>.
Experiment with these different markup buttons to determine which level of tag display you prefer. You may find it helpful to switch between levels of tag display while you edit. See Figure 6 for an example of a CNXML file with the large markup tags displaying.
module-authentic.png
Figure 6: A CNXML file displaying in Authentic mode with large markup tags.
The Authentic view is the view in which you edit the CNXML file. Please note the following things about this view:
  • Some CNXML tags require an ID. For these, Authentic shows (id: ) after the tag name. You must enter a unique identifier for each such tag in your document. The ID is displayed in red in this view to indicate that this is required, but tag name and the ID do not display in the final output.
  • There are links within some tags that when clicked prompt you to choose a child tag to insert in the tag. These links only appear when there are child tags or other attributes that can be included within the given tag. For example, an add type link appears when you insert a list. Click the link and a drop-down menu appears that contains the options for the type of list you may enter at this point.
  • Authentic makes a distinction between inserting and appending elements. Insert means to add an element before the current element. Append means to add an element after the current element.

Adding Content

Adding New Content To add new content, use the following steps:
  1. Display the CNXML file in the Authentic view.
  2. Place the cursor in the file at the point where you want to add the new content and click. Be careful to place the cursor correctly relative to the opening and closing tags for existing elements.
  3. Select the type of element you want to add, either from the Elements box or right-click to display the pop-up menu of elements you can add.
  4. Enter the content for the element within the opening and closing tags for the element.
Editing Existing Content To edit existing content, use the following steps:
  1. Display the CNXML file in the Authentic view.
  2. Insert or delete content as necessary. When deleting an entire element, be certain to select opening and closing tags for that element along with the content.
Applying Inline Tags Once you have written some text, you may want to mark up a word or phrase with an inline CNXML tag. Inline tags are used on content within an element marked up by block tags to identify content with special characteristics. To do this:
  1. Select the text to be marked.
  2. Specify the desired element type. Either click the element name in the Elements box, or right-click and select Apply->*element* where *element* is the name of the desired tag.
elements.png
Figure 7: The Elements box.
Working with Element Markup Tags CNXML contains many markup tags and some of the tags have different rules for applying them to your content. The following list highlights some general rules about applying CNXML tags:
  • When you add a section you are required to give it a name, an ID, and at least one child element. You can click the add... link below the section name to display a list of the elements that are valid children inside of the section.
    Note: Always remember to add an ID when it appears next to a tag. The document cannot validate without an ID in each required location.
  • When you add a para a box appears in which you enter the text for your paragraph. Give the paragraph an ID and then type the text in the box. The box is merely an editing aid. It does not display in the final document.
  • When you add an example a box appears that is designated as an 'Example'. You can add a name if you wish. The ID (as always) is mandatory. Click the add... link below the example name to add a child element to the example.
  • When you add an exercise the word 'Exercise' followed by problem and solution. You must add an ID to the exercise. Next, you must add some content to the problem. To see a list of valid child elements for problem click the add... link next to the word 'Problem'. You may add a Solution, but this is optional.
  • When you add a list the first thing to do is add an ID. Next, add a type by clicking the add type link beside the list ID. Move the cursor down next to the bullet to add content to the item. To add another item press Enter.
    Known Bug: In Authentic the list type does not change automatically when you select a type. To work around this, select a type then save and re-open the document, or select a type then switch to the Browser view and back again.
For a complete list of all the CNXML tags and a description of how to use them, see the CNXML Language Specification.

Adding a Glossary

To add a glossary entry, use the following steps:
  1. Click the add glossary link at the bottom of the document. A glossary entry box displays.
  2. Insert an ID for the definition entry.
  3. Insert the term you want in the glossary.
  4. Insert the text of the meaning for the term.
  5. Optional. Click the add seealso link to add a reference to related material.
  6. Optional. Click the add example link to add an example.
glossary.png
Figure 8: Adding a glossary entry box

Adding a Bibliography

To add a bibliography entry, use the following steps:
  1. Click the add bib:file link at the bottom of the document. A bibliography entry box displays.
  2. Insert an ID for the bibliography.
  3. Click the add... link. A pop-up list of the valid types of bibliography entries appears.
  4. Select the desired type of entry from the list. Entry fields appropriate for that type of entry appear.
  5. Enter the necessary information.
bibliography.png
Figure 9: Adding a bibliography entry box.

Validating and Previewing Your Work

Now that you have created your document, you will want to see what you have created. First ensure that the document is valid. To do so, simply press the F8 function key on your keyboard. If there are errors in your page they will be displayed at the bottom of the page. You will have to fix these errors before you will be able to preview your document. The cursor will automatically move to the position in the document where the error exists.
To preview the document simply switch to browser view by clicking on the browser view button. (This button is on the toolbar and looks like a piece of paper with a planet on it. See the far right button in (Reference)). This is what your finished document will look like. Note that IDs, labels, and paragraph boxes do not appear in the finished text.

Helpful Hints

  • Save your work often!
  • If you have trouble clicking in the space to add an ID, try moving the cursor slightly to the left or right. Sometimes Authentic is picky about where it allows you to click.
  • Preview often to make certain you are getting the output you want to have.
  • Do not forget to add IDs where they are required.
  • Do not be afraid to make a mistake. If you do something and you change your mind, press CTRL+Z to undo the last editing action you did. You can repeat this action to undo several changes.

Comments, questions, feedback, criticisms?

Send feedback