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
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.
00res/images and/or new PDFs or other files to 00res/downloads, first type the command oracc resources and hit return.oracc build portal and hit return.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 esp2-live.sh doc2 force ... p3-colours.plx: using colours file 00lib/p3colours.txt esp2 portal is now live at http://oracc.MUSEUM.upenn.edu/doc2
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.
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.
Exception in thread "main" java.lang.NullPointerException at ImageInfo.main(ImageInfo.java:1025)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.Error at line:x, column:x of file:/// tag name "div" is not allowed.<div>). You will need to remove or replace it.<esp:image file="picture1" ...> instead of the correct version: <esp:image file="picture1.jpg" ...>.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:
<p> or <blockquote> (or a system element which creates one), inside an inline XHTML element, such as <a> or <b> (or a system element which creates one). NB. This means that when using <blockquote> you should nest the tags <blockquote><p>text here</p></blockquote> rather than the other way around.<esp:bookmark>, <esp:link>, <esp:glossary>, <esp:reference>, and <esp:index> may occur inside any of those same elements.All of these errors are easily avoided if you edit your XML files in Emacs using the ESP schemas and templates.
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.
Ruth Horry & Eleanor Robson
Ruth Horry & Eleanor Robson, 'Checking, correcting, and rebuilding an ESP website', Oracc: The Open Richly Annotated Cuneiform Corpus, Oracc, 2019 [http://oracc.museum.upenn.edu/doc/help/portals/buildinganespsite/]
Released under a Creative Commons Attribution Share-Alike license 3.0, 2014.
[http://www.facebook.com/opencuneiform]
[http://oracc.blogspot.com]
[http://www.twitter.com/oracctivity]
Oracc uses cookies only to collect Google Analytics data. Read more here; see the stats here [http://www.seethestats.com/site/oracc.museum.upenn.edu]; opt out here.