This document is a literate programming exposition of a Forth program designed to allow literate programming directly in Forth.
Literate programming is a technique, conceived of by Donald Knuth, in which the documentation of a program is emphasised in precedence over the code that implements it. Rather than being linearly presented, code is interspersed inside documentation. Prior to evaluation by the target language, a special pre-processor is used to "tangle" the source code into a machine readable form.
The Forth programming language has the relatively unique flexibility of a dynamically re-definable parser. This allows the possibility of applying literate programming techniques to Forth, without the need of external pre-processors.
eBook readers such as the Amazon Kindle are pleasant tools for reading documentation. Most literate programming tools such as WEB, CWEB, and noweb are designed to emit TEX and LATEX output, targeting printed output. While these tools produce high quality printed output, they produce eBooks which badly matched the limited feature set of eBook formats. Thus, the system presented emits documents in a format ready for processing by the kindlegen MOBI document processor. The Kindle's native format (MOBI) restricts documents to a minimalistic format that emphasizes user text preferences over document designer layout. While the Adobe PDF format is also supported, such documents are second class citizens which hi-lite the wisdom of MOBI's restrictions, particularly on eInk devices.
When useful, Forth style stack effect comments ( xyz -- abc ) will be used to describe stack effects.
The capital letter A will be used throughout indicate the "atomic string" type (described later). (e.g. ( A -- f ))
The dollar sign $ will be used to indicate an address count pair referencing a string. So ( -- $ ) will be used in place of ( -- a n ).
Other typical Forth stack effect abbreviations will be used.
When generating runnable code (weaving), literate.fs is emitted. This file should typically be renamed to literate_tangled.fs and included in other literate programs to active the syntax described herein.
It will contain a single file expansion of all the code described in this document.
literate.fs +≡*
This is the basic structure of the literate programming parser:
* +≡isolate in wordlist data structures and tools user facing tags primary program flow
A variety of user facing formatting tags are provided.
user facing tags +≡chapters chapter structure formatting tags bullet lists tex and latex shortcuts arrow symbols chunk tags
The data structures and tools needed to put this together are detailed.
data structures and tools +≡assertion support utility words implement atoms parsing chunks global fields output files document boundaries