CourseComposer Details

Copyright © 2004 Myrnham Associates

Table of Contents

Requirements
Overview
Using CourseComposer

Myrnham Associates' CourseComposer™ is an authoring tool for creating instructor-led training manuals for use with its partner application CourseManager™. With CourseComposer™ you are able create and edit your own library of content as an individual or as part of a team. CourseComposer™ is built on the Eclipse platform and includes the following features:

  • Editable Document Templates

  • Full support for DocBook

  • CSS Stylesheets for use with Previewing tools (Mozilla/Firefox)

  • Project/Document management

  • Context sensitive element insertion

  • Drag and Drop Training components

  • Task List

  • Outline Preview

  • Editor Bookmarks

  • Built-in Attribute/Properties view

  • Extensive DocBook Help & Reference system

  • Robust Search & Replace supporting Regular Expressions

  • Team Collaboration tools including CVS, WebDAV & FTP.

  • Built-in Image viewer

  • Spell-Checker

  • Extensible platform using Plug-ins

Requirements

The minimum requirements for installing and using the Myrnham Associates CourseManager™ are as follows:

  • Pentium 500MHz or equivalent:

    • 80Mb disk space

    • 128Mb Memory

    • Windows 98/ME

    • Mozilla/Firefox Web Browser (Optional)

  • Pentium 500MHz or equivalent:

    • 80Mb disk space

    • 256Mb Memory

    • Windows 2000 or Windows XP

    • Mozilla/FireFox Web Browser (Optional)

  • CD-ROM Drive

Overview

Installing your software

CourseComposer™ should be installed using Administration rights. CourseComposer™ is Free - there is no registration process or unlock keys required.

The CourseComposer Workbench

The CourseComposer™ Workbench is built from a generic Integrated Development Environment (IDE) toolkit called Eclipse.

Detailed Help and a Tutorial on the CourseComposer™ environment - known as the Workbench is available in the CourseComposer™ Help System. Select HelpHelp Contents to access the Workbench documentation.

The Workbench documentation is also available Online.

The CourseComposer Perspective

A Perspective defines the initial set and layout of views and features in the Workbench window. The CourseComposer Perspective contains the following:

Feature

Description

Navigator

The Navigator view provides a hierarchical view of the resources in the Workbench. From here, you can open files for editing or select resources for operations such as exporting.

Outline

The Outline view displays an outline of the XML structure of the file that is currently open in the editor area, and lists structural elements. The contents of the Outline view are editor specific.

Properties

The properties view displays property names and values for a selected XML item or element.

Tasks

As you work with your XML document, various problems, errors, or warnings may automatically be logged in the Tasks view. You can also add items to the Tasks view manually.

Snippets

The Snippets area is core to CourseComposer™. It provides pre-formatted XML objects that can dragged into your document to provide the structure necessary to build a compatible CourseManager™ course.

Editor

The Editor area opens up when you select a file to edit/view from the Navigator pane.

Table 1. 

The Toolbar

The main toolbar is displayed at the top of the Workbench window directly beneath the menu bar. The contents of this toolbar change based on the active perspective. Items in the toolbar might be enabled or disabled based on the state of either the active view or editor. One toolbar item unique to CourseComposer™ is ID attribute creator button.This toolbar button (and menu option CourseComposerSquirt ID Attribute) is used to add a unique id to XML elements that require them. These are:

  • Prefaces, Chapters & Appendices

  • Topic sections

  • Topic Element sections

  • Figures & Tables

For example:

<section id="id1198351421500">
  <sectioninfo>
    <author><firstname>A.N.</firstname>
    <surname>Other</surname></author>
    <releaseinfo>
      <remark role="teaching_time">0</remark>
      <remark role="num_pages">0</remark>
    </releaseinfo>
  </sectioninfo>
  <title>New Topic</title>
  <subtitle></subtitle>
</section>

The Editor Area

To edit a document, double-click it in the Navigator pane. The document will open in the Editor area.

[Note] Note

By right-clicking on the document in the Navigator pane, you can select Open with... from the popup menu where you can choose which type of available editor you want to use. By selecting System Editor you can open the document in an external Web Browser, assuming *.xml files are associated with with your favourite Browser. This comes in very handy for previewing your work-in-progress.
[Important] Important

Myrnham Associates recommends Mozilla Firefox as a suitable Web Browser with CSS support for previewing XML documents.

All the usual features that you would expect from a text editor are available.

Editor Pane

Figure 1. Editor Pane

Editor Views

You will notice that the Editor pane (Figure 1, “Editor Pane”) has a Design tab and a Source tab. Both tabs can be used to build up your document however most editing will be done in the Source tab. The editor can be used in conjunction with the Properties view to edit element attributes.

An Overview of DocBook

DocBook is the dialect of XML used in Myrnham Associates products. DocBook is a standard format based on XML for technical documentation of all kinds. It has been adopted as a de facto standard by a large community of authors, including computer companies, Open Source documentation groups, and other organisations, allowing these groups to share, exchange and reuse technical information easily. There are countless DocBook-based articles, books, reference manuals, and other materials on the Internet, including the Linux Documentation Project, the full content of some O'Reilly books, and other books.

For more information on XML visit www.xml.com

For more information on DocBook visit www.oasis-open.org/docbook

There are several reasons for which DocBook should be preferred over WYSIWYG editing and unstructured text in technical writing:

  1. Focus on content - DocBook document concentrates solely on the content of a piece of writing rather than its physical appearance. This means that the technical writer is not distracted by such minor issues as numbering figures, creating lists of contents, whether to use 10pt or 12pt font, single or double line spacing etc.

  2. Automatic formatting - DocBook documents can be rendered to a variety of file types such as HTML or PDF fully automatically. During this process a special set of rules called a stylesheet determines the physical appearance of the document. This ensures coherent layout among a set of documents created by different authors. Also, no matter the number and size of source documents, they can be easily reformatted (e.g. to a bigger font or line spacing) by simply changing the stylesheet.

  3. Portability - Being plain text XML documents, DocBook files can be created with any text editor such as Notepad, vim, gEdit or built-in Eclipse editor on any platform. This also means that DocBook documents can be easily put under the control of source code management tools such as CVS, which facilitates group work and synchronisation of changes.

Using CourseComposer

Creating a New Document

CourseComposer files are created within content folder of the Workspace. The Navigator pane is used to view the files and folders within the content.

When a new file is created, using the FileNewCourseComposer File menu option, you can specify a document template that will be picked up from the templates folder. You can create your own DocBook document templates if required - most users will be happy with the default.

An XML document will be created (and opened) for you as well as an empty folder of the same name which should be used to store images etc.

Using Snippets

Snippets Pane

Figure 2. Snippets Pane

Use items from the Snippets Pane to build up a DocBook document to the Myrnham Courseware specification. You can either drag Snippet items or double-click them to place the items in the Editor. You will notice that the categorisation of the Snippets pane is mostly heirarchical which makes it easier for the user to build up an outline before writing the course detail.

Tasks & Comments

The Tasks feature of CourseComposer™ can be very useful as you develop your course. Apart from creating Tasks manually in the usual way (right-click in the Tasks pane), you can combine the use of comments in your XML with the automatic creation of Tasks.

Comments within XML are formed using the <!-- --> bracket pairs.

<section id="abc123" role="discussion">
   <title>Discussion</title>
   <subtitle></subtitle>
   <para><!-- Pad this out later --></para>
</section>

By adding the TODO keyword to your comment, you can automatically add your comment to the Tasks pane (see Figure 3, “TODO item in Tasks Pane”).

<section id="abc123" role="discussion">
   <title>Discussion</title>
   <subtitle></subtitle>
   <para><!-- TODO: Pad this out later --></para>
</section>
TODO item in Tasks Pane

Figure 3. TODO item in Tasks Pane

[Warning] Warning

TODO items are updated in the Tasks pane after saving the document.

Spell-Check

CourseComposer™ has a built-in Spell-Checker. Detailed Help and a Tutorial is available in the CourseComposer™ Help System. Select HelpHelp Contents to access the SpellChecker documentation.

Validating your Project

From time to time, as you build your course, it is advisable to Validate your XML. There are two categories of XML documents: well-formed and valid.

Well-formed Documents

A document can only be well-formed if it obeys the syntax of XML. A document that includes sequences of markup characters that cannot be parsed or are invalid cannot be well-formed.

In addition, the document must meet all of the following conditions (understanding some of these conditions may require experience with XML):

  • The document instance must conform to the grammar of XML documents. In particular, some markup constructs (parameter entity references, for example) are only allowed in specific places. The document is not well-formed if they occur elsewhere, even if the document is well-formed in all other ways.

  • The replacement text for all parameter entities referenced inside a markup declaration consists of zero or more complete markup declarations. (No parameter entity used in the document may consist of only part of a markup declaration.)

  • No attribute may appear more than once on the same start-tag.

  • String attribute values cannot contain references to external entities.

  • Non-empty tags must be properly nested.

  • Parameter entities must be declared before they are used.

  • All entities except the following: &amp;, &lt;, &gt;, &apos; and &quot; must be declared.

  • A binary entity cannot be referenced in the flow of content, it can only be used in an attribute declared as ENTITY or ENTITIES.

  • Neither text nor parameter entities are allowed to be recursive, directly or indirectly.

By definition, if a document is not well-formed, it is not XML. This means that there is no such thing as an XML document which is not well-formed, and XML processors are not required to do anything with such documents.

[Important] Important

CourseComposer™ has built-in functionality to help ensure your documents remain well formed.

Valid Documents

A well-formed document is valid only if it contains a proper document type declaration and if the document obeys the constraints of that declaration (element sequence and nesting is valid, required attributes are provided, attribute values are of the correct type, etc.). The XML specification identifies all of the criteria in detail.

CourseComposer™ files will have automatically included the document type definition (<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "rules/docbookx.dtd" []> at the top of your document. This specifies that the rules of how to format XML to the DocBook standard should be applied.

[Important] Important

Only Valid documents can be used by CourseManager™.

Changing the Workbench

The online Help for the CourseComposer™ Workbench is available in the CourseComposer™ Help System. This has detailed information on how to modify such things as:

  • Layout & position of Views

  • Add & Remove views

  • Create customised Perspectives

  • Adjust Keybindings (keyboard shortcuts)

  • Change colours & fonts

Select HelpHelp Contents to access the Workbench documentation.

As the CourseComposer™ Workbench is based on Eclipse, it is possible to add any Eclipse Plugin to the system too - making CourseComposer™ almost infinitely extensible!