There are no other files named ivory.info in the archive.
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
And BUG-IVORY@MIT-MC is also where you should send bug
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
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.:
: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:
!"! :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
5M.CFoo Option* Controls the action of M-X Foo
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:
<w> <variable name> "," <w> <comment> ":" <w> <value>
<w> is any horizontal or vertical whitespace.
<comment> is a string. Quote any ":"s with the
2-character sequence Control-] Control-Q.
Quote any Altmodes or Control-]s with just a
<value> 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-].
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 <EAK at MIT-MC>, John Pershing <JPershing at BBNA>, and
Eugene Ciccarelli <ECC at MIT-AI>.
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:
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.
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.
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
The user may then trim the list further.
When the is exited, those names that are left are killed.
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
(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.
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
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 Quote with ^] all altmodes and ^]'s in the region.
This is to aid quoting inside a string argument to a Teco command.