Docs:Course Processor

Introduction

The course processor is a modular, perl-based text processing application utilising a series of run-time loaded plugins to maximise its flexibility. The default distribution provides plugins capable of processing LaTeX and HTML into HTML structured around the CBT package paradigms that PEVE implement in their courses. However, the design of the system is such that the potential input and output formats, and the structure of both, is not enforced by the software, only the plugins installed or selected at any time.

The documentation for the course processor is split over multiple pages: this page contains general instructions regarding the reqirements of the processor, its installation, operation, and configuration. Each input and output handler has a corresponding page linked later in this document

Content creators who do not wish to use the processor directly may just want to consult the input and output handler documentation relevant to their needs rather than follow all the contents of this document.

Requirements

The following list contains the minimal software environment required to run the course procesor. Later revisions of perl modules and external software are likely to work, provided they retain backwards compatibility.

• a Linux or Unix (Solaris/*BSD) system of relatively recent vintage. The course processor will not run on Windows natively or in Cygwin due to techniques used inside it and its dependencies.
• Perl 5.8 or later. Any Perl 5.x version might handle it, but it has only been tested on 5.8.x and 5.12.x
• The latest versions of the following non-standard Perl modules:
  • DBI
  • Digest
  • Encode
  • File::HomeDir
  • GD (and its associated modules)
  • MediaWiki::API
  • MIME::Base64
  • Term::Size
  • Text::Wrap
  • URI::Encode
  • XML::Simple

If any LaTeX processing is needed (LatexInputHandler, or [latex] blocks in html), the following additional requirements must be met in addition to those listed above:

• latex2html 2002.2.1 or later.
• tetex 3 or similar LaTeX compiler.
• netpbm 10 or later (earlier versions of netpbm will not work correctly).

If the tidy facility provided by the HTMLOutputHandler plugin is enabled you will also need:

• HTML Tidy

Installing

The course processor software can be installed anywhere, however the directory structure provided in the distribution must be preserved. That is the directory containing the processor.pl file must also contain at least the modules and plugins directories as well as, optionally, a template directory containing one or more template directories.

If you are using the processor on elearn, everything has already been set up for you: the processor is installed globally and appears in your path, so you can just invoke the processor as described below without having to do any additional work.

Running processor.pl

To run processor.pl, ensure that the courseprocessor directory is in your path (if you are using elearn, this is already done for you), and then you can run processor.pl using a command like the following:

processor.pl -c coursedata -d output

This will process the contents of the coursedata directory into the format supported by the output handler specified in your configuration file (see below), merge the framework with it, and store the resulting course in the output directory. If the status output from the script overwhelms your command line tool, you can redirect the output to a file:

processor.pl -v -v -v -c coursedata -d output | tee export.txt

you can then read the contents of export.txt in Your Favourite Text Editor.

processor.pl command line options

When you run processor.pl, you provide a number of arguments via the command line. The following arguments are supported:

--coursedata coursedir, -c coursedatadir

This argument must be provided. Sets the course data source directory. This argument is not optional, and the processor will exit with an error if it is not supplied.

--dest outputdir, -d outputdir

This argument must be provided. Specifies the name of the directory into which the course should be processed. NOTE: if this directory exists it will be deleted during processing. Take great care to ensure that the output directory does not contain any vital pre-existing data as the processed course will delete, overwrite, and otherwise trash it.

--config, -f

Allow a configuration file to be loaded instead of the default ~/.courseprocessor.cfg

--debug, -b

Enable low-level debugging output, potentially more detailed than -v -v -v mode.

--filter, -s

Specify a comma-separated list of filters to apply to the course material during processing. Please see the Docs:Filtering page for details.

--help, -h, -?

Print a brief help message and exits.

--listhandlers, -l

Lists the available input, output and reference handlers and then exit.

--mediadir

Specify an alternative media directory name (by default, this will be 'media'). This is rarely used, and should only be needed in unusual situations.

--man, -m

Prints the manual page and exits.

--outargs arguments

Allows options supported by the output handler to be set on the command line. If more than one output handler option needs to be set, you may specify this argument multiple times, or separate output handler options with commas. When specifying the option, you should separate the option name and value with a colon, eg: --outargs templates:some_template_name All options supported by the output handler in its configuration file may be provided here to override the default or any value in the configuration file.

--outhandler outputhandler, -o outputhandler

Overrides the outputhandler specified in the configuration file (if there is one). Note that this must be the full name of an outputhandler loaded by the software and it is case sensitive. Use -l to obtain the list of known handlers for valid values. If this is not specified, and the configuration file does not contain a default, then the processor will exit with an error.

--pid pidfile

Write the processor's process ID to a file. This is only likely to be of any use when invoking the processor from another system (it was added to support the requirements of the web interface). The file is not removed when the processor exits!

--verbose, -v

Increase the output verbosity. This may be repeated several times to increase the verbosity level. -v -v -v enables all levels of output, including debug. Note that you will need to redirect the output to a file when you specify -v, or most of the status messages will be lost.

Configuration

Please see the Configuration file documentation for the format, location, and content of the configuration file for the processor.

Plugin documentation

The remainder of the documentation for the processor is split over serveral pages, one for each input or output processor. Each plugin has its own specific requirements and purpose, and you should consult the documentation carefully when creating your content.

Input handler plugins

Docs:HTMLInputHandler
Docs:LatexInputHandler

Output handler plugins

Docs:HTMLOutputHandler

Other resources

The following pages are additional information for the curious or those intending to extend the processor, they are not required reading for those just using it (although they may help with understanding some of the behavioural quirks of the processor).

Docs:Operational Overview
Docs:How to write a processor plugin