xml-lit is Copyright © 2001 Rafael R. Sevilla
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Table of Contents
|
Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. | ||
| --Donald E. Knuth | ||
I recently found a simple program called xmltangle by Jonathan Bartlett [BART01] that provides a simple literate programming system based on DocBook. I have been somewhat frustrated by that program though; for one thing, it did not allow program code snippets to be enclosed within CDATA sections, which would make including a program inline a lot easier to do, and easier to read on screen while you're editing it, especially with programming languages that are chock full of <'s such as the typical C program, or worse yet, an XSL stylesheet, which I planned to use Jonathan's program for. So I set off to create a complete rewrite of the program, which uses James Clark's expat XML parser [CLAR01].
So now, I have come up with my own simple literate programming system, xml-lit which takes a similar approach, but instead of enclosing code snippets within within DocBook <programlisting/> tags, I define a new namespace xml-lit which contains all of the special elements which we use to support the system. The program is also backward-compatible with Jonathan's work given a command line switch.
I heard about the concept of literate programming long ago, but never really tried it because I felt at the time that it wouldn't really be very useful. Boy was I wrong. I recently got a hold of a copy of a small program called xmltangle and tried it. While it was a very nice program that worked okay, I had a number of small frustrations that gradually grew, which I have already mentioned before. But attempting to use it to mark up a small program I wrote for the office was a highly enlightening experience, and I understand now what Donald Knuth was saying when he said of the concept of literate programming: "In fact, my enthusiasm is so great that I must warn the reader to discount much of what I shall say as the ravings of a fanatic who thinks he has just seen a great light." [KNUT83] My brief work with xmltangle had convinced me that this is indeed a superior approach to the methodology of programming, because now, my job is not just to write instructions for a computer to do, but write those instructions in such a way as to make it possible for someone else to understand what I'm trying to do. Along the way the approach has forced me to think more carefully about everything I do when writing a program.
I of course contacted Jonathan Bartlett about his program, but since he didn't respond for a long time, I set out to make my own version of his program, just as an excercise. I was also going to do some work programming XML myself and felt this would be perfect as a vehicle for learning how to use the Expat library. At around the time I completed version 0.5, a nearly exact replica of Jonathan's program, I had also read Donald Knuth's original paper and a few other papers on the subject of literate programming, and thought of many ideas on how to improve xmltangle. I conceived of creating a new namespace, and then creating elements within the namespace that would support the literate programming concept. At around that time Jonathan Bartlett finally answered my email to him about his program, and I discussed this with him a little. He told me he had other ideas on how to add these other features (using XML processing instructions), so I then decided to strike out on my own. Now, here it is.