# XC (HTML Composer)

One of the key ideas of GenBorg is that all program representations can be synthesized from equations; just as we can synthesize .java files from base and extension code files, we should be able to synthesize HTML files from base and extension markup files.

XC is an elementary text preprocessor that is useful in composing base and extension HTML and (hopefully) XML files. XC really doesn't understand HTML or XML, so its utility isn't limited to HTML and XML. Never-the-less, XC is the first step toward a really useful document composition tool.

### Basic Idea

A base document is a template: it has a set of labeled holes that are to be filled with document fragments. Extension documents contain named document fragments, which also might have labeled holes. The figure below shows a base document and two extension documents. The base document has two holes (holeA and holeB). Both extension documents have definitions for both holes. Note that the definition of holeA in extension document1 also has a hole (whose name is holeA).

There is a parallel between the above figures and abstract classes and their concrete subclasses. An abstract class has a set of abstract methods whose implementation is not specified. The implementation of abstract methods is provided by concrete subclasses. The analogy is the following: a base document is an abstract class; holes in the base document are abstract methods. Extension documents are concrete subclasses (or more exactly, mixins that assume an abstract superclass); hole definitions are method declarations.

Instead of using the terms "hole" and "hole definition" from this point on, we will use the term call (short for call-to-concrete method) and method (short for method declaration). Thus, the above base document makes a call to concrete methods holeA and holeB; both extension documents have methods holeA and holeB.

Given base and extension documents, it should be possible to compose them. The figure below represents the equation extension_document2( extension_document1( base_document )), where the resulting document is shown to the right:

Another composition corresponds to the equation extension_document2( base_document ), which yields a different document than the previous equation:

A base document consists of a single (implied) method called "main". Main is a special method because it doesn't have to be declared. All other methods must be explicitly declared to XC. There can be zero or more method calls in a base document.

An extension document is a series of explicit method declarations, each of which may have zero or more method calls. A call never references methods within the current document; calls always reference methods of an extension document that will be composed with it. (In layer-speak, calls only reference methods of the next lower-layer or next extension).

Because HTML is such a forgiving language, it is easy to create base and extension HTML documents using standard HTML editors (e.g., FrontPage). By flipping to the HTML source page, one can introduce XC commands to define calls and methods. These calls and methods are not displayed in HTML browsers.

The following sections describe methods, calls, and other features of XC.

- Examples
- Calling XC from the Command Line
- Calling XC from Programs
- Limitations

### Examples

Consider the following base document B:

>     1
>     2
>     <call foo >
>     6
>     7
>     <call bar >
>     11
>     12

The composition of B with E (written as E(B)) yields:

>     1
>     2
>     3  -- method foo
>     4  -- method foo
>     5  -- method foo
>     6
>     7
>     8  -- method bar
>     9  -- method bar
>     10 -- method bar
>     11
>     12

### Calling XC from the Command-Line

Use the following to invoke XC from the command line:

>     > XC.Main base.html ext1.html ext2.html ...

The output of XC is placed in a file "result.html". Error messages are sent to standard out.

### Calling XC from a Program

XC is a package that can be called from another program. To use it is simple:

> (a) initialize error reporting stream

> >     XC.MLObject.setReportStream( print_writer );

> > note: if this method isn't called, the report stream goes to standard out.

> (a) to parse a base or extension file, use:

> >     try {
> >        XC.MLObject base = new XC.MLObject( baseFileName );
> >     }
> >     catch (Exception e) {
> >        // errors -- failed to open or create MLObject
> >     }

> (b) to compose a parsed base or extension file, use:

> >     try {
> >        base.compose( new XC.MLObject( extensionFileName );
> >     }
> >     catch (Exception e) {
> >        // errors -- failed to open, create MLObject or to compose
> >     }

> (c) to write (output) a text representation of a composed file, use:

> >     try {
> >        base.write( outputFileName );
> >     }
> >     catch (Exception e) {
> >        // failed to write file
> >     }

### Limitations and Future Editions

XC is really primitive. It would be nice to add properties (i.e., variables with set and get methods) to XC files, and have conditional expansions. This can be done and should follow the notions already developed in GenVoca design rule checking.

Also, it is not clear that XC works with XML (or XML editors and browsers). So to make XC more general, we'll have to look into this too.