5.14.10. How do I debug Interscript

This is a very hard question. With some vexation, I have decided to make Interscript robust rather than fragile. (Generally, this is a bad idea).

First, the standard weaver is an object of the class multiplexor. That object is a proxy which dispatches method calls to every weaver in a list of delegates, but only if the delegate supports that method.

This means that the default behaviour of a method is to do nothing, which seems appropriate for weavers. For example the plain text weaver cannot do bolding, so rather than implement a 'pass' method, you just don't bother to implement the method at all.

When the Python engine detects an unexpected exception, usually coming from Python script in your document, but sometimes from I/O failures, and sometimes from bugs, Interscript attempts to put debugging information into the current document and continue. So, for example, if you try to include a file that doesn't exist, you'll get a message in the current document.

There are two excuses for doing this. The first is that it allows the rest of the process to continue, in particular, it prevents errors in documentation constructions holding up code development.

This feature was crucial in developing Interscript itself for the following interesting reason: when I added a new feature to a weaver I would have to use the existing version of Interscript to tangle the code containing the implementation of that feature. If I tried to use that feature in the documentation, it would always crash, because the feature wasn't implemented in the old version.

So, I would build the new version, then start using the new constructions. The problem was that there would be bugs in the implementation. If I just fixed the bugs, I'd be trying to tangle the code using the old bugged version, which would crash. On the other hand, if I used an older backup version of the program, it would also crash because there was _no_ implementation of the construction.

Developing a program generator which generates itself is an excellent way to test the program generator -- but there it is sometimes difficult to recover from faults!

So, I decided that documentation errors shouldn't stop the system generating code, as, in my case, the fixes would be in the code I was trying to generate!

Instead, error messages are printed in the documentation if possible. One excuse for this is that such messages are easy to find, and where they occur is a good indication of the fault. Separate logs are much harder to use, and if the process is to continue in the presence of a documentation fault, there's no harm from corrupting an already corrupt document.

One downside of this features comes if you don't read your documents: you may not notice an error. Another downside is that a corrupt weaver may not be able to print the error into the document, and it may not be there to read.

I'd be very interested hearing reports of how this facility trips people up: I'm sure it will, but not sure of the details. (Putting errors after a corrupt '</HTML>' tag, for example, means some browsers will never show the error!)

Most diagnostics are also written to a log file and standard output.

NOTE: the details described herein are currently not properly implemented!