Docs:Wiki2course messages

In general, aside from the help message and initial startup message, all messages generated by the wiki2course script will be prefixed by ERROR:, WARNING:, or NOTE: indicating the level of severity of the message. The following sections discuss the messages in detail, ordered alphabetically where possible, along with the probable cause and potential fixes where appropriate.

Fatal errors

Messages prefixed with 'FATAL:' are serious problems that will either halt the script or produce potentially meaningless course data output. If you encounter one of these messages, you must take action to correct the problem before the course data can be considered valid.

FATAL: $cdlink page is missing!

Cause: A CourseData link was found on the course's Course page, but the page does not actually exist.

Fixes: Create the CourseData page and populate it as specified in the DevWiki Course Structuring document.

FATAL: $cdlink page is empty!

Cause: A CourseData link was found on the course's Course page, but the CourseData page has no content.

Fixes: Populate the CourseData page as specified in the DevWiki Course Structuring document.

FATAL: $nspace:Course page is missing!

Cause: The specified course namespace does not contain a Course page.

Fixes: Check that the correct namespace has been specified, and that the contents of the namespace conform to the requirements given in the DevWiki Course Structuring document.

FATAL: $nspace:Course page does not contain a CourseData link.

Cause: While the namespace specified does contain the required Course page, the system could not locate a link to its CourseData page from the Course page.

Fixes: Check that the contents of the namespace conform to the requirements given in the DevWiki Course Structuring document.

FATAL: $pagename page is missing!

Cause: A page linked to in the wiki is missing. This is not generally a fatal error, but may indicate a problem in your course.

Fixes: Check that the named page exists, or that any links to the page are corrected to link to the intended page.

FATAL: Attempt to invoke highlight without sufficient information.

Cause: One or more <source> blocks are missing either the lang="" or style="" arguments.

Fixes: Ensure that all <source> blocks in your course material have at least the lang and style arguments specified.

FATAL: dir $name corresponds to a file or other resource.

Cause: While the system was attempting to create a directory, it encountered a file or link with the required name in the location it was going to create the directory. This should generally only happen in situations where the coursedata directory specified via the --outputdir command line argument actually corresponds to a pre-existing file or link.

Fixes: Specify a different name in the --outputdir argument, delete the old coursedata directory you are attempting to replace, or make sure that there is not file or link with the same name as the outputdir you specify.

FATAL: highlight did not produce any output. Unable to process source.

Cause: the highlight program did not write any data during processing of a source block. This may indicate that one of your source blocks is empty, or there is a low-level system problem.

Fixes: check that all of your <source> blocks have some content. If they do, contact Chris for assistance as this may indicate a filesystem-level problem.

FATAL: highlight did not produce any stylesheet output. Unable to process source.

Cause: the highlight program did not write any stylesheet data during processing of a source block. This may indicate that the selected colour theme is invalid, or a low-level system error occurred.

Fixes: check that the colour theme specified in the <source> 'style' argument is valid. If it is, contact Chris for assistance.

FATAL: Maximum level of allowed recursion ($maxlevel levels) reached while fetching page content.\nRecursion path is: $path

Cause: Too many levels of transclusion have been encountered. This is most likely to be the result of one page including another, which in turn includes the page that included it forming an infinite recursive loop, or a very long chain of nested transclusions.

Fixes: Ensure that no transclusion loops appear in your material, and be careful to ensure that you do not have a lot of nested transclusions in your pages. The path shown should give you the titles of the pages the script has recursed through before giving up, you should examine the pages it lists to ensure they are correctly written.

FATAL: metadata element does not have a name attribute. Unable to save theme.

Cause: The metadata for the theme appears to be malformed and does not contain a name="" attribute for the theme.

Fixes: Correct the metadata to conform to the Metadata specification.

FATAL: name element for $theme contains spaces. This is not permitted.

Cause: the name="..." attribute for the theme element in the metadata contains a space.

Fixes: Don't include spaces in any of the name="..." attributes in the metadata!

FATAL: name element for module $title contains spaces. This is not permitted.

Cause: the name="..." attribute for the module element in the metadata contains a space.

Fixes: Don't include spaces in any of the name="..." attributes in the metadata!

FATAL: No content for $cdlink. Unable to process course.

Cause: The course data page is empty or missing.

Fixes: This error should, in general, never happen - if the page really is missing or empty, it will have been flagged as such by earlier checks, and processing should have already stopped. This error will generally only be generated in situations where the wiki has been edited during export (very unlikely), or a serious problem has occurred with the API. If you get this error, contact Chris for assistance.

FATAL: No password provided

Cause: The user did not enter a wiki password when prompted, and just pressed return.

Fixes: Enter a valid wiki password when prompted by the system, or provide a password via the command line.

FATAL: The API returned a relative path for the URL for '$title'. You must provide a value for the fileurl argument and try again.

Cause: The API through which wiki2course.pl communicates with MediaWiki generated a relative path when asked for the URL of a media file. The wiki2course.pl script requires absolute URLs for many operations, and will break if the API does nto provide them.

Fixes: Specify the --filesurl=http://url/of/mediawiki/ argument on the command line when invoking wiki2course.pl (for example: --filesurl=http://elearn.cs.man.ac.uk/devwiki/ )

FATAL: Unable to create directory $name: $@

Cause: While trying to create a directory, the system encountered an error that prevented it from proceeding. The reason the operation could not be completed will follow the directory name.

Fixes: Examine the message following the directory name to determine what prevented the system from creating the directory and take the appropriate steps to correct them. The most common cause of this error is likely to be a permissions problem (in which case, ensure that you have write access to the output directory), or a drive space problem (ensure there is enough space to perform the action).

FATAL: Unable to determine filename from $entry.

Cause: The system could not decide what to call the specified entry. In general, This Can't Happen.

Fixes: Tell Chris, as this should not actually be possible.

FATAL: Unable to fetch $entry. Error from the API was:

Cause: The named media resource could not be downloaded because of a communication problem with the wiki.

Fixes: As this is a low-level error you may need to contact Chris for assistance with fixing problems this reports.

FATAL: Unable to fetch page '$pagename'. Error from the API was:

Cause: An error occurred while the system was attempting to fetch the page shown. The reason the operation failed will be shown after the error message.

Fixes: As this is a low-level error you may need to contact Chris for assistance with fixing problems this reports.

FATAL: Unable to fetch $nspace:Course page. Error from the API was:

Cause: An error occurred while the system was attempting to fetch the course's Course page. The reason the operation failed will be shown after the error message.

Fixes: As this is a low-level error you may need to contact Chris for assistance with fixing problems this reports.

FATAL: Unable to fetch $theme page. Error from the API was:

Cause: An error occurred while the system was attempting to fetch the theme page shown. The reason the operation failed will be shown after the error message.

Fixes: As this is a low-level error you may need to contact Chris for assistance with fixing problems this reports.

FATAL: Unable to fetch coursedata page ($cdlink). Error from the API was:

Cause: An error occurred while the system was attempting to fetch the course's CourseData page. The reason the operation failed will be shown after the error message.

Fixes: As this is a low-level error you may need to contact Chris for assistance with fixing problems this reports.

FATAL: Unable to fetch page '$title'. Error from the API was:

Cause: A problem occurred in the communications layer between the script and the wiki. An error message that may (or may not...) explain the cause of the problem will follow the error message.

Fixes: Possible fixes depend entirely on what happened to break the communication. In this situation, you may need to contact Chris for help if the problem is not obvious.

FATAL: Unable to launch highlight:

Cause: The script was unable to invoke Andre Simon's Highlight program to process the contents of a <source> block. The exact cause should follow the error message.

Fixes: Possible fixes depend entirely on what happened to break the communication. In this situation, you may need to contact Chris for help if the problem is not obvious.

FATAL: Unable to locate course metadata in the course data page

Cause: No metadata has been provided on the coursedata page, or the format of the metadata is incorrect.

Fixes: Check that you have specified a == Metadata == block on the course data page, and that the metadata following it is enclosed in pre or source tags.

FATAL: Unable to locate metadata entry for $module. (Remember, the module name without namespace MUST match the metadata title!)

Cause: The specified module does not appear to be included in the theme metadata.

Fixes: Check that the metadata includes the name of the module in the wiki, without the namespace, in a title="..." attribute. The match must be exact, including case sensitivity.

FATAL: Unable to log into the wiki. Error from the API was:

Cause: An error occurred while trying to log the user into the wiki. This is most likely to be an authentication error (ie: incorrect username or password specified), but additional information will be shown after the error message.

Fixes: Check that the username and password provided are valid, and check that no unusual issues are reported after the error message.

FATAL: Unable to open $stepname ($title) for writing:

Cause: The system could not open the step file shown. The OS-level error that caused the problem will be shown after the error message.

Fixes: This error may be caused by insufficient drive space, in which case space may need to be freed before the script can complete successfully. However, examine the message provided by the operating system after the error message, and contact Chris for advice if needed.

FATAL: Unable to parse anything from $step

Cause: No valid content appears to be present in a step. The contents of the step will be shown as part of the error so that you can identify where the problem is.

Fixes: Ensure that the step conforms to the requirements specified in the DevWiki Course Structuring document. This error will usually be generated when you forget to include a title for the first step in a page - remember that all steps in a module need to have a == Step Title==, even the first step!

FATAL: Unable to parse body from $step

Cause: No valid content appears to be present in a step. The contents of the step will be shown as part of the error so that you can identify where the problem is.

Fixes: Ensure that the step conforms to the requirements specified in the DevWiki Course Structuring document.

FATAL: Unable to parse metadata. Check the metadata format and try again.

Cause: The metadata for the theme appears to be malformed.

Fixes: Check that the metadata conforms to the requirements of the [Docs:HTMLOutputHandler#Metadata|Metadata specification]].

FATAL: Unable to parse metadata from $theme. Unable to process theme.

Cause: The system could not read any metadata out of the theme page.

Fixes: Check that the theme contains a metadata section and that it conforms to the requirements given in the Metadata specification.

FATAL: Unable to parse module names from theme page.

Cause: The current theme page does not appear to contain any modules listed.

Fixes: Add some module links to the theme page in accordance with prophesy the DevWiki Course Structuring document.

FATAL: Unable to parse steps from content of $module.

Cause: The system is unable to split the module page up into steps.

Fixes: Ensure that the contents of the module page are valid and conform to the requirements specified in the DevWiki Course Structuring document.

FATAL: Unable to parse theme names from course data page.

Cause: The course data page does not appear to contain a themes section.

Fixes: Add the theme links to the coursedata page as specified in the DevWiki Course Structuring document.

FATAL: Unable to parse title from $step

Cause: No valid title appears to be present in a step. The contents of the step will be shown as part of the error so that you can identify where the problem is.

Fixes: Ensure that the step conforms to the requirements specified in the DevWiki Course Structuring document.

FATAL: Unable to remove namespace from $module.

Cause: The system couldn't work out what the module page name is without its namespace. In general, this should never happen.

Fixes: Tell Chris about this, as it probably indicates a serious low-level error somewhere.

FATAL: Unable to read highlight css file: $!

Cause: The system couldn't read the contents of the stylesheet generated by highlight when processing a <source> element. This should never actually happen!

Fixes: Tell Chris about this, as it probably indicates a serious low-level error.

FATAL: Unable to read highlight output file: $!

Cause: The system couldn't read the contents of the data file generated by highlight when processing a <source> element. This should never actually happen!

Fixes: Tell Chris about this, as it probably indicates a serious low-level error.

FATAL: Unable to save $filename: $!

Cause: The system could not save the file named. The OS-level error that caused the operation to fail will be shown after the error message.

Fixes: This error may be caused by insufficient drive space, in which case space may need to be freed before the script can complete successfully. However, examine the message provided by the operating system after the error message, and contact Chris for advice if needed.

FATAL: Unable to write metadata to $outdir: $!

Cause: The system could not open the metadata.xml file in the theme directory shown. The OS-level error that caused the problem will be shown after the error message.

Fixes: This error may be caused by insufficient drive space, in which case space may need to be freed before the script can complete successfully. However, examine the message provided by the operating system after the error message, and contact Chris for advice if needed.

Warnings

Messages prefixed by WARNING: are important notifications that something may require your attention, but the system is able to continue operating correctly. In general, you should examine warning messages to make sure that they are in line with your expectations for the material, but you do not need to ensure all warnings are removed before invoking the processor proper.

WARNING: Dir $name exists, the contents will be overwritten.

Cause: The named directory already exists, and the system will just write into it anyway, potentially overwriting any existing contents.

Fixes: If you remove the old course data directory prior to running the wiki2course script, this should never be shown. In most cases it is harmless, as long as you are reusing an appropriate, pre-existing coursedata directory.

WARNING: name attribute for module $title contains spaces. This is not permitted.

Cause: name="" attributes in metadata must not contain spaces.

Fixes: remove any spaces in the name attribute's value, or replace them with spaces.

WARNING: No content for $listpage.

Cause: The media page for the course is empty.

Fixes: Only a problem if your course contains any images, animations, or similar resources that must be listed on the media page. If it does, you must ensure they appear on the media page or they will not be exported with your material.

WARNING: No content for $module.

Cause: The named module exists, but it has no contents.

Fixes: During course development, this is not a real problem. If you have any of these appearing when the course is 'done', you're either not done, or you have a stray link to a module with no content somewhere.

WARNING: No content for $theme.

Cause: The named theme exists, but it has no contents.

Fixes: during development this is not a problem. All warnings of this kind should be resolved before the course is finished.

WARNING: Request for non-existent file $filename in $page.

Cause: A step in the indicated module page contains a reference to a file (an image, for example) that does not exist inside the wiki. This will also generate an error marker in the exported material where the erroneous reference is.

Fixes: Check that all the image, animation, and other files used by your course have been uploaded to the wiki and are present in the course media page.

WARNING: Unable to load configuration file: $error

Cause: The configuration file could not be opened or read.

Fixes: ensure that the configuration file exists and is readable by the current user. See the Config file documentation for more details.

WARNING: Unable to fetch $entry: the file can not be downloaded at this time.

Cause: An error occurred while downloading a file from the wiki.

Fixes: This should generally never happen. If it does, try running the export tool again later, and contact Chris for advice.

WARNING: Unable to fetch $entry: the file does not exist in the wiki.

Cause: The media page contains a link to a file that does not exist in the wiki.

Fixes: Check that all the links in the media page go to valid files, and upload any files listed on that page that do not exist in the wiki.

WARNING: Unable to locate $filename in the media directory.

Cause: A step contains an image, or a link to a file, but the corresponding image does not appear in the course media page. This warning indicates that the file exists on the wiki, and the markup in your step is correct for using it, but since you have not added the appropriate entry for the file to the media page, you may be using it without fully realising it.

Fixes: Ensure that all images, animations, and files linked within your course using the [[File:<name>]] syntax appear in the media page. Note that, as long as this warning is followed by "WARNING: Fetched $filename. Consider adding it to your media page to avoid this warning." your course will work as expected, the media file will have been exported, and this warning can be ignored. However, if the "Unable to locate $filename in the media directory" warning is followed by any other message, the media file in question may not work in your exported course.

WARNING: Zero length file written for $filename! This file will be ignored.

Cause: A file downloaded from the wiki appears to have no content.

Fixes: This should generally never happen, if it does it may indicate a low-level problem, contact Chris for assistance.

Notes

Messages prefixed by NOTE: are purely informative, in general you don't really need to pay much attention to them, as they're just telling you where the system is in the export process. If something appears to be odd in the output data, you may need to review these to trace where the problem might be.

NOTE: $listpage shows $count files to download. Processing...

Cause: Indicates that the script has successfully parsed a media list page and will download the indicated number of files. Each file will be listed individually as it is downloaded.

NOTE: Converting mediawiki markup in $stepname to html.

Cause: Indicates that the module page has been retrieved and split into steps, and the script is now processing the contents of the named step to convert mediawiki markup into html. Note that this message is only generated when conversion is enabled.

NOTE: Creating theme directory $name for $theme...

Cause: Generated when creating the directory to contain a theme. There should be one of these messages for each theme in your material.

NOTE: Downloading $entry...

Cause: The script is downloading the named file to the course data output directory.

NOTE: Exporting module $module to $moduledir.

Cause: Generated when creating a module, indicates that the module and its steps will be written into the named module directory.

NOTE: Extracting metadata xml from $title...

Cause: Indicates that the metadata for the specified page is being processed. Any problems with the metadata will generate errors after this notice.

NOTE: Fetching page data for $theme...

Cause: Generated when the script begins to fetch the named theme page for processing.

NOTE: Found the following markers in $step:

Cause: If any '???' markers have been located in the material, one or more of these notes will be generated after processing has completed indicating their locations.

NOTE: No files or images listed on $listpage. Nothing to do here.

Cause: The script managed to successfully read the named media list page, but the page has no contents.

NOTE: Parsing metadata information to determine directory structure...

Cause: Indicates that the script is attempting to map module names to filesystem directories in preparation for exporting modules and steps.

NOTE: Parsing module names from theme page...

Cause: Generated when the system starts to read module names from the current theme page.

NOTE: Parsing theme names from course data page...

Cause: Indicates that the script has started to read the list of themes from the course data page.

Other messages

There are three situations under which messages may be generated without a prefix:

• when wiki2course is invoked without the correct arguments, or the help argument is specified, the generated help documentation has no prefix.
• when the script starts an informational startup message similar to wiki2course.pl version 1.5 (26 March 2010) [Course Processor v3.7.0 (26 March 2010)] started. is printed.
• some error messages involve multiple line output, in these cases only the first line will have the ERROR: prefix associated with it.