Enter your search terms Submit search form
	Web pdp-10.trailing-edge.com

-*-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:

	<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
		  Control-].
	<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-].

    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 <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:

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.:
	    <not-C-Q><C-L><CRLF>.

^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: