author:  Michael Sannella
file:  {Phylum}<LispUsers>IMTEDIT. (& .DCOM)
loads file:  {Phylum}<LispUsers>IMTRAN.DCOM

******  The IMTEDIT IM-to-TEDIT translation program.  *****

IM format is the text formatting language that the Interlisp Reference Manual is represented in.  It is somewhat like TEX source code, in that there are keywords, and brackets are used to delimit text.  However, IM format was specifically designed for representing the Interlisp Manual, so the "text objects" used are semantically meaningful objects within the manual, such as "function definition", "lisp code", "subsection".

IM format files are easy to edit (IM format only uses normal printing ascii characters, so IM files can be edited with Laurel, Bravo, Tedit, etc..), but they don't look very pretty.  To produce the manual, it was necessary to find a way to format and print IM files.  After much thought, I finally decided to create IMTRAN, a program that translates from IM format files to TEX souce files, and use TEX to actually format and print the manual.

<< for more information on IM format and IMTRAN, see {Phylum}<LispUsers>IMTRAN.txt >>

Recently, as more people have indicated interest in using IM format for their documentation, I realized that the normal way of producing IM format hardcopy (IM -> TEX -> PRESS) was too unwieldy.  It would be better if people could generate hardcopy entirely within Interlisp, even if the formatting quality was not as good as TEX output.  As it happened, at that time the formatting capabilities of Tedit were being extended, so that Tedit could handle most of the formatted needed for IM format.  Therefore, I created the program IMTEDIT, which translates IM format files to formatted Tedit text streams.  These text streams can be proofread and edited by the user, or automatically printed.

To translate an IM format file into a formatted Tedit text stream, use the following function:

(IM.TEDIT INFILE.NAME OUTFILE.FLG)

This function takes an IM format file, and produces a formatted Tedit text stream.  INFILE.NAME is the name of an IM format file.  OUTFILE.FLG determines what happens to the translated textstream.  If OUTFILE.FLG = T a Tedit window is created showing the translated document (the user is prompted for the region for the edit window).  If OUTFILE.FLG = NIL, the document is immediately sent to the printer.  If OUTFILE.FLG = anything else, it is taken as a file name for the press file which is created <but not printed>.

Important note:  It is necessary to understand that IM.TEDIT produces a totally seperate document from the IM format original.  Any edits to this document will NOT be reflected in the original.  In general, all of the editing should be done to the IM format files, to insure that there are no inconsistancies.


*****  Formatting problems in IMTEDIT  *****

Currently, IM.TEDIT produces a good-looking document.  However, there are some features that I was not able to provide, because Tedit did not provide the formatting capability.  These are as follows:

(1)  Footnotes.  Tedit does not supply footnotes.  Currently, I "fake" footnotes by positioning them in-line after the paragraph wherein they were created.  They also will not appear within definitions, tables, or lisp code.

(2)  Page numbers, cross-references, table of contents, index.  Currently, Tedit does not keep track of page numbers.  Therefore, I cannot supply any of the facilities that depend on them.  Eventually, Tedit will be extended, and it will be a simple task to provide these capabilities.

(3)  Tables.  Tedit doesn't do table formatting, so I fake it by "staggering" different items in the same row.  This should be good enough for now, since tables are not used too often.

(4)  Headers.  Not in Tedit.

(5)  Some of the special characters in IM format (like {pi}) are not accessable within Tedit.

(6)  Currently, I have not found a way to format the "definition types" (like "[Nlambda Function]") so they are right-aligned on the page.  Should be fixed eventually.


*****  Known Bugs  *****

When IM.TEDIT automatically creates a press file (when OUTFILE.FLG = NIL or <filename>), two small scratch files (PRESSELSTRM.PRESS and PRESSPDSTRM.PRESS) are left open.  This is a known problem with EMPRESS.  The main press file should be correct.  These scratch files can be closed and deleted.