Content Authoring using Markup Languages

The ideas described in this document have been implemented in Reauthoring: A Toolkit to create Liquid HTML Active Learning Resources.

Markup languages are used to write a document in a different way. The document contains the text and the instructions to decorate the text or define its properties all mixed. For example, if a document has a title, with markup languages, rather than simply write the title (and perhaps apply some style as you probably do in Word), you include an additional set of characters (previously defined) that denote that the text is the title. A markup language must define which ones are these additional characters and how are they included mixed with the text.


Suppose you have a document with title The Way I Teach. Here are two examples of how would you write the title in two different markup languages. The first one is written in HTML (yes, HTML is a markup language):

<title>The Way I Teach</title>

And the second is written in ReStructuredText.

The Way I Teach

What is the advantage of using these languages? Did it ever happened to you that when you delete an empty line following a paragraph in Word, the entire paragraph changes font and you have to restored or undo the delete? This is because the apparently innocuous space contains a mark with the type of font to use in the paragraph. Deleting the mark brings another mark to affect the paragraph, and if it has a different type of font, it is applied. Yes, Word uses a markup languages, but it is hidden from you. A word document is plagued with marks, but you don’t see any of them. Even though these documents are edited with programs called WYSIWYG (What You See Is What You Get), sometimes they should be called WYDSAWYS (What You Don’t See Affects What You See).

Markup languages such as HTML, LaTeX or ReStructuredText have the advantage that all the instructions to shape your document are visible. The documents become a bit trickier to read because they have things interspersed in between the text, granted, but if you are patient enough and get use to it, you read it with no effort. You then will be seeing the whole document and its structure.

Some of these markup languages are extensible. In other words, if you want to include a new mark to shape the document in a different way, they allow you to create it. However, this process is quite sophisticated for most users (have you ever written a VBasic Macro in Word?).

The other great feature about markup languages is that they are typically encoded in plain text format, that is, a file that only contains basic characters and it can be read by a wide variety of tools (the files that you open with the Notepad or similar).

The final catch, in order to obtain a PDF document or similar from a file written in a markup language you need a push-button procedure (in the form of an additional program) that takes your file, applies a translation process and produces the final product (that PDF file). In other words, if you want to see the final result, you have to push this button and wait. But as in the case of reading a document, once you get used to it, you simply write the document and push that button and the end and see if the result is what you wanted. If not, you go back to the plain text file and make the appropriate changes.

Course Content Generation

I have been generating course material using markup languages for quite some time. I have tried several languages in a long and sometimes tortuous path in search of that ideal simple markup language that allows me to write documents, insert cross-references (one part of the text points to another one), table of contents, handle documents fragmented into multiple files, images, lists, tables, references, footnotes, be extensible, and if possible, translate files into several formats (mainly PDF and HTML but lately I am curious to produce EPUBs as well).

After trying (as in several years using) LaTeX, DocBook and Markup, I am currently using ReStructuredText and the enhanced version supported by the translator Sphinx. You may check the result in a sample of activities for the course ELEC1601. All those HTML pages have been written as plain text files in ReStructuredText.

But, along the journey, I needed some extra features not provided, so I ended extending the set of markups provided by Sphinx with additional marks to include additional elements.

Multiple Choice Questions

The first addition is one of the classics: multiple choice questions. I wanted to be able to include the questions in the middle of the notes for formative assessment purposes. This is how you write on of these questions:

.. eqt:: COD-integerencoding-videoeqt-eqt_11

   **Question 1** What is the representation of the number -127 in 2s
   complement with 8 bits?

   A) :eqt:`I` `1000 0000`

   #) :eqt:`I` `1111 1111`

   #) :eqt:`C` `1000 0001`

   #) :eqt:`I` None of the above

Can you spot which answer is marked as the correct one? After processing, the result is:

Question 1 What is the representation of the number -127 in 2s complement with 8 bits?

  1. 1000 0000
  2. 1111 1111
  3. 1000 0001
  4. None of the above

Go ahead, answer it! The question is translated to the proper HTML, the right scripts inserted, and everything handled properly as specified by the markup.

Youtube Videos

Videos are now increasingly present in learning scenarios. If you publish your own video, or use a video already existing in YouTube, how could you include it in your notes in a simple way? Here is the markup you would use:

.. embedded-video:: SeoW3YNo3Zs

The strange string following the two colons is the identifier that YouTube attaches to any video. Any video you watch in YouTube will have something similar in its URL. Here is the result:

The program translating the file to HTML takes care of all the details. Inserts the right HTML elements, the right scripts in the page, and you can publish this immediately in your scenario.

Activity Duration

The example showing the Multiple Choice Questions shows how to insert an interactive element in an HTML page. The same mechanism can be used to produce succinct questions that students may answer while reading the document.

One of the dangers when designing a learning scenario is to create tasks or activities with an adequate workload. How do we know the load is adequate? I don’t have a good answer for that question, but one possibility is to ask the students. How? Inserting a markup that translates into a question and a range of values for students to answer. Here is the markup required:

.. activity-duration:: 30 my-activity-name

This instruction says that the activity is supposed to require 30 minutes of work. And the way the question is shown to the students (in the middle of the HTML document is:

How long did this activity take you? mins.

As you can see, a form is produced with the question, a pull down menu with the value 30 in the center and six more options at equal intervals similar to a Likert scale, and the button to answer. Go ahead, answer. If everything goes well, you see a green tick to denote that the information has been sent.

In this example, though, some additional hidden functionality is present. The sentence for the question is in a configuration file, and the information is sent to a previously defined URL that is capable of receiving the data and stores it. All these configurations are kept in a separate file which is also encoded in plain text, and hopefully you can simply use as a template, without barely any changes.

Instructor Guide

I have found myself very often creating material for an activity or task and wanting to document some aspect that is not relevant for the student but for the instructor in charge of enacting it. The more elaborated the activity, the more important this description. For example, suppose you want to stage an activity that requires students to use mimic. You have tried this several times and found some techniques that improve student engagement. What happens if another instructor simply sees the description of the activity for the students? You would have to communicate these techniques verbally.

An alternative is to write learning material as if you were writing the score for an orchestra. You want to keep the score for all instruments together despite the fact that each of them only needs to see a subset of the overall composition. This is very easy to implement with markup languages. You only need to mark text with a label that is then interpreted as an include/exclude alternative. Here is how to include content that must be visible only to the instructor:

.. iguide:: Instructor Guide

   This content is only visible in the instructor version of the course
   notes. It is removed completely in the student version.

And this is the result (this document has been generated as if it were the instructor guide):

Instructor Guide

This content is only visible in the instructor version of the course notes. It is removed completely in the student version.

As in the case of the previous examples, the translation process adds some styling (a box around the text and an icon).

Feedback from Instructor

Combining the possibility of including simple HTML forms with the feedback from instructors we obtain the possibility of including a text box in which instructors may include comments about a task, lecture, session, so that they need to be taken into account for the next edition. The markup to include this form is a combination of two markup mechanisms, instructor guide and a form:

.. iguide:: Your comments about this session

   .. instructor-feedback:: lecture_feedback_02

The first mark up includes the comment to include in the text box, whereas the second markup includes the label to use withe comments. The resulting HTML uses a form that submits the message and the label to a pre-determined URL:

Your comments about this session

Upon submission the text box is replaced by a green tick denoting that the data has been sent to the server.

Sequence of MCQ

MCQs can also be used to create a sequence of questions that are shown to the user. If the answer is correct, they contribute to a partial score (100 means all questions answered correctly). If the answer is incorrect, the question is pushed back to the pool and a new one is selected.

The markup for this construction consists simply on denoting the correct answer with a number included only in the instructor guide. For example, the following markup construction (the solution is denoted in the last two lines) defines a problem that includes a figure:

Circuit Evaluation

Consider the following combinational circuit

.. figure:: cdl_exc_circuit2.png
   :align: center
   :alt: Three input boolean circuit

Can you determine the value of the output of the XOR gate without knowing the
input value of x?

A) Yes, it is zero

#) Yes, it is one

#) Yes, if I know the values of y and z.

#) No, I need to know all three input signals

.. iguide:: Solution


The resulting rendering for the students is:

Sequence of problems phrased as MCQs

This rendering requires two tools, one that generates the question (surrounded by a border) and another that places the buttons and keeps the score. The solution is written using the instructor guide directive, which produces the following rendering:

Circuit Evaluation

Consider the following combinational circuit

Three input Boolean circuit

Can you determine the value of the output of the XOR gate without knowing the input value of x?

  1. Yes, it is zero
  2. Yes, it is one
  3. Yes, if I know the values of y and z.
  4. No, I need to know all three input signals