Last updated: 2008 June 27

SGML version

Instructions for using the SGML version.

The current version does the following.

C/C++ version

Reference to C/C++ version. It is unsupported since 1994. No further modifications are being made.

Introduction

FlexOr technology combines the programming and documentation ideas of the Web system developed by Donald Knuth with frame processing technology developed by Gunnar Gotshalks. The Web system was developed by Knuth to document his typesetting program TeX. His book, "TeX the Program", is the first published example of a large program. Frame processing technology enhances the writing of general purpose frames (frames are similar to templates) which can be adapted, at the programming language source text level, to many different environments.

A FlexOr frame is a sequential text file of ASCII characters with embedded FlexOr commands which is the union of two logical files.

The documentation file contains user, designer and programmer documentation, and program source text. The physical order of the text presents the information is in the order in which the designer wants the reader to view the information.

The program file contains the program source text that is to be compiled. The source text is not in the order the compiler requires, but in the order in which the designer expects the reader to best understand the program and way it works.

The documentation file

A FlexOr file is physically partitioned into sections just as there are chapters in a book or sections within a chapter. Each section can contain documentation text, program source text, or a mixture of both.

The sections can be physically in any order regardless of the order that the compiler requires. The semantics of the program contained within the FlexOr frame do not depend upon the physical order of the sections. The physical order selected by the designer is the best order, in the opinion of the designer, in which the information can be presented and understood by a reader.

The program file

Sections in a FlexOr frame that contain program source text represent nodes in a directed acyclic graph of the program contained in the FlexOr frame.

FlexOr frame processing

Since a FlexOr frame contains two logical files, two programs are needed that can extract each logical file. The two programs are called Weave, which produces typesetting commands for the FlexOr frame and Tangle, which restructures all the program text segments according to the designer's commands.

What the Weave program does

Weave produces, from the FlexOr frame, a file containing sufficient document markup commands to typeset the FlexOr frame. Each version of weave inserts commands for a different documentation markup language.

Weave programs produce the following for the user:

What the Tangle program does

Tangle collects all the program source text segments within each section and restructures them according to the designer's commands. The designer must embed the appropriate section references in the program source text, creating an acyclic graph, so that an in-order pass of the acyclic graph processes the program source text in the order required for the compiler. At least one section must be named "The Program Begins Here". Tangle begins processing the program source text from "The Program Begins Here".

Tangle programs do the following for the user:

Language dependencies

So that the maximum benefits from the FlexOr methods are achieved, some programming language dependencies are built into the weave and tangle programs. Programming language dependencies provide macro expansion and variable cross-references. While variable cross-references can be produced by other tools, their output would not reference sections in FlexOr frames, consequently reducing their effectiveness.

Programming language dependencies that should be built into the weave and tangle programs are the following.

Weave is highly dependent upon the typesetting language, because it must output typesetting commands. Output of appropriate commands can involve customized processing for each language, because characters or symbols may have to be encoded and typesetting commands can have complex syntactic structures depending upon the amount of text or context in which typesetting takes place.

Benefits of using FlexOr

FlexOr combines literate programming with adaptation and frame processing. Literate programming provides the following advantages: Adaptation and frame processing provide the following advantages: