REBOL for COBOL programmers

Module documentation idea

Date written: November 5, 2012
Date revised:
Date reviewed:

This is a little diversion into an idea for documenting mezzanine modules and using REBOL to format that documentation.

Note about downloading samples

This is a presentation of an idea for documenting modules. Sample documentation is provided along with script(s) for doing things with the documentation. Links are below. If you want to try the script(s) provided, and don't want to go into them to modify file names, you will have to do the following things. The first thing would be to install REBOL on your computer so that double-clicking a script file will run it. The second thing would be to download the files below into this structure:

your-choice-of-directory
    documentation
        BuildModuleList.r
    graphics
        rfcp-logo.png
    modules
        color-code.r
        glb.r
        htmlfile.r

What we are going to do

You probably have, as some point, come up with one or more schemes for easing the documentation chore, including the idea of keeping documentation in the code as comments, and then extracting the comments out of the code to produce documentation. That is the basis of this scheme.

Comments can be anywhere in REBOL code. If they are in the front before the REBOL header, they don't need any special comment character. The advantage of putting them at the front is that they are in a known location, namely, the front. The disadvantage is that they don't look so nice and that, if you use vim as an editor, the vim color coding for REBOL seems to break down.

The comment scheme in these samples is borrowed from Powershell. The comments are divided into areas based on a keyword header. The keyword headers are TITLE, SUMMARY, DOCUMENTATION, SCRIPT. Look in the samples and you can see the headers. A program will locate those header keywords and pull out the comments under the headers, and format it into html pages.

We are not going to talk our way through the documentation formatting and the coding to produce the html pages. We are just going to put it out there and let you examine it. This point in the sequence of pages that make up this site is too early a point to explain some of these items, but it is the appropriate time to explain how we are documenting our common modules. Have a look at it all and see what you can make of it, but don't worry if it is too obscure because it will be explained later.

REBOL features highlighted in this project

The BuildModuleList.r program uses a few fun features of REBOL that we will mention, with short explanations.

Emitting text

The program uses a common REBOL technique to build a text file. The key functions is "append" which adds something to the end of a big string. Eventually, that big string will be written to disk as a text file. You can append text, and the keyword "newline" will append a line feed. If you "repend" a block, then the block will be "reduced" which means that any REBOL items in it will be evaluated, and then the evaluated stuff will be appended to the output. You also can append a block that you "rejoin" which means that you reduce the block by evaluating the items in it, and then join them all together with no embedded spaces between items.

Building html markup

One extremely useful REBOL function is "build-markup." You can code a REBOL string, and within it, mark off areas with the less-than-percent and percent-greater-than tags. Look in the BuildModuleList.r file for examples. Within those tags, you put stuff that eventually will be replaced. This is similar to php. What is that stuff that will be replaced? It is REBOL code. In other words, you embed REBOL code in this text string, and the build-markup function will evaluate that REBOL code and put the results of that evaluation in place of the REBOL code. The code shows this fairly clearly. There are strings of html in the program. You will recognize it. Within that html are the above-mentioned tags, and REBOL words within those tags. Those REBOL words will be replaced by their values when that text is run through the build-markup function.

Parsing the documentation

Imagine what you might have to do if you had to examine a file of text, locate the various words (tokens) in the text, and take various actions based on the words you found. Depending on the level of your programming language, you might have to go as low as reading the text one character at a time, assembling it into words based on various items of "white space," putting the tokens into some data structure or maybe coding some monster "if" statement to account for all the words you might expect to encounter. That operation is called "parsing." One of the huge features of REBOL, and one of the hardest to understand, is that it has one source-level command to do all that stuff. One word. Parse. That is a huge amount of power.

This example uses a rather basic level of parse. It uses the key words TITLE, SUMMARY, DOCUMENTATION, and SCRIPT as delimiters and divides up the whole script based on them. It puts each section into its own word in memory, and then reassembles those chunks of the script into various documentation files.

Real REBOL versus "COBOL" REBOL

One of the scripts used to make this example is the color-code.r script harvested from the rebol.org web site. This script was written by Carl, and therefore can be assumed to be REBOL as he imagined it should be written. The other scripts are ones I wrote. The difference between master and novice should be obvious. But there's no shame in being a novice. I have come to embrace it.

Code samples

Left-clicking a link below will give a result that will depend on your computer, your browser, and maybe in whether or not you have REBOL installed. You should get either a new window with the code displayed, or a dialog box for saving the file on your own computer, or "opening" the file which makes no sense in this situation. Right-clicking should give you a menu from which you can save it to your own computer.

This is the global services module mentioned elswwhere.

This is a module used to emitting html code into a disk file.

This is a module borrowed from rebol.org and used to color an html page of REBOL code.

This is a program that will locate all the modules in a "modules" directory and produce html documentation from comments coded in the modules in front of the REBOL header.