-*-Text-*-  File: CONV Node: Top Up: (DIR) Next: Init Programming in TECO for EMACS * Menu: * Init Files: Init INIT files and what they can do. * Syntax: Syntax Syntax library source files to be compiled by the EMACS library compiler in the PURIFY library. Description of TECO mode, good for editing source code for libraries. * Libraries: Lib Other conventions for Libraries and sources. * Ivory: (Ivory)Top The IVORY library has an alternative compressor and purifier mechanism. * Programming: Prog Conventions for TECO programs to be operated in the EMACS enviromnment. * Buffers:: Data structures for EMACS buffers. * Windows:: Data structures for two window mode. * Complete:: How to read names with completion. * Variables: Vars Named variable (QFoo, etc) conventions. * Major Modes: Major How to define new major modes. * Submodes:: How to define submodes. * Prefix:: Prefix characters, such as C-X. * Hooks:: Variables which EMACS will call at specific times. * Novice:: Setting up restricted subsets for beginners. * Dump:: Dumping EMACS environments. * Build:: Building and dumping the standard EMACS environment. * Wall Charts:: Making wall charts. * Abstracts:: Making abstracts of libraries (for documentation) and source listings and source indexes of TECO code (good for studying the code). * Q-registers: Qregs Conventions for use of Q-registers. * FS ^R PREV: FS^RPREV Conventions for setting/examining FS ^R PREV. * Debugging: Debug Debugging aids in EMACS. * TDEBUG: (TDEBUG) TDEBUG is a package for stepping and breakpoints in TECO code.  File: CONV Node: Init, Up: Top, Previous: Top, Next: Syntax INIT Files. This is not a full description of how to write init files, because such a description has to include a full course on TECO programming. People who want to learn to program in TECO should follow this course of action: find a DEC TECO manual and read it (much of that will apply to this TECO as well, though many individual commands are different or missing in DEC TECO), look through the TECORD file, then read this file. After that, you can read some EMACS source code and init files using TECORD and this file as a reference. Each user can have his own file of TECO commands for EMACS to execute each time he starts it up. EMACS looks for the file ; EMACS and then for ;* EMACS, where stands for the user's home directory. If neither file exists, the file EMACS;* EMACS (the default init file) is used instead. On Twenex, the init file is called EMACS.INIT in your login directory, and the default init file is EMACS.INIT. You can cause an EMACS to read another user's init file by giving it that user's name as its XUNAME; just do ^S in DDT immediately before starting the EMACS. To avoid running your own init file, specify a name like FOO which has no init file. Setting up the default character definitions and named variables need not be done in an init file, since that is done before the EMACS environment is dumped out. As a result, your init file need only define those commands which you wish to change. Use MM Load Lib to load any additional libraries (or the :EJ command, for libraries which have no & Setup Library function). To obtain a function as a value so you can put it on a character, simply use M.M . The U command can define a character, as in for example U..^RX which puts its argument on Meta-X. The character is specified in the same manner as in an EVARS file; *Note EVARS: (EMACS)Init. Use M.V to create and assign a variable, or better yet M.C to give it some documentation as well. *Note Vars: Vars, for details of how to use M.V and M.C. When the init file is started, all q-registers not used by EMACS (and described herein) will probably be zero. One exception is Q1, which contains the version number of EMACS :EJ (on ITS, [PURE] >), as a string. The default init file types this out as the "EMACS version number". If you have no init file, EMACS runs the default init file, which is the init file on the EMACS directory. This does various things such as processing a command line from the superior, loading LISPT if necessary, printing the EMACS version number and offering help, ... Most people will find that they wish to perform the actions of the default init file after their own peculiar initializations. To do this, just end your own init file with ER EMACS;* EMACS @Y ET@ > :M(HFX*) (On Twenex, do EREMACS;EMACS INIT or EREMACS.INIT instead) This practice is recommended because some of the things in the default init file are important for the proper functioning of EMACS. The above sample of code calls the default init file with an empty buffer. If you call it with text in the buffer, that text is used instead of the job's command line arguments. To prevent the default init file from printing its help message, create the variable Inhibit Help Message and make it nonzero. If you have enough of your own functions to have a private library of them, you need not have both the library and an init file to load the library. You can just call your library EMACS and give it a ~Filename~ of INIT and a & Setup INIT Library function to perform the other initialization. The & Setup INIT Library function should end by jumping to the default init file, just like an ordinary init file made of text should.  File: CONV Node: Syntax, Up: Top, Previous: Init, Next: Lib Syntactic Conventions for EMACS Library Source Files The fundamental basis of EMACS is the library, which contains a set of functions written in TECO, together with their names and documentation. There is one standard library which contains the main body of EMACS, and there are other libraries that are loaded sometimes automatically or by request. For more information on how to use libraries, *Note Use: (EMACS)Libraries. This node describes how to write library source files, and the next node describes how to compile them. A source file of EMACS functions contains one function on each page. Each function has a name and documentation as well as its definition. These source files are processed by a compressor which deletes spaces and comments and performs other syntactic transformations before they are run. You can also ask to compress and install a single function, for testing, by pointing at it and using MM Compile. Every function definition should end with a CRLF, after which may come a ^L and the next function definition. Function definitions are separated only by CRLF ^L CRLF. A ^L in the middle of the line is just part of a function. If you want to put CRLF ^L CRLF inside a function, use CRLF ^]^Q^L CRLF. The Function Name Every function's definition begins with the function name, which is preceded by a ! and followed by :!. You must not ever put a :!, even with spaces in between, in a source file except to end a function name. The function name must be the first thing on a page except for a CRLF which must follow the previous formfeed on pages after the first. The name conventions are that subroutine names start with "& " and names of commands intended to be put on characters start with "^R ". This is to keep them from limiting the user's ability to abbreviate the names of commands he wishes to type. Another convention is that "#" begins the names of commands which form a dispatch table. For example, in INFO, the command M causes # INFO M to be run. If you define a command named # INFO +, that will automatically give you an INFO command called +. The Function Documentation After the function name comes a space, an !, and then the function class. Then, after another space, the rest of the line is the "brief" documentation which is used when only a single line is wanted. It should be a complete sentence. The function class should be the character C for a command which users should call by name, S for a command intended to be used as a subroutine, and ^R for a command intended to be placed on a character. The function class does not restrict how the function can actually be used; some of the documentation commands filter commands to be described by class. The function may have only the brief documentation. In this case, the brief documentation should be followed by an !. Otherwise, the lines following the brief documentation are the full documentation, which ends with the first !. The ! must be at the end of its line, and should not be an excuse to omit punctuation for the last sentence, since it will not be seen by the user. To put an ! in the text of the documentation, use control-^. If you wish to refer to one or two character commands in the documentation, you should not just put in the characters of the command, since that would make the documentation wrong for users who move their commands around. The thing to do instead is to put in the full name of the function which you are referring to, surrounded by  characters. When the documentation is printed out, this is replaced by the name of the character which is connected to the function, if there is one. If there isn't one, the function's name is used instead. For example, you could use ^R Exit to refer to the command to exit from a recursive edit, which in the standard environment can be invoked with either Control-Altmode or C-M-C, and when the documentation is printed it will say "Control-Altmode" or "Control-Meta-C". The  construct cannot be used in the brief documentation because only the command which prints the full documentation knows how to process it. For even more flexibility in the documentation of a function, if the string between the  characters starts with an Altmode, it is considered a TECO program to be executed, rather than a function name to be looked up. It does not undergo the same syntactic preprocessing that the function definitions do;; spaces are represented as spaces, not as underlines, etc. The TECO program can either print text out or insert it in the buffer (from which M-X Describe will print it out). When this TECO program is run, it receives the name of the function as a postcomma argument (a string pointer) or the numeric code for the character being described as a precomma argument, or both. A string containing the command character sequence being described can be passed as a precomma argument instead of a number. The Function Definition After the line ending with !, the next line contains the beginning of the function definition proper. Usually, a blank line is put there to improve readability. You must remember that the definition will not be used as written, but will be processed syntactically first: all spaces and tabs, except those following a ^Q, will be deleted. all _'s not following a ^Q will be turned into spaces. !* is taken to start a comment and everything from there up to and including the following ! is deleted (again, a ^Q will prevent this). Double CRLFs are converted to single ones. Normally, you should use ^]^Q to do such quoting, since that is safe in all contexts. Inside search commands and file commands a ^Q by itself is enough. TECO Mode The major mode TECO Mode is useful for editing EMACS source files. Comments are defined to start with !* and end with !. Tab is set to the command ^R Indent Nested, which normally moves the current line to be under the previous line. With an argument, it takes the argument to be the number of levels "up" to go, where up means a lesser amount of indentation. Thus, Tab with an argument of 2 or more is good for the first line after the end of a conditional or iteration. In addition, unindented lines and lines containing only comments are ignored. In addition, Meta-' is defined to move forward over a TECO conditional, and Meta-" to move back. These commands ignore quotes that are inside comments.  File: CONV Node: Lib, Up: Top, Previous: Syntax, Next: Prog Library File Conventions The command Generate Library, in the library PURIFY, is used to generate :EJ'able libraries from source files following the syntactic conventions. The operation has two logical subparts: compression, which removes spaces and comments, and extracts the documentation into separately named functions; and purification, which converts the intermediate form into a :EJ'able library. It is possible to divide the source for a large library into several subfiles, which will be compressed separately but purified together. This saves time if only some of the subfiles are modified, since the compressed versions are saved in separate files and reused if more recent than the sources. Generate Library handles such multi-file sources automatically if all the source files' names are given to it. One of the source files going into a library should define a "function" named ~Filename~. The "definition" of this function should be some kind of identification for the file. It should usually be the same as the first filename of the library. The documentation for ~Filename~ should describe the purpose of the library as a whole. It should NOT have a function class ("S", "C" or "^R") at the front. Generate Library automatically creates a ~Directory~ object which contains a list of all the functions in the file. A library should never contain two functions with the same name (~Filename~ is an exception: see below). Sometimes it is desirable to merge several library sources into one :EJ file. If you always like to use, say, TAGS :EJ, and have a private library, you may save space and increase speed by including the source of TAGS when generating your private library. This, however, means that you need to be able to override the ~Filename~ function which comes from the source of TAGS. Generate Library solves this problem by deleting all but the first ~Filename~. Your private source file must come first, and contain a ~Filename~, to override the one in the TAGS source. Libraries intended to be accessed via the Run Library command should contain a function named , which will be the default entry point, so that the user need not specify the entry point name. In addition, they MUST have a ~FILENAME~ which is identical to the actual first name of the file, so that Run Library can tell whether the library is already loaded. If a library contains a function named & Setup Library, where is the library's ~Filename~ name, then whenever the library is loaded with MM Load Library that function will be called. It can be used to connect some of the library's functions to characters, for example. If it is used for that purpose, then it should allow the user to override it by setting up a named variable. For example, the TAGS library has an & Setup TAGS Library function, which defines Meta-. as a command. However, if the variable TAGS Setup Hook is nonzero, & Setup TAGS Library executes that variable instead of its default actions. Thus, a user's init file can specify where the TAGS commands should go if TAGS is ever loaded, by defining TAGS Setup Hook. If you wish, you can put a function called & Kill Library in the library. If the library is killed with the Kill Libraries command, this function will be called. A string pointer to the library in core will be passed to it as an argument. The & Kill function might try to remove pointers into the library from important places where they were put by the & Setup Library function. It is probably not worth while looking for characters which have been connected to functions in the library, since this is painful and slow, and the worst that can happen is that those commands will cause errors when used. However, if pointers into the library were placed in important FS flags, it may be essential to remove them if TECO is to continue functioning properly. It is a good idea for an & Kill library function to execute the value of Kill Hook if it exists and is nonzero. In addition to the names of functions, there are several names that (usually or always) be found in libraries. For every function FOO, an object named ~DOC~ FOO is available, that contains FOO's documentation. In addition, ~DIRECTORY~ contains a list (one per line) of all the functions that the file wishes to advertise that it contains. Special things such as described in this section, and all commands with ~ in their names, are not included. ~INVERT~ is supposed to be a function that is the inverse of the loader function. That is, , fed to the ~INVERT~ function should return a string containing the name of the object. You should not have to be aware of ~INVERT~, because it will be provided automatically, and called by & Macro Name when necessary. The BARE library, which contains "definitions" for the sake of documentation of the built-in functions used to define some command characters, has a different loader function and so must be generated in a special way. The command MM BARE Library Generatesource-file-name will generate and write out the BARE library. The difference in the loader function is simply that if a function's definition is three characters long or fewer then it is treated as the name of a command character (as in .^RA for C-A) and that character's initial raw-TECO definition is returned instead. If the function's definition as found in the ordinary way is longer than three characters, it really is the definition. This way, documentation strings act normally but the command names themselves can return the raw TECO commands as their definitions. BARE has a ~INVERT~ function which knows how to find the names of raw TECO commands as well as strings in the library. However, & Macro Name has to know specially that such commands, which are positive numbers rather than strings, should be passed to the BARE library to invert.  File: CONV Node: Prog, Up: Top, Previous: Lib, Next: Buffers Programming Conventions For good programming practise, every CRLF that is not part of a string argument should be followed by an indentation to a position that indicates the current depth in iterations and conditionals. Use of the Tab command will make this easy. Since the FS S ERROR flag is normally set in EMACS, searches that are followed by ";" must always be given the ":" modifier; otherwise, they will cause errors when they fail, before noticing the ";". This is because, if FS S ERROR is not set, a user who types an iteration in the minibuffer and omits the ";" is likely to cause himself extreme lossage. The Tab TECO command is disabled in the EMACS environment, and is a no-op. Use 9I or I^]^Q to insert a tab. Calling Subroutines Use named subroutines whenever convenient. The subroutine should usually have documentation beginning with "S " so that users doing a "List Commands" will not see it, and a name beginning with "& " so that it will not interfere with the user's attempt to abbreviate command names. Call the subroutine with M( M.M&_Subroutine) (note the _ is used to get a space). MM&_Subroutine would work, but functions are not supposed to depend on having no-dot q-regs set up. Use M.A to run a function in a specific library, loading the library temporarily if necessary. For example: M(M.A DIRED& DIRED Enter) calls the function & DIRED Enter in the DIRED library. M.A is analogous to M.M. Both M.A and M.M accept a variable named MM Foo as a definition of the function named Foo, and this takes precedence over an actual definition of Foo in a loaded library. ^R Mode The normal EMACS command level is precisely the TECO ^R command, with characters redefined to run EMACS functions or user-supplied functions. All of the information in TECORD on the ^R command, facilities available for functions which are definitions of characters, and what values should be returned by such functions, are very important for anyone who writes functions which are to be placed on characters. The Mark The mark is kept in TECO's "Ring buffer of point". It's value can be obtained with :^V with no argument; :^V will push a new value of the mark. ^V with no colon can be used to pop the mark (read TECO ORDER for details). One consequence of this scheme is that there is always a mark somewhere. Note that the C-W EMACS command POPS the mark, rather than leaving a useless mark at point. Recursive Editing Levels A recursive editing level is implemented by the TECO command ^R. Commands that call ^R on data that the user is likely not to regard as "the thing he is editing" should do 0[..F before the ^R, to turn off auto-saving, and inhibit window, buffer or file switching (either of which would cause garbage results if allowed to proceed). See the & Check Top Level subroutine. They should also bind the default filenames to GAZONK .DEL, which will prevent the user from screwing himself with a C-X C-W. No non-dotted Q-regs should be reserved by functions, except for user interfaces like MM. Also, avoid using double-dot Q-regs except as defined in TECORD. All temporary Q-regs should be pushed and popped. All functions should return with ^\ if possible, except for those like M.A which need to leave something on the stack to be popped later. Numeric Arguments The TECO commands ^X and ^Y refer to the values of the precomma and postcomma arguments. (A function invoked with a character command gets only a postcomma argument). If there was no argument, the default value (zero or one, depending) is returned. To find out whether there was an argument, use F^XF^Y. F^XF^Y"N succeeds if there was an explicit argument (C-U or otherwise). This makes it convenient to use the function as a subroutine, since then one can give it any argument to mean "C-U", and no argument to mean "no C-U". F^XF^Y can also be used to check individually for precomma arguments or postcomma arguments. The Mode Line Anything that changes information which is displayed in the mode line should do 1FS MODE CHANGE so that FS MODE MACRO will eventually be run to update q-register ..J and thus the mode line. Printing in the Echo Area The @FT command can be used to print in the echo area. To clear the echo area, do :I*^PC FS ECHO DISP. The echo area is normally cleared after each command which uses it. If you want to print in the echo area and prevent the message from being erased after the command, you must set FS ECHO ACTIVE to zero after printing the message. Reading Input Commands that read input should do M.I before actually doing the FI to read a character of input. M.I is in charge of prompting. It also supplies a definition for FS HELP MAC that will handle the Help character if it is typed at that time. The user may redefine .I if he wishes to eliminate prompting, but even so he should still define all his functions to use M.I so that other users will receive the behavior they want. For more info on using M.I, do M-X Describe& Prepare for Input. M.I is useful for input read a character at a time. Other ways of reading input are & Read Line, which reads a line terminated by a Return, and & Minibuffer, which reads input allowing the user to edit it in the minibuffer. See the code of those two functions for calling conventions. The TECO command F^K allows a function to take a string argument if called with M-X, or read a line if invoked with a character command. Do 1,F^KFoo:_ to read the argument in whichever fashion is appropriate, prompting with "Foo: " if the argument is read from the terminal, and return a pointer to the string containing the value. This can be followed with a [1 command to store the string in q-register 1.  File: CONV Node: Buffers, Up: Top, Previous: Prog, Next: Windows EMACS Buffer Data Structures An EMACS buffer is not the same thing as a TECO buffer object. A TECO buffer an anonymous object which is a string stored in a special way, so that it can be edited by the TECO program. It contains text, the cursor location, and virtual boundaries, plus flags for modified and read-only, and that is all. Selection is controlled by the q-register ..O: whichever buffer object is put in ..O, that buffer is the one edited by all TECO commands. An EMACS buffer is a more complicated structure and a TECO buffer is just part of it. All information about EMACS buffers is stored in a qvector called the buffer table, which lives in q-register .B. This table contains a sequence of variable-length entries, each describing one buffer. The first word in each entry is its length in words; the next 12 have fixed meanings; the remained describe the EMACS buffer's local variables, 2 words per variable. The index in words of the start of a buffer's entry is called the buffer's index. The index of a buffer is needed to access the components of the buffer's entry; but it can't be expected to stay fixed while other buffers are selected, since a buffer earlier in the table might have to make its entry larger to create new local variables. Therefore, to remember one buffer for a while, you must always use its name, not its index. Killing a buffer that is not selected can change the current buffer's index! It knows how to change the value of QBuffer Index if this happens. An EMACS buffer has, among other things, a name, a TECO buffer, a major mode, and visited filenames. It also has a buffer number which identifies it uniquely from all other buffers ever created earlier or later in the same EMACS. This number is not the same as the buffer index. It is computed when the buffer is created (by incrementing QNext Buffer Number) and remembered while the buffer exists. A buffer also has some "TECO-default filenames". These are not the same in meaning to the visited filenames, though often they are equal. When the buffer is selected, these names are made the TECO filename defaults. When the buffer is deselected, the TECO filename defaults are remembered here for the next selection. Format of a Buffer Table Entry Each fixed word in the buffer table entry has a symbolic name. These names are just comments, so the numeric offset must be used as well, but the name helps clarify the code and makes it easier to identify places that need to be changed if the entry format is changed. For example, to refer to the name of a buffer whose buffer index is in Q1, you would write Q:.B(Q1+1!*Bufnam!) Word 0: the length of this entry, in words. Word 1!*bufnam!: the name of this buffer, a string. Word 2!*bufvis!: the filenames visited in the buffer, a string, or 0. Word 3!*bufmod!: the name of the major mode the buffer is in, a string, such as "LISP". This may not be accurate for the buffer which is selected. Word 4!*bufbuf!: the TECO buffer used to hold the text. Word 5!*buftdf!: the TECO-default filenames remembered for this buffer. They are 0 in a buffer that has never been selected. This is not accurate for the buffer which is selected. Word 6!*bufwin!: the FS WINDOW associated with the buffer. This is not accurate for the buffer which is selected. Word 7!*bufnum!: the buffer's buffer number. Word 8!*bufdat!: the creation date of last file visited or saved. This is used to give the warnings about files changed on disk since they were visited. Word 9!*bufver!: the version number of the last file read or written. Word 10!*bufsav!: controlls auto-save for this buffer. Zero if no auto saving. If 1, auto save as the visited file name. Otherwise it should be a string which contains the names to save as. Word 11!*bufsiz!: the size of the buffer at the time of the last visit or real save or auto save. Word 12!*bufnwr!: the read protection flag for the buffer. Positive means the buffer can be changed but the file cannot be saved unless you insist. Negative means the buffer cannot be changed. Word 13!*buflcl!: the beginning of the local variables of the buffer. Words 13,14: these describe one local variable of this buffer. Word 13 is the string which is the variable's name. Word 14 is the value. When the buffer is selected, this is the global value. When the buffer is not selected, this is the local value. The TECO command F^G is used for swapping the local and global values of variables. Words 15,16: the next local variable, etc. The Current Buffer The index of the current buffer is kept in QBuffer Index. All information about it could be obtained from that through the buffer table. However, the most important information is kept redundantly in variables to be convenient to access. The name of the buffer is kept in QBuffer Name, and the visited filenames are in QBuffer Filenames, which will be zero if no file is visited. The current major mode is in QMode, but looking at the name of the mode is usually the wrong way to do something. The TECO buffer of the current EMACS buffer can normally be found in ..O. Switching between EMACS buffers officially is slow. For specific temporary purposes, it is often enough to put an EMACS buffer's TECO buffer object into Q..O temporarily so that the text of the buffer can be manipulated. This is how Kill Some Buffers lets you examine a buffer that you might want to kill. Special Purpose Buffers Often an EMACS subsystem will need to store data permanently. Sometimes it is convenient to create a special EMACS buffer for this. For example, TAGS keeps the tag table in a buffer called *TAGS*. This allows the EMACS file visiting operations to be used as subroutines by Visit Tag Table. It also allows the tag table to be selected by the EMACS user when he wants to examine it. Since M-. needs to look at the tag table, for efficiency a redundant pointer to the TECO buffer object of the *TAGS* buffer is kept in a variable. This saves M-. from having to search for the *TAGS* buffer in the buffer table. The convention for such special purpose buffers is that their names start and end with stars. The Previous Buffer QPrevious Buffer contains the name of the buffer selected before the current one. C-X B will use this as the default buffer to select. Searching the Buffer Table To refer to a buffer given its name or its buffer number, it is necessary to search the buffer table, which contains the entries of the buffers in order of creation. The subroutine & Find Buffer does this. & Find File searches for a buffer visiting a given filename. In either case, the buffer index is returned.  File: CONV Node: Windows, Up: Top, Previous: Buffers, Next: Complete Data Structures for Two Window Mode TECO can only deal with a single display window. When EMACS is in two window mode, TECO is just displaying one buffer in a small window. Only one EMACS buffer is selected, as always. Various information about the buffer in the other window is remembered in a special set of variables. Some information is kept which overrides what is remembered in the buffer table, so that it is possible to select the same buffer in both windows with different values of point, for example. When in two window mode, each window has several variables describing its contents. Some of them are set up only when the window is not selected; some are always valid. For window one, these are: Window 1 Buffer the name of the EMACS buffer in window 1. Window 1 Window the FS WINDOW setting for window 1. Valid only when the window is not selected. Window 1 Point the value of point in window 1. Valid only when the window is not selected. Window 1 Size the height of the window, in lines. Window two has a similar set of variables. These variables stay around when two window mode is left, so that if it is used again things can be as they were before. To get information about either window 1 or window 2, deciding which one at run time, put either character (1 or 2) in a q-register such as Q1 and look at QWindow_1_Buffer, etc. In addition, there are these variables: Other Window Buffer the TECO buffer object of the EMACS buffer in the other window. Total Size the total size of the two windows plus the line between them. Default Size the setting of FS LINES in one window mode, saved here while in two window mode. To tell whether two window mode is in effect, see if QWindow 2 Size exists. If it does, two windows are being shown. This variable can be killed with no loss of information when reentering one window mode because its value can be deduced from QWindow 1 Size together with QTotal Size. When two window mode is in effect, to tell which window is selected, use FS TOPLINE. Window 1 is selected if it is zero. Redisplay of both windows when EMACS is continued is done by putting & Multi-Window Refresh in FS REFRESH. This uses the variable QOther Window Buffer to redisplay without having to do an EMACS buffer switch.  File: CONV Node: Complete, Up: Top, Previous: Windows, Next: Vars Completion Completion is the feature whereby, when a command name is being read in, Altmode and Space cause the appearance of characters determined by the ones already read. It is possible to provide completion when reading something other than a command name. Here is how. The basic way to read something with completion is to use the F command with the 8 bit set in its precomma argument. For example, 8,F Command:_ reads a command name with completion and returns it as a string. To read something other than a command name, you must supply a table of allowed strings. This table has the same form as the variable table (that which lives in Q..Q): it is a qvector whose first element is a number, the number of elements per entry, and whose following elements are any number of entries. The first element of each entry should be the string which is the name of the entry. For completion's sake, it does not matter how long the entries are, since only the name of each entry is used. The table can have one element per entry, if its only purpose is completion. It can have more than one element per entry if you wish. For example, the actual variable table itself, which has three elements per entry, can be used for completion of variable names. Specify the table to be used for completion by putting it in the variable CRL List before doing the F , and setting the 2 bit in the argument to the F . Thus, Q..Q[CRL_List 12.,F Variable_to_frobnicate:_ To allow the user to specify names which are not in the table, turn on the 20. bit in the precomma argument. If this bit is set, the user can type any string at all, followed by Return, and it will be accepted. Only if the user types Altmode will it be rejected. Normally, Return also rejects any string which is not in the table. If you like, you can use Linefeed to specify names not in the table, and make Return continue to insist on an existing name. To do this, set the variable CRL Non-match Method to 4. (The normal behavior is obtained with the value 2). The 40. bit in the precomma arg says that Return should be allowed as the first character typed. An empty string is returned as the specified name. You can additionally restrict completion to those names which start with a prefix, at the same time making the prefix invisible to the user (he does not have to type it, and does not see it echo). For example, suppose your library LOSER uses variables with names such as LOSER Object FOO to represent LOSER's definition of the object FOO. Then you can read the name of a LOSER object with completion by doing :I*LOSER_Object[CRL_Prefix Q..Q[CRL_List 12.,F LOSER_Object:_ Then only variables with names starting with LOSER Object will be considered. The user can type F and complete it to FOO; he does not see the "LOSER Object" as part of the string, and just "FOO" is returned. You should set the variable CRL Name Type to a string which describes what sort of name is being read. It is used as part of the message printed if the user asks for help while typing the name. The value of CRL Help is printed as additional help, after the standard completion help, if that variable is not zero. The hook CRL Name Lister allows you to customize the display done if the user types "?" to list the possible completions of what he has typed. It is called at two different times, with arguments to allow it to distinguish the reason it was called. For each possible completion, the CRL Name Lister is called once, with a postcomma arg which is an index into the table in CRL List. That table is also in Q.1 at the time. The function should insert information about that name into the buffer beginning at point, and include a CRLF at the end. The function CRL Name Lister is called again after all the possible completions have been processed. This time it will receive 1 as a precomma arg. The text previously inserted in the temporary buffer for all the alternatives is still there. The function might take the opportunity to sort the list of names, or insert a heading.  File: CONV Node: Vars, Up: Top, Previous: Complete, Next: Major Named Variable Conventions EMACS makes extensive use of named variables, and provides features for creating, destroying, editing, and listing them. The basic way of getting the value of a named variable that already exists is to do Q. See TECORD for details. If you are not sure whether a variable exists, you can do FO..Q  which will return the value if the variable exists, or if the variable does not exist. :FO can be used to tell whether a variable exists. Any TECO command that can use a q-register, except for ^], can also use an existing named variable if it is given the name of the variable, surrounded by Altmodes, as the q-reg name. Although TECO allows unambiguous abbreviations of the name to be used, it is unwise to use abbreviations in a program. To create a variable, do M.V. Unlike Q and FO, M.V deliberately does not handle abbreviations. It does discard leading and trailing spaces (in a library source file, spaces and tabs are deleted anyway, and to get a real space you must use "_"). If the variable already exists, nothing will happen, but its value will be returned. If it does not exist, it will be created with a value of 0, and 0 will be returned. M.V can also be used. This creates the variable if it doesn't exist, but also in any case sets its value to . The value returned by the M.V will be . To give a variable a comment, use M.C. This sets the variable's comment to , creating the variable first if necessary. M.C will set the variable to if it creates the variable. It will not change the value if the variable already exists. This is NOT the same as what M.V does! What M.C does is good for defaulting variables which are options, whereas what M.V does is good for setting a variable for internal use while making sure that it exists. M.C's value is the value of the variable. Sometimes it is more efficient for changing a variable's value to redefine some command characters, instead of having one definition which always checks the value of the variable. Do this by providing a function to be run whenever the variable's value is changed. This function is supplied by making it the variable's comment. Whenever the comment begins with a "!" it is taken to be a function to be run in this manner. The function is given the variable's new value as an argument. For example, the comment could be "!! FS^rmdly" to copy the variable's value into the FS ^R MDLY flag. This is (approximately) what is used for the variable Auto Save Interval. If you want a variable to be presented for editing by MM Edit Options, you should give the variable a comment which starts with a "*". If the variable is to have a function to run when it changes, and so the comment must start with a "!", then the variable is an option if the comment starts with "!*". NOTE: if you are not careful, the TECO code to set up such a variable will contain "!*" which will be taken as the beginning of a comment. Leaving a space (which will be removed by compression) between the "!" and the "*" will prevent such lossage. See where the file EINIT sets up such variables if this isn't clear. You can examine the value, and comment if any, of a variable by doing MM Describe, just as you would ask for the documentation of a function. Overriding Command Definitions You can override the library definition of a function by defining a variable named "MM " followed by the function name. M.M checks for such a variable before looking the name up in the loaded libraries. MM Compile installs the compiled function in just this way. A few such MM variables are present in the default environment. This is to make calling certain key subroutines more efficient; M.M takes less time finding the variable than searching the libraries. Listing and Killing Variables To see a list of all existing variables, do MM List Variables with a null string argument. Each variable's name and value (abbreviated if too long) will be shown. A list of variables whose names contain can be seen by doing MM List Variables. To destroy a variable, do M(M.M Kill Variable) to run MM Kill Variable. This is necessary only in special situations. Local Variables Variables can be local to an individual buffer. To make a variable local to the current buffer, do M.L. From then on, setting the variable when the current buffer is selected will not affect its global value, which other buffers will continue to see, nor will changing that global value affect the local value. Each buffer in which the variable is made local has its own value for the variable, while all other buffers share one global value. Doing M.L has the side-effect of creating the variable globally with the value of 0 if it did not already exist globally. Local variables will be created automatically when a file is visited which contains a local modes specification at the end. They are also the way in which major modes perform their redefinitions. Not only variables, but q-registers as well, and command character definitions, can be made local. To make a q-register local, use the Make Local Q-register command, with the q-register name as a string argument: M(M.M Make Local Q-reg)A makes QA local, and M(M.M Make Local Q-reg).^RF makes the definition of Control-F local. You can also make a TECO FS flag local by specifying "FS" followed by the name of the flag as the "q-register" name. For example, M(M.M Make Local Q-register)FSCTLMTA. Inside Major Mode functions, this function is available as M.Q. Temporary and Permanent Locals There are two types of local variables: permanent ones and temporary ones. The permanent ones have to be the first on the list; they remain forever local in the buffer that has them. All others are temporary; these disappear when you switch major modes. The locals created by major modes are temporary, which is how one major mode gets undone when a new one is selected. Other locals created by local mode lists and by random use of M.L are also temporary. The initial buffer is given a set of permanent local variables when the EMACS environment is built. The way permanent locals are told from temporary ones is that the number of permanent ones is kept in the variable QInitial Local Count, and the first that many locals are permanent. When a new buffer is created, some or all of the locals of the previously selected buffer are copied into it. If Default Major Mode is empty, they are all copied (thus, the major mode is copied). If Default Major Mode specifies a mode, then only the permanent locals are copied into the new buffer. The value of Initial Local Count is used to tell how many there are. Some of these locals are reinitialized, however; and you can reinitialize others in the Buffer Creation Hook. To add a new permanent local to a buffer, use 2,M.L. This adds a local at the front of the list instead of at the end, and increments the value of Initial Local Count (which requires making IT into a permanent local as well, if it isn't one already, but that happens automatically). To increase the set of permanent local variables of all buffers, you can simply create a few locals in your init file with M.L and then increase QInitial Local Count. This will give the initial buffer extra locals, and all other buffers will get them through the copying. To do this for all users at your site, you can modify & Load Essential Environment at the end where it creates the standard set, to create a few extra. You can also cause each buffer to get extra permanent locals when it is created, in the Buffer Creation Hook, by using 2,M.L inside it.  File: CONV Node: Major, Up: Top, Previous: Vars, Next: Submodes Defining Major Modes. Each major mode is embodied by a command, such as MM TECO Mode or MM Lisp Mode. A major mode can be created simply by defining an appropriate command. However, major mode commands must work in a particular way. Major modes make all their redefinitions by creating local variables. This is how each buffer can have its own major mode. Buffer switching does not consciously "switch" modes; it just swaps the local variables, which has that effect. The first thing which each major mode command must do is eliminate the local variables, if any, made by the previous major mode. This is done by calling M(M.M &_Init_Buffer_Locals). All local variables of the current buffer, except those made when the buffer was created, are killed, and the global values reassert themselves. In addition, & Init Buffer Locals leaves Q.Q bound to the Make Local Q-register command until the major mode command returns with . Then, the major mode function should create any local variables and local q-registers that it wants. Supplying a 1, argument to M.L causes M.L to run much faster, assuming that the specified variable is not already local. Example: 1,(:I*;) M.L Comment_Start. This is recommended for cuatious use by major mode commands. Command characters can be redefined by using M.Q, since character definitions count as q-registers. Example: M.M ^R_Indent_for_Lisp M.Q ^^I makes the Tab character local to the current buffer, and redefines it for Lisp. The "1," argument can be used with M.Q also. Many major modes have their own values of the delimiter dispatch table Q..D. They construct these values by making Q..D a local q-register, copying the value of Q..D that is lying around with :I..D..D, and then changing the necessary entries with the command MM & Alter ..D. This is so that any other changes to ..D made by the user will not be discarded. A new ..D should be constructed only the first time a mode is entered. It should be saved in a variable such as Text ..D or Lisp ..D, and retrieved from there when the mode is entered again. This way, if the user changes ..D with the command Edit ..D, his changes remain in effect whenever he is in that mode. He can also define the variable in advance in his initfile if he knows that, whenever he is in a certain mode, he wants his ..D to be just so. Finally, the major mode function should do 1M(M.M &_Set_Mode_Line  ^\ & Set Mode Line makes the new mode appear in the mode line, and the 1 as argument tells it to do everything else appropriate for finishing up the change of major mode: Setting the variable QMode, running the value of Mode Hook if it is defined. Exiting with ^\ causes the binding of Q.Q, left by & Init Buffer Locals, to be popped, as well as any other bindings made by the major mode function.  File: CONV Node: Submodes, Up: Top, Previous: Major, Next: Prefix Submodes and ..F A submode is just a command which rebinds commands or variables and then calls ^R recursively on the same buffer. A submode's name usually starts with the word "Edit", as in "Edit Picture". Submodes are to be distinguished from commands such as Edit ..D which call ^R recursively on some other text. For submodes to indicate that they are active, the variable Submode is provided. Binding QSubmode to FOO causes [FOO] to appear in the mode line after the name of the major mode. However, you must call & Set Mode Line yourself before entering ^R, and you must do an FN command to cause & Set Mode Line to be called on the way out (even if you come out via a throw or an MM Top Level). Usually, the Edit FOO submode will put FOO in the Submode variable. Submodes need not bind ..F to zero. Because the buffer is not bound, it works reasonably well to switch files, buffers or windows inside a submode. However, you stay inside the submode when you switch, which you may not like. Someday there may be a different implementation of Submodes which makes them local to a buffer. In fact, submodes are not fully worked out at this time.  File: CONV Node: Prefix, Up: Top, Previous: Submodes, Next: Hooks Defining Prefix Characters. An EMACS environment can contain any number of prefix characters, although EMACS normally contains only one - C-X. To define a prefix character, you must choose a place to put the dispatch table for it. This can be a q-register or a variable. Call MM Make Prefix Character which returns a string which is a definition of a prefix character which will look in the specified q-register for the dispatch table. Then put this string into the desired character's definition. Normally, dispatch tables are made 96 characters long. If you want Rubout to be available as a subcommand, you must make it 128 characters long, which you can do by providing 128 as an argument to Make Prefix Character. For example, a prefix character C-Y can be defined to dispatch through q-register .Y by doing M(M.M Make Prefix Character).Y U.Y After this, you can define individual subcommands by doing things like M.MFOO U:.Y(A) which puts MM FOO on C-Y A. To use a variable to hold the dispatch table, first create the variable using M.V. Then create the prefix chararacter definition by calling MM Make Prefix Character, supplying the variable name surrounded by quoted altmodes in place of a q-register name. For example, M.V My Prefix Table M(M.M Make Prefix Character)My Prefix Table U.Y The altmodes are quoted by  characters so that they become part of the argument to Make Prefix Character. How Prefix Characters Dispatch. All prefix characters made by Make Prefix Character, including the initially present C-X, do their work by calling the contents of q-register .P, providing the dispatch table as an argument. .P reads the input character, extracts the definition of the subcommand, and returns it. The prefix character itself then calls whatever .value P returns. You are free to redefine .P to get different behavior, as long as you respect the interface conventions. Take a look at the source code for & Prefix Character Driver, which is the default contents of .P. Making Self-documentation Work for Prefix Characters. In order for Where Is and Apropos to list all the ways a command can be reached as a subcommand of a prefix character, all prefix characters must be listed in QPrefix Char List. The value of this variable is a string containing one line for each prefix character. first on the line comes the way this prefix character should be named when a command character is printed out (for example, "Control-X"). This is followed by two spaces (two, so that single spaces can be part of the string to be printed) and a TECO expression which evaluates to the dispatch table. For the default EMACS Control-X command, the value of the string is "Control-X Q.X".  File: CONV Node: Hooks, Up: Top, Previous: Prefix, Next: Novice Hooks Provided by EMACS EMACS offers several hooks in the form of variables whose values will be executed, if nonzero, at specific times. Buffer Creation Hook This variable is executed when a new EMACS buffer is made by Select Buffer, just after that buffer has been selected. If you wish to use this to create local variables, you should see under "Temporary and Permanent Locals" in *Note Locals: Vars. The Buffer Creation Hook is not run when a buffer is created by Append to Buffer. This is obviously wrong, but since the buffer thus created is never actually selected, there is no easy way to fix this. However, if the buffer is eventually selected, the Buffer Creation Hook will be run then. Buffer Selection Hook This variable is executed whenever a buffer has just been selected. It is most likely to be useful when made local to a particular buffer. Buffer Deselection Hook This variable is executed whenever a buffer is just about to be deselected. It is most likely to be useful when made local to a particular buffer. Visit File Hook This variable is executed whenever a file has been visited. All the normal actions of visiting are already complete. It is also called when the name of the visited file is changed by the commands Write File and Set Visited Filename. In that case (change of name but the text is not newly read in) an argument of 1 will be passed to the function in Visit File Hook. In the case of actual visiting, the argument will be zero. Exit Hook This variable is executed by the function & Exit EMACS, which is called when EMACS is about to be exited other than momentarily. This is in addition to auto saving and possibly a real save. A useful thing to put in this hook might be MM Save All Files, if you want that. Exit to Superior Hook This variable is executed by ^R Return to Superior after it calls & Exit EMACS, but before it actually returns to the superior. Return from Superior Hook This variable is executed by ^R Return to Superior after EMACS is continued by the superior. Exit to Inferior Hook This variable is executed by various Twenex-only commands that invoke inferior forks, before they do so. Return from Inferior Hook This variable is executed by various Twenex-only commands that invoke inferior forks, on return from the inferior fork. These commands all run Exit to Inferior Hook before invoking the inferior. Not all commands which invoke inferior forks run the two hooks. If the fork is expected to return almost immediately, then the hooks are not used. If the fork is expected to run indefinitely then the hooks are executed. Compile Command This variable is executed to perform the compilation of the visited file. It can find the filename in q-register 1, and it MUST exit with . After Compilation Hook This variable is executed by M-X Compile after the compiler returns to EMACS. The Return from Superior Hook or Return from Inferior Hook is NOT executed. This hook only applies if Compile Command has not been specified. Set Mode Line Hook This variable is executed by & Set Mode Line. When it is called, the buffer contains the first part mode line as it is going to appear, everything up to just before the closeparen. The Set Mode Line Hook can insert text in the buffer to get it into the mode line at that point. The purpose of this variable is to allow libraries which have state variables to display them in the mode line. So that several libraries can do this without interfering with each other, each library should append its own hook to the variable Set Mode Line Hook instead of setting it. When Set Mode Line Hook is called, the currently selected TECO buffer (which normally belongs to the selected EMACS buffer) can be found in Q8. Setup Hook Each library's & Setup Library function should check for the existence of a Setup Hook variable, using 0FO..Q. If the variable exists and is nonzero, the setup function should execute the variable INSTEAD of its normal actions. Mode Hook Each major mode executes a mode hook variable after making its normal redefinitions, but before updating the mode line. Mode hooks can create additional local variables or local q-registers (including local character command redefinitions). Hooks on Variables Each variable can have a hook to be executed when it is set. The hook is stored in the variable's comment: if the comment starts with an exclamation mark, then it is executed when the variable changes, and the new value is supplied as an argument. The hook does not need to change the actual value of the variable; that is done automatically after the hook is finished. Unfortunately there is no way for the hook to change the value of the variable. Sometimes you want the hook for each of two variables to change the other. To avoid an infinite recursion in hooks, bind F[VARMAC to zero in each hook before setting the other variable. If you want the variable to be an option also, the exclamation mark can be followed with a star, followed by the real comment.  File: CONV Node: Novice, Up: Top, Previous: Hooks, Next: Dump Creating Restricted EMACS Subsets for Beginners. When dealing with large communities of beginning users, it is sometimes desirable to give them limited subsets of EMACS, in which commands that they are unlikely to want to use and might be confusing to them are not allowed. This could be done simply with an init file that redefined those commands to be undefined; however, this would prevent the beginners from learning to use those commands. The NOVICE library solves this problem by allowing the user to read about, experiment and eventually re-enable the commands that were initially disabled for him. To set up a limited EMACS subset with NOVICE, the biggest piece of work is to decide which commands you want to allow. Then you must create the user's command profile, a file which says which commands are enabled for him. This file contains 512 characters, one for each EMACS command character, and each character of the file should be an "E" to enable the EMACS command or a "D" to disable it. The file should be named ; EPRFIL on ITS, or EMACS.PROFILE on Twenex. Finally, you must make the user's init file load and invoke the NOVICE library. This can be done with M(M.M Load Library)NOVICE M(M.M & Load Disable Profile) Alternatively, the default init file at your site could do the work: FS :EJPAGE[1 !* Remember what libraries we have.! M(M.M Load Library)NOVICE !* Load this library.! M(M.M & Load Disable Profile)"E !* try to process profile.! Q1FS:EJ PAGE' !* If there is none, flush NOVICE.! ]1 !* restore q-reg 1.! This discards the NOVICE library if it says that it does not find a profile file for this user. One way to create a profile file is to edit it with NOVICE. Load NOVICE and then use the command Disable Commands to turn off some commands. This creates or modifies a profile file for you automatically. To turn commands back on, try using them and answer the questions appropriately. This also edits your profile. When you are done, give a copy of that profile to the user you made it for. You will probably want to delete the original!  File: CONV Node: Dump, Up: Top, Previous: Novice, Next: Build Dumping an EMACS Environment. Dumping an EMACS environment so that it can be loaded and run again is no simple feat. Since the environment, when dumped (with @EJ), contains absolute pointers into the main EMACS library, we must make sure that when the environment is run again the same version of that library will be at the same place in the address space. This is accomplished by the Dump Environment command in the PURIFY library. The Dump Environment command in the PURIFY library has the ability to dump out an EMACS environment so that, when loaded, it will reload the same libraries that were loaded at dumping time - the same versions, even, if multiple versions of the libraries are maintained. Before calling Dump Environment, you must decide which of the loaded libraries are to be reloaded by the dump file. Given such a library, called (say) "Mumble", you must set up a variable QMumble Library Filename containing the filename to be used to reload that library. This filename can contain a version number, if you are interested in loading the same version as the dumped environment was made with (this is necessary if any pointers to functions in that library exist in q-registers or character definitions, etc.). Only libraries for which such variables are created will be reloaded by the dumped environment. Not all loaded libraries must be included, but any which are not included must all have been loaded after the ones which are included. In addition, before calling Dump Environment you must specify the TECO commands to be executed when the dump file is reloaded. This is done by creating a variable named QMM & Startup Mumble, where Mumble stands for the contents of QEditor Name. For EMACS, it is called QMM & Startup EMACS. The QMM & Startup Mumble variable is killed by Dump Environment, since it will be no use afterward. Actually, if you wish, you can have a command named just & Startup Mumble in one of the libraries to be reloaded by the dump file, instead. The contents of q-register ..L when Dump Environment is called are NOT used to initialize the dump file when it is reloaded. However, they do persist in ..L when the reloaded dumped environment is running, and if that job is stopped and restarted again, the ..L will be used. EMACS actually happens to make MM & Startup EMACS the same as ..L, despite all the emphasis above on allowing them to be different. ..L and & Startup EMACS both point to the function & Toplevel ^R, which simply enters the TECO real-time editing mode. The user's init file is executed after entering real-time editing. When the outermost level of ^R mode is entered, the hook variable *Initialization* is executed if it is nonzero, and also set to zero. Thus, it is only done the first time the top level ^R is entered. When EMACS is dumped, *Initialization* contains the TECO code to find, read and execute the user's init file. The code to implement this is in the TECO init file for EMACS, and in & Recursive ^R Set Mode. If your EMACS init file takes a long time to run, you can use Dump Environment yourself after running the init file. The QEMACS Library Filename variable remains set up, so you need not worry about getting the right version of it. You must create similar variables for any other libraries you want loaded when the dump is restarted (Load Library can make them for you automatically). Just provide a suitable variable MM & Startup EMACS (or make that variable a copy of Q..L and supply *Initialization*), and call Dump Environment. If you do this, it is best not to call the default init file from your own init file, but instead call it from the & Startup or the *Initialization* variable. This way, various actions will be performed when the dump is started, based on the terminal type, user name and command string that you have at that time, rather than being done when you build the dump, based on the terminal type, user name and command line at the time the dump was built.  File: CONV Node: Build, Up: Top, Previous: Dump, Next: Wall Charts How to Build and Dump a New EMACS Before building a new dumped EMACS, you may wish to Generate up-to-date versions of the essential libraries. This can be done by M-X RunEINIT? Generate However, there is no need to do this if the new versions of functions to be changed are present in the patch files (see below). The visible procedure for building a new EMACS is simply to do EMACS :NTECO which runs NTECO using EMACS's TECO init file. On Twenex, simply run TECO while connected to . This leaves you in the TECO top-level loop, typing TECO command strings, and should display an EMACS-style mode line. Then, to dump the EMACS, type MMRunPURIFYDump which will dump the environment you have built. Then kill the job. How Building and Dumping Work Building a new EMACS environment has three phases: loading libraries, creating the "essential environment" necessary for EMACS functions to work at all, and making the default set of command bindings. Two other minor operations are the loading of the patch file, and the purification of variable names. The first phase is straightforward: it simply loads the latest version of EMACS :EJ, and also the EINIT library which contains the code for performing the rest of the initialization. Loading the essential environment is done by the & Load Essential Environment command in EINIT. This sets up things like q-registers .M, .L, .V, .A, etc. as well as the option variables which many commands assume the existence of. Part of loading the essential environment is loading the patch file EMACS;PATnnn >, which contains corrected versions of functions changed since EMACS :EJ was generated. nnn stands for the version number of EMACS; thus, different versions can coexist with different patch files. The format of PATnnn is just that of a library source file, with a function on each page. It is read in and MM TCompile is done on each page of it. Thus, the function definitions in the patch file exist as impure strings which override the definitions in the library. Another file named EMACS;PATCH > is also loaded. This file is intended to have site specific changes, which are not generally expected to become obsolete in the next version, wheras PATnnn's fixes will all be incorporated therein. Loading the default EMACS environment is done by & Load Default Environment in EINIT. This is what defines C-N to run ^R Down Real. The reason why it and & Load Essential Environment are not combined is so that other command environments which use the EMACS execution environment can be easily built. Building such an environment would involve calling & Load Essential Environment, and then using something else instead of & Load Default Environment. Also, loading the patch files requires using the essential environment, and must precede loading the default environment so that the command character definitions use the patched versions of functions instead of the original versions. At the end of building the environment, the variable names are purified. In order to save a few hundred words of impure core for all users, the predefined variables' names and their comments are made to live inside EMACS :EJ instead of in impure string space. The necessary strings are created in the library by the special file VARS, which is included in the generation of the library. It inserts the strings into the EMACS :EJ file inside of another string, so that they are conveniently out of the way. Then, the Purify Variables command in EINIT is used to look at each variable and replace its impure name with the corresponding pure string, if there is one. How Stand-alone RMAIL and INFO are Built and Dumped. Stand-alone INFO differs from an EMACS in that, on start-up, instead of running the user's or the default init file, a particular procedure (that of entering ^R-mode and then running MM INFO) is followed. INFO is built by an EMACS init file which calls Dump Environment, setting Editor Name to INFO and providing an appropriate MM & Startup INFO function to be used to start up the dump file when it is reloaded. On the practical level, the EMACS init file for INFO actually dumps the INFO, instead of returning and letting the user dump it. Stand-alone RMAIL differs from INFO because it is presumed that since users will be doing things such as editing replies from Rmail, he probably wants his EMACS init run. Therefore the program TS RMAIL actually just loads an EMACS into itself, passing it the JCL string 2,MMRMAIL. The argument of 2, is merely used to instruct Rmail to kill the job upon exit, instead of returning into Emacs. The MM RMAIL command in Emacs just runs the Rmail library, which by convention on ITS is kept in EMACS;[RMAI] >. Effectively users could just as well enter EMACS themselves and run Rmail. TS RMAIL is only there because many people seem to prefer thinking of it as a different program. The TRMAIL command is a version of RMAIL that runs in a bare Teco ^R environment. It exists purely because RMAIL used to run that way itself, and some RMAIL users who are not EMACS users want it that way. TRMAIL must be dumped by a TECO init file to avoid getting the Emacs character command definitions in the dumped library. The file AI:EMACS1;RMAIL TECO must be loaded into a bare teco and executed to do this. New versions of stand-alone TRMAIL and INFO must be made for each new TECO or EMACS version, just like new versions of the EMACS dump file. The stand-alone TRMAIL and INFO always load up the current version of the RMAIL and INFO libraries, rather than the version which was current when they were dumped, so new TRMAIL and INFO dump files do not generally need to be made when new versions of those libraries are installed.  File: CONV Node: Wall Charts, Up: Top, Previous: Build, Next: Abstracts Making Wall Charts Wall Charts are made by MM RunABSTRWall Chart with an empty buffer. This produces a wall chart in the buffer, describing the environment as it exists. is a list of names of prefix characters, each of which should get a page describing all of its subcommands. The prefix characters are named as if you were accessing their definitions as q-registers, such as ".X" for C-X. The names should be separated by Altmodes. Two Altmodes end the list of prefix character names. Writing the Documentation Files EMACS CHART and EMACS DOC. These two files are produced from the self-documentation strings within EMACS by the functions in the library ABSTR. Simply doing M-X RunEINIT? Document will update them according to the current environment. Make sure that you do this as a user who does not have an init file! Otherwise, the files will reflect your command definitions rather than the default.  File: CONV Node: Abstracts, Up: Top, Previous: Wall Charts, Next: Qregs Library Abstracts, Source Listings and Source Indexes Library Abstracts are a form of automatically generated documentation files for libraries. Source listings and indices are files useful in hardcopy form for studying code. This node tells about making all three. An abstract of a library is a file of the documentation of all the commands in the library. Abstracts are useful for documentation of the library. They can follow the order of the functions in the library itself or can be alphabetized. To make an abstract, load the ABSTR library and then call either Abstract File or Alphabetical Abstract. Abstract File makes an abstract using the order functions appear in the library sources; usually this order is a logical classification of the functions if the sources are arranged carefully. It takes three arguments; a name prefix, a documentation prefix, and the library name. The name prefix and documentation prefix are used as filters; only functions whose name and documentation start with those prefixes are included in the abstract. The prefixes can be null. Alphabetical Abstract takes just a library filename as its argument, and abstracts all functions in the library. The functions are first sorted by documentation class (S, C or ^R) and then alphabetically within each class. Listings of TECO Code There are two ways to make a listing of TECO code. One is the function @ TECO, in the PURIFY library. This function takes the library file name as a string argument and writes an XGP listing as ; XGP. You can supply a font name as a second string argument and a number of lines per page as a numeric argument. If you don't have an XGP or anything that can print XGP files, you can use instead two functions in the TMACS library. Load the TECO source file into EMACS, then do M-X Run LibraryTMACSUncontrolify. This replaces each control character with an "^" and a letter. Then do M-X Run LibraryTMACSSave Trees. This combines consecutive short pages together so that the listing uses fewer pages. Otherwise, each function would come out on a separate page of the listing, which would be very wasteful for the many small functions that often exist. After Save Trees, the listing is now in the buffer. Source Indexes A source index describes the contents of several TECO source files. It is sorted alphabetically by function name and says which file each function is in. It is useful for studying listings of those source files. To make a source index, create a buffer and put in it the names of the source files, one filename per line. Then load ABSTR and call Make Source Index. When it is finished, the buffer contains the source index.  File: CONV Node: Qregs, Up: Top, Previous: Abstracts, Next: FS^RPREV Usage of Q-registers in EMACS and Functions Intended for EMACS EMACS makes no use of non-dot q-regs except as saved and restored local variables, unless the user explicitly requests such use with (say) C-X X, except for M and R, and even those are not depended on by the EMACS functions. User functions may use non-dot q-regs freely, but those intended for general use should not do so except as local variables (pushed and popped). User functions should not use single or double dot q-regs except as listed here. If it is really essential, you should ask RMS to allocate another single-dot q-reg for a specific use. Normally, a named variable is just as good. .A MM & Autoload. This function loads a library temporarily and returns a pointer to a specified function in it. For example, M.A DIREDClean Dir loads the DIRED library and returns a pointer to the Clean Dir function in it. FS :EJPAGE is pushed and left on the stack, so that the library will be flushed when the function which invoked M.A exits and unwinds the stack. .B The buffer table. This is a q-vector which is subdivided into a section for each EMACS named buffer. The details of the format are described in a comment at the front of the EMACS source file BUFFER. .C Set Variable Comment. Like .V, but creates a comment for the variable. M.C   creates if necessary, giving it the comment and the value . defaults to 0. If the comment starts with "*", then the variable is an "option" and MM Alter Options will let the user edit it. .F The "normal" (top-level) contents of ..F. When .F and ..F are not the same, EMACS knows that it is not safe to switch buffers, windows or files. .F should not be zero; that would lose. See ..F. .H The horizontal position "goal" for ^N and ^P commands. If it is a small positive number, it is a temporary goal, which will be reset by each ^N or ^P not following another such. The other possible values in .H are 1000000. plus a small number, which indicates a semipermanent goal that was established by ^R Set Goal Column and which it alone can alter. .I & Prepare for Input. Do M.I before doing an FI to read input. The second argument, if any is the character to prompt with (default is in Q..0). The first argument is bit-decoded: 1 means that the control and meta prefix characters should be noticed, and 2 suppresses prompting and echoing (acts as if the characater being read is an independent command). .L Make Local Variable. Do M.L  to make into a local variable of the current buffer. If it already is local, nothing is changed. If didn't exist at all, 0M.V is implied. The global value of is not changed; the local starts off with that same value as well. If M.L is given a numeric argument, it becomes the new value of the (local) . .M & Macro Get. M.M returns a pointer to the function . Normally, an error will occur if the name is undefined or ambiguous, but if 1, is given as argument, instead of an error, the value 0 or 1 will be returned. Independently, a pointer to a file can be given as an argument, and the function will be looked for in that file. .N The ring buffer of minibuffer commands. All commands that use the minibuffer and execute its contents normally push their commands onto this ring, so you can run them again easily. Q.N is a q-vector whose 0th element is the most recent minibuffer. .P M.P is the driver for prefix commands such as C-X which read another character and dispatch on it. Whatever you put in .P should work like what is usually put there: & Prefix Character Driver. See Make Prefix Character. .Q Inside major mode functions, this contains the function Make Local Q-register. .V Named Variable maker. (Teco "altmode" Q-regs) .W Is a flag that determines whether the word commands refer to LISP atoms. It holds either a null string (if they do not) or an "@" (if they do). .X Is the dispatch table for the C-X prefix command. It is a qvector 128 elements long, indexed by subcommand. This is only in the default environment. If you build a completely separate environment, .X is available. ..F normally holds the auto-filing secretary function. Auto-saving is turned off by zeroing FS ^R MDLY, not by changing ..F. Normally, .F contains the same thing as ..F. Functions which call ^R recursively should bind ..F to 0, thus inhibiting auto-saving. Also, the fact that .F and ..F will then be different will serve as an indication that it is not safe to switch buffers, files or windows. If you use a modified version of the secretary function, you must store it in both ..F and .F for proper operation. To turn off the secretary function globally, you should not simply set .F and ..F to zero, because then the functions that bind ..F to zero will not make it different from .F. You must make a null string and put it in .F and ..F. ..K A qvector used to hold strings of deleted text by the ^R Kill ... and ^R Un-kill commands. The elements are the strings, in the order they were killed. The beginning may be filled with zeros, if there are not enough remembered killed strings to use the whole qvector. ..M holds the keyboard macro call stack. See the file KBDMAC. ..U holds the data base for the Undo command. It is a qvector containing these 5 objects which describe the most recent undoable change. :..U(0) is the buffer in which the change was made. :..U(1) is the text that was deleted. :..U(2) is the number of characters which preceded that text. :..U(3) is the number which followed that text. :..U(4) is a string like "kill" or "sort" which says what sort of operation made the change.  File: CONV Node: FS^RPREV, Up: Top, Previous: Qregs, Next: Debug FS ^R LAST / FS ^R PREV Convention Some commands set FS ^R LAST to a special value not in the range of 9-bit characters, to make it possible to test whether the previous command was in a certain class without having to know which characters various functions are on. These are the values used: 512+27 is set at times in minibuffering, when the (1033 octal) most recent character was an altmode but a following altmode should not exit. 1001 (decimal) is set by deleting commands. This allows multiple consecutive deletions to be combined in the ..K ring. 1002 is set by the vertical-motion commands so that repeated vertical motion commands can use the same horizontal position as a goal. 1003 signals that it is OK for m-Y (^R Un-kill Pop) to work even though the current region is not on the kill-ring. This is used by commands like Fill Region which save the region then do a simple but possibly dangerous transformation to it.  File: CONV Node: Debug, Up: Top, Previous: FS^RPREV Debugging For debugging, make use of the function TCompile, which compresses the definition of the function you are pointing at and makes it available to M.M. This makes it possible to test a new version of a function without purifying the whole file containing it. Insert a ^R command into the definition to make a "breakpoint" which will allow you to look around. Exiting the ^R will cause execution of the function to resume. To test-compile the function and put it on a character, use the fact that TCompile returns the definition as its value; thus, do MM TcompileU.N to set C-N's definition. The default EMACS error handler runs MM Backtrace after every error, if the first character you type is "?". Inside the backtrace you can examine the functions on the call stack, look at the buffer being edited, and resume execution either at the place it stopped or elsewhere. To find out the details of how, type "?" while inside Backtrace. If QDebug is nonzero, you can type "?" to get a backtrace after a quit as well as after an error. *note TDEBUG: (TDEBUG)Top, for info on the superb TDEBUG package which allows you to step through the execution of a function, and examine the macro and q-register pdls.