Mklesson is simply a program which takes as input a file called a ``lesson file'' (with the file extension .les). Mklesson produces a large set of WWW files in HTML format (with the file extension .htm or .html). You can create or modify the .les file using whatever text editor you prefer, and then run mklesson. The resulting HTML format files can then be used by tutorial users.
First, some terminology. Mklesson considers a tutorial to be a set of two or more lessons, numbered 1, 2, 3, etc. Each lesson consists of two or more sections, again numbered 1, 2, 3, etc. A section may optionally end with a question. Each section with a question has two or more responses to that question, each of them numbered 1, 2, 3, etc. Mklesson requires that exactly one response is correct; the rest are incorrect.
To invoke mklesson once it's installed, type:
mklesson lesson1.lesreplacing '1' with whatever the number of your lesson is.
Since "mklesson" is a Perl 5 program, you'll need to make sure your computer knows to invoke perl when running mklesson. If you can't talk your computer into doing that (it's automatic on Unix systems), try the following (change "perl" below to the full filename, or add the perl directory to your "path"):
perl mklesson lesson1.les
Mklesson will create the following files in the current directory:
For each section: sLESSON-SECTION.htm For each response: sLESSON-SECTIONrRESPONSE.htm For each lesson outline: lessonLESSON.htm For each processed file: lessonLESSON.tim (as a timestamp)where LESSON is the lesson number, SECTION is the section number, and RESPONSE is the response number for a given question.
Mklesson requires that the current directory contain the file "template", which provides mklesson with formatting information (how to generate the lesson sections, responses, and outline). You can edit this "template" file to give your tutorial a different look-and-feel, and/or to generate tutorial formatting for languages other than English (see the French template, for example).
Mklesson also uses the file "default" if it exists to set certain default values. If you are creating lessons for an existing tutorial, use the "default" and "template" files used by the tutorial creator. If you're creating lessons for an existing tutorial you will also need to set the PREVIOUS_LESSON and NEXT_LESSON location so that users can go backward and forwards to connected lessons.
Mklesson only changes files that ACTUALLY changed; thus, it's possible to run mklesson and not change any files. If no files are changed, that means that the lesson file, template file, and default file did not change enough to cause a change in the generated files.
Mklesson does _NOT_ generate the "master outline" or the home page of the tutorial, nor any auxillary files; you'll need to create those files in other ways.
Another somewhat similar program is available that generates tutorials for WWW browsing. However, it's an HTTP server, and thus it requires you to change your HTTP server. This is difficult for many people to do (for example, for security reasons). Also, it doesn't support distributed tutorials like mklesson does. Mklesson's input format is intentionally similar to this other tutorial's to ease transition of lessons and people.
I've added a "-s" option; if you use this option, mklesson will generate "short" filename extensions (.htm instead of .html). This is useful for CD-ROMs, since some machines (notably Macintoshes) do not support the CD-ROM Rock River extensions to handle filenames longer than 8+3 characters. While using the "-s" option isn't strictly needed for MS-DOS machines (they'll just ignore the last character), it does make it easier because you can use the same filenames on all platforms.
A related option is the "-a" option, which uses "s" instead of dashes in the generated filenames. This is all in an effort to deal with CD-ROM filenames, which by the immorally shortsighted ISO standard don't even support dashes in filenames. Thus, if you're developing for CD-ROMs, you might want both the -a and -s options.
I've also added a "-b" option to permit generating hardcopy books and hypertext lessons from the same source. If you use the "-b" option, mklesson assumes that you're generating a book from the same source as the regular lesson. The "BOOK" variable will then be set, and therefore text inside "IFDEF BOOK" sections will be used. See the format information for about books.
If you're creating tutorial files for Lovelace (an Ada tutorial), talk to me first before starting, and read the guidelines for helping to expand Lovelace.
To install mklesson on your machine, create a new directory, download the collection of mklesson-related files into that directory, then gunzip and untar it. On many machines, the command to gunzip a file is "gunzip mklesson.tar", and the command to untar a file is "tar xvf mklesson.tar.gz", You will then find a big set of files, including mklesson (the program). Next, install the program perl if it's not already installed (you'll need perl version 5 or later). Copy the file `blank.les' into a new lesson filename, and you're ready to go.
As noted above, mklesson requires a specific input format called the lesson file (.les) format. More information on the lesson file (.les) format is available.
You can also:
This page last modified on 20-May-1996.
David A. Wheeler (dwheeler@ida.org)