Return to spec.out CVS log

Up to [CSRG BSD Unix] / 43BSDReno / contrib / emacs-18.55 / dist-1.3 / fi

Annotation of 43BSDReno/contrib/emacs-18.55/dist-1.3/fi/spec.out, revision 1.1

1.1     ! root        1:              Franz Inc. GNU Emacs/Common Lisp Interface
        !             2:                             Release 1.3
        !             3: 
        !             4: This document is a specification of the Franz Inc. GNU Emacs interface
        !             5: to Common Lisp, which is written entirely in GNU Emacs Lisp (for GNU
        !             6: Emacs version 18.50).
        !             7: 
        !             8: 0. Concepts and Terminology
        !             9: 
        !            10:    In Emacs, each buffer has a `mode.'  A mode is a collection of key
        !            11: and variable `bindings' which are specialized to a certain task.  When
        !            12: the cursor is in a `buffer' and you depress a key, its action is
        !            13: determined by the binding found in the `keymap' associated with that
        !            14: buffer (the buffer-local keymap).  If there is no binding in the
        !            15: buffer-local keymap, then the binding is sought on the `global' keymap.
        !            16: Thus, a mode is usually implemented by creating a buffer-local keymap
        !            17: and adding bindings to do specific tasks.  The result is that certain
        !            18: keys act differently in the buffer but most keys act just as they do
        !            19: in all the other buffers.  Usually the mode of a buffer is displayed
        !            20: in parentheses at the bottom of the screen (in what is called the
        !            21: `mode line').
        !            22: 
        !            23:    Two terms used interchangeably in this document are `subprocess' and
        !            24: `inferior process'.  They both refer to the interaction between Emacs
        !            25: and running program, and their names come from the fact that UNIX
        !            26: processes are part of a hierarchical structure--each process has a
        !            27: parent and some processes have children.  Here, Lisp is run as a child
        !            28: of Emacs, or a subordinate process under Emacs.
        !            29: 
        !            30:    Most machines available today have a `network' interface.  There
        !            31: are several `protocols' in use today, of which `TCP/IP' (Transmission
        !            32: Control Protocol) is one.  TCP/IP is most commonly used for
        !            33: communication between machines using `ethernet'--ethernet is the
        !            34: hardware and TCP/IP is the software.  TCP/IP is available on Berkeley
        !            35: UNIX and some other UNIX systems, and is a powerful tool for making
        !            36: resources from a large number of machines easily available to all
        !            37: users on the network.  The X window system, for example, uses TCP/IP
        !            38: to communicate between clients and server.
        !            39: 
        !            40:    In order for Emacs and Lisp to communicate, Lisp must accept
        !            41: messages sent to a certain address and Emacs must know that address.
        !            42: There are two types of addressing available: internet and UNIX domain.
        !            43: An internet address is a machine address and a port number.  A UNIX
        !            44: domain address is a file name.  The advantage of an internet address
        !            45: is that it can be accessed from any machine on the network because the
        !            46: address contains the machine number.  The disadvantage is that only
        !            47: one process (a Lisp process in our case) on a given machine can listen
        !            48: for messages on a given internet address.  Thus, if you wanted to use
        !            49: the Emacs to Lisp interface on a machine with many users, only one
        !            50: user at a time could use it.  A UNIX domain address can only be used
        !            51: from programs running on the same machine.  However the flexibility of
        !            52: using file names in UNIX domain addresses allows the Emacs to Lisp
        !            53: interface to choose unique addresses for each user running on a
        !            54: machine.  The file name convention we use is this: when user `smith'
        !            55: starts up Lisp, the UNIX domain address `~smith/.excl_to_emacs' is used
        !            56: by Lisp.  When `smith' directs Emacs to connect to Lisp, it knows it
        !            57: was started by smith and thus talks to address `~smith/.excl_to_emacs'.
        !            58: Thus multiple users on a given machine can run the Emacs to Lisp
        !            59: interface.
        !            60: 
        !            61:    The Emacs/Lisp interface in this document can use both of these
        !            62: methods of communication, but the preferred method uses UNIX domain
        !            63: sockets, because more than one person on a machine may use the
        !            64: Lisp/Emacs interface.
        !            65: 
        !            66: 1. Introduction
        !            67: 
        !            68:    The purpose of this package is to enhance the Lisp environment.  To
        !            69: this end, GNU Emacs and Lisp have been tightly coupled, and in the
        !            70: case of Allegro CL 3.0 the interface uses TCP/IP UNIX or internet
        !            71: domain sockets.  This interface can be broken down into three modes:
        !            72: 
        !            73:        * Common Lisp,
        !            74:        * Inferior Common Lisp, and
        !            75:        * TCP Common Lisp.
        !            76: 
        !            77: The first is for editing Lisp programs, the second for starting up a
        !            78: Lisp subprocess under Emacs, and the third for TCP/IP communication
        !            79: between Emacs and Lisp.
        !            80: 
        !            81:    While editing Lisp source code, there are commands that make it
        !            82: easy to send expressions to, and receive information from, a Lisp
        !            83: process.  For example: a function can be sent to Lisp from a source
        !            84: buffer, a form in a source buffer can be macroexpanded, and
        !            85: source for functions defined by loading files into Lisp may be located
        !            86: automatically.
        !            87: 
        !            88:    For many of the bindings set up in the editing modes to be useful,
        !            89: there must be a Lisp to which Emacs can communicate.  In this area the
        !            90: interface can be broken down into three parts: an enhanced mode for
        !            91: running an inferior Lisp process in an Emacs buffer, a new mode that
        !            92: creates an Emacs buffer onto an existing Lisp process via a TCP/IP
        !            93: socket, and mechanisms to query the Lisp environment for information
        !            94: which can be used in the Emacs environment (also using TCP/IP
        !            95: sockets).
        !            96: 
        !            97:    Running an inferior Lisp in an Emacs buffer is not new--Emacs
        !            98: supports this `off the shelf.'  This feature allows users to interact
        !            99: directly with Lisp while editing Lisp source code.  Although the
        !           100: existing inferior Lisp mode has been enhanced and a new mode added to
        !           101: support socket connections to Lisp, the most significant contribution of
        !           102: this package is in offering tighter coupling of the Lisp and Emacs
        !           103: environments and in providing better subprocess management tools.
        !           104: 
        !           105:    By taking advantage of Lisp multiprocessing, an Emacs buffer can be
        !           106: opened onto a Lisp not started as a subprocess of Emacs.  This
        !           107: connection uses TCP/IP sockets (UNIX or internet domain), which in turn
        !           108: means that Emacs can talk to a Lisp running on any machine on the
        !           109: network.  Sockets and multiprocessing also mean that one can establish
        !           110: more than one connection between Lisp and Emacs.
        !           111: 
        !           112:    These socket connections to Lisp are the key to the integration of
        !           113: the two environments.  Emacs uses a `back door' connection to exchange
        !           114: information with a Lisp process.  Users can obtain information about
        !           115: Lisp function argument lists and symbol documentation, macroexpand Lisp
        !           116: forms, and locate source definitions of Lisp symbols (which are recorded
        !           117: by Lisp when a symbol is defined, usually by loading a file).  All these
        !           118: features are accessible with a few key-strokes.
        !           119: 
        !           120:    Aside from the Lisp interface proper, this package provides useful
        !           121: features for subprocess manipulation, including an input ring for
        !           122: handy retrieval of previously-typed input, filename completion,
        !           123: special handling of certain subprocess-specific keys (e.g., ^C or ^D),
        !           124: and continuously showing output from a subprocess in a visible buffer.
        !           125: 
        !           126: 2. Editing Lisp
        !           127: 
        !           128:    This package modifies `auto-mode-alist' so that the major modes
        !           129: defined in this package are invoked when certain types of source files
        !           130: are edited.  The list of filename extensions given by the value of
        !           131: `fi:common-lisp-file-types' cause `fi:common-lisp-mode' to be invoked
        !           132: whenever a file with one of these types is visited.  The important
        !           133: actions done by Common Lisp mode are (in order):
        !           134: 
        !           135:        1. set up local variables specific to the mode;
        !           136:        2. check for package information;
        !           137:        3. set up keymaps; and
        !           138:        4. call hooks.
        !           139: 
        !           140: The above functions are enhancements to the standard available GNU
        !           141: Emacs Lisp mode.
        !           142: 
        !           143:    The major mode function for Common Lisp is called
        !           144: `fi:common-lisp-mode', and this function can be interactively called
        !           145: to put a buffer in Common Lisp mode.
        !           146: 
        !           147: fi:common-lisp-file-types...........................................[variable]
        !           148:    Value: (".cl" ".lisp" ".lsp")
        !           149:    A list of the files which are automatically put in fi:common-lisp-mode.
        !           150: This variable should be set before this package is loaded.
        !           151: 
        !           152: 
        !           153: 
        !           154: 2.1 Bindings
        !           155: 
        !           156:    The key bindings for Common Lisp mode are set up only once, the
        !           157: first time the mode is entered, and are taken from the variable
        !           158: `fi:common-lisp-mode-map'.  Users wanting to change the bindings could
        !           159: explicitly set this variable or augment the map from within the hooks
        !           160: for the mode.
        !           161: 
        !           162:    The initial local bindings for Common Lisp mode are:
        !           163: 
        !           164: fi:common-lisp-mode-map...............................................[keymap]
        !           165:    Major mode map used when editing Common Lisp source.
        !           166: 
        !           167: C-c             Prefix Command
        !           168: RET             fi:lisp-reindent-newline-indent
        !           169: DEL             backward-delete-char-untabify
        !           170: TAB             lisp-indent-line
        !           171: C-x             Prefix Command
        !           172: ESC             Prefix Command
        !           173: 
        !           174: C-c C-r         fi:lisp-eval-region
        !           175: C-c C-s         fi:lisp-eval-last-sexp
        !           176: C-c C-b         fi:lisp-eval-current-buffer
        !           177: 
        !           178: ESC C-x         fi:lisp-eval-defun
        !           179: ESC W           fi:lisp-walk
        !           180: ESC M           fi:lisp-macroexpand
        !           181: ESC F           fi:lisp-function-documentation
        !           182: ESC D           fi:lisp-describe
        !           183: ESC C           fi:lisp-who-calls
        !           184: ESC A           fi:lisp-arglist
        !           185: ESC TAB         fi:lisp-complete-symbol
        !           186: ESC ,           fi:lisp-tags-loop-continue
        !           187: ESC .           fi:lisp-find-tag
        !           188: ESC C-q         indent-sexp
        !           189: 
        !           190: 
        !           191: 
        !           192: 
        !           193: 2.2 Variables
        !           194: 
        !           195:    All local variables are killed when Common Lisp mode is
        !           196: entered--this is a convention to insure that there are no name
        !           197: conflicts with user variables.
        !           198: 
        !           199:    To correctly deal with the Common Lisp package system, Emacs must
        !           200: know the package for each file, so that it may use this when sending
        !           201: expressions from a buffer to Lisp.  There is a buffer-local variable
        !           202: which contains the name of the package:
        !           203: 
        !           204: fi:package..........................................................[variable]
        !           205:    Value: "user"
        !           206:    A buffer-local variable whose value should either be nil or a string
        !           207: which names a package in the Lisp world (ie, in a Lisp subprocess running
        !           208: as an inferior of Emacs in some buffer).  It is used when expressions are
        !           209: sent from an Emacs buffer to a Lisp process so that the symbols are read
        !           210: into the correct Lisp package.
        !           211: 
        !           212: 
        !           213: 
        !           214: There are three ways to automatically set this variable (the first and
        !           215: third items here are standard GNU Emacs features):
        !           216: 
        !           217:   1. If the first line in the file contains text surrounded by -*-,
        !           218:      the `package' field of this line is parsed for the package name.
        !           219:      For example,
        !           220: 
        !           221:                ;; -*- mode: common-lisp; package: excl -*-
        !           222: 
        !           223:      would put the file in package `excl'.
        !           224: 
        !           225:   2. If the above attempt fails, then the buffer is searched for an
        !           226:      `in-package' form, which is parsed for the package name.
        !           227: 
        !           228:   3. Lastly, the values obtained in one of the first two locations can
        !           229:      be over-written by manually setting fi:package in the local
        !           230:      variables list.  For example, the following at the end of the
        !           231:      file will override any value given previously given to
        !           232:      fi:package:
        !           233: 
        !           234:        ^L
        !           235:        ;; Local Variables:
        !           236:        ;; eval: (setq fi:package "excl")
        !           237:        ;; End:
        !           238: 
        !           239:      Note that the normal method for setting a variable will not work,
        !           240:      because `fi:package' contains a `:' and this confuses GNU
        !           241:      Emacs, hence the use of `eval'.
        !           242: 
        !           243: If Emacs cannot determine the package, then it is assumed to be
        !           244: "user" (the initial Common Lisp package).
        !           245: 
        !           246: 2.3 Functions
        !           247: 
        !           248:    The following functions are either bound to keys in Common Lisp
        !           249: mode or are available as extended commands:
        !           250: 
        !           251: fi:lisp-reindent-newline-indent.....................................[function]
        !           252:    Invoke with: RET in Common Lisp mode.
        !           253:    Indent the current line, insert a newline and indent to the proper
        !           254: column.
        !           255: 
        !           256: 
        !           257: fi:lisp-eval-region.................................................[function]
        !           258:    Invoke with: C-c C-r in Common Lisp mode.
        !           259:    Send the text in the region to the Lisp subprocess associated with this
        !           260: buffer, one expression at a time if there is more than one complete
        !           261: expression.  If a Lisp subprocess has not been started, then one is
        !           262: started.  With a prefix argument, the source sent to the subprocess is
        !           263: compiled.
        !           264: 
        !           265: 
        !           266: fi:lisp-eval-last-sexp..............................................[function]
        !           267:    Invoke with: C-c C-s in Common Lisp mode.
        !           268:    Send the sexp before the point to the Lisp subprocess associated with
        !           269: this buffer.  If a Lisp subprocess has not been started, then one is
        !           270: started.  With a prefix argument, the source sent to the subprocess is
        !           271: compiled.
        !           272: 
        !           273: 
        !           274: fi:lisp-eval-current-buffer.........................................[function]
        !           275:    Invoke with: C-c C-b in Common Lisp mode.
        !           276:    Send the entire buffer to the Lisp subprocess associated with this
        !           277: buffer.  If a Lisp subprocess has not been started, then one is started.
        !           278: With a prefix argument, the source sent to the subprocess is compiled.
        !           279: 
        !           280: 
        !           281: fi:lisp-eval-defun..................................................[function]
        !           282:    Invoke with: ESC C-x in Common Lisp mode.
        !           283:    Send the current top-level (or nearest previous) form to the Lisp
        !           284: subprocess associated with this buffer.  A `top-level' form is one that
        !           285: starts in column 1.  If a Lisp subprocess has not been started, then one is
        !           286: started.  With a prefix argument, the source sent to the subprocess is
        !           287: compiled.
        !           288: 
        !           289: 
        !           290: fi:remove-all-temporary-lisp-transaction-files......................[function]
        !           291:    This function will clean up all the files created for Lisp/Emacs
        !           292: communication.  See the variable fi:emacs-to-lisp-transaction-directory for
        !           293: the location of the files.
        !           294: 
        !           295: 
        !           296: 
        !           297:    The following functions are bound to keys in Common Lisp mode, and
        !           298: require the TCP/IP communication channel to Lisp:
        !           299: 
        !           300: fi:lisp-find-tag....................................................[function]
        !           301:    Invoke with: ESC . in Common Lisp mode.
        !           302:    Find the Common Lisp source for a symbol, using the characters around
        !           303: the point as the default tag.
        !           304: 
        !           305: 
        !           306: fi:lisp-tags-loop-continue..........................................[function]
        !           307:    Invoke with: ESC , in Common Lisp mode.
        !           308:    Find the next occurrence of the tag last used by fi:lisp-find-tag.
        !           309: 
        !           310: 
        !           311: fi:lisp-arglist.....................................................[function]
        !           312:    Invoke with: ESC A in Common Lisp mode.
        !           313:    Print the arglist (using excl:arglist) for a symbol, which is read from
        !           314: the minibuffer.  The word around the point is used as the default.
        !           315: 
        !           316: 
        !           317: fi:lisp-describe....................................................[function]
        !           318:    Invoke with: ESC D in Common Lisp mode.
        !           319:    Describe a symbol, which is read from the minibuffer.  The word around
        !           320: the point is used as the default.
        !           321: 
        !           322: 
        !           323: fi:lisp-function-documentation......................................[function]
        !           324:    Invoke with: ESC F in Common Lisp mode.
        !           325:    Print the function documentation for a symbol, which is read from the
        !           326: minibuffer.  The word around the point is used as the default.
        !           327: 
        !           328: 
        !           329: fi:lisp-macroexpand.................................................[function]
        !           330:    Invoke with: ESC M in Common Lisp mode.
        !           331:    Print the macroexpansion of the form at the point.
        !           332: 
        !           333: 
        !           334: fi:lisp-walk........................................................[function]
        !           335:    Invoke with: ESC W in Common Lisp mode.
        !           336:    Print the full macroexpansion the form at the point.
        !           337: With a prefix argument, macroexpand the code as the compiler would.
        !           338: 
        !           339: 
        !           340: fi:lisp-who-calls...................................................[function]
        !           341:    Invoke with: ESC C in Common Lisp mode.
        !           342:    Print all the callers of a function.  The default symbol name is taken
        !           343: from the sexp around the point.
        !           344: 
        !           345: 
        !           346: fi:lisp-complete-symbol.............................................[function]
        !           347:    Invoke with: ESC TAB in Common Lisp mode.
        !           348:    Perform completion on the Common Lisp symbol preceding the point.  That
        !           349: symbol is compared to symbols that exist in the Common Lisp, to which there
        !           350: is a TCP/IP connection (see fi:eval-in-lisp).  If the symbol starts just
        !           351: after an open-parenthesis, then only symbols (in the Common Lisp) with
        !           352: function defintions are considered.  Otherwise all symbols are considered.
        !           353: 
        !           354: 
        !           355: 
        !           356: fi:set-associated-sublisp...........................................[function]
        !           357:    When evaluated in a Lisp source buffer causes further `eval'
        !           358: commands (those which send expressions from Emacs to Lisp) to use
        !           359: BUFFER-NAME as the buffer which contains a Lisp subprocess.  If evaluated
        !           360: when not in a Lisp source buffer, then the process type is read from the
        !           361: minibuffer ("common-lisp" or "franz-lisp").  The buffer name is
        !           362: interactively read and must be the name of an existing buffer.  New buffers
        !           363: with the same mode as the current buffer will also use BUFFER-NAME for
        !           364: future `eval' commands.
        !           365: 
        !           366: 
        !           367: 
        !           368: 2.3 Hooks
        !           369: 
        !           370:    The hooks run for Common Lisp mode are fi:lisp-mode-hook and
        !           371: fi:common-lisp-mode-hook.  The form of the hook function is determined
        !           372: by `run-hooks', which is used to process the hooks.  Hooks are run
        !           373: last during mode initialization.  For example, the following hook
        !           374: enables auto-fill in Common Lisp mode:
        !           375: 
        !           376:     (setq fi:lisp-mode-hook
        !           377:       '(lambda ()
        !           378:        (define-key (current-local-map) "\t" 'lisp-indent-line)
        !           379:        (setq fill-column 75)
        !           380:        (auto-fill-mode 1)))
        !           381: 
        !           382: 3. Running Lisp
        !           383: 
        !           384:    What follows is a discussion of the bindings, variables and
        !           385: functions allowing the user to interact with and manipulate a Lisp run
        !           386: as an inferior to Emacs.  A discussion on how to start up and use the
        !           387: interface is discussed in the next section.
        !           388: 
        !           389: 
        !           390: 3.1 Bindings
        !           391: 
        !           392:    The initial local bindings for Inferior Common Lisp mode are:
        !           393: 
        !           394: fi:inferior-common-lisp-mode-map......................................[keymap]
        !           395:    The inferior-common-lisp major-mode keymap.
        !           396: 
        !           397: DEL             backward-delete-char-untabify
        !           398: TAB             lisp-indent-line
        !           399: C-x             Prefix Command
        !           400: ESC             Prefix Command
        !           401: C-c             Prefix Command
        !           402: RET             fi:inferior-lisp-newline
        !           403: 
        !           404: C-c C-\         fi:subprocess-quit
        !           405: C-c C-d         fi:subprocess-send-eof
        !           406: C-c C-c         fi:subprocess-interrupt
        !           407: C-c C-w         fi:subprocess-backward-kill-word
        !           408: C-c C-v         fi:subprocess-show-output
        !           409: C-c C-u         fi:subprocess-kill-input
        !           410: C-c C-s         fi:re-search-forward-input
        !           411: C-c C-r         fi:re-search-backward-input
        !           412: C-c C-p         fi:pop-input
        !           413: C-c C-o         fi:subprocess-send-flush
        !           414: C-c C-n         fi:push-input
        !           415: C-c RET         fi:subprocess-input-region
        !           416: C-c C-l         fi:list-input-ring
        !           417: C-c C-k         fi:subprocess-kill-output
        !           418: C-c C-a         fi:subprocess-beginning-of-line
        !           419: 
        !           420: C-x RET         fi:inferior-lisp-input-list
        !           421: 
        !           422: ESC W           fi:lisp-walk
        !           423: ESC M           fi:lisp-macroexpand
        !           424: ESC F           fi:lisp-function-documentation
        !           425: ESC D           fi:lisp-describe
        !           426: ESC C           fi:lisp-who-calls
        !           427: ESC A           fi:lisp-arglist
        !           428: ESC TAB         fi:lisp-complete-symbol
        !           429: ESC ,           fi:lisp-tags-loop-continue
        !           430: ESC .           fi:lisp-find-tag
        !           431: ESC RET         fi:inferior-lisp-input-sexp
        !           432: ESC C-q         indent-sexp
        !           433: 
        !           434: 
        !           435: 
        !           436: 
        !           437: and for the TCP Common Lisp mode:
        !           438: 
        !           439: fi:tcp-common-lisp-mode-map...........................................[keymap]
        !           440:    The tcp-lisp major-mode keymap.
        !           441: 
        !           442: DEL             backward-delete-char-untabify
        !           443: TAB             lisp-indent-line
        !           444: C-x             Prefix Command
        !           445: ESC             Prefix Command
        !           446: C-c             Prefix Command
        !           447: RET             fi:inferior-lisp-newline
        !           448: 
        !           449: C-c C-\         fi:tcp-lisp-kill-process
        !           450: C-c C-d         fi:tcp-lisp-send-eof
        !           451: C-c C-c         fi:tcp-lisp-interrupt-process
        !           452: C-c C-w         fi:subprocess-backward-kill-word
        !           453: C-c C-v         fi:subprocess-show-output
        !           454: C-c C-u         fi:subprocess-kill-input
        !           455: C-c C-s         fi:re-search-forward-input
        !           456: C-c C-r         fi:re-search-backward-input
        !           457: C-c C-p         fi:pop-input
        !           458: C-c C-o         fi:subprocess-send-flush
        !           459: C-c C-n         fi:push-input
        !           460: C-c RET         fi:subprocess-input-region
        !           461: C-c C-l         fi:list-input-ring
        !           462: C-c C-k         fi:subprocess-kill-output
        !           463: C-c C-a         fi:subprocess-beginning-of-line
        !           464: 
        !           465: C-x RET         fi:inferior-lisp-input-list
        !           466: 
        !           467: ESC W           fi:lisp-walk
        !           468: ESC M           fi:lisp-macroexpand
        !           469: ESC F           fi:lisp-function-documentation
        !           470: ESC D           fi:lisp-describe
        !           471: ESC C           fi:lisp-who-calls
        !           472: ESC A           fi:lisp-arglist
        !           473: ESC TAB         fi:lisp-complete-symbol
        !           474: ESC ,           fi:lisp-tags-loop-continue
        !           475: ESC .           fi:lisp-find-tag
        !           476: ESC RET         fi:inferior-lisp-input-sexp
        !           477: ESC C-q         indent-sexp
        !           478: 
        !           479: 
        !           480: 
        !           481: 
        !           482:    Superkeys are keys that are handled specially at the end of a
        !           483: buffer.  At the end of a buffer it has a buffer-specific meaning, but
        !           484: anywhere else in the buffer it has the normal global meaning (obtained
        !           485: by looking the key up in the global keymap).  This way, ^D can send an
        !           486: EOF to the Lisp process at the end of a buffer but invoke delete-char
        !           487: ("delete character") anywhere else.
        !           488:  
        !           489:    The values of `fi:inferior-common-lisp-mode-super-key-map' and
        !           490: `fi:tcp-common-lisp-mode-super-key-map' are used as superkey maps for
        !           491: Inferior Common Lisp and TCP Common Lisp modes.
        !           492:    
        !           493:    Superkeys are turned off by default.
        !           494: 
        !           495: 3.2 Variables
        !           496: 
        !           497:    The name of the Common Lisp image to activate for an inferior Lisp
        !           498: is taken from the following variables:
        !           499: 
        !           500: fi:common-lisp-image-name...........................................[variable]
        !           501:    Value: "cl"
        !           502:    *Default Common Lisp image to invoke from `fi:common-lisp'.  If the
        !           503: value is a string then it names the image file or image path that
        !           504: `fi:common-lisp' invokes.  Otherwise, the value of this variable is given
        !           505: to funcall, the result of which should yield a string which is the image
        !           506: name or path.
        !           507: 
        !           508: 
        !           509: 
        !           510:    After the image name as been determined and the process has been
        !           511: started, a file in the user's home directory called .emacs_<IMAGE>,
        !           512: where <IMAGE> is the image name, is fed to the newly created process.
        !           513: This could be used to customize a initialization file on the name of
        !           514: the Lisp binary.
        !           515: 
        !           516:    The command-line arguments passed to the activated image are taken
        !           517: from the following variables:
        !           518: 
        !           519: fi:common-lisp-image-arguments......................................[variable]
        !           520:    Value: nil
        !           521:    *Default Common Lisp image arguments when invoked from `fi:common-lisp',
        !           522: which must be a list of strings.
        !           523: 
        !           524: 
        !           525: 
        !           526:    The prompt pattern for the inferior Lisp is taken from a variable
        !           527: with the name `fi:<IMAGE>-prompt-pattern' or from the following:
        !           528: 
        !           529: fi:common-lisp-prompt-pattern.......................................[variable]
        !           530:    Value: "^\\(\\[[0-9]+c?\\] \\|\\[step\\] \\)?<[-A-Za-z]* ?[0-9]*?> "
        !           531:    *The regular expression which matches the Common Lisp prompt, used in
        !           532: Inferior Common Lisp mode.  Anything from beginning of line up to the end
        !           533: of what this pattern matches is deemed to be a prompt.
        !           534: 
        !           535: 
        !           536: fi:common-lisp-package-regexp.......................................[variable]
        !           537:    Value: "(in-package\\>\\|:\\<pa\\>\\|:\\<pac\\>\\|:\\<pack\\>\\|:\\<packa\\>\\|:\\<packag\\>\\|:\\<package\\>"
        !           538:    *The regular expression matching the Common Lisp expression(s) to change
        !           539: packages.  If nil, no automatic package tracking will be done.
        !           540: 
        !           541: 
        !           542: 
        !           543:    The following variables are used in TCP Common Lisp mode:
        !           544: 
        !           545: fi:unix-domain......................................................[variable]
        !           546:    Value: t
        !           547:    *If non-nil, then `fi:unix-domain-socket' specifies the name of the
        !           548: socket file.  It is recommended that this interface be used, and not
        !           549: internet ports, because when internet ports are used only one process on a
        !           550: machine may use this interface (it is a global resource).  When using UNIX
        !           551: domain sockets, communication is done through a socket file in the user's
        !           552: home directory.  But, if you really want to use internet ports, here are
        !           553: the steps to take:
        !           554: 
        !           555: 1. Set this variable to nil.
        !           556: 2. Add the following line to /etc/services:
        !           557:        excl            6789/tcp
        !           558: 3. Make sure `fi:local-host-name' is in /etc/hosts and points to the local
        !           559: or loopback host.
        !           560: 4. On the Common Lisp side, put the following in you .clinit.cl file:
        !           561:        (setq ipc:*inet-port* 6789)     ; the number from /etc/services
        !           562:        (setq ipc:*unix-domain* nil)
        !           563: 
        !           564: The problem with this, is that people can then use `telnet' to get a
        !           565: listener on your lisp!
        !           566: 
        !           567: 
        !           568: fi:unix-domain-socket...............................................[variable]
        !           569:    Value: "~/.excl_to_emacs"
        !           570:    *The name of the socket file that lisp and emacs use to communicate.
        !           571: This is used when fi:unix-domain is non-nil.
        !           572: 
        !           573: 
        !           574: fi:excl-service-name................................................[variable]
        !           575:    Value: "excl"
        !           576:    *The service name from /etc/services (`tcp' type).  This is only used
        !           577: when fi:unix-domain is nil.
        !           578: 
        !           579: 
        !           580: fi:local-host-name..................................................[variable]
        !           581:    Value: "localhost"
        !           582:    *On 4.2 BSD the name of 127.1--usually localhost or loopback.
        !           583: This is only used when fi:unix-domain is nil.
        !           584: 
        !           585: 
        !           586: fi:source-info-not-found-hook.......................................[variable]
        !           587:    Value: find-tag
        !           588:    *The value of this variable is funcalled when source information is not
        !           589: present in Lisp for a symbol.  The function is given one argument, the name
        !           590: for which source is desired (a string).  The null string means use the word
        !           591: at the point as the search word.  This allows the GNU Emacs tags facility
        !           592: to be used when the information is not present in Lisp.
        !           593: 
        !           594: 
        !           595: 
        !           596: plus the following miscellaneous variables:
        !           597: 
        !           598: fi:echo-evals-from-buffer-in-listener-p.............................[variable]
        !           599:    Value: nil
        !           600:    *If non-NIL, forms evalutated directly from a lisp buffer by the
        !           601: fi:lisp-eval-* functions will be echoed by the lisp listener.
        !           602: 
        !           603: 
        !           604: fi:emacs-to-lisp-transaction-directory..............................[variable]
        !           605:    Value: "/tmp"
        !           606:    *The directory in which files for Emacs/Lisp communication are stored.
        !           607: When using Lisp and Emacs on different machines, this directory should be
        !           608: accessible on both machine with the same pathname (via the wonders of NFS).
        !           609: 
        !           610: 
        !           611: fi:subprocess-enable-superkeys......................................[variable]
        !           612:    Value: nil
        !           613:    *If t, certain keys become `superkeys' in subprocess buffers--this
        !           614: should be set before starting any subprocesses.  The superkeys are C-a,
        !           615: C-d, C-o,C-u, C-w, C-z, and C-\, which will behave as they would in the
        !           616: current local keymap when typed at the end of a subprocess buffer.  If
        !           617: typed elsewhere, these keys have their normal global binding.  This is a
        !           618: buffer-local symbol.  Use setq-default to set the default value for this
        !           619: symbol.
        !           620: 
        !           621: 
        !           622: fi:pop-to-sublisp-buffer-after-lisp-eval............................[variable]
        !           623:    Value: t
        !           624:    *If non-nil, then after sending expressions to a Lisp process do pop to
        !           625: the buffer which contains the Lisp.
        !           626: 
        !           627: 
        !           628: fi:display-buffer-function..........................................[variable]
        !           629:    Value: switch-to-buffer
        !           630:    *If non-nil, then it is used as the function which is funcall'd with one
        !           631: argument, a buffer, to display a subprocess buffer when it is created (ie,
        !           632: from `fi:common-lisp').
        !           633: 
        !           634: 
        !           635: fi:lisp-evalserver-timeout..........................................[variable]
        !           636:    Value: 5
        !           637:    The time which fi:eval-in-lisp will wait before timing out and
        !           638: signalling an error.  Without a timeout Emacs would potentially be locked
        !           639: out if Lisp did not `return' a result.
        !           640: 
        !           641: 
        !           642: fi:lisp-evalserver-number-reads.....................................[variable]
        !           643:    Value: 20
        !           644:    The number of times the Lisp eval server tries to read from the
        !           645: lisp-evalserver process before giving up.  Without this feature Emacs would
        !           646: hang if Lisp got into an infinite loop while printing.  If the size of the
        !           647: values returned to Emacs is large, then the value of this variable should
        !           648: be increased.
        !           649: 
        !           650: 
        !           651: 
        !           652:    The following are miscellaneous subprocess variables:
        !           653: 
        !           654: fi:default-input-ring-max...........................................[variable]
        !           655:    Value: 50
        !           656:    *The default maximum length to which an input ring is allowed to grow.
        !           657: 
        !           658: 
        !           659: fi:shell-token-pattern..............................................[variable]
        !           660:    Value: "[   
        !           661: ()<>&|;=]"
        !           662:    *The regular expression used by file name completion to mark path name
        !           663: boundaries.
        !           664: 
        !           665: 
        !           666: fi:subprocess-continuously-show-output-in-visible-buffer............[variable]
        !           667:    Value: t
        !           668:    *If t, output from a subprocess to a visible buffer is continuously
        !           669: shown.  If a subprocess buffer is visible and the window point is beyond
        !           670: the process output marker, output to that buffer from its associated
        !           671: process will be continuously visible.  If the window point is before the
        !           672: process output marker, the window is not updated.  This is a buffer-local
        !           673: symbol.
        !           674: 
        !           675: 
        !           676: 
        !           677:    The following three variables are used to track the shell commands
        !           678: which change the current working directory.  For Common Lisp, the
        !           679: aliases in Appendix A together with these variables will allow Common
        !           680: Lisp to emulate the shell commands and for Emacs to track them:
        !           681: 
        !           682: fi:shell-cd-regexp..................................................[variable]
        !           683:    Value: ":?cd"
        !           684:    *The regular expression matching the C shell `cd' command.  If nil,
        !           685: no automatic directory changes will be made.
        !           686: 
        !           687: 
        !           688: fi:shell-popd-regexp................................................[variable]
        !           689:    Value: ":?popd"
        !           690:    *The regular expression matching the C shell `popd' command.  If nil, no
        !           691: automatic directory changes will be made.
        !           692: 
        !           693: 
        !           694: fi:shell-pushd-regexp...............................................[variable]
        !           695:    Value: ":?pushd"
        !           696:    *The regular expression matching the C shell `pushd' command.  If nil,
        !           697: no automatic directory changes will be made.
        !           698: 
        !           699: 
        !           700: 
        !           701: 3.3 Functions
        !           702: 
        !           703: fi:common-lisp......................................................[function]
        !           704:    Start a Common Lisp subprocess in a buffer whose name is determined
        !           705: from the optional prefix argument BUFFER-NUMBER.  Common Lisp buffer names
        !           706: start with `*common-lisp' and end with `*', with an optional `-N' in
        !           707: between.  If BUFFER-NUMBER is not given it defaults to 1.  If BUFFER-NUMBER
        !           708: is >= 0, then the buffer is named `*common-lisp-<BUFFER-NUMBER>*'.  If
        !           709: BUFFER-NUMBER is < 0, then the first available buffer name is chosen.
        !           710: 
        !           711: The image file and image arguments are taken from the variables
        !           712: `fi:common-lisp-image-name' and `fi:common-lisp-image-arguments'.
        !           713: 
        !           714: See fi:explicit-common-lisp.
        !           715: 
        !           716: 
        !           717: fi:explicit-common-lisp.............................................[function]
        !           718:    The same as fi:common-lisp, except that the image and image arguments
        !           719: are read from the minibuffer.
        !           720: 
        !           721: 
        !           722: fi:remote-common-lisp...............................................[function]
        !           723:    Start a Common Lisp subprocess in a buffer whose name is determined
        !           724: from the optional prefix argument BUFFER-NUMBER, where the Common Lisp
        !           725: image is run on another machine.  Common Lisp buffer names start with
        !           726: `*common-lisp' and end with `*', with an optional `-N' in between.  If
        !           727: BUFFER-NUMBER is not given it defaults to 1.  If BUFFER-NUMBER is >= 0,
        !           728: then the buffer is named `*common-lisp-<BUFFER-NUMBER>*'.  If BUFFER-NUMBER
        !           729: is < 0, then the first available buffer name is chosen.
        !           730: 
        !           731: The host on which the image is run is read from the minibuffer.
        !           732: 
        !           733: The image file and image arguments are taken from the variables
        !           734: `fi:common-lisp-image-name' and `fi:common-lisp-image-arguments'.
        !           735: 
        !           736: See fi:explicit-remote-common-lisp.
        !           737: 
        !           738: 
        !           739: fi:explicit-remote-common-lisp......................................[function]
        !           740:    The same as fi:remote-common-lisp, except that the image and image
        !           741: arguments are read from the minibuffer.
        !           742: 
        !           743: 
        !           744: fi:tcp-common-lisp..................................................[function]
        !           745:    In a buffer whose name is determined from the optional prefix argument
        !           746: BUFFER-NAME, connect to a Common Lisp using either a UNIX domain socket
        !           747: file or internet port number.  Common Lisp buffer names start with
        !           748: `*common-lisp' and end with `*', with an optional `-N' in between.  If
        !           749: BUFFER-NUMBER is not given it defaults to 1.  If BUFFER-NUMBER is >= 0,then
        !           750: the buffer is named `*common-lisp-<BUFFER-NUMBER>*'.  If BUFFER-NUMBER is <
        !           751: 0, then the first available buffer name is chosen.
        !           752: 
        !           753: See `fi:unix-domain' and `fi:explicit-tcp-common-lisp'.
        !           754: 
        !           755: 
        !           756: fi:explicit-tcp-common-lisp.........................................[function]
        !           757:    The same as fi:tcp-common-lisp, except that the host name a port number
        !           758: are read from the minibuffer.  Use a port number of 0 for UNIX domain
        !           759: sockets.
        !           760: 
        !           761: 
        !           762: 
        !           763: fi:inferior-lisp-newline............................................[function]
        !           764:    Invoke with: RET in Inferior Common Lisp mode.
        !           765:    Bound to RET in an inferior Lisp buffer.  At the end of the buffer it
        !           766: inserts a newline and performs automatic indentation.  Whole expressions
        !           767: are sent to Lisp (not each piece after each newline is typed).  This allows
        !           768: previously typed lines to be edited before Lisp is sent the input.  Typed
        !           769: anywhere else in the buffer, this functions causes the input previously
        !           770: typed (around the point) to be copied to the end of the subprocess buffer
        !           771: and send to Lisp.
        !           772: 
        !           773: 
        !           774: fi:inferior-lisp-input-sexp.........................................[function]
        !           775:    Invoke with: ESC RET in Inferior Common Lisp mode.
        !           776:    Send the sexp on which the point resides to the Lisp subprocess.  With a
        !           777: numeric prefix argument, send that many sexps.
        !           778: 
        !           779: 
        !           780: fi:inferior-lisp-input-list.........................................[function]
        !           781:    Invoke with: C-x RET in Inferior Common Lisp mode.
        !           782:    Send the list before the point to the Lisp subprocess.  With a numeric
        !           783: prefix argument, send that many lists.
        !           784: 
        !           785: 
        !           786: fi:subprocess-input-region..........................................[function]
        !           787:    Invoke with: C-c RET in Inferior Common Lisp mode.
        !           788:    Send the region defined by the point and mark to the Lisp subprocess.
        !           789: 
        !           790: 
        !           791: fi:subprocess-kill-input............................................[function]
        !           792:    Invoke with: C-c C-u in Inferior Common Lisp mode.
        !           793:    Kill all input since the last output by the subprocess.
        !           794: 
        !           795: 
        !           796: fi:subprocess-beginning-of-line.....................................[function]
        !           797:    Invoke with: C-c C-a in Inferior Common Lisp mode.
        !           798:    Moves point to beginning of line, just like (beginning-of-line),
        !           799: except that if the pattern at the beginning of the line matches the
        !           800: current subprocess prompt pattern, this function skips over it.
        !           801: 
        !           802: 
        !           803: fi:subprocess-backward-kill-word....................................[function]
        !           804:    Invoke with: C-c C-w in Inferior Common Lisp mode.
        !           805:    Kill previous word in current subprocess input line.  This function
        !           806: takes care not to delete past most recent subprocess output.
        !           807: 
        !           808: 
        !           809: fi:subprocess-kill-output...........................................[function]
        !           810:    Invoke with: C-c C-k in Inferior Common Lisp mode.
        !           811:    Kill all output from the subprocess since the last input.
        !           812: 
        !           813: 
        !           814: fi:subprocess-quit..................................................[function]
        !           815:    Invoke with: C-c C-\ in Inferior Common Lisp mode.
        !           816:    Send a quit signal to the subprocess.
        !           817: 
        !           818: 
        !           819: fi:subprocess-send-flush............................................[function]
        !           820:    Invoke with: C-c C-o in Inferior Common Lisp mode.
        !           821:    Send the `flush output' character (^O) to subprocess.
        !           822: 
        !           823: 
        !           824: fi:subprocess-show-output...........................................[function]
        !           825:    Invoke with: C-c C-v in Inferior Common Lisp mode.
        !           826:    Display the start of this batch of shell output at top of window.
        !           827: Also move the point there.
        !           828: 
        !           829: 
        !           830: fi:subprocess-suspend...............................................[function]
        !           831:    Suspend, with a SIGSTOP, the current subprocess.
        !           832: 
        !           833: 
        !           834: 
        !           835:    The following three functions are used in fi:inferior-lisp-mode to
        !           836: interrupt, kill or input an end-of-file to the Lisp process:
        !           837: 
        !           838: fi:subprocess-interrupt.............................................[function]
        !           839:    Invoke with: C-c C-c in Inferior Common Lisp mode.
        !           840:    Interrupt the current subprocess.
        !           841: 
        !           842: 
        !           843: fi:subprocess-kill..................................................[function]
        !           844:    Send a `kill' (SIGKILL) signal to the current subprocess.
        !           845: 
        !           846: 
        !           847: fi:subprocess-send-eof..............................................[function]
        !           848:    Invoke with: C-c C-d in Inferior Common Lisp mode.
        !           849:    Send an end of file to the subprocess.
        !           850: 
        !           851: 
        !           852: 
        !           853:    The following three functions are used in fi:tcp-common-lisp-mode to
        !           854: interrupt, kill and input an end-of-file to the Lisp process at the
        !           855: other end of the TCP/IP socket:
        !           856: 
        !           857: fi:tcp-lisp-interrupt-process.......................................[function]
        !           858:    Invoke with: C-c C-c in TCP Common Lisp mode.
        !           859:    Interrupt the tcp-lisp process via a mp:process-interrupt spoken to the
        !           860: backdoor Common Lisp listener.
        !           861: 
        !           862: 
        !           863: fi:tcp-lisp-kill-process............................................[function]
        !           864:    Invoke with: C-c C-\ in TCP Common Lisp mode.
        !           865:    Kill a tcp-lisp process via a mp:process-kill spoken to the backdoor
        !           866: Common Lisp listener.
        !           867: 
        !           868: 
        !           869: fi:tcp-lisp-send-eof................................................[function]
        !           870:    Invoke with: C-c C-d in TCP Common Lisp mode.
        !           871:    Simulate an EOF on the tcp-lisp process via a db:debug-pop spoken to the
        !           872: backdoor Common Lisp listener.
        !           873: 
        !           874: 
        !           875: 
        !           876:    All input typed to a subprocess buffer is saved in a ring.  The
        !           877: following functions retrieve input and manipulate the ring:
        !           878: 
        !           879: fi:pop-input........................................................[function]
        !           880:    Invoke with: C-c C-p in Inferior Common Lisp mode.
        !           881:    Yank previous text from input ring.  Cycle through input ring with each
        !           882: successive invocation.
        !           883: 
        !           884: 
        !           885: fi:push-input.......................................................[function]
        !           886:    Invoke with: C-c C-n in Inferior Common Lisp mode.
        !           887:    Yank next text from input ring.  Cycle through input ring in reverse
        !           888: order with each successive invocation.
        !           889: 
        !           890: 
        !           891: fi:list-input-ring..................................................[function]
        !           892:    Invoke with: C-c C-l in Inferior Common Lisp mode.
        !           893:    Display contents of input ring, starting at arg.  The list is displayed
        !           894: in reverse order if called from a program and the optional second parameter
        !           895: is non-nil.
        !           896: 
        !           897: 
        !           898: fi:re-search-backward-input.........................................[function]
        !           899:    Invoke with: C-c C-r in Inferior Common Lisp mode.
        !           900:    Search in input ring for text that contains regexp and yank.
        !           901: 
        !           902: 
        !           903: fi:re-search-forward-input..........................................[function]
        !           904:    Invoke with: C-c C-s in Inferior Common Lisp mode.
        !           905:    Search in input ring for text that contains regexp and yank.
        !           906: 
        !           907: 
        !           908: 
        !           909: plus the following miscellaneous function:
        !           910: 
        !           911: fi:eval-in-lisp.....................................................[function]
        !           912:    Apply format (in Emacs) to STRING and ARGS and evaluate the result
        !           913: in the Common Lisp to which we are connected.  If a lisp-eval-server has
        !           914: not been started, then this function starts it.
        !           915: 
        !           916: 
        !           917: 
        !           918: 3.4 Hooks
        !           919: 
        !           920:    The hooks run at the end of Inferior Common Lisp mode
        !           921: initialization are:
        !           922: 
        !           923:        fi:lisp-mode-hook
        !           924:        fi:subprocess-mode-hook
        !           925:        fi:inferior-common-lisp-mode-hook
        !           926: 
        !           927: and for TCP Common Lisp mode are:
        !           928: 
        !           929:        fi:lisp-mode-hook
        !           930:        fi:subprocess-mode-hook
        !           931:        fi:tcp-common-lisp-mode-hook
        !           932: 
        !           933: 4. Starting the Interface
        !           934: 
        !           935:    The two parts of the (full) interface which require user setup are:
        !           936: 
        !           937:        * running Lisp as an inferior of Emacs, with a "Lisp
        !           938:          listener daemon" listening for connections from Emacs
        !           939:        * a set of Emacs bindings that query Lisp for information
        !           940:        
        !           941: In this sections the setup of these features will be discussed.
        !           942: 
        !           943: 4.1 Setup
        !           944: 
        !           945:    (After the installation procedure has been followed (see the file
        !           946: INSTALL in the main distribution directory) the interface will be in a
        !           947: subdirectory of the `lisp' directory.  Typically the location is
        !           948: /usr/local/lib/emacs, which is the pathname used throughout the rest
        !           949: of this document.)
        !           950: 
        !           951:    The Lisp part of the interface consists of a Lisp process called
        !           952: the "Lisp listener daemon" which lies dormant until Emacs tries to
        !           953: communicate with it.  When Emacs "connects" an interactive top level
        !           954: is started (called a "read-eval-print" loop) to which Emacs can send
        !           955: expressions for evaluation and from which Emacs receives the results
        !           956: of evaluation (see fi:eval-in-lisp).  The preferred method to start
        !           957: this daemon is to put the following in your .login file:
        !           958: 
        !           959:        setenv EMACSLIBRARY /usr/local/lib/emacs
        !           960: 
        !           961: and to put the following in your .clinit.cl file in your home directory:
        !           962: 
        !           963:        (defparameter *emacs-library*
        !           964:          (let ((emacs-lib (si:getenv "EMACSLIBRARY")))
        !           965:            (if emacs-lib (format nil "~a/lisp/fi/" emacs-lib))))
        !           966: 
        !           967:        (and *emacs-library*
        !           968:             (find "+ipc" (system:command-line-arguments) :test #'string=)
        !           969:             (load (merge-pathnames "clinit.cl" *emacs-library*))
        !           970:             (load-and-start-ipc-package))
        !           971: 
        !           972: and to put the following in your .emacs file in your home directory:
        !           973: 
        !           974:        (load "fi/site-init.el")
        !           975: 
        !           976:        (setq fi:common-lisp-image-arguments '("+ipc"))
        !           977: 
        !           978:        (setq fi:unix-domain-socket
        !           979:          (format "/tmp/%s_emacs_to_acl" (user-login-name)))
        !           980: 
        !           981: Now consider the following typed to Emacs:
        !           982: 
        !           983:        M-x fi:common-lisp RET
        !           984: 
        !           985: This will cause a Common Lisp (the default image name is `cl') to be
        !           986: started in a buffer called `*common-lisp*', as an inferior process of
        !           987: Emacs.  This Common Lisp will be passed a command line argument of
        !           988: `+ipc', which will cause Common Lisp to load and start the Lisp
        !           989: listener daemon.  Emacs and Common Lisp will communicate through a
        !           990: UNIX domain socket (a file) in /tmp called `USER_emacs_to_acl', where
        !           991: USER is the currently-logged-in-user's name.  All of the bindings and
        !           992: functions described above are now available.
        !           993: 
        !           994: 
        !           995: 4.2 Examples
        !           996: 
        !           997:    After fi:common-lisp has started a Common Lisp and all the above
        !           998: modifications to .emacs and .clinit.cl have been made, the following
        !           999: Emacs command will open a second buffer onto the same Lisp.  This
        !          1000: listener is a separate Common Lisp process (as opposed to a separate
        !          1001: Operating System process) and the entire Common Lisp environment
        !          1002: available in the first listener is available in this one:
        !          1003: 
        !          1004:        M-x fi:tcp-common-lisp RET
        !          1005: 
        !          1006: To run a second Common Lisp and get a completely fresh Common Lisp:
        !          1007: 
        !          1008:        C-u 2 M-x fi:common-lisp RET
        !          1009: 
        !          1010: The former uses one Common Lisp for multiple purposes (compiling a
        !          1011: program in one buffer while typing forms to another), while the latter
        !          1012: starts two separate Common Lisp processes, and thus uses twice the
        !          1013: memory and swap space.
        !          1014: 
        !          1015: 
        !          1016: 4.2.1 Remote Common Lisps using TCP/IP
        !          1017: 
        !          1018:    It is possible, with the functions and bindings in this interface,
        !          1019: to run an Emacs and Common Lisp on two different machines.  For
        !          1020: example, to run Emacs on a machine called `snooze' and Common Lisp on
        !          1021: one called `akbar', where both machines are accessible on the network,
        !          1022: ~/.emacs on `snooze' would contain:
        !          1023: 
        !          1024:        (setq fi:unix-domain nil)
        !          1025:        (setq fi:local-host-name "akbar")       ; the remote host name
        !          1026: 
        !          1027: and ~/.clinit.cl on `akbar' would contain the forms given in section
        !          1028: 4.1 with the call to load-and-start-ipc-package replaced with:
        !          1029: 
        !          1030:        (load-and-start-ipc-package :unix-domain nil)
        !          1031: 
        !          1032: Then, make sure the value of ipc::*inet-port* in ipc.cl and
        !          1033: fi:excl-service-name in tcplisp.el (all in the lisp/fi directory)
        !          1034: match what is in /etc/services.  For the interface as distributed, put
        !          1035: the following line in /etc/services:
        !          1036: 
        !          1037:        excl            6789/tcp
        !          1038: 
        !          1039: on both `akbar' and `snooze'.
        !          1040: 
        !          1041: Then, on `akbar', possibly in a shell buffer remotely logged into
        !          1042: `akbar', startup Common Lisp with the +ipc argument:
        !          1043: 
        !          1044:        akbar% cl +ipc
        !          1045: 
        !          1046: (If you get the error "bind: Address already in use" then the port
        !          1047: number you chose is already being used by another program.  In this
        !          1048: case, use something other than 6789 (in the default case) or the one
        !          1049: currently being used.)  Then, on `snooze' do:
        !          1050: 
        !          1051:        M-x fi:tcp-common-lisp RET
        !          1052: 
        !          1053: which will open a connection to the Lisp on `akbar' from `snooze'.
        !          1054: 
        !          1055: 
        !          1056: 4.2.2 Remote Common Lisps using `rsh'
        !          1057: 
        !          1058:    It is also possible to run Common Lisp on another machine using
        !          1059: `rsh'.  For example, typing the following to Emacs will start a Lisp
        !          1060: process on host `akbar' without using the TCP/IP connection between
        !          1061: Common Lisp and Emacs:
        !          1062: 
        !          1063:        M-x fi:remote-common-lisp RET akbar RET
        !          1064: 
        !          1065: NOTE: fi:remote-common-lisp uses fi:common-lisp-image-name to
        !          1066: determine which image to activate.  If the image name is incorrect for
        !          1067: the remote machine, then use fi:explicit-remote-common-lisp.
        !          1068: 
        !          1069:                              Appendix A
        !          1070:                            Sample .emacs
        !          1071: 
        !          1072: ;;                             -[Fri Nov 18 18:53:13 1988 by layer]-
        !          1073: ;; Sample .emacs file
        !          1074: ;;
        !          1075: ;; $Header: dot.emacs,v 1.1 88/11/18 19:00:50 layer Exp $
        !          1076: 
        !          1077: (load "fi/site-init.el")
        !          1078: 
        !          1079: ;; use a socket file in /tmp since can't communicate via files on NFS
        !          1080: ;; mounted file systems
        !          1081: ;;
        !          1082: (setq fi:unix-domain-socket
        !          1083:   (format "/tmp/%s_emacs_to_acl" (user-login-name)))
        !          1084: 
        !          1085: ;; turn on superkeys in subprocess modes
        !          1086: ;;
        !          1087: (setq-default fi:subprocess-enable-superkeys t)
        !          1088: 
        !          1089: ;; the following causes fi:common-lisp to give the inferior Common
        !          1090: ;; Lisp, by default, a command line argument of `+ipc':
        !          1091: ;;
        !          1092: (setq fi:common-lisp-image-arguments '("+ipc"))
        !          1093: 
        !          1094: ;; the following causes fi:common-lisp to invoke the image `acl', but
        !          1095: ;; to ask for an image name when given a prefix argument:
        !          1096: ;;
        !          1097: (setq fi:common-lisp-image-name
        !          1098:   '(lambda ()
        !          1099:     (let ((image "acl"))
        !          1100:       (if current-prefix-arg
        !          1101:          (setq image
        !          1102:            (read-file-name (format "cl image (default: %s): " image)
        !          1103:                            default-directory image nil)))
        !          1104:       (setq mode-line-buffer-identification
        !          1105:        (format "%s (%s)" (buffer-name) (file-name-nondirectory image)))
        !          1106:       image)))
        !          1107: 
        !          1108: ;; This redefines `kill-emacs' so that transaction files in /tmp are
        !          1109: ;; removed emacs is killed:
        !          1110: ;;
        !          1111: (fset 'old-kill-emacs (symbol-function 'kill-emacs))
        !          1112: (defun kill-emacs (&optional arg)
        !          1113:   (interactive "P")
        !          1114:   (fi:remove-all-temporary-lisp-transaction-files)
        !          1115:   (old-kill-emacs arg))
        !          1116: 
        !          1117:                              Appendix B
        !          1118:                          Sample .clinit.cl
        !          1119: 
        !          1120: ;;                             -[Fri Nov 18 19:00:37 1988 by layer]-
        !          1121: ;; Sample .clinit.cl file
        !          1122: ;;
        !          1123: ;; $Header: dot.clinit.cl,v 1.1 88/11/18 19:00:54 layer Exp $
        !          1124: 
        !          1125: (format t "; Loading home clinit...~%")
        !          1126: 
        !          1127: (defparameter *emacs-library*
        !          1128:   (let ((emacs-lib (si:getenv "EMACSLIBRARY")))
        !          1129:     (if emacs-lib (format nil "~a/lisp/fi/" emacs-lib))))
        !          1130: 
        !          1131: (and *emacs-library*
        !          1132:      (find "+ipc" (system:command-line-arguments) :test #'string=)
        !          1133:      (load (merge-pathnames "clinit.cl" *emacs-library*))
        !          1134:      (load-and-start-ipc-package :unix-domain nil))
        !          1135: 
        !          1136: ;; The following emulates the C shell cd, pushd, popd, pwd, and dirs,
        !          1137: ;; and allows Emacs to track directory changes:
        !          1138: 
        !          1139: (defvar *directory-stack*
        !          1140:   (list (namestring
        !          1141:         (setq *default-pathname-defaults* (current-directory)))))
        !          1142: 
        !          1143: (tpl:alias ("pushd" :string) (&optional dir)
        !          1144:   (if* (string= "" dir)
        !          1145:      then (let ((old-top (pop *directory-stack*))
        !          1146:                (new-top (pop *directory-stack*)))
        !          1147:            (push old-top *directory-stack*)
        !          1148:            (push (chdir new-top) *directory-stack*))
        !          1149:      else (push (chdir dir) *directory-stack*))
        !          1150:   (format t "~a~%" *directory-stack*))
        !          1151: 
        !          1152: (tpl:alias "popd" ()
        !          1153:   (if (> (length *directory-stack*) 1)
        !          1154:       (pop *directory-stack*)
        !          1155:     (format t "nothing to pop into~%"))
        !          1156:   (chdir (car *directory-stack*))
        !          1157:   (format t "~a~%" *directory-stack*))
        !          1158: 
        !          1159: (tpl:alias "dirs" ()
        !          1160:   (format t "~a~%" *directory-stack*))
        !          1161: 
        !          1162: (tpl:alias ("cd" :string) (dir)
        !          1163:   (setf (car *directory-stack*)
        !          1164:     (apply #'chdir
        !          1165:           (if (string= "" dir) nil (list dir))))
        !          1166:   (format t "~a~%" *directory-stack*))
        !          1167: 
        !          1168: (tpl:alias "pwd" ()
        !          1169:   (format t "process cwd = ~a~%*default-pathname-defaults* = ~a~%"
        !          1170:          (namestring (current-directory))
        !          1171:          (namestring (truename *default-pathname-defaults*))))
        !          1172: 
        !          1173:                              Appendix C
        !          1174:                        Sample X11 interaction
        !          1175: 
        !          1176: ;;                             -[Fri Nov 18 20:21:56 1988 by layer]-
        !          1177: ;; Sample X11 bindings for .emacs file
        !          1178: ;;
        !          1179: ;; $Header: dot.emacs_x11,v 1.1 88/11/18 20:22:52 layer Exp $
        !          1180: 
        !          1181: (require 'x-mouse)
        !          1182: 
        !          1183: (defun x-lisp-find-tag (arg)
        !          1184:   (x-mouse-set-point arg)
        !          1185:   (cond ((eq major-mode 'fi:common-lisp-mode) (fi:lisp-find-tag))
        !          1186:        (t (find-tag-other-window (find-tag-default)))))
        !          1187: 
        !          1188: (defun x-lisp-eval-defun (arg)
        !          1189:   (x-mouse-set-point arg)
        !          1190:   (cond ((memq major-mode '(fi:common-lisp-mode fi:franz-lisp-mode
        !          1191:                            fi:lisp-mode))
        !          1192:         (fi:lisp-eval-defun nil))
        !          1193:        ((eq major-mode 'fi:emacs-lisp-mode) (eval-defun))))
        !          1194: 
        !          1195: (defun x-lisp-arglist (arg)
        !          1196:   (x-mouse-set-point arg)
        !          1197:   (cond ((eq major-mode 'fi:common-lisp-mode) (fi:lisp-arglist))
        !          1198:        (t (describe-function (intern (find-tag-default))))))
        !          1199: 
        !          1200: (define-key mouse-map x-button-left-up 'x-lisp-find-tag)
        !          1201: (define-key mouse-map x-button-middle-up 'x-lisp-eval-defun)
        !          1202: (define-key mouse-map x-button-right-up 'x-lisp-arglist)
        !          1203: 
        !          1204: ;; we ignore mouse button-down events, because if we put something
        !          1205: ;; on it the `up' event will cause the minibuffer output to disappear
        !          1206: (define-key mouse-map x-button-left 'x-mouse-ignore)
        !          1207: (define-key mouse-map x-button-middle 'x-mouse-ignore)
        !          1208: (define-key mouse-map x-button-right 'x-mouse-ignore)
        !          1209: (define-key mouse-map x-button-c-left 'x-mouse-ignore)
        !          1210: 
        !          1211:                              Appendix D
        !          1212:                          Franz Lisp Support
        !          1213: 
        !          1214: D.1 Introduction
        !          1215: 
        !          1216:    Franz Lisp is handled very similar to Common Lisp, the only
        !          1217: difference being that Franz Lisp does not support TCP/IP socket
        !          1218: communication.  In all other ways, the features, function and variable
        !          1219: names mirror those of the corresponding Common Lisp functions and
        !          1220: variables.
        !          1221: 
        !          1222: D.2 Editing Franz Lisp
        !          1223: 
        !          1224:    As with Common Lisp, editing a Franz Lisp source file (.l
        !          1225: extension) causes fi:franz-lisp-mode to be invoked.  The order of
        !          1226: setup in the mode follows that of fi:common-lisp-mode.
        !          1227: 
        !          1228:    Package system set-up also occurs in the same way as in
        !          1229: fi:common-lisp-mode.
        !          1230: 
        !          1231:    Franz Lisp does not support the commands depending on TCP/IP.
        !          1232: 
        !          1233: D.2.1 Bindings
        !          1234: 
        !          1235: fi:franz-lisp-mode-map................................................[keymap]
        !          1236:    Major mode map used when editing Franz Lisp source.
        !          1237: 
        !          1238: C-c             Prefix Command
        !          1239: RET             fi:lisp-reindent-newline-indent
        !          1240: DEL             backward-delete-char-untabify
        !          1241: TAB             lisp-indent-line
        !          1242: C-x             Prefix Command
        !          1243: ESC             Prefix Command
        !          1244: 
        !          1245: C-c C-r         fi:lisp-eval-region
        !          1246: C-c C-s         fi:lisp-eval-last-sexp
        !          1247: C-c C-b         fi:lisp-eval-current-buffer
        !          1248: 
        !          1249: ESC C-x         fi:lisp-eval-defun
        !          1250: ESC C-q         indent-sexp
        !          1251: 
        !          1252: 
        !          1253: 
        !          1254: 
        !          1255: D.2.2 Variables
        !          1256: 
        !          1257:    The buffer-local variable fi:package is set up as in
        !          1258: fi:common-lisp-mode.
        !          1259: 
        !          1260: D.2.3 Functions
        !          1261: 
        !          1262:    The functions in the keymaps are a subset of those in Common Lisp
        !          1263: mode--refer to the main document for a description of those commands.
        !          1264: 
        !          1265: D.2.4 Hooks
        !          1266: 
        !          1267:    The hooks run are fi:lisp-mode-hook and fi:franz-lisp-mode-hook,
        !          1268: and are done last in the mode initialization.
        !          1269: 
        !          1270: D.3 Running Franz Lisp
        !          1271: 
        !          1272:    As with Common Lisp, there are two entry points for running an
        !          1273: inferior Franz Lisp. `M-x fi:franz-lisp' and `M-x fi:explicit-franz-lisp'
        !          1274: create Franz Lisp processes.  The default name of the Franz Lisp image
        !          1275: is `lisp'.
        !          1276: 
        !          1277: D.3.1 Bindings
        !          1278: 
        !          1279: fi:inferior-franz-lisp-mode-map.......................................[keymap]
        !          1280:    The inferior-franz-lisp major-mode keymap.
        !          1281: 
        !          1282: DEL             backward-delete-char-untabify
        !          1283: TAB             lisp-indent-line
        !          1284: C-x             Prefix Command
        !          1285: ESC             Prefix Command
        !          1286: C-c             Prefix Command
        !          1287: RET             fi:inferior-lisp-newline
        !          1288: 
        !          1289: C-c C-\         fi:subprocess-quit
        !          1290: C-c C-d         fi:subprocess-send-eof
        !          1291: C-c C-c         fi:subprocess-interrupt
        !          1292: C-c C-w         fi:subprocess-backward-kill-word
        !          1293: C-c C-v         fi:subprocess-show-output
        !          1294: C-c C-u         fi:subprocess-kill-input
        !          1295: C-c C-s         fi:re-search-forward-input
        !          1296: C-c C-r         fi:re-search-backward-input
        !          1297: C-c C-p         fi:pop-input
        !          1298: C-c C-o         fi:subprocess-send-flush
        !          1299: C-c C-n         fi:push-input
        !          1300: C-c RET         fi:subprocess-input-region
        !          1301: C-c C-l         fi:list-input-ring
        !          1302: C-c C-k         fi:subprocess-kill-output
        !          1303: C-c C-a         fi:subprocess-beginning-of-line
        !          1304: 
        !          1305: C-x RET         fi:inferior-lisp-input-list
        !          1306: 
        !          1307: ESC RET         fi:inferior-lisp-input-sexp
        !          1308: ESC C-q         indent-sexp
        !          1309: 
        !          1310: 
        !          1311: 
        !          1312: 
        !          1313: D.3.2 Variables
        !          1314: 
        !          1315: fi:franz-lisp-image-name............................................[variable]
        !          1316:    Value: "lisp"
        !          1317:    *Default Franz Lisp image to invoke from `fi:franz-lisp'.  If the value
        !          1318: is a string then it names the image file or image path that
        !          1319: `fi:common-lisp' invokes.  Otherwise, the value of this variable is given
        !          1320: to funcall, the result of which should yield a string which is the image
        !          1321: name or path.
        !          1322: 
        !          1323: 
        !          1324: fi:franz-lisp-image-arguments.......................................[variable]
        !          1325:    Value: nil
        !          1326:    *Default Franz Lisp image arguments when invoked from `fi:franz-lisp'.
        !          1327: 
        !          1328: 
        !          1329: fi:franz-lisp-prompt-pattern........................................[variable]
        !          1330:    Value: "^[-=]> +\\|^c{[0-9]+} +"
        !          1331:    *The regular expression which matches the Franz Lisp prompt, used in
        !          1332: Inferior Franz Lisp mode.  Anything from beginning of line up to the end
        !          1333: of what this pattern matches is deemed to be a prompt.
        !          1334: 
        !          1335: 
        !          1336: 
        !          1337: D.3.3 Functions
        !          1338: 
        !          1339: fi:franz-lisp.......................................................[function]
        !          1340:    Start a Franz Lisp subprocess in a buffer whose name is determined
        !          1341: from the optional prefix argument BUFFER-NUMBER.  Franz Lisp buffer names
        !          1342: start with `*franz-lisp' and end with `*', with an optional `-N' in
        !          1343: between.  If BUFFER-NUMBER is not given it defaults to 1.  If BUFFER-NUMBER
        !          1344: is >= 0, then the buffer is named `*franz-lisp-<BUFFER-NUMBER>*'.  If
        !          1345: BUFFER-NUMBER is < 0, then the first available buffer name is chosen.
        !          1346: 
        !          1347: The image file and image arguments are taken from the variables
        !          1348: `fi:franz-lisp-image-name' and `fi:franz-lisp-image-arguments'.
        !          1349: 
        !          1350: See fi:explicit-franz-lisp.
        !          1351: 
        !          1352: 
        !          1353: fi:explicit-franz-lisp..............................................[function]
        !          1354:    The same as fi:franz-lisp, except that the image and image arguments
        !          1355: are read from the minibuffer.
        !          1356: 
        !          1357: 
        !          1358: 
        !          1359: D.3.3 Hooks
        !          1360: 
        !          1361:    The following hooks are run when starting up an inferior Franz
        !          1362: Lisp:
        !          1363: 
        !          1364:        fi:lisp-mode-hook
        !          1365:        fi:subprocess-mode-hook
        !          1366:        fi:inferior-franz-lisp-mode-hook

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.