Overview:

• Getting Started
• Downloading the Connexions DocumentTemplate
• Applying the Template to Your Documents
• Creating a New Document with the Template
• Applying the Template to an Existing Document
• Authoring Documents using the Connexions Template
• Word Template Styles and CNXML
• Word Importer Do’s
• Word Importer Don’ts
• Uploading your Connexions Document
• Post-Import Editing
• Notes on Including Mathematics
• Caution to Users of MathType 5

Recent Changes

With the rollout of CNXML 0.6, Connexions has changed some of the features of its Microsoft Word importer. If you have used the importer in the past, please note the following changes:

• The importer now supports Microsoft Word 2007 documents (i.e. the .docx file format)
• The importer can preserve boldface and italicized text. See the Word Template Styles section below for more information.
• Table entries now support lists and multiple paragraphs

Getting Started

Microsoft Word offers one of the easiest paths for creating documents in Connexions, especially if your documents contains mathematics. When used with our custom Connexions Word template, Word allows you to write a document which can be translated into the CNXML format required by Connexions modules. Here, we will show you how to use Word to properly prepare your document for importing into the Connexions repository.

The first thing you need to do before you start creating Connexions Documents, is to obtain a copy of the Connexions Document Template. Using this template you can create Connexions modules that preserve formatting from your Word document.

Downloading the Connexions Document Template

Click the link below to download a copy of the Connexions Document Template:

Connexions Document Template

You may also want to download a copy of a sample document that has been prepared to properly exercise all the features of the Connexions Word template:

Sample Word Document

Applying the Template to Your Documents

Once you’ve obtained the template, you can use it to either create a new Word document or modify an existing Word document to conform to proper Connexions style. In each case, you must incorporate the template into your document using the instructions below.

Creating a New Document with the Template

To create a new document using the Connexions styles, double-click on the "Connexions-Document.dot" icon for the Connexions document template file you downloaded in the previous step. This will open the template in Word. Then go to the File menu in Word and select Save As. In the "Save As" dialog box that appears make sure that "Word Document (*.doc)" or "Word 2007 Document (*.docx)" appears in the Save as Type drop-down box. Give your document a unique name in the File Name box, and click the Save button. You have now created a new Word document with the template styles included in it. Delete the default text from the template (beginning with "[Section Name]") and begin editing your document according to the instructions in "Authoring Documents using the Connexions Template" below.

Alternatively, you can install the template file into Word so that it is available through the New option in the Word File menu. Instructions to install this template are specific to your version of Word, so we recommend that you consult Word's Help feature if you wish to do so.

Applying the Template to an Existing Document

To apply the template to an existing document, first open that document in Word. Then, follow the steps below:

1. Go to the Tools menu and click Templates and Add-Ins.
2. Click the Attach button, and use the file browser to navigate to the folder where you saved the template file.
3. Select the "Connexions_Document.dot" icon in that folder and click Open.
4. In the “Templates and Add-Ins” window, make sure the “Automatically Update document styles” box is checked and click Ok. (Figure 1)

Figure 1: Microsoft Word's template add-in window.

As an alternative, you can also create a new blank document with the Connexions template styles as described in "Creating a New Document with the Template". Once you have done so, you can copy and paste the text from your original document into the new blank document as follows. Go to the Edit menu in the original Word document and select the Select All option. Then go to the Edit menu in the original Word document again and select the Copy option. This copies the text of the original document to your system clipboard. Next, go to the Edit menu in the new blank Word document with the Connexions template styles and select the Paste option. The text of the original document is now copied into your new document, and you can begin modifying it with Connexions style information as described in the next section.

Authoring Documents using the Connexions Template

Once you have created a new document using the Connexions template (or applied the template to an existing document), you can begin preparing your document for importing into the Connexions repository. To do so, you must make use of the styles available in Word with the Connexions template. You’ll notice that in addition to the standard Heading 1, Normal, and Hyperlink,... styles in Word you now have Connexions-specific styles such as Connexions Emphasis, Connexions Term, etc. Each style corresponds to a specific CNXML tag (see the next section for a comprehensive list).

To apply a word style to a specific piece of text, you follow the instructions below.

1. Highlight the word, phrase, or paragraph you want to semantically mark up.
2. In your toolbar at the top of the screen, locate the style drop-down box (it usually displays the default style Heading 1 or Normal).
3. Open the style drop-down box.
4. Click the name of the semantic style you want to apply to the highlighted text. The text that was highlighted is automatically given the style you selected.

You can download an example of a properly prepared Word document using the styles supported by the Connexions Word importer. We encourage you to have a look at the document and practice uploading it into Connexions (see "Uploading Your Connexions Document" below) to get a feel for how the Word import process works.

Word Template Styles and CNXML

Connexions documents contain not only structural information about the document but also semantic information. This means that boldface text will be preserved as emphasized text with the effect attribute set to "bold", and italicized text will be preserved with the effect attribute set to "italics". If you have been using bold text to designate section headings, you should use the Word heading styles instead.

Using the Connexions Word template with the Word importer, you can produce the following effects in your CNXML document. Please click on the hyperlink in each explanation to see an example usage of the particular CNXML element.

Headings

H1 applied to a section title produces a new section. The section lasts until the next H1-marked title. An H2-marked title in between produces a subsection (which lasts until the next H2- or H1-marked title).

Emphasized text

CNXML Emphasis produces emphasized text. Microsoft Word's bold or italics styles will be preserved as emphasized text with the appropriate effect attribute.

Foreign words and phrases

CNXML Foreign allows you to designate text written in a different language from the rest of the document. When used in conjunction with a Word hyperlink, you can use point the foreign text to a URL related to its source.

Computer code printout

CNXML Code (Inline) allows you to designate programming language code inline with respect to the rest of your text. CNXML Code (Block) allows you to format it as block code.

Citations

CNXML Cite allows you to reference materials. When used in conjunction with a Word hyperlink, you can point the cited text to the URL of its location.

Key terms

CNXML Term allows you to designate a key word. When used in conjunction with a Word hyperlink, you can point the term to a URL containing its meaning location.

Quotations

CNXML Quote (Inline) allows you to produce an inline quotation. CNXML Quote (Block) allows you to produce a block quotation.

Hyperlinks

Hyperlink allows you to designate text as a link. A link element is generated for all hyperlinks, with the appropriate attributes filled in.

Exercises

CNXML Exercise (Problem) allows you to designate an exercise with a problem statement. Following this with CNXML Exercise (Solution) allows you to provide a solution to the problem. These do not need to be numbered by you - Connexions will automatically handle exercise numbering on import (click here to see an example).

Theorems

CNXML Theorem (Statement) allows you to designate a theorem with a theroem statement. Following this with CNXML Theorem (Proof) allows you to provide a proof to the theorem. These do not need to be numbered by you - Connexions will automatically handle theorem numbering on import (click here to see an example).

Definitions

CNXML Definition (Term) allows you to designate a defined term. This must be followed by CNXML Definition (Meaning), in which you provde the meaning of the term or point to the meaning later in the document (as discussed above).

Notes

CNXML Note allows you to format text in centered note box.

Examples

CNXML Example allows you to format text in centered example box.

Paragraphs

You can also use certain features of the Word editor to produce other CNXML tags. Pressing Enter gives a new line and produces a new paragraph.

Lists

Creating a bulleted list gives a CNXML bulleted list. Creating a numbered list gives a CNXML numbered list.

Images

Inserting an image (Insert menu, Picture option) includes an image media object in your document. Text immediately preceeding the image, and marked using the CNXML Figure Title style, will generate a figure title. Text immediately following the image, and marked using the CNXML Figure Caption style, will generate a figure caption.

Tables

Inserting a table (Table menu) produces a table.

Mathematics

Inserting a Microsoft Word Equation Editor 3.0 equation (Insert menu, Object option) produces a MathML expression. See “Notes on Including Mathematics” below for some guidelines on inserting mathematics into your Word document.

Footnotes

Inserting a Microsoft Word footnote (Insert menu, Reference option, Footnote) produces a Connexions footnote.

Glossary

Finally, you can use CNXML Glossary Section to designate the start of a glossary section. This must be the last section designation used at the end of your word document, and it cannot be followed by H1, H2, etc. styles. After you've started the glossary section, term/definition pairs specified as indicated above will appear in the glossary section for your module.

Word Importer Do’s

1. Use only the formatting styles in the Connexions Word template (described above), along with bold and italics if necessary.
2. Use only images that are locally available on your machine. Make sure either that (1) the images are already available under a creative commons (CC) attribution license, or (2) you own the image copyrights and are willing to make them available under a CC attribution license.
3. Use image types such as .eps, .jpg, .png, and .gif (or any format with a valid image type); avoid formats such as .wmf and .svg, and avoid Clip Art.
4. Use the Word table tool to create tables. Fill your table entries with single-paragraph text, images, and mathematics; avoid multi-paragraph text and lists.
5. Use the default Word equation editor for all math (especially subscripts and superscripts), so that MathML will be imported.

Word Importer Don’ts

1. Do not add line breaks betwen paragraphs using cntl-Enter. This will not import as a new paragraph.
2. Do not use tabs. This formatting will not import.
3. Do not use lists or tables to invisibly format the document, as these constructs are literally imported as lists and tables into CNXML.
4. Do not continue list numbering across separate lists.
5. Do not insert images whose source files are remotely available via a hyperlink.
6. Do not use Word’s image captioning option; the caption will import as a new paragraph.
7. Do not use fonts such as “Wingdings" to produce symbols: They will be interpretted as text.
8. Do not use the MathType editor inside Word to create equations. This is the default (and only) option if MathType is installed on your system. See “Notes on Including Mathematics” below for more details.

Uploading Your Connexions Document

You are now ready to upload the document to Connexions. Follow the steps below to upload your Connexions Document:

1. After creating your module in Connexions (see Editing Modules) click the Edit tab (Figure 2).
2. Select Microsoft Word from the Import drop-down list and click Import.
3. Click Browse to locate the document you want (Figure 3).
4. Click Import to upload your document. Your new document is uploaded and ready to edit or publish using Connexions.

Figure 2: The import/export screen in the Connexions editing interface.

Figure 3: The import file selection box.

Post-Import Editing

The Connexions Word importer can produce most of the CNXML tags available for authors to use in their modules (see “Word Template Styles and CNXML” above) and several combinations of tags. Any use case not available as a Word style must be added after import, either using the Edit-in-Place interface (recommended) or full-source editing.

It is important when using the Word importer that you finish preparing the document to your satisfaction in Word before importing and editing the CNXML. Any re-import of the Word document will erase the changes you make using Edit-in-Place or full-source editing. Once you have imported, we recommend not using Word any more to work on your module.

Notes on Including Mathematics

Word comes with a built in equation editor called Microsoft Equation 3.0. It can be launched by opening the Insert menu in Word, selecting the Object option, selecting Microsoft Equation 3.0 in the “Object Type”, and clicking OK (Figure 4).If you can’t find this option in the list, you must install Equation 3.0 from your Microsoft Office installation CD. Please consult your Microsoft Office help for more information on this procedure.

Figure 4: Microsoft Office object insert window.

The Connexions Word importer properly generates Presentation MathML when the Equation 3.0 editor is used to add math to your Word document. It is very important that you only use Equation 3.0 to enter all your mathematics. Do not mix textual mathematic representations (e.g., super- and sub-scripts) with Equation 3.0 mathematics. Textual mathematics will import as plain text and not be recognized as MathML objects in your Connexions module.

Caution to Users of MathType 5

MathType 5 is a stand-alone equation editing package written by Design Science, makers of the Microsoft Equation 3.0 editor. When MathType 5 is installed on your system, equations written with the Microsoft equation editor will be saved as MathType 5 equations rather than Equation 3.0 equations. Even merely editing equations from a document with Equation 3.0 equations on a machine with MathType 5 will cause those equations to be saved in MathType 5 format. This is problematic, since the Connexions Word importer cannot properly convert MathType 5 equations to Presentation MathML.

We recommend un-installing MathType 5 from your system if it is currently installed. This will cause Word to revert to using Equation 3.0 for equation editing, which will allow the Connexions Word importer to properly generate mathematics.

Should you inadvertently include a MathType 5 equation in your Word document, in the Edit-in-Place interface where the mathematics should appear you will instead see the warning message shown in Figure 5.

Figure 5: Edit-in-Place warning for MathType mathematics import.

You can go replace each of these warning messages by hand using the following procedure. To begin, double click on the MathType equation in Word to open the MathType editor.

If this is your first time to use this procedure, you must configure MathType to properly generate MathML. Go to the Preferences menu and select the Translators option. In the window that appears, make sure that “Translation to other language (text)” is selected, and in the drop-down box next to “Translator:”, select the “MathML 2.0 (m namespace)” option. Also, make sure that “Include translator name in translation” and “Include MathType data in translation” are NOT selected (see Figure 6 below). Click OK to complete the configuration. This sets the translation preferences permanently, so you will not have to repeat these steps again.

Figure 6: Setting the translator in MathType to copy MathML to the system clipboard.

Once the Translators preferences are set, you can copy the MathType equation’s MathML equivalent by highlighting the equation in the MathType editor and copying to the clipboard (Edit menu, Copy option). This stores a copy of the MathML on your system’s clipboard.

Return to your browser and find the appropriate placeholder for the equation in the Edit-in-Place interface (appearing as in Figure 5). Double click to edit the paragraph and delete the text “***SORRY, THIS MEDIA TYPE IS NOT SUPPORTED***” (Figure Figure 7 below). Paste the contents of the clipboard into is place (Figure Figure 8), and click Save. Your equation should now appear in the Edit-in-Place interface (Figure Figure 9).

Figure 7: Editing the paragraph with the warning text.

Figure 8: Pasting the MathML copied from the MathType editor into the paragraph where the equation should appear.

Figure 9: MathML equation appearing in the edit-in-place interface.