Skip to content Skip to navigation

Connexions

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

Navigation

Content Actions
  • Download module PDF
  • Add to ...
    Add the module to:
    • My Favorites
    • A lens
    • An external social bookmarking service
    • My Favorites (What is 'My Favorites'?)
      'My Favorites' is a special kind of lens which you can use to bookmark modules and collections directly in Connexions. 'My Favorites' can only be seen by you, and collections saved in 'My Favorites' can remember the last module you were on. You need a Connexions account to use 'My Favorites'.
    • A lens (What is a lens?)

      Definition of a lens

      Lenses

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

      What is in a lens?

      Lens makers point to Connexions 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 Connexions 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
  • E-mail the authors
  • Rate this module (How does the rating system work?)

    Rating system

    Ratings

    Ratings allow you to judge the quality of modules. If other users have ranked the module then its average rating is displayed below. Ratings are calculated on a scale from one star (Poor) to five stars (Excellent).

    How to rate a module

    Hover over the star that corresponds to the rating you wish to assign. Click on the star to add your rating. Your rating should be based on the quality of the content. You must have an account and be logged in to rate content.

    		(0 ratings)

Lenses

What is a lens?

Definition of a lens

Lenses

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

What is in a lens?

Lens makers point to Connexions 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 Connexions 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: ConnexionsAs a part of collection:"Connexions Tutorial and Reference"

    Comments:

    "The canonical how-to guide to using 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.

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.

Warning: Altova Authentic Not Currently Supported:

Due to changes introduced in recent versions of Altova Authentic and updates to the CNXML language with version 0.6, we are not currently able to support this method for creating and maintaining Connexions content. We hope to be able to reintroduce support in the near future. We apologize for any inconvenience. If you have questions about authoring support, please contact techsupport@cnx.org and we will be happy to assist you.

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.
    Figure 1: The "Create new document" dialog box.
    Figure 1 (altovasps.png)
  3. Click the Browse... button. The "Open" dialog box appears.
    Figure 2: The "Open" dialog box.
    Figure 2 (altovaopen.png)
  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.

Figure 3: The Authentic view of a CNXML file.
Figure 3 (authenticview.png)
Figure 4: The Browser view of a CNXML file.
Figure 4 (browserview.png)

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.

Figure 5: The four Markup buttons in the toolbar.
Hide MarkupSmall MarkupLarge markupMixed markup
(a) (b) (c) (d)
Hide Markup (hidemarkup.png)Small Markup (smallmarkup.png)Large markup (largemarkup.png)Mixed markup (mixedmarkup.png)
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.

Figure 6: A CNXML file displaying in Authentic mode with large markup tags.
Figure 6 (module-authentic.png)

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.

Figure 7: The Elements box.
Figure 7 (elements.png)

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.
Figure 8: Adding a glossary entry box
Figure 8 (glossary.png)

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.
Figure 9: Adding a bibliography entry box.
Figure 9 (bibliography.png)

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