Checking, correcting, and rebuilding an ESP website

This page explains how to (re)build your ESP website, how to correct errors that emerge during the rebuild, and how to avoid them in the first place.

Errors in the structure and content of your XML may be picked up by your text editor, and will certainly be reported by Oracc when you come to rebuild your site. They will cause the generation of the associated page, or even of the whole site, to fail. The cause of such problems should usually be obvious from the error message.

Checking as you edit | Rebuilding | Structural errors | Some of the more cryptic errors explained | Good practice for avoiding errors

Checking as you edit

To save yourself inordinate amounts of time in checking and correcting, you should edit your XML files in Emacs, using the ESP templates and schemas. As you work, the mode line in Emacs will tell you whether your file is valid or not, by saying (nXML valid) or (nXML invalid). Errors in your tagging will also be displayed in red in the main window.

To find and eliminate validation errors, move your cursor to the start of the buffer, then do ^C ^N. The cursor will move to the next error, and an error message will appear in the mode line. Correct that error and do ^C ^N again until the mode line reads (nXML valid).

Regularly remind yourself of the recommendations in the Style Guide to help reduce errors too.


When you have finished creating and editing XML pages and embedded content for your ESP website, make sure that all the files are in the correct directories on Oracc (see the ESP overview page) and that parameters.xml and structure.xml have all been correctly edited.

Log in to Oracc with PuTTy or Terminal.

When oracc build portal has finished running, type less oracc.log. If there are no errors in your ESP code, you will see output like this:

ESP processing file:/home/oracc/doc2/01bld/espdev/about/licensing/index.html
ESP processing file:/home/oracc/doc2/01bld/espdev/about/contributing/index.html
ESP processing file:/home/oracc/doc2/01bld/espdev/about/contributing/howandwhy/index.html
ESP processing file:/home/oracc/doc2/01bld/espdev/about/standards/index.html
ESP processing file:/home/oracc/doc2/01bld/espdev/about/standards/schemas/index.html
ESP processing file:/home/oracc/doc2/01bld/espdev/about/standards/opendoc/index.html
ESP processing file:/home/oracc/doc2/01bld/espdev/about/standards/tei/index.html
ESP processing file:/home/oracc/doc2/01bld/espdev/tools/index.html
ESP processing file:/home/oracc/doc2/01bld/espdev/tools/cuneify/index.html
ESP processing file:/home/oracc/doc2/01bld/espdev/404/index.html
Validating pages as XHTML (only non-validating pages reported)
calling doc2 force ...
p3-colours.plx: using colours file 00lib/p3colours.txt
esp2 portal is now live at

If there are errors, error messages will be interspersed with this listing (see below) and the rebuild may fail. Correct all reported errors and run oracc build portal again. Do less oracc.log again.

When there are no errors left, take a look at the site. You should thoroughly test every HTML page on the website whenever it is changed. Ensure that all parts behave as expected--for example, that all links are present and working. If there are problems, you will need to correct the corresponding XML files and rebuild the site once again.

You can repeat this process as many times as you like.

Structural errors

The oracc build portal command will report any errors made during the rebuilding of the site, in oracc.log. Although errors are reported for the html files being generated, it is the associated xml files in 00web/ that must be fixed.

Usually the error messages will indicate clearly what has gone wrong. However, sometimes it takes experience (and/or some trial and error!) to decode them. If you are unsure, try pasting the error message into Google and you may come up with some useful answers. Contact the Oracc team if you need additional help. Remember to make a note of anything that you may wish to refer to in future.

NB. The system does not do extensive error checking for consistency. You will get a warning message if you try to create a <esp:link> to a non-existent page, or if you use <esp:glossary> on a term that is not defined on the glossary page, but some other errors, such as wrong bookmarks, may not be reported.

After correcting any sources of error (e.g. mis-named files, badly formed XML, filenames with spaces in, etc.) and run the oracc build portal again. When no errors are returned, all pages of the site have been generated correctly.

Some of the more cryptic errors explained

Error before Phase 1 has started

Exception in thread "main" java.lang.NullPointerException at ImageInfo.main(
This error is returned by the script that automatically detects the size of images. It means that the size of one or more images couldn't be detected properly, and that image may not display properly on the website. The most likely cause of this error is image files that contain a space in their filename (e.g. my great image.jpg). (Spaces are not permitted in image filenames in order for the script to work properly.) To solve the error: go through the images folder and remove any spaces from image filenames (i.e. change to mygreatimage.jpg). The error may also occur if files other than image files are placed in the images folder.

Validation errors

Error at line:x, column:x of file:/// tag name "div" is not allowed.
You have use an invalid element (in this example <div>). You will need to remove or replace it.
Error returned when <esp:image> tag refers to an image without a file extension
For instance, <esp:image file="picture1" ...> instead of the correct version: <esp:image file="picture1.jpg" ...>.

Good practice for avoiding errors

Using and nesting elements

Most XHTML and system elements can be used inside (nested in) most other XHTML and system elements. However, there are exceptions. Because of the syntax of XML/XHTML, certain system elements will not work in certain places. If you use an element in a place where it doesn't work, it will be filtered out, and a warning will be generated at the final stage of processing.

Because the site claims to be valid XHTML, it must respect the XHTML specification. This places certain prohibitions on element nesting.

Broadly, you should avoid the following:

All of these errors are easily avoided if you edit your XML files in Emacs using the ESP schemas and templates.

Names and naming

To prevent errors, always use lowercase names for your files and when creating short page ids etc. Do not use spaces in file names or ids; instead separate words with an underscore or a hyphen.

The text in the navigation bar is given by <esp:name> – see the documentation on page structure. Keep <esp:name> entries short as they will be used in the navigation bar.

The page title is given by <esp:title> – see the documentation on page structure. This text can be much longer than that given in <esp:name>.

Links to internal pages should use the short page id defined in the <esp:page> tag in structure.xml – see the documentation on internal links.

Each page is referenced in the site structure, i.e., in structure.xml, using its file name (e.g., assurbanipal.xml). Using the wrong name, such as the page id, is a common reason for stage 1 errors when the code is processed. Keep file names and folder names short and memorable as they are used to create the site's URL structure.

18 Dec 2019 osc at oracc dot org

Ruth Horry & Eleanor Robson

Ruth Horry & Eleanor Robson, 'Checking, correcting, and rebuilding an ESP website', Oracc: The Open Richly Annotated Cuneiform Corpus, Oracc, 2019 []

Back to top ^^

Released under a Creative Commons Attribution Share-Alike license 3.0, 2014. [] [] []
Oracc uses cookies only to collect Google Analytics data. Read more here; see the stats here []; opt out here.