-*-Text-*-  Node: Top, Next: CommandAbstract, Up: (CONV)Top The IVORY library is a alternative to the PURIFY library for aiding the construction and maintenance of EMACS libraries. It was originally developed so that source library code could be executed without compressing, to aid debugging. This necessitated certain changes from PURIFY's syntactic conventions, especially regarding what whitespace can be compressed out. Since its inception, though, it has grown to include various features that aid in creating and editing library sources, e.g. facilities for automatically generating some library setup routines. This INFO node will briefly explain the differences from PURIFY regarding syntax and give an abstract of the various commands. Several of these commands are essentially the same as their counterparts in PURIFY; they are in IVORY too just to allow IVORY to be a substitute -- i.e. these commands are editing aids and unrelated to compressing and purifying libraries. The IVORY user should first familiarize himself with the general EMACS source library conventions described in the CONV INFO file. If you decide to use IVORY and want to receive messages about changes to IVORY, you should place yourself on the IVORY@MIT-MC mailing list. If you need assistance with this, send a message to BUG-IVORY@MIT-MC asking someone to put you on the IVORY mailing list. And BUG-IVORY@MIT-MC is also where you should send bug messages. A special hack has been implemented to allow PURIFY format libraries to be compressed in with IVORY libraries. For a library FOO, if variable PURIFY Library FOO exists and is non-zero, the library will be treated as a PURIFY library. IVORY knows about a number of common PURIFY libraries already -- see M-X Generate Library. Some syntax notes, differences from PURIFY: Only comments and surrounding whitespace are compressed out. PURIFY compresses out spaces and tabs; the user must force them by using underscores and quoting. However IVORY cannot do this, as that prevents uncompressed code from being executable. Thus IVORY will not be able to compress out many spaces; only those surrounding comments are clearly recognizable as compressable. Typically, these uncompressed spaces increase code size by 5% to 12%. Putting comments within string arguments is discouraged: it makes the uncompressed code have different (undoubtedly wrong) semantics from compressed code. A macro may have multiple names. These must precede the macro documentation string. They may be on separate lines if desired. FF-CRLFs (formfeed carriage-return linefeed) separate functions in the source file. PURIFY uses CRLF-FF-CRLF, but again that can force incorrect semantics for executed source code. (In particular, for strings which are M.M'd -- similar to documentation strings.) As with PURIFY, to force FF-CRLF into a function, quote the FF with Control-Q or Control-] Control-Q. E.g. ^]^Q^L^M^J. Blank macros are ok, e.g. for formatting/commenting source files. These macros must ONLY contain comments. No macro names, no code... We remove all comments and surrounding whitespace BEFORE checking the major syntax, and thus you may have comments, e.g. before a macro name. Unlike PURIFY, comments may contain :!, or : Space !, since comments are removed before looking for :!s, and spaces are not removed. However, having :!s in comments is discouraged -- : Space ! is recommended; this is so that simple commands may be written that understand a little about source file structure, in particular recognizing where names are. As with PURIFY, to force a ! into command documentation, use a Control-^ -- the compressor converts it to an !. Suggested style, for fewer chances of weird bugs executing source code: don't put apostrophes, double-quotes, or angle-brackets ('"<>) into comments, or else balance them. Teco will not recognize that these are in comments if it is scanning looking for them. To avoid worrying about them, leave them out of comments. E.g. avoid: !* If positive, don't do it.! since Teco might find that ' as the end of a conditional. Note though, that you may have to worry about a related problem -- even in compressed code: If you have a string argument with one of these characters in it, it is best to balance that character inside a teco-label outside that command. E.g.: qFoo Option"g :i*The Foo option doesn't yet work. It will soon. fsErr' will not work when the conditional is skipped -- Teco will think that the conditional ends with "doesn" and will thus start executing "t yet...". Correct code is: qFoo Option"g !"! :i*The Foo option doesn't yet work. It will soon. fsErr' IVORY will do some automatic & Setup ... Library function creating when you generate a library. Some of this is complicated, and the user is referred to the description of the commands. But basically: if you compress together several source libraries, and some of these have their own & Setup... functions, these functions will automatically be called by the main & Setup... function. Furthermore, this main & Setup... will contain M.C commands to create and default certain variables, called "declared variables". These are variables listed at the beginning of various functions, in a "call" to & Declare Load-Time Defaults, e.g.: !Foo:! !C Do something...! m(m.m& Declare Load-Time Defaults) Foo Option, * Controls the action of M-X Foo: 5 Foo State,: 0  ..... When the library containing this function is generated, the Foo function will NOT contain any call to & Declare Load-Time Defaults; that will have been removed, and instead, the & Setup... function will contain: 5M.CFoo Option* Controls the action of M-X Foo 0M.CFoo State However, a & Declare Load-Time Defaults function does exist, so that if this function's source is executed, the variables will be created if necessary. Note that the "call" to declare these variables must come before any code in the function -- this makes finding it easier and more reliable. (Comments may precede it, since they are removed before looking for it.) Note that the & Setup... will not contain redundant M.Cs. Also, the compressor will check each declaration it finds to ensure that all declarations of the same variable actually are the same declaration -- same value, same comment. Each variable declaration is of the form: "," ":" is any horizontal or vertical whitespace. is a string. Quote any ":"s with the 2-character sequence Control-] Control-Q. Quote any Altmodes or Control-]s with just a Control-]. may be either a number or string surrounded by delimiters. Quotes should be avoided as delimiters, so that the & Setup... code is safer; we suggest you quote with the "|" character as a rule. Quote Altmodes or Control-]s with a Control-]. Sample specification: Test Foo, * foo fah: 123 Test Oof, * fah foo: |hello there| Test Num, Random string variable: |123| Random Hook, 0 or a Teco program: sets random seed: | m(m.m& Random Hook) | Note that comments or string values may be more than one line long. The & Setup... routine will have some automatically generated documentation too: it will record information about the generation of this library: who generated, on what machine, the date, the exact source files. This information can be helpful to maintainers who FTP an ITS library to a Twenex, where they would like to have the version number of the library match the source version; after they FTP it over, they can then describe & Setup... and find out the proper version. A final note: loading IVORY defines an incorrect-looking subroutine, & File PURIFY Loaded, which is a signal to the M-X Teco Mode command that "PURIFY has been loaded". This means that if you have IVORY loaded, going into Teco mode will not then try to outsmart you by loading PURIFY. IVORY contains all the Teco-editing functions that Teco mode wants. IVORY's source is on MIT-MC in EAK;IVORY > and is maintained by Earl Killian , John Pershing , and Eugene Ciccarelli . If you want to receive mail about IVORY (e.g. announcements of new features or proposed changes), you should be on the mailing list IVORY at MIT-MC. Reports of bugs should be mailed to BUG-IVORY at MIT-MC.  Node: CommandAbstract, Previous: Top, Up: Top Commands in file IVORY: 1Generate C Make one :EJ file from just one source file. Takes one string argument which is the source filename. If no string argument is given, it defaults to the buffer filenames. Generate Library C Make one :EJ file from several source files. Takes desired name for :EJ file as first string argument, followed by the names of the input files. A null string argument (altmode-altmode) ends the argument list. The input files are all compressed and purified together. You are told as each is compressed etc. However, if $Silent Running$ is non-0 nothing is printed. (Good for ^Z ^Ping.) Filename defaulting is sticky; input FN2's default to >; the output FN2 to :EJ. The defaults are restored after the macro is finished. ~FILENAME~ is taken from first file's ~FILENAME~. It must have one. Other ~FILENAME~s are turned into "& Compressed foo Library:"s. All "hidden" & SetUps (i.e. not of same name as object ~FILENAME~) will be accumulated, and code to call them will be inserted at the beginning of the first file's &Setup. If that file has no &Setup, one will be created. Also, the &Setup documentation will have a record (as part of its documentation string) telling who generated the object, when, and from what source files. All "hidden" & Kills (i.e. not of same name as object ~FILENAME~) will be accumulated and called from the main &Kill in a similar manner. Note that all source libraries are always compressed, no COMPRS files are created, and the destination library is always created. For a given FN1, if variable PURIFY Library FN1 is non-zero, then the file is assumed to be a PURIFY library. No Key Test Load C Test Load with Test Load Sets Keys bound to 0. Thus Test Load will not offer to set any keys. Useful if running Test Load over an entire library with many ^R commands. Numeric arguments are passed along to Text Load. Key Test Load C Test Load with Test Load Sets Keys bound to 1. Thus Test Load will offer to set keys. Numeric arguments are passed along to Test Load. Test Load C Load any modified macros into MM-variables and ^R-keys. A library source is in the buffer. Compares each macro (compressed) with M.M-found version; if different, puts the new macro (uncompressed) in an MM-variable. If Test Load Sets Keys is non-0 (the default) and if the macro is an ^R one, user is asked which key to put it on. Rubout means do not put it on any key. (any better?) If a positive NUMARG is given, compressed macros are put into MM-variables when differences are found. Negative NUMARG means make uncompressed, without checking difference. If a pre-comma ARG is given, the library is searched for a & Setup... macro, which if found is macroed. Flush Test Functions C  mode on all (TEST) function names, then kill. This is for killing sets of impure test functions created by M-X Test Load. String argument, if non-null, prunes the list. The user is put into a recursive  mode on the list of all MM-variable names which contain "(TEST)" and the string argument if any. The user may then trim the list further. When the  is exited, those names that are left are killed. Compress File C Generate a PURIFY style COMPRS file from a source file. STRARG1 is the COMPRS file. STRARG2 is the source file. Filename defaulting is sticky left to right. (The second filename of the COMPRS file MUST be COMPRS.) This command is useful for creating COMPRS files so people using the standard EMACS purify package can GEN them into their libraries. One tricky thing: it always leaves ^Ls on their own lines, even if not there to begin with, since PURIFY will change CRLF ^L to ^L, and CRLF CRLF ^L to CRLF ^L. TecDoc C Look up information on Teco commands. String arg is command, e.g. MM TecdocF^B or MM TecdocFS HPOS. Represent a control character with a "^" not followed by a space. Spaces elsewhere are ignored. For speed (of another TecDoc) it keeps TECORD in an EMACS buffer, named *TECORD*. If you are worried about space, kill that buffer. Giving TecDoc a numeric argument will inhibit use of the buffer. The format of INFO;TECORD is understood. Type "?" for help. List TECO FS Flags C List names of all TECO FS flags. ^R Commands in file IVORY: ^R Ivory-Bound This Page ^R Even if already bounded. Thus calling this always results in the same thing, unlike the normal EMACS ^R Mark Page, which moves forward a page if already bounded. Uses IVORY-style definition of what a page is, i.e.: . ^R Forward TECO Conditional ^R Move past the ' matching the following ". This ignores "s or 's inside comments. ^R Backward TECO Conditional ^R Move back past the " matching the preceding '. This ignores "s or 's inside comments. ^R TQuote ^R Quote with ^] all altmodes and ^]'s in the region. This is to aid quoting inside a string argument to a Teco command.  Local Modes: Fill Column:65 End: