| XML Literate Documentation |
This documentation provides all that is needed to use the XML Literate Programming System. Is not provided as any type of tutorial on literate programming. There are lot's of books and web sites for that.
Definitions of objects. These objects are woven by "weave" above. The actual definitions are XML files.
Most of the current programming systems allow you to use an IDE to generate all of the different parts of your code, and then you generate documentation, re-factor the code etc.
XMLLiterate works differently. In your project directory you have a folder called "literate" which contains all the files necessary to represent your program at a very high level. You are basically working directly on the "story" (or Web) of your program in XML.
When you want to study documentation of your work so far, you "Weave" your story into some type of documentation. We create DocBook XML files, and then from that we also generate HTML files. But you could get all the DocBook stuff and easily make PDF's etc.
When you have some type of design of your program, you can "Tangle" your story into actual program code, build files, data files or whatever
The story of your program is built using an XML file format that we call "schema" which is simply a bunch of definitions for code in XML format.
The current literate programming tools are perfect for structured languages in combination with LaTeX for documentation. Since then, object oriented languages have come to the fore, and many XML tools are available for generating documentation.
This system extends the idea of the WEB definition with a new idea called a "Schema" which allows a tree of object definitions to be described. There are a few emerging XML definitions for defining objects and methods, but instead of actually using one of these, we create our own. It's reasonably simple to use XSLT to convert between one format and another. There is an XSL script in xsl/schema2xsd.xsl which will convert our schemas to "XMLSchema" definitions for example.
Rather than using LateX, we use XSLT to create docbook files. This seems like the best use of resources since there are tools for generating docbook into HTML etc. There is a very simple docbook to HTML XSL script in xsl/docbook.xsl which understands the docbook that we create, but this could (and should) be replaced with the entire docbook set of tools at a later date.
Of course we still have an XML version of the WEB which contains the actual source code, and because we specify (and handle) namesapces correctly, you can embed docbook tags directly inside the documentation. This gives our webs the same type of functionality that the original WEB/LaTeX system had.
We could have used XSL to tangle the source code, but some things like looking up namespace names, including files, forward class definitions, overriding methods etc are really hard (take a look at how complex the XSLT for making docbook is...), so we have a new XML-based scripting language called TGL for defining the different types of files that make up a project. It is very general so it can be used for other things, but it has special objects for forwards, includes etc.
Get the current boost build. Often this comes with an OS install, so if it does, you just need to find
out where it is on your machine. On my machine it's in:
/usr/src/boost_1_33_1
Get cppxmlobj. You don't have to build it, but you can if you want.
# cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/cppxmlobj login
[Just hit return when asked for a password]
# cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/cppxmlobj co -P cppxmlobj
Now edit the file "boost-build.jam" inside the cppxmlobj folder just placed, and change the "[change to your boost path]"
to the place where boost was above.
On my machine cppxmlobj/boost-build.jam looks like:
BOOST_ROOT = /usr/src/boost_1_33_1 ;
PROJECT_ROOT = $(.boost-build-file:D) ;
boost-build /usr/src/boost_1_33_1/tools/build/v1 ;
Then get and build xmlliterate.
# cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/xmlliterate login
[Just hit return when asked for a password]
# cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/xmlliterate co -P cppliterate
Finally, build cppliterate.
# cd cppliterate
# bjam -sBUILD=release
I wouldn't recommend this, but it's what most people do. I just don't get a lot of time to update the downloads for the latest builds since it's a one person project, so it would be a lot better to just use CVS to get the very latest.
Get the current boost build from www.boost.org.
Often this comes with an OS install, so if it does, you just need to find
out where it is on your machine. On my machine it's in:
/usr/src/boost_1_33_1
Download and unzip cppxmlobj and xmlliterate from sourceforge.
Now edit the file "boost-build.jam" inside the cppxmlobj and cppliterate folder just placed, and
change the "[change to your boost path]" to the place where boost was above.
On my machine boost-build.jam's looks like:
BOOST_ROOT = /usr/src/boost_1_33_1 ;
PROJECT_ROOT = $(.boost-build-file:D) ;
boost-build /usr/src/boost_1_33_1/tools/build/v1 ;
Finally, build cppliterate.
# cd cppliterate
# bjam -sBUILD=release
When you have a good build, you can install the tangle program and the weave script as
"xtangle" and "xweave" by running simple scripts that make aliases in the
correct place on your system. You will be asked for your password, so type it.
# sbin/install_weave.sh
# sbin/install_tangle.sh
Although tangle is a real program that we provide (since we have our own scripting tool), weave actually uses XSLT so you won't find a "weave" program. Check sbin/weave.sh to see how we weave.
The last step is to setup the location of your root xmlliterate folder so that
you can place other projects in different folders. Edit "files.xml" in the root
and change "[change to your cppliterate path]" entry to the full path of your cppliterate folder. On my machine, the
entry looks like:
<xmlliterateroot>/usr/src/cppliterate<xmlliterateroot>
To generate all of the documentation, use
# xweave
The code is already pre-tangled for you and checked into CVS, but on another project you won't want to checkin
generated code. If you want to generate all of the code (you need tangle to exist for this to work!), just do the following:
# xtangle
When making changes to cppliterate, or any other project, always make sure you run all of the tests.
# bjam -sTOOLS=darwin test
Each folder inside a project which uses the system will have a "literate" folder inside with at least two files.
"schema.xml" contains a description of all of the objects and code for the project. This (and all of it's included files) make up the source for your program.
"tangle.xml" contains information that's used to build your project like names of things, where to put the source etc. We don't need a "weave" file because weave simply uses the schema above to do it's thing.
You can try tangling/weaving some of our own files to see what happens. To tangle a single object
you need to know which schema that object is in, and then issue the appropriate command for the tangle,
passing the object name in. For example if you made a change to "@block" inside the TGL code
"tgl", you can tangle it with
# xtangle tgl @block
# xweave tgl @block
The entire literate programming system is a actually written using literate programming. A sort of mirror in the mirror type of thing. So it serves as an example itself.
Currently there is only a single developer working on this system. Paul Hamilton (paul@phamtec.com). But the following credits need to be made to others who have gone before: