February 19, 2008

3i: Individualized, Interactive Instruction's Lecture File Format (v2)

This document explains the version 2, also known as v2, lecture file format that is used by Instructor application. The version number does not match that of the Instructor or Student applications.

How It Works

The way to structure your lecture file and images can be done in several ways as described here.

In the above image, the example lecture file is named example.lec. The location of your images can be either in the same folder as your lecture file like image 2.jpg, or in another folder that is at the same location of your lecture file like folder that contains the image image.jpg.

You can also have folder's within folders to images. For example A and B are folders and C.jpg is an image. You can create the directory structure as follows: A\B\C.jpg.

The only requirement is that the images be 1.) in the same folder as the lecture file OR 2.) in a folder that is at the same location of your lecture file. Do not put images anywhere else, otherwise the Instructor application won't find them.

Naming: The name of the lecture file, folders, and images can be anything. Just don't use weird characters not allowed by the operating system.

Below, I explain the lecture file format using the above example.

The Format

The 3i lecture file format (version 2) is an ASCII tab-delimited file. The structure of the file is outlined below using the above example.lec file. The numbers and colon on the left, in blue, indicate line numbers.

1:	v2\n
2:	label  \t  question  \t  answer  \t  folder\image.jpg\n
3:	label 2  \t  question 2  \t  answer 2  \t  image 2.jpg\n
4:

The above example lecture file has two questions. Line 4 is blank to help the Instructor application know where to stop parsing the lecture file.

Version 2 file format requires Line 1 to have the characters v2 in order for the Instructor application to know what file format it needs to parse. The grayed out \n characters represent the newline character (ASCII decimal: 10).

The Lines 2 to N represents each question. Each part of a question is separated by one tab character (ASCII decimal: 9) and is represented here as \t.

1. Labels: The first item each line needs is a question label. In this example, I used the text label and label 2 for question 1 and 2, respectively. However, the label could be any text to represent the name of the question. (This will appear in the drop down box where the list of all questions appear.) The label is then followed by one tab character.
2. Questions: The second item each line needs is the question written in ASCII text followed by one tab character. The question is optional as long as you have an image. If you want to omit the question, put a blank space followed by one tab character.
3. Answers: The third item each line needs is an answer in ASCII text followed by one tab character. The answer is optional.
4. Images: The fourth item each line needs is an image followed by on newline character. The image is optional as long as you have a question. The image can be a JPEG or BMP. Notice that question on Line 1 includes a path to its image folder\image.jpg (without the leading \), whereas the question on Line 2 just has image 2.jpg.

But what if I want to insert tabs or newlines in my question and/or answer?
This could be done by embedding special ASCII characters into the lecture file.

• To insert a tab in your question or answer, you'll have to insert the ASCII decimal 4. This is the End of Transmission character in ASCII, not the number 4 you can type on your keyboard. This will be converted to a tab character when the file is parsed.
• To insert a newline in your question or answer, you'll have to insert the ASCII decimal 3. This is the End of Text character in ASCII, again, not the number 3 you can type on your keyboard. This will be converted to a newline character when the file is parsed.