    ======================================================================
    
                    XML-based preprocessor for Java

    ======================================================================
    
    Author: Alexey Semenjuk, sas@osw.com.ru, 2002

    
    This project is devoted for processing source files like Java that 
    doesn't support preprocessor. 
    
    Suppose you have a code:

    void f(...) {
        try {
            System.out.println("job started");
            some_job();
            System.out.println("job OK");
        } catch(...) {
            System.out.println("job FAILED");
        }        
    }

    "println"-s are used to track method execution and are likely to
    be removed from final version of this function. You can do it with 
    hands, but is is rather boring job. I think that many Java-programmers 
    wish they could write something like this:

    void f(...) {
        try {
    #ifdef DEBUG
            System.out.println("job started");
    #endif
            some_job();
    #ifdef DEBUG
            System.out.println("job OK");
    #endif
        } catch(...) {
    #ifdef DEBUG
            System.out.println("job FAILED");
    #endif
        }
    }

    The solution is to present Java source file as XML document and transform 
    it with XSLT stylesheets. 
    In this case you have to rewrite this code as follows:

    <?xml version="1.0" encoding="utf-8" ?><prep:root xmlns:prep="http://java.preprocessor.ru"> <![CDATA[
    void f(...) {
        try {
    // <-- ]]> <prep:debug> <![CDATA[
            System.out.println("job started");
    // --> ]]> </prep:debug> <![CDATA[
            some_job();
    // <-- ]]> <prep:debug> <![CDATA[
            System.out.println("job OK");
    // --> ]]> </prep:debug> <![CDATA[
        } catch(...) {
    // <-- ]]> <prep:debug> <![CDATA[
            System.out.println("job FAILED");
    // --> ]]> </prep:debug> <![CDATA[
        }        
    }
    // ]]> </prep:root>

    As you see we have added only ONE line that javac will not understand 
    and a lot of comments that are OK. But it doesn't matter, cause we will
    not let javac compile this file.

    The next step is to create two xslt stylesheets 
    (e.g. "release.xsl" and "debug.xsl") that will transform our original 
    java file formatted as xml document into valid java file that javac can 
    compile. Using "release.xsl" we will get java source without "println"-s 
    and using "debug.xsl" we will get java source file with "println"-s. 
    There are two requirements to these stylesheets:
        1. they must produce valid java source file that javac can compile;
        2. they must not change number of lines in produced file, so that
           information about errors that javac will produce (it happens 
           time-to-time) can be applied to our original java source and
           not only to transformed one.
    
    Both stylesheets (i.e."release.xsl" and "debug.xsl") fulfill requirements 
    mentioned above. 
    The first one ("release.xsl") produces java files that have code enclosed 
    in 
        "// <-- ]]> <prep:debug> <![CDATA[" and            
        "// --> ]]> </prep:debug> <![CDATA["
    lines commented away. 
        
    The "debug.xsl" stylesheet applies no transformations to original java 
    file (except of producing valid java source). It is trivial.


    -------------------------------------------------------------------------
    To apply XSLT transformation to xml files you need some application.
    I use XT Version 20020426a from http://blnz.com/xt/.

    There are two BAT files that runs XT with proper arguments:
    
        -- release.bat  - produces release version of java file;
        -- debug.bat    - produces debug version of java file;
    
    XT itself is started with xslt.bat BAT file.
