Motivation: I've begun writing an introduction to the Eiffel programming language. Being very constrained in how much time I can dedicate to this, I'm frustrated by the tedium of developing the text and the examples in parallel, and trying to keep the two in sync. It would be great if I could develop the code examples outside of the document and then integrate them into it seamlessly, or if I could develop the code in the document and then have the examples automatically become test programs, or even better, go both ways.
It should support the evolution of the code as I write the book, and the evolution of the examples as the code progresses through the book.
In some ways, this like literate programming, but goes deeper, since I want to iterate over the examples and refine them.
- Ease of use -- of course
- The ability to extract entire programs from the document and automatically compile and test them.
- Cohesion of code fragments. When a fragment is repeated in different sections, every place that fragment is referenced is properly updated. In other words, rather than the code itself, what's in the document is a reference to the code that gets expanded appropriate for display purposes?
- Appropriate styling of code. Reserved words should be one format, regular code another, comments italicized, etc.
- Wiki-like reference support. In addition to styling the text, I'd like the reserved words to become links to documentation that explains them, or explains the programming construct(s) that use them, or both.
- The Wiki-like references can go deeper. When the text makes a reference to a concept like "Boolean expression" then the text should automatically become a reference to the explanation or sidebar about boolean expressions.
In other words, I would like an editing tool that can read my mind, is extremely efficient for generating intertwined code and documents, that makes optimum use of the hypertext capabilities of electronic publishing, and can then coerce documents and code into a format that's completely acceptable for printing.
The tool (or suite of tools) should automatically verify the integrity of the document in parts and as a whole.
