1
0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-12-25 10:47:00 +00:00
emacs/lisp/tpu-doc.el
1994-06-20 22:22:58 +00:00

470 lines
21 KiB
EmacsLisp

;;; tpu-doc.el --- Documentation for TPU-edt
;; Copyright (C) 1993, 1994 Free Software Foundation, Inc.
;; Author: Rob Riepel <riepel@networking.stanford.edu>
;; Maintainer: Rob Riepel <riepel@networking.stanford.edu>
;; Keywords: emulations
;; This file is part of GNU Emacs.
;; GNU Emacs is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 2, or (at your option)
;; any later version.
;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING. If not, write to
;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
;; This is documentation for the TPU-edt editor for GNU emacs. Major
;; sections of this document are separated with lines that begin with
;; ";; %% <topic>", where <topic> is what is discussed in that section.
;; %% Contents
;; % Introduction
;; % Terminal Support
;; % X-windows Support
;; % Differences Between TPU-edt and the Real Thing
;; % Starting TPU-edt
;; % TPU-edt Default Editing Keypad, Control and Gold Key Bindings
;; % Optional TPU-edt Extensions
;; % Customizing TPU-edt using the Emacs Initialization File
;; % Compiling TPU-edt
;; % Regular expressions in TPU-edt
;; % Etcetera
;; %% Introduction
;; TPU-edt is based on tpu.el by Jeff Kowalski and Bob Covey. TPU-edt
;; endeavors to be even more like TPU's EDT emulation than the original
;; tpu.el. Considerable effort has been expended to that end. Still,
;; emacs is emacs and there are differences between TPU-edt and the
;; real thing. Please read the "Differences Between TPU-edt and the
;; Real Thing" and "Starting TPU-edt" sections before running TPU-edt.
;; %% Terminal Support
;; TPU-edt, like it's VMS cousin, works on VT-series terminals with
;; DEC style keyboards. VT terminal emulators, including xterm with
;; the appropriate key translations, work just fine too.
;; %% X-windows Support
;; Starting with version 19 of emacs, TPU-edt works with X-windows.
;; This is accomplished through a TPU-edt X keymap. The emacs lisp
;; program tpu-mapper.el creates this map and stores it in a file.
;; Tpu-mapper will be run automatically the first time you invoke
;; the X-windows version of emacs, or you can run it by hand. See
;; the commentary in tpu-mapper.el for details.
;; %% Differences Between TPU-edt and the Real Thing (not Coke (r))
;; Emacs (version 18.58) doesn't support text highlighting, so selected
;; regions are not shown in inverse video. Emacs uses the concept of
;; "the mark". The mark is set at one end of a selected region; the
;; cursor is at the other. The letter "M" appears in the mode line
;; when the mark is set. The native emacs command ^X^X (Control-X
;; twice) exchanges the cursor with the mark; this provides a handy
;; way to find the location of the mark.
;; In TPU the cursor can be either bound or free. Bound means the
;; cursor cannot wander outside the text of the file being edited.
;; Free means the arrow keys can move the cursor past the ends of
;; lines. Free is the default mode in TPU; bound is the only mode
;; in EDT. Bound is the only mode in the base version of TPU-edt;
;; optional extensions add an approximation of free mode.
;; Like TPU, emacs uses multiple buffers. Some buffers are used to
;; hold files you are editing; other "internal" buffers are used for
;; emacs' own purposes (like showing you help). Here are some commands
;; for dealing with buffers.
;; Gold-B moves to next buffer, including internal buffers
;; Gold-N moves to next buffer containing a file
;; Gold-M brings up a buffer menu (like TPU "show buffers")
;; Emacs is very fond of throwing up new windows. Dealing with all
;; these windows can be a little confusing at first, so here are a few
;; commands to that may help:
;; Gold-Next_Scr moves to the next window on the screen
;; Gold-Prev_Scr moves to the previous window on the screen
;; Gold-TAB also moves to the next window on the screen
;; Control-x 1 deletes all but the current window
;; Control-x 0 deletes the current window
;; Note that the buffers associated with deleted windows still exist!
;; Like TPU, TPU-edt has a "command" function, invoked with Gold-KP7 or
;; Do. Most of the commands available are emacs commands. Some TPU
;; commands are available, they are: replace, exit, quit, include, and
;; Get (unfortunately, "get" is an internal emacs function, so we are
;; stuck with "Get" - to make life easier, Get is available as Gold-g).
;; Support for recall of commands, file names, and search strings was
;; added to emacs in version 19. For version 18 of emacs, optional
;; extensions are available to add this recall capability (see "Optional
;; TPU-edt Extensions" below). The history of strings recalled in both
;; versions of emacs differs slightly from TPU/edt, but it is still very
;; convenient.
;; Help is available! The traditional help keys (Help and PF2) display
;; a three page help file showing the default keypad layout, control key
;; functions, and Gold key functions. Pressing any key inside of help
;; splits the screen and prints a description of the function of the
;; pressed key. Gold-PF2 invokes the native emacs help, with it's
;; zillions of options. Gold-Help shows all the current key bindings.
;; Thanks to emacs, TPU-edt has some extensions that may make your life
;; easier, or at least more interesting. For example, Gold-r toggles
;; TPU-edt rectangular mode. In rectangular mode, Remove and Insert work
;; on rectangles. Likewise, Gold-* toggles TPU-edt regular expression
;; mode. In regular expression mode Find, Find Next, and the line-mode
;; replace command work with regular expressions. [A regular expression
;; is a pattern that denotes a set of strings; like VMS wildcards.]
;; Emacs also gives TPU-edt the undo and occur functions. Undo does
;; what it says; it undoes the last change. Multiple undos in a row
;; undo multiple changes. For your convenience, undo is available on
;; Gold-u. Occur shows all the lines containing a specific string in
;; another window. Moving to that window, and typing ^C^C (Control-C
;; twice) on a particular line moves you back to the original window
;; at that line. Occur is on Gold-o.
;; Finally, as you edit, remember that all the power of emacs is at
;; your disposal. It really is a fantastic tool. You may even want to
;; take some time and read the emacs tutorial; perhaps not to learn the
;; native emacs key bindings, but to get a feel for all the things
;; emacs can do for you. The emacs tutorial is available from the
;; emacs help function: "Gold-PF2 t"
;; %% Starting TPU-edt
;; In order to use TPU-edt, the TPU-edt editor definitions, contained
;; in tpu-edt.el, need to be loaded when emacs is run. This can be
;; done in a couple of ways. The first is by explicitly requesting
;; loading of the TPU-edt emacs definition file on the command line:
;; prompt> emacs -l /path/to/definitions/tpu-edt.el
;; If TPU-edt is installed on your system, that is, if tpu-edt.el is in
;; a directory like /usr/local/emacs/lisp, along with dozens of other
;; .el files, you should be able to use the command:
;; prompt> emacs -l tpu-edt
;; If you like TPU-edt and want to use it all the time, you can load
;; the TPU-edt definitions using the emacs initialization file, .emacs.
;; Simply create a .emacs file in your home directory containing the
;; line:
;; (load "/path/to/definitions/tpu-edt")
;; or, if (as above) TPU-edt is installed on your system:
;; (load "tpu-edt")
;; Once TPU-edt has been loaded, you will be using an editor with the
;; interface shown in the next section (A section that is suitable for
;; cutting out of this document and pasting next to your terminal!).
;; %% TPU-edt Default Editing Keypad, Control and Gold Key Bindings
;;
;; _______________________ _______________________________
;; | HELP | Do | | | | | |
;; |KeyDefs| | | | | | |
;; |_______|_______________| |_______|_______|_______|_______|
;; _______________________ _______________________________
;; | Find |Insert |Remove | | Gold | HELP |FndNxt | Del L |
;; | | |Sto Tex| | key |E-Help | Find |Undel L|
;; |_______|_______|_______| |_______|_______|_______|_______|
;; |Select |Pre Scr|Nex Scr| | Page | Sect |Append | Del W |
;; | Reset |Pre Win|Nex Win| | Do | Fill |Replace|Undel W|
;; |_______|_______|_______| |_______|_______|_______|_______|
;; |Move up| |Forward|Reverse|Remove | Del C |
;; | Top | |Bottom | Top |Insert |Undel C|
;; _______|_______|_______ |_______|_______|_______|_______|
;; |Mov Lef|Mov Dow|Mov Rig| | Word | EOL | Char | |
;; |StaOfLi|Bottom |EndOfLi| |ChngCas|Del EOL|SpecIns| Enter |
;; |_______|_______|_______| |_______|_______|_______| |
;; | Line |Select | Subs |
;; | Open Line | Reset | |
;; |_______________|_______|_______|
;; Control Characters
;;
;; ^A toggle insert and overwrite ^L insert page break
;; ^B recall ^R remember, re-center
;; ^E end of line ^U delete to beginning of line
;; ^G cancel current operation ^V quote
;; ^H beginning of line ^W refresh
;; ^J delete previous word ^Z exit
;; ^K learn ^X^X exchange point and mark
;;
;;
;; Gold-<key> Functions
;; -----------------------------------------------------------------
;; W Write - save current buffer
;; K Kill buffer - abandon edits and delete buffer
;;
;; E Exit - save current buffer and ask about others
;; X eXit - save all modified buffers and exit
;; Q Quit - exit without saving anything
;;
;; G Get - load a file into a new edit buffer
;; I Include - include a file in this buffer
;;
;; B next Buffer - display the next buffer (all buffers)
;; N Next file buffer - display next buffer containing a file
;; M buffer Menu - display a list of all buffers
;;
;; U Undo - undo the last edit
;; C Recall - edit and possibly repeat previous commands
;;
;; O Occur - show following lines containing REGEXP
;; S Search and substitute - line mode REPLACE command
;;
;; ? Spell check - check spelling in a region or entire buffer
;;
;; R Toggle Rectangular mode for remove and insert
;; * Toggle regular expression mode for search and substitute
;;
;; V Show TPU-edt version
;; -----------------------------------------------------------------
;; %% Optional TPU-edt Extensions
;; Several optional packages have been included in this distribution
;; of TPU-edt. The following is a brief description of each package.
;; See the {package}.el file for more detailed information and usage
;; instructions.
;; tpu-extras - TPU/edt scroll margins and free cursor mode.
;; tpu-recall - String, file name, and command history.
;; vt-control - VTxxx terminal width and keypad controls.
;; Packages are normally loaded from the emacs initialization file
;; (discussed below). If a package is not installed in the emacs
;; lisp directory, it can be loaded by specifying the complete path
;; to the package file. However, it is preferable to modify the
;; emacs load-path variable to include the directory where packages
;; are stored. This way, packages can be loaded by name, just as if
;; they were installed. The first part of the sample .emacs file
;; below shows how to make such a modification.
;; %% Customizing TPU-edt using the Emacs Initialization File
;; .emacs - a sample emacs initialization file
;; This is a sample emacs initialization file. It shows how to invoke
;; TPU-edt, and how to customize it.
;; The load-path is where emacs looks for files to fulfill load requests.
;; If TPU-edt is not installed in a standard emacs directory, the load-path
;; should be updated to include the directory where the TPU-edt files are
;; stored. Modify and un-comment the following section if TPU-ed is not
;; installed on your system - be sure to leave the double quotes!
;; (setq load-path
;; (append (list (expand-file-name "/path/to/tpu-edt/files"))
;; load-path))
;; Load TPU-edt
(load "tpu-edt")
;; Load the optional goodies - scroll margins, free cursor mode, command
;; and string recall. But don't complain if the file aren't available.
(load "tpu-extras" t)
(load "tpu-recall" t)
;; Uncomment this line to set scroll margins 10% (top) and 15% (bottom).
;(and (fboundp 'tpu-set-scroll-margins) (tpu-set-scroll-margins "10%" "15%"))
;; Load the vtxxx terminal control functions, but don't complain if
;; if the file is not found.
(load "vt-control" t)
;; TPU-edt treats words like EDT; here's how to add word separators.
;; Note that backslash (\) and double quote (") are quoted with '\'.
(tpu-add-word-separators "]\\[-_,.\"=+()'/*#:!&;$")
;; Emacs is happy to save files without a final newline; other Unix programs
;; hate that! This line will make sure that files end with newlines.
(setq require-final-newline t)
;; Emacs has the ability to automatically run code embedded in files
;; you edit. This line makes emacs ask if you want to run the code.
(if tpu-emacs19-p (setq enable-local-variables "ask")
(setq inhibit-local-variables t))
;; Emacs uses Control-s and Control-q. Problems can occur when using emacs
;; on terminals that use these codes for flow control (Xon/Xoff flow control).
;; These lines disable emacs' use of these characters.
(global-unset-key "\C-s")
(global-unset-key "\C-q")
;; top, bottom, bol, eol seem like a waste of Gold-arrow functions. The
;; following section re-maps up and down arrow keys to top and bottom of
;; screen, and left and right arrow keys to pan left and right (pan-left,
;; right moves the screen 16 characters left or right - try it, you'll
;; like it!).
;; Re-map the Gold-arrow functions
(define-key GOLD-CSI-map "A" 'tpu-beginning-of-window) ; up-arrow
(define-key GOLD-CSI-map "B" 'tpu-end-of-window) ; down-arrow
(define-key GOLD-CSI-map "C" 'tpu-pan-right) ; right-arrow
(define-key GOLD-CSI-map "D" 'tpu-pan-left) ; left-arrow
(define-key GOLD-SS3-map "A" 'tpu-beginning-of-window) ; up-arrow
(define-key GOLD-SS3-map "B" 'tpu-end-of-window) ; down-arrow
(define-key GOLD-SS3-map "C" 'tpu-pan-right) ; right-arrow
(define-key GOLD-SS3-map "D" 'tpu-pan-left) ; left-arrow
;; Re-map the Gold-arrow functions for X-windows TPU-edt (emacs version 19)
(cond
((and tpu-emacs19-p window-system)
(define-key GOLD-map [up] 'tpu-beginning-of-window) ; up-arrow
(define-key GOLD-map [down] 'tpu-end-of-window) ; down-arrow
(define-key GOLD-map [right] 'tpu-pan-right) ; right-arrow
(define-key GOLD-map [left] 'tpu-pan-left))) ; left-arrow
;; The emacs universal-argument function is very useful for native emacs
;; commands. This line maps universal-argument to Gold-PF1
(define-key GOLD-SS3-map "P" 'universal-argument) ; Gold-PF1
;; Make KP7 move by paragraphs, instead of pages.
(define-key SS3-map "w" 'tpu-paragraph) ; KP7
;; TPU-edt assumes you have the ispell spelling checker;
;; Un-comment this line if you don't.
;(setq tpu-have-spell nil)
;; Display the TPU-edt version.
(tpu-version)
;; End of .emacs - a sample emacs initialization file
;; After initialization with the .emacs file shown above, the editing
;; keys have been re-mapped to look like this:
;; _______________________ _______________________________
;; | HELP | Do | | | | | |
;; |KeyDefs| | | | | | |
;; |_______|_______________| |_______|_______|_______|_______|
;; _______________________ _______________________________
;; | Find |Insert |Remove | | Gold | HELP |FndNxt | Del L |
;; | | |Sto Tex| | U Arg |E-Help | Find |Undel L|
;; |_______|_______|_______| |_______|_______|_______|_______|
;; |Select |Pre Scr|Nex Scr| |Paragra| Sect |Append | Del W |
;; | Reset |Pre Win|Nex Win| | Do | Fill |Replace|Undel W|
;; |_______|_______|_______| |_______|_______|_______|_______|
;; |Move up| |Forward|Reverse|Remove | Del C |
;; |Tscreen| |Bottom | Top |Insert |Undel C|
;; _______|_______|_______ |_______|_______|_______|_______|
;; |Mov Lef|Mov Dow|Mov Rig| | Word | EOL | Char | |
;; |PanLeft|Bscreen|PanRigh| |ChngCas|Del EOL|SpecIns| Enter |
;; |_______|_______|_______| |_______|_______|_______| |
;; | Line |Select | Subs |
;; | Open Line | Reset | |
;; |_______________|_______|_______|
;; Astute emacs hackers will realize that on systems where TPU-edt is
;; installed, this documentation file can be loaded to produce the above
;; editing keypad layout. In fact, to get all the changes in the sample
;; initialization file, you only need a one line initialization file:
;; (load "tpu-doc")
;; wow!
;; %% Compiling TPU-edt
;; It is not necessary to compile (byte-compile in emacs parlance)
;; TPU-edt to use it. However, byte-compiled code loads and runs
;; faster, and takes up less memory when loaded. To byte compile
;; TPU-edt, use the following command.
;; emacs -batch -f batch-byte-compile tpu-edt.el
;; This will produce a file named tpu-edt.elc. This new file can be
;; used in place of the original tpu-edt.el file. In commands where
;; the file type is not specified, emacs always attempts to use the
;; byte-compiled version before resorting to the source.
;; %% Regular expressions in TPU-edt
;; Gold-* toggles TPU-edt regular expression mode. In regular expression
;; mode, find, find next, replace, and substitute accept emacs regular
;; expressions. A complete list of emacs regular expressions can be
;; found using the emacs "info" command (it's somewhat like the VMS help
;; command). Try the following sequence of commands:
;; DO info <enter info mode>
;; m regex <select the "regular expression" topic>
;; m directives <select the "directives" topic>
;; Type "q" to quit out of info mode.
;; There is a problem in regular expression mode when searching for
;; empty strings, like beginning-of-line (^) and end-of-line ($).
;; When searching for these strings, find-next may find the current
;; string, instead of the next one. This can cause global replace and
;; substitute commands to loop forever in the same location. For this
;; reason, commands like
;; replace "^" "> " <add "> " to beginning of line>
;; replace "$" "00711" <add "00711" to end of line>
;; may not work properly.
;; Commands like those above are very useful for adding text to the
;; beginning or end of lines. They might work on a line-by-line basis,
;; but go into an infinite loop if the "all" response is specified. If
;; the goal is to add a string to the beginning or end of a particular
;; set of lines TPU-edt provides functions to do this.
;; Gold-^ Add a string at BOL in region or buffer
;; Gold-$ Add a string at EOL in region or buffer
;; There is also a TPU-edt interface to the native emacs string
;; replacement commands. Gold-/ invokes this command. It accepts
;; regular expressions if TPU-edt is in regular expression mode. Given
;; a repeat count, it will perform the replacement without prompting
;; for confirmation.
;; This command replaces empty strings correctly, however, it has its
;; drawbacks. As a native emacs command, it has a different interface
;; than the emulated TPU commands. Also, it works only in the forward
;; direction, regardless of the current TPU-edt direction.
;; %% Etcetera
;; That's TPU-edt in a nutshell...
;; Please send any bug reports, feature requests, or cookies to the
;; author, Rob Riepel, at the address shown by the tpu-version command
;; (Gold-V).
;; Share and enjoy... Rob Riepel 7/93
;;; tpu-doc.el ends here