programmer notes

Some notes about the code.
As of April 2006, this has become slightly out of date, particularly the notes on class Transform.

packages

com.centeredwork.xilize Xilize translator (discussed below)
com.centeredwork.xilize.parser parser, mostly generated by JavaCC
xilize jEdit plugin and XAA code

Nearly half the total code simply supports the XAA GUI component in the jEdit plugin.

class Main

This is just what you would expect: the top-level driver. The execute() method expects an environment (a simple key/value map) that minimally defines the mode in which Xilize is to run and a target from which to read source files.

method main(), command line interpreter

Creates an environment from the command line arguments and calles execute().

method execute(), entry point for XAA

Essentially a dispatcher. All classic mode operations are handled in class Main. Natural mode operation is handed off to the class Natural.

class Natural, natural mode driver

This class is responsible for natural mode's autoinclude ability. It finds the appropriate CSS and autoinclude files, handles page ordering, and ensures the environment is set up correctly before translation of each .xil file.

class Xilize, top-level parsing

Summary:

  • reads a *.xil file, removes comment lines and \r (carriage returns), converts tabs to spaces
  • creates an array of String's — using blank lines as block-separators
  • from that array uses BlockFactory to create a list of block objects of the appropriate type — using JavaCC to parse the block signatures and modifiers.
  • calls each block's transform() method to generate HTML for the block
  • creates any TOC's if present as well as the file prolog & epilog
  • calls each block's output method to generated the HTML output file

class Transform, translating a block of text

This is primarily a collection of routines that use regular expressions to convert Xilize markup to HTML inline elements.

There are two entry points: text() and pre() which differ only in their handling of \n. text() will convert it to <br /> — pre() will not. Both call the method xilizeString() to do the real work.

method xilizeString()

Translates the inline elements in one block of text.

  • User-defined key/value substitutions preformed.
  • Text regions that must be protected from subsequent transformations are stored in a map and replaced in the original by their keys. This includes any existing HTML elements, == no modification markup, and @ code element markup.
  • Any &, <, and > — characters which require special handling due to their special meaning in HTML — are transformed appropriately.
  • Xilize inline element markup (links, images, phrases, etc. ) is translated.
  • The keys from the protected regions are mapped back to their values.
  • If this method was called by text(), then any end-of-line characters \n are translated to <br />

efficiency

author's note

Xilize began as a few hundred lines of code to add some functionality to Textile markup — then one thing led to another and it now weighs in at more than 10,000 lines (using the Unix wc utility) if you include the XAA GUI component.

Version 2.0 was all about adding functionality and is getting great feedback. Perhaps in a future version 3.0 the code will get the rewrite, refactoring, redesign, and update to Java5 features that it deserves and cast off its bit-by-bit construction legacy.