This directory contains a package which documents an Rdb
 database in a format suitable for various PC and Macintosh word
 processing programs.

    I originally wrote a DCL command procedure which read the
 output of SQL and formatted it into a plain text file.  However,
 I discovered that it was fairly easy to write the information in
 RTF format instead.  RTF is the "Rich Text Format", developed by
 Microsoft, which can be read by many word processing programs on
 IBM PCs and clones, on the Macintosh, and probably other
 platforms. There is no license or royalty needed to write a
 document in RTF format.

    By writing in RTF format, the output of the procedure is a
 document which contains a header, page numbering, column headers,
 bolding and underlining, and so on: but the document is also
 revisable within the word processor.  It also makes it possible
 for us to include the database documentation within our existing
 application documentation (which is already in a Macintosh word
 processor) without having to do a lot of re-formatting of plain
 ASCII text each time the database changes.

    The procedure was originally entirely in DCL
 (RTF_TO_RDB_DCL.COM is the last version in this form), but when I
 added the cross reference of domain usage I found that SQL did
 not give the original domain reference for views.  I had in the
 past written some experimental programs (embedded SQL in C) which
 extracted information about a database directly from the database
 metadata. I adapted one of them to do the cross reference, and
 then moved some additional processing from DCL to the program. 
 It is now about 50-50 between the program and DCL.

                            WARNINGS

    The procedure is intended to work on our databases, where all
 fields (columns) in a relation (table) are based on domains
 (global fields).  I don't know what it will do if it hits a table
 containing original field definitions.

    The list of tables will write up to 90 tables in two columns
 on one page.  I don't know what will happen if the database has
 more than 90 columns.

    I originally wrote the new section information on the first
 page of each section manually.  I decided that it would look a
 lot nicer if the name of the database and some other information
 appeared in a header on each page.  I am still working on getting
 the header and footer (with the page numbers) to come out right;
 it works for some programs (WriteNow) and not for others
 (Microsoft Word).  There may also be some oddities in how many
 blank lines there are at the top of each page.  However, even
 with some hand touch-ups, it does nearly all of our documentation
 work automatically.  It's been a big step forward for our
 documentation.

 Bart Z. Lederman
 System Resources Corp.
 Burlington, MA