What is it?

The Teapot-7 Documentor is an Xtra for Macromedia Director, in the form of a protected Director file (a .dxr).

This program takes the pain out of complex Lingo projects by producing documentation in the form of a set of comprehensively linked WWW pages, suitable for local viewing on recent versions of either Netscape or Explorer. These pages contain the full text of the scripts with comments highlighted, and every use or declaration of a handler, a global variable, or a symbol made into a hypertext link leading to further information.

The aim of this program is to provide up to date and useful documentation automatically, generated straight from the original code, so program and documentation are never out of synch.

It provides a way of automatically highlighting the structure of a director program and provides a way of documenting the work you've done which doesn't need to be viewed inside Director itself. At the same time, when used in conjunction with Director it can serve as a valuable debugging tool and programmers assistant by providing access to the source of every handler, the uses of every global, and the structure and ancestry of every object.

The object browser shows the ancestry of every object, its handlers and properties, and the handlers and properties it inherits from its ancestors. In a neatly laid out table all occurrences of handlers and properties in this ancestor chain are arranged as hypertext links, making the structure of the object clear and the code instantly accessible.

Specially marked comments in the scripts (with a "--^" instead of "--") are incorporated into script, handler and object summaries, allowing selective extraction of higher level comments. This feature is inspired by Donald Knuth's concept of 'Literate Programming' in which the code and the documentation for a program are the same piece of writing. Special comments which appear inside handlers, or in the lines immediately before them are extracted and used as comments on those handlers in the documentation. Special comments appearing in the body of the script are treated as comments on the entire script or object.

Used sparingly, these meta-comments can be a powerful tool for delineating the structure of a program.

The "Problems" section of Documentor reports on any local variables which have the same name as other variables declared global elsewhere in the program. These are often variables that the author has forgotten to declare global, thus causing Director to automatically create a local variable, as well as a hard to find bug.

Scripts and handlers are also indexed both alphabetically and in order of occurrence, and global variables and symbols are listed in tables containing hypertext links to each of their occurrences in the scripts.

Within each script, all invocations of other handlers, and uses of globals and symbols are hyperlinked either to their source code, or to a table of hyperlinks to other places they are used.

Pages can be generated as either framed or unframed, according to your taste.

Click here to examine some sample output from Teapot-7 Documentor.

Evaluation versions of the program will only document the first fifteen scripts, and the first seven objects they find, though they will still list all scripts, handlers, globals, and symbols.

THIS PRODUCT IS NO LONGER FOR SALE. USE THE CODE TP7DOC-qXTm-SZFv-Cppp IF YOU WISH TO USE IT, BUT BE WARNED THAT IT IS NO LONGER SUPPORTED ON MODERN VERSIONS OF DIRECTOR.

For Director 5 and 6...
For PC, in zip format:	tp7dc102.zip (318k)
For Mac, in .sit.hqx format:	tp7doc1.02.sit.hqx (414k)
For Director 7...
For PC, in zip format:	tp7doc102b.zip (95k)
For Mac, in .sit.hqx format:	tp7doc102b.dxr.hqx (385k)
For Director 8...
For PC, in zip format:	tp7doc102c.zip (126k)
For Mac, in .sit format:	tp7doc102c.sit (111k)
For Director MX 2004...
Please note that release 1.03a has some only partially implemented functionality - you can now select colours for the HTML pages, but no note is (yet) taken of these selections.
For PC, in zip format:	tp7doc103a.zip (146k)
Note: The functionality of versions 1.02, 1.02b and 1.02c is exactly the same. They differ only in which versions of Director they work with. The same serial number will work with all versions, so you don't need to choose between them. To install the program, unzip or unstuff the downloaded file and place the contents in the Xtras folder contained in the same folder as your copy of Director, then restart Director. Teapot-7 Documentor can then be used by selecting it from Director's Xtras menu. Remember that if you've installed both 16 and 32 bit versions of Director on Windows, you have two Xtras folders - one for each version of Director. NOTE that this version of Teapot-7 Documentor requires you to have Macromedia's Fileio Xtra installed.

If you have any questions, bug reports, feature requests or comments, please write to documentor@teapot7.com