Last updated: 2008 June 27
SGML version
-
Javadoc for the FlexOr library --
FlexOr.container, FlexOr.searchAndSort, FlexOr.io (input & output)
and FlexOr.utilities in Java
- Program source text for the FlexOr library in Java
Instructions for using the SGML version.
The current version does the following.
- Weaves to Postscript.
- Tangle has a simple macro facility and handles adaptation.
- Extracts Z specification text for typechecking by the Fuzz type checker.
- Extracts text documentation for spelling and language checking in MSword or TextEdit.
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:
- A table of contents listing the section numbers of
selected sections;
- Typesetting of the program source text;
- A cross-reference of variables by section (single
letter variable names are not cross-referenced because
they are often used as local temporary indices and
counters);
- An alphabetic list of all the section names with
cross-reference information on the location of section
definition and use.;
- Section cross-reference information at the end of each
section containing program source text.
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:
- Produce a compilable program source text file
(implementation file)
- Expand macro definitions
- Apply adaptations
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.
- The definition of a variable name, so that variables
can be put into the cross-reference tables and
identified for macro expansion
- The list of keywords in the language, so that the
keywords can be typeset in a different font (making
the weave output more readable) and can be removed
from the variable cross-reference tables
- The definition of a comment, so that macro expansion
cannot occur within comments
- The definition of a quoted string, so that macro
expansion cannot occur within a quoted string and
string characters are not interpreted as FlexOr
commands.
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:
- Documentation and code are in one file, which
minimizes redundancy, simplifies maintenance,
and encourages the designer to write documentation,
which includes the section headings and section
references
- Code is introduced in a logical sequence: the order is
not compiler driven; it is driven by human factors,
such as the consideration of the best presentation and
development order
- Documentation is improved because it occurs as part of
the design and programming effort, not as something to
be done later
- Programming style is improved because the focus is on
the current task, stubs are created more easily,
programs can be developed incrementally, and use of
macros can make programs more readable.
Adaptation and frame processing provide the following advantages:
- Time and energy are saved in producing better
documentation and programs.
- Adaption encourages reuse of designs and program
source text through customization of existing
solutions instead of "reinventing the wheel".
- The designer has only to specify what is unique about
the application and does not have to design the entire
solution from scratch. A major source of errors is
eliminated.
- In the development of new frames, algorithms, software
maintenance and reuse of existing designs are improved
because designers know that they and others will be
using and adapting the program at the source level.