Docs:Course2wiki.pl

This tool is designed to take a course generated using an old version of the Course Processor and import it into a namespace in a wiki in a format suitable for later export and processing. It operates on the generated HTML version of the course - the original source data is not needed (see the notes below about metadata, however) - and the end result of running this script on an old course will be a nearly complete course in the wiki, including theme and module structure, as much metadata as possible, and all statically included images and animations needed by the course.

The course2wiki script is included with the course processor, and can be found in the course processor main directory. Like the course processor, this tool has been designed for, and has only been tested on, Linux systems running perl 5.8 and 5.12. It may or may not operate correctly on other operating systems or versions of perl.

Important information

The course2wiki tool is intended to significantly reduce the effort required to take the contents of old PEVE or APEcs courses and add them to a wiki for editing and later processing. It is important to note that, while this tool will reduce the work needed to import a course, it does not - and indeed can not - entirely remove the need for thorough checking and manual correction of imported material.

There are some important things keep in mind while using the tool:

• The conversion from HTML to wiki markup can introduce formatting errors in some situations (especially when steps include complicated content). While every effort is made to import the course content as accurately as possible, you must check the material to ensure it is formatted correctly.
• While the script will attempt to be as complete as possible, some resources might not be imported. It is important to thoroughly check the material in the wiki after importing a course with this tool. In particular:
  • Links to steps (other than the first step in any module) are not converted to the equivalent MediaWiki links. Warnings will be printed during import giving you the location of each link, and the theme, module, and step number it is a link to.
  • Links to themes are not converted.
  • Some anchors and links are inserted using [target] and [link] tags - these should export, but they should be checked, and probably converted to MediaWiki links.
  • Glossary entries are not imported correctly - they need to be manually fixed.
  • Media loaded using javascript (things like rollover images in particular), or resources loaded by Flash animations that are not part of the .swf file, will not be automatically imported, as the system can not handle these situations properly. You will need to manually upload dynamically loaded media.
  • image and animation formatting (alignment, frames, and so on) is not preserved. You will need to fix the formatting of any images or animations in the material.
  • No attempt is made to import the 'Front page' of the course (found in frontpage.html in many old courses). There is too much variation in content and structure in old courses to justify attempting to import this data: you will need to recreate the appropriate information in the course metadata.
• The metadata is unlikely to be complete or entirely correct. The script will attempt to generate up-to-date metadata whenever possible, but some data may simply be missing from the source material or nearly impossible to reverse engineer.
• It is important to run the tool in 'dry run' mode until you are satisfied that the data that will be added to the wiki is as complete and correct as possible. If you do not do this, incomplete and incorrect data may be added to the wiki.

Metadata requirement

This tool expects each theme directory in a course to contain its own metadata.xml file (so that it can distinguish between theme directories and other content directories.) Theoretically, this is not an onerous requirement: old versions of the course processor did not strip the metadata.xml file from themes during processing, so many old courses retain their legacy metadata files. The importer will attempt to update the metadata to the latest standard before adding it to the wiki, so users may not need to modify the xml in the course after importing.

If you are attempting to import a course that no longer has its metadata.xml files, you will either need to copy them in from the original source for the course, or recreate them by hand.

Running course2wiki.pl

To run course2wiki.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 course2wiki.pl using a command like the following:

course2wiki.pl --dry-run -u YourUserName -n Namespace -c /home/your/coursedir

This will prompt you to enter the password that corresponds to the specified username, log into the wiki, and pretend to import the course stored in the '/home/your/coursedir' directory into the 'Namespace' namespace in the wiki. If the output overwhelms your command line tool (as it almost certainly will), you can redirect the output to a file:

course2wiki.pl --dry-run -u YourUserName -n Namespace -c /home/your/coursedir | tee import.txt

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

A note about --dry-run

You are strongly advised to run the course2wiki.pl script with the --dry-run argument, and study the output from the script, until you are sure that the course will import correctly. If you do not do this, spurious pages or files may be created in the wiki (this is not going to break the wiki, and you may run course2wiki.pl multiple times on the same course and namespace if needed, but it can result in unnecessary clutter.)

Once you are confident the import will work, remove the --dry-run argument to update the wiki.

course2wiki.pl command line options

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

--course=PATH, -c PATH

This argument must be provided. This argument tells the script where the course to be imported is stored. The specified path should be the root of the course (the directory containing the course themes).

--namespace=NAME, -n NAME

This argument must be provided. This argument identifies the namespace containing the course you want to export, and it must correspond to a valid namespace in the wiki. As ever, case is important here, so triple-check that you have provided the namespace name in the correct case. The namespace must already exist in the wiki before you can import a course into it, this tool will not create a namespace for you!

--username=UNAME, -u UNAME

This argument must be provided. This argument specifies which username should be used to log into the wiki. This must correspond to a valid user in the selected wiki, and you will need to either provide the password using the --password option described below, or you will be prompted to enter the password by course2wiki.pl. If your username contains spaces, please ensure that you either enclose the username in quotes, or replace any spaces with underscores. Note that wiki usernames are case sensitive, so check that you use the correct case when specifying your username or the login will fail.

--dry-run

Perform the import process without updating the wiki. When the script is invoked with this argument, it will go through the course pretending to import it into the wiki without actually updating it. All actions that would be performed are reported on the terminal so that the user can verify that the course would be imported correctly. It is important that you run the importer with this argument until you are certain the course will import correctly. If the script is invoked without this argument (and without the --force argument) it will show a warning message and 5 second countdown before starting the import.

--force

If specified, this will suppress the warning message and countdown shown when the script is started without the --dry-run argument.

-t THEMEDIR, --only-theme=THEMEDIR

If provided, the course2wiki script will only attempt to import the theme in the specified theme directory - no changes will be made to the course page, or coursedata page (although the media page will be updated). This can be useful for incremental course imports, or importing part of an old course into a new one, but usually you will not need this option.

--allow-naive

Enables a very-basic "naive" step loader. Normally, if the course2wiki.pl script can not identify the contents of a step file as a file written by an older version of the course processor, it will simply print a warning message and fail to load the step. If you specify this option, a very simplistic step loader is turned on that can read any html file - at the expense of potentially including spurious navigation and page layout content in imported steps. Generally you will want to avoid this option!

--config=FILE, -g FILE

Specify an alternative configuration file to use during importing. If not set, the .courseprocessor.cfg file in the user's home directory will be used instead.

--help, -h, ?

This argument is optional. If specified, this will force the script to print out usage information and then exit. Use this if you can't remember the arguments course2wiki.pl supports.

--man

Prints the manual page (this documentation) and exits.

--password=WORD, -p WORD

This argument is optional. If provided, the script will attempt to use the specified password when logging into the wiki. Use of this argument is very strongly discouraged in general use. The argument is provided to allow the export script to be called programmatically, and providing your password this way from a normal shell account can be a security risk (anyone looking over your shoulder could see the plain text password on the command prompt, and the whole command line will be saved in your shell history, including the password).

--pid=FILE

If specified, the script will write its process ID to the file provided. This is primarily needed to support the web interface.

--quiet, -q

suppresses all normal status reporting. If this is specified, no status information or startup banner is written to the terminal when course2wiki.pl is working. Fatal error messages are still reported via stderr as normal.

--uploadurl=URL

Specifies the location of the Special:Upload page in the target wiki. If you do not provide this argument, the script will attempt to fall back on using the upload_url specified in the wiki2course section of your course processor configuration file. If your configuration file is missing, or does not contain a value for the upload_url, the script will exit with a fatal error. If you specify a different wiki with the --wiki argument you will almost certainly need to specify your own uploadurl as well!

--verbose, -v

Increase the verbosity of status reporting. By default (unless the quiet flag is set), course2wiki.pl will only output warning messages during course export. If you include -v on the command line, it will output warnings and notices. For complete status information including debug messages, specify -v twice (-v -v).

--wiki=WIKIURL, -w WIKIURL

If provided, the script will use the specified MediaWiki API script. If you do not provide this argument, the script will attempt to fall back on using the api_url specified in the wiki2course section of your course processor configuration file. If your configuration file is missing, or does not contain a value for the api_url, the script will exit with a fatal error. As noted above, if you set this, you will probably need to set --uploadurl as well.

Output

All pages and media read from the course will be written to the wiki. When course2wiki.pl is started with the --dry-run argument it will report any actions it would take on the wiki to the terminal so that the user can check it will import the course correctly.

The course2wiki script can produce a number of messages during normal operation, and a range of error or warning messages on encountering errors or unexpected situations. These messages are documented on the course2wiki messages page.