|
Ed Beroset
Last modified: Sun Jul 6 15:12:04 EDT 2004 |
|
Inspired by Brad Eckert who wrote the original Forth2HTML and placed it into the public domain, I finally finished off the Forth2XML variant (also public domain, of course) and here it is.
The Forth2XML converter is only one component which allows for the flexible processing of Forth source code. Once the code is rendered into XML, it can be processed using XSLT and turned into other useful forms. For example, forth.xsl was used on the color-ed5.xml file to create color-ed5.htm.
However, this is only one of many possible transformations. Another example is a different transform which creates HTML pages with a very different style.
More interesting uses are also possible. For instance, this XSLT creates a reference table which lists each defined word and the number of times it's used.
As I have time for it, I'll be creating and donating more transforms, which you are free to use for whatever purpose you like -- I'm donating all of them to the public domain as well.
If you're converting Forth source code into XML documentation, you'll need a Forth implementation. The one I most often use is gforth which is an open source Forth implementation that runs on many platforms, including Linux, Windows, and Mac OS X.
If your code is in a file called mycode.f, and you're using
gforth, you could do the conversion as follows:
gforth color-ed5.f at a command line prompt.xml mycode.f.bye to exit gforth.
If you've followed all of these steps, you'll now have a file named mycode.xml.
First, it's worth noting that one can convert XML into many other forms other than just HTML. For instance, it is possible to write transforms that will create plain text, SVG graphics, or other forms. However, the most popular transform is from XML into HTML.
To apply a XSLT to an XML document, one can use a number of different tools. Many current web browsers include some XSLT processing. For many purposes, however, it's often handy to have a standalone processor. For this purpose, I use and recommend Saxon which is an open source, multiplatform XSLT and XQuery processor.
Following along from the example above, here is how to transform mycode.xml into mycode.htm:
saxon -o mycode.htm mycode.xml forth.xslThat's it!
I have been asked about the colors in the Forth2XML implementation and what they mean. In fact, the XML representation doesn't actually refer to colors. Instead, it classifies words according to their semantic meanings within the Forth source code, and it's up to the XSL to apply colors (or not) as desired. For instance, the colors for the main XSLT are assigned by the use of a style sheet which is embedded within the XSLT.
To make it more concrete, here's a sample. A typical line of Forth might look like this:
VARIABLE intag \ within tag
The Forth2XML processor would render this as:
<a std="#6.1.2410"><tag type="core_ws">VARIABLE</tag></a><a name="xintag"><tag type="variables"> intag</tag></a><tag type="commentary">
\</tag> <tag type="commentary"> within tag</tag><br />
As you can see, words which are references to standard words are tagged with <a std= labels
and other words are labelled using <tag type designators. In both cases, this labelling
is transcribed by the XSLT and rendered into a span which can then be assigned a style. Following along
this example, we can see that the XML fragmment above is translated into:
<a name="xintag">
<span class="variables"> intag</span>
</a>
<span class="commentary"> </span>
<span class="commentary"> within tag</span>
In this instance, the mapping is done from XML into HTML named spans, and so the colors are easily applied by the forth.xsl file. The colors are assigned clearly and automatically from witihin the XSL. Here is the relevant extract:
body {background: white; font-family: monospace;}
h1 {color: black;font-family: serif}
a {text-decoration:none;}
span.unknown {color: gray;}
span.commentary {color: green; font-style: italic;}
span.numeric {color: orange;}
span.errors {color: red;}
span.values {color: purple;}
span.userwords {color: black;}
span.userdefiner {color: teal;}
span.variables {color: fuchsia;}
span.core_ws {color: blue;}
span.core_ext_ws {color: black;}
span.block_ws {color: black;}
span.double_ws {color: black;}
span.exception_ws {color: black;}
span.facilities_ws {color: black;}
span.file_ws {color: black;}
span.fp_ws {color: black;}
span.local_ws {color: black;}
span.malloc_ws {color: black;}
span.progtools_ws {color: black;}
span.searchord_ws {color: black;}
span.string_ws {color: black;}
So the conclusion is that if you wish to change the colors, you may do so either by editing the XSLT file, or by editing the resulting HTML file which will contain a copy.
|
Ed Beroset
Last modified: Sun Jul 6 15:12:04 EDT 2004 |
|