Background

Prof. Doron Lamm of the Near Eastern Studies Dept. envisioned a website for his Hebrew courses that would present various poems and passages from Hebrew literature annotated in a manner with which students can interact. For example, as one moves the mouse over certain words in a poem being displayed in the browser, a balloon might pop up with an English translation for that word, while an image, explanatory text, and HTML links might be displayed alongside the study text. In addition, the page might contain different modes of annotation, so that one mode might display literary annotations, while the other displays annotations that refer to historical events.

Requirements

Prof. Lamm identified the following requirements for pages:

• A page displays a study-text, i.e. a poem or literary passage.
• Certain words or phrases in the passage are "active" and respond to mouse-over events.
• In addition, certain words in the passage may be HTML links. Such links always open a new window so as not to disprupt the original context..
• It is possible to select from one of several annotation modes. Each mode is independent of all others, and activates its own set of words or phrases in the study-text that display their own annotations and pop-ups.
• The pages must contain both Hebrew in its natural right-to-left direction, and English in its natural left-to-right direction.
• Instructors and students who are not HTML experts should be able to compose pages with Hebrew text and annotate words sections of text in a manner that is intuitive and not overly complicated.

Examples

1. Breishit 1:1-3
2. a poem by Natan Zach

Strategy

In order to accomodate Hebrew and leave Ilanot robust and open-ended to accomodate other languages, Ilanot pages are written in UTF-8 an encoding of Unicode. ASCII is, by definition, a default of UTF-8, so any ASCII document also satisfies a UTF-8 parser. There are text editors and word processors available on both Windows and Unix that are capable of generating documents encoded in UTF-8. For example, on Windows 2000 one may use Microsoft Word or Notepad, while on Unix, one might use vim or emacs.

The only other requirement that Ilanot places on a text editor is that it be capable of entering and displaying bi-directional text in the logical order of each language. By logical order, we mean that each character of text in a right-to-left language is entered in the same order that a native speaker would write them down on paper, beginning at the right margin of the page for each line and proceeding to the left. The other choice available for entering and displaying right-to-left text visual order which means that each line of text in a right-to-left language is entered beginning with the character that appears nearest the left margin (the end of the line for a right-to-left language), followed by the letter that is second from the left, and so on. Visual order is necessary for older browsers that do not support logical rendering of text in right-to-left languages. However, the currently released versions of Microsoft Internet Explorer, Netscape Navigator, and the Mozilla browsers all correctly render right-to-left text that is entered in it's logical order.

All of the editors mentioned above present options that enable entry and display of bi-directional text in logical order.

The next problem that presented itself is how to create pages that present different and independant modes of annotation without having to create multiple version of the same page, one for each annoation mode. Ilanot adopted the strategy of encoding only the structure of each page with HTML and placing all content in Javascript variables in order that the content of the document can be manipulated by the browser without having to fetch a new page each time the user chooses a different mode of annotation. Each time the user selects a different mode of annotation, the browser replaces the contents of the HTML element containing the study-text with a different version of the same study-text, but marked up with links to annotations that correspond to the new mode just chosen.

The above strategy saves the page author from having to create a different version of the same page for each node, but it does not save the author from having to copy multiple versions of the same study text, each refered to by a different Javascript string reference, and mark up each version separately with HTML tags for the mode it corresponds to. This would force an author who later discovers a mistake in the study-text to correct it multiple times, once for each Javascript string literal corresponding to each annotation mode. In order to avoid this, Ilanot defines it's own markup syntax that makes it possible to mark up one copy of the study-text for all annotation modes. When the user selects an annotation mode the browser dynamically replaces the contents of the HTML element containing the study text with a copy of the study text for which it has replaced all the Ilanot markup with HTML markup only for the selected mode.

The above strategy is highly dependent on Javascript and the Javascript browser's ability to recognize and replace text that matches regular expressions. Without further refinement, this would require Ilanot page authors to become dynamic HTML experts, a skill that might require a significant investment of their time in days or weeks. To avoid this, Ilanot defines an XMLT template that determines the skeletal structure of every page and contains all the Javascript code required to change the contents of each page to match the annotation mode selected by the browser. Now each page can be authored in XML, according to a simple and hopefully intuitive schema, and converted by an XSLT processor into HTML according to the Ilanot template. This significantly reduces the learning curve for Ilanot authors because the XML schema is much simpler than the HTML that is generated from it.

Below are the XML pages that generated the examples refered to above.

1. breishit.xml
2. mizur.xml

While viewing one of the examples in your browser, use your browser to view the HTML source for the sample (almost all desktop browsers have a command to do this) and compare it with the corresponding XML source from which it was generated.

Generating Pages

In order to generate the above example HTML pages, Ilanot uses an XSLT template. The template is a specification for converting an XML file into an HTML file that displays the study text and annotations in the manner described above. The steps for creating a study page are:

1. Write an XML file that follows the schema described in ilanot.dtd. This file contains the study-text and all related annotations and modes.
2. Run the XML file through an XSLT processor that transforms the XML file into an HTML file according to the XSLT template ilanot.xslt using the Perl script ilanot.pl. The command for this is

   ilanot.pl XSLT-template-file XML-source-file

   Output is sent to stdout.

Caveats

1. One must be careful not to use names that are already defined in the Javascript language or the browser's DOM for naming annotation modes. For example, I discovered that naming a mode text causes all Javascript references to "text.x" to return undefined when x is an annotation. I have not been able to determine the exact reason for this and this behavior may vary from browser to browser. To be certain that a name does not clash with any name in the Javascript language or in the DOM, I suggest referring to Core Javascript Reference 1.5 / Appendix A Appendix A Reserved Words and The Gecko DOM Reference when in doubt..
2. One must take the same care to replace special characters such as "&" with their corresponding entity references, i.e. "&" in the study-text.

Remaining Issues

1. The process of creating an XML document for a page, although far easier than directly writing its HTML counterpart, can still be messy and error-prone. Currently, most errors cannot be caught until a page is displayed in a browser, by which time it can be difficult to identify the source of the error. It is important to log Javascript errors during testing because these can give a clue as to where a mistake in the XML might have occured. It might be helpful to have more validation of the input XML while it is being translated into HTML.
2. It would be useful to also validate the output and report any problems.
3. When there is only one annotation mode, suppress the drop-down selection box for annotations.

Development Platform Requirements

Ilanot requires that the following tools be installed on the development platform (the platform on which HTML pages are generated).

• Perl
• Perl module XML::LibXML
• Perl module XML::LibXSLT

All of the above can be installed on Windows by first installing ASPN Perl by Active State. To obtain the LibXML and LibXSLT modules, you will need to install and run the PPM Installer that comes with ASPN Perl. In the PPM shell, you must add the repository "http://www.apache.org/dest/perl/win32-bin/ppms" to the list of repositories to search for modules. Next, search for and install LibXML and LibXSLT. The command "install -follow" will install each module along with any pre-requisite modules, such as XML::Common.

(Caveat: this page is not meant to be a primer on using PPM! You may find this on ActiveState's website, or type "help" in the PPM shell.)

Collaborators

• Prof. Doron Lamm, Dept. of Near Eastern Studies, University of Michigan.
• Larry Siden, independent consultant.