Authoring Tips: the <exercise> tag

Last week I discussed the merits of formatting materials to be placed in the Connexions repository in CNXML. This week we'll explore one great markup feature of CNXML: the <exercise> tag.

What is it?

If you have written, or plan on writing, educational materials, chances are that you will have some exercises or problem sets in your content. An <exercise> in CNXML specifies:

• one <problem>,
• zero, one, or more <solution> items, and
• zero, one, or more <commentary> items.

Connexions automatically numbers and formats your exercises for professional layout both online and in print. Online, the solutions are "hidden" until the reader clicks a link to reveal the answer. Here's how an exercise looks with the solution hidden:

And here is how it looks after the solution is revealed:

In the PDF, the solutions for each exercise will be moved to the end of a chapter in most cases, just like in a conventional textbook, though that default can be overridden by the author.

The CNXML markup

While editing your module, click on the "insert" dropdown menu and choose <exercise> from the menu.

"

Edit-in-Place will create an exercise template for you, which you can then fill in with your problem and solution. For the example shown above, the CNXML would look something like this (I have added in some optional commentary):

<exercise id='hyd_test'>
  <problem id="id9">
    <para id='hyd_testp1'>
      The color of a hydrangea changes with the pH of the
      soil. What color would the hydrangea be if the soil
      were highly acidic? Highly basic? Neutral?
    </para>
  </problem>
  <solution id="id10">
    <para id='hyd_sol1p1'>
      Highly acidic soil produces blue flowers. Highly
      basic soil produces pink flowers. Neutral soil produces
      very pale cream flowers.
    </para>
  </solution>
  <commentary id="ex1_comment">
    <para id="ex1_comment_para">
      Who would have known?!
    </para>
  </commentary>
</exercise>

One way to override the default behavior of having the solution at the end of each module in the PDF is to change this line:

<solution id="id10">

to this:

<solution id="id10" print-placement="here">

Learn more

You can learn more about the <exercise> tag here and here.

Apply for Google Summer of Code Projects

Starting today, students can apply for Google Summer of Code projects. Connexions has been selected as a participating organization and we have 2 projects students can apply for. The deadline for applications is Friday, April 8. Get your application in today!

Including your original document in your module

Some people are shocked to learn that the Connexions repository hosts only two formats of content: (1) modules, which are small chunks of knowledge saved in CNXML, a markup language developed specifically for modules, and (2) collections, which are ordered collections of modules (think: book, journal, course, etc.)

So. What do you do if you already have learning materials you want to make publicly available, but they are in PDF format, or PowerPoint slides, or any other format besides CNXML? Well, if you are particularly attached to your content's original formating, you are still able to include your original document (in any format) as an Included File in your module. It's like a side dish -- not the meat of your module, but still there if anyone is interested. To do this, go to your module for editing and find the green "Files" tab located just under the module title in orange.

Click the blue button in the middle of the page that says "Add new image/included file" to browse to your saved file on your computer and upload it. When you do publish your module, those included files will be published too, and will be subject to the same licensing agreements that all content in the Connexions repository is subject to.

The astute will realize at this point that the module is blank. Completely and totally blank. Online? Blank. Generated PDF? Blank. Generated EPUB for use on mobile devices? Blank. And that, my friends, is because all of those viewing formats are generated from the underlying CNXML, and ours is still blank. You will first want to make your uploaded file accessible to anyone reading your module online or in the downloadable PDF format. To do this, include a link to it within your module text. For instance, if the file you added was called "myfile.doc", you would add the following snippet to your module.

"Download this <link resource='myfile.doc'>file.</link>"

Your module will now proudly display the text "Download this file", with "file" hyperlinked to your file. (In the downloadable PDF, the URL will show up as a footnote.) You can also add it as a Featured Link, so that in the online view it will show up in a box overlaying your module like the one pictured to the right.

Including a file like this is no substitute for converting your materials to CNXML, and we have plenty of tools to help you with that, including importers (which can take Word .doc, OpenOffice .odt, LaTeX .tex, or CNXML .cnxml files), an online graphical editor called Edit-in-Place, and a Full Source Edit that will allow you to edit the CNXML directly online. A module written in the CNXML format brings these advantages:

• Standardization. Modules can be easily reused in different collections when all modules are of the same format.


• Accessibility. A PDF or PPT may not be easily read by a screen reader or by other devices that people may be using to access your content. CNXML is a text document that can be easily parsed by screen readers. We also have built in accessibility features, such as requiring alt text inside images.


• Functionality. There's a lot you can do with CNXML that you can't do easily or quickly with Word or any other format. We've built the language to handle common occurrences in learning resources, like exercises, code examples, poetry, figures, images, tables, and more. These features can be easily overlooked by new authors, which is why I'll be writing a series of CNXML Tips & Tricks for several weeks. Come back each Tuesday to learn about another CNXML feature and how to implement it in your own modules. In the meanwhile, we will still be posting about other Connexions updates.

If you'd like to learn more about editing modules and including files in them, check out the Connexions Tutorial and Reference.