Authoring Tips: Glossaries for each module

We first learned about <term> tags in last week's post, which for some reason posted under the wrong date. At the blog.cnx.org homepage you need to scroll down a bit to see it.

Each module can contain a glossary at the end of the module, containing definitions of important terms used in the module. Now, if you are using our Edit-in-Place online editor, you will notice that there is no "Glossary" option in the "insert" dropdown menu. For this, we need to bring out the big guns. Switch to the Full Source Editor by clicking on the link just above the editing area, as pictured below:

A glossary must go at the end of the module, so scroll down to the end of the text where you will find a </content> tag. After that tag, put in your glossary tags. It will look like this:

...
</content>

<glossary></glossary>

Between your opening and closing tags, you will have one or more <definition> tags. Each definition must contain one <term> tag (that's the term you are defining), and at least one <meaning>. It can also (optionally) contain one or more examples (examples follow the relevant meaning that they illustrate) and further references (<seealso>, which should be the last item in the <definition>). Be sure to give a unique id to each element that needs one.

To illustrate:

<glossary>
  <definition id="cnxdef">
    <term>Connexions</term>
    <meaning id="cnxdef-part1">An online repository of open educational resources licensed under the <link url="http://creativecommons.org/">Creative Commons</link> CC-by license, powered by a unique content management system and editing interface called <link url="http://rhaptos.org/">Rhaptos</link>.</meaning>
    <example>
      <para id="cnxdef-part1-para">Are you using a textbook on Connexions for your class?</para>
    </example>
    <meaning id="cnxdef-part2">The British spelling of Am. 'connections'.</meaning>
    <seealso>
      <term>OER</term>
      <term>repository</term>
    </seealso>
  </definition>
</glossary>

Click "Save" and move back to "Edit-in-Place" to continue editing your module. The above code results in this excellent display:

For extra coolness, you can link any terms you use in your module text directly to the definition in the glossary, using the linking techniques we learned two weeks ago. Link to the target-id of the definition:

Everyone should study with <link target-id="cnxdef">Connexions</link>!

Connexions for Android Updated

Version 1.4 of Connexions for Android was released this morning. It adds two new features and fixes a file downloading issue.

• The app now displays a list of the PDF or EPUB files that have been downloaded to your device. From this list, you can select a file which will open it in the appropriate application. An application for the file type must be installed for the file to be opened. Examples of apps for file types would be Adobe Reader for PDF files and Aldiko for EPUB files. You can also delete PDF or EPUB files from your device by doing a long press on the file name and selecting Delete from the menu.
• Pinch and Zoom is now enabled in the web view on devices with Android 2.1 and above.
  
• Corrected a defect that caused some devices to have problems when downloading large EPUB or PDF files.
  

You can download the app directly from Connexions or from the Android Market. If you try the app and find it useful, please leave a comment in the Android Market.

Connexions Improves Site Performance

Last Thursday, the Connexions team, with the help of Enfold Systems, rolled out a new feature that doesn't change how the site works, but changes how the site performs. We have added additional caching of content pages which is resulting in quicker load times for those pages. From our internal testing, most pages are twice as fast as a result of the caching. The only obvious visual change is the addition of collection ids in module URLs when a module is viewed in a collection's context. An example is

http://cnx.org/content/m10884/latest/?collection=col10151/latest

We are continuing to improve the site and would like to hear if you notice the speed improvement. Leave a comment or email us at cnx@cnx.org.

Authoring Tips: Linking on Connexions

What's an educational resource without copious amounts of cross-referencing? Not much, I say! Luckily, we've got you covered.

The <link> tag can create hyperlinks to webpages, files uploaded to your module, other modules or collections, specific portions of other modules and collections, and even specific versions of other modules or collections, or any combination of the above. Sound like a lot? We'll break it down for you.

The hyperlinks we are all familiar with whisk you away to a new webpage. This is easy enough to do in Connexions, where all you need to do is specify the @url attribute, like so:

Here's a link to a great <link url="http://cnx.org/">open educational resource repository</link>.

where what you see is:

Here's a link to a great open educational resource repository.

The fun starts when you want to link to other resources in the Connexions repository, for which you can use special Connexions attributes, like in these examples:

<link document="m12345">some text</link>

links you to a specific module or collection. You can find the module ID (the m12345 number) or the collection ID (a col12345 number) in the URL bar of the content you are linking to, or you can find it on the metadata page (a link to it is at the bottom of the page).

<link document="m12345" resource="FileName.png">some text</link>

links you directly to a file (in this case, named "FileName.png") that has been uploaded to module m12345. If you want to link to a file that you have uploaded to your own module, just leave out the document="m12345". This is hands-down the easiest way to point readers to included files; we'll be talking about other ways (like embedding) in the coming weeks.

<link document="m12345" target-id="eip-987">some text</link>

links you to a specific element in module m12345. (Again, if you want to link to the module you are editing, you can leave off the document="m12345".) Pretty much every element in your module (paragraphs, figures, sections, etc.) requires a unique ID. If you are using Edit-in-Place, or if you imported a Word document or LaTeX file to create your module, Connexions generates random unique IDs for you. You can find them by clicking on the element in Edit-in-Place to open it for editing. The target-id is in the upper left corner; this one is "delete_me":

<link document="m12345" version="1.2">some text</link>

links to version 1.2 of modules m12345, just in case the last overhaul of the module removed the information you wanted to link to. (You can find a list of all past versions through the link to the metadata at the bottom of the content.) And my favorites:

<link document="m12345" version="1.2" target-id="eip-987">some text</link>

<link document="m12345" version="1.2" resource="FileName.png">some text</link>

...because who wouldn't want to link to a specific portion (or a specific file) of a specific version of a specific module in the Connexions repository?

So there you go. No excuses for not linking to your sources! As we discussed last week, you can find complete information about the <link> tag in our eip-help at http://cnx.org/eip-help/link.

Authoring Tips: Automatic Indices

This is a great feature for those of you creating or uploading textbooks to Connexions. Connexions will create an automatic index of terms and keywords which you can specify; this index will appear in the back of the downloadable PDF of the collection and contains the term or keyword as well as the page number or section it can be found in.

Two different elements will get pulled into the index: keywords and <term>.

Keywords

You can specify keywords for each module or for the collection as a whole under the metadata tab. The green metadata tab can be found underneath the module title; click it to edit the metadata. Enter in keywords (one per line) and click the "Save" button.

Keywords will be pulled in to your index with a section reference (referencing the module it refers to); keywords on a collection level will have references to every module within the collection, so some people like to leave them out. Keywords have the extra bonus of making your content more searchable.

Terms

The <term> tag is meant to mark words that are important to the text or defined in a text, like the <term>Pythagorean Theorem</term> in math or <term>classical conditioning</term> in psychology. They are set off as bolded text. Terms will be displayed in the index with reference to the specific page they occur on. Not too shabby, eh?

Next week we will show you another great trick for textbooks: how to create a Glossary in a module or collection, and how to turn <term>s into links that point to definitions in the glossary.

Authoring Tips: Stylizing your content

Our online module editor (a graphical interface called "Edit-in-Place") gives you a lot of options. When you choose to insert a "list", you are given the option to create a bulleted list, a numbered list, a stepwise function, or a labeled item list. Oftentimes, a CNXML tag has a lot more versatility written into it than we can easily fit in a graphical editor, and to access them you will have to type them in yourself.

So how can find out what options you have? At the upper-right hand corner of every tag you can edit in Edit-in-Place is one of Connexions' best-kept secrets: a link to a cheat sheet with all the allowed attributes for that particular tag. It always has the format "Help editing <tag name>".

The link for <list>, for example, takes you to cnx.org/eip-help/list, where you will find attributes to change the style of bullet (or numbering) of the list, a way to make numbered lists begin at a number other than one, a character to separate each item in the list (like a comma or a period), and more. This markup creates a numbered list starting with number 50, with a colon after each number and a period after each item:

<list id="write-numbers-list" list-type="enumerated" start-value="50" mark-suffix=":" item-sep=".">
  <title>How to Write Some Numbers</title>
  <item>Fifty</item>
  <item>Fifty-one</item>
  <item>Fifty-two</item>
</list>

You can even stylize inline tags like <emphasis>. If you take a look at cnx.org/eip-help/emphasis, you see that you aren't limited to having your emphasized text always bolded. You can use <emphasis effect="italics"> to create italicized emphasis, <emphasis effect="underline"> to create underlined emphasis, or <emphasis effect="smallcaps"> to create SMALLCAPS emphasis.

By playing with the attributes and options allowed for each tag, you can create a module using your own conventions.

There is a complete list of all the tags in CNXML at cnx.org/eip-help/tags.

Connexions Adds Like and Tweet Buttons

Found a great module or collection on Connexions? Today we added Like and Tweet buttons so you can share Connexions content with your friends on Facebook and Twitter. Now it is easy to let the world know about your favorites in Connexions.

Connexions for Android

The Connexions Android app has had over 700 downloads from the Android Market. Version 1.4 will be released soon which will allow users to open PDF and EPUB files from inside the application. If you have not downloaded it yet, give it a try. You can find it in the Android Market or download it from the Connexions website.