Otherware/Otherware_1_SB_Development.iso/amiga/utility/text/emacsdif.lha/emacs-18.58/amiga.doc

Text File | 1992-05-17 | 15.6 KB | 413 lines

1. Introduction
---------------

Emacs is a powerful, but sometimes cryptic, editor. In this Amiga
version, I have tried to make it easier to use with menus, mouse
support and arrow key support, but it still requires some getting used
to. I would recommend starting with the tutorial, which can be started
from the Help menu (if it is missing, you didn't install emacs
correctly. Check that the file s:.emacs-menu.el exists) or from the
keyboard by typing Control-H and then t.

This file only describes the Amiga specific features of emacs, and it
assumes a working knowledge of emacs. For more documentation you can
consult the emacs help (Information in the Help menu, or C-h i) or
read the emacs manual (which is the same document in a printed form).
This manual can be bought from the

     Free Software Foundation
     675 Mass Ave
     Cambridge, MA 02139
     USA

See the file gnuemacs:etc/DISTRIB for more information (you can type
C-h C-d to view it).

To install emacs, read the file INSTALLATION.


2. Using emacs in a window
--------------------------

Emacs runs in a window on the Workbench (this can be changed). It
basically works like just any other version of GNU Emacs, using the
same keys, etc. It uses the standard amiga keymap, but with some strange
modifications:

o The left alt key is stolen as a meta key for emacs. This means you can't use
it to enter accents. However, the right alt key remains untouched. Hence
'left alt-f e' moves forward one word and inserts an e, while
'right alt-f e' inserts an e acute. In the rest of the text, the meta key
always means the 'left alt' key.

o C-space is always mapped to C-@, the set-mark command, for convenience.

o The backspace key always sends DEL (delete previous character in emacs),
and DEL sends C-d (delete character under cursor). If you don't like this,
add the line
    (setq amiga-remap-bsdel nil)
to your .emacs file (in s:).

There are also a number of extra features:

a) Mouse support, similar to the X-Windows version.

You can position the cursor with the left mouse button. Other possibilites are:

action            result
------------------------------
shift-left button    set mark at mouse position
control-left button    cut between point and mouse position
meta-left button    copy between point and mouse position
middle button        paste
shift-middle button    iconify emacs window (double click to deiconify)

Some of the control, meta, etc combinations may be stolen by Intuition or
commodities programs, so don't be surprised if they don't all work.

All of these actions may be redefined (this is emacs after all!), see the
file lisp/amiga-mouse.el for details (you will need to learn lisp if you don't
already know it ...) [Note: this file is not included in the binary only
distribution, you will need the source code version].

b) Clipboard

At first glance, emacs uses the Amiga clipboard, ie it cuts to the
clipboard and pastes from it (via the menu operations or the C-w
(kill-region), M-w (copy-region-as-kill) & C-y (yank) commands).

Things are actually complicated by emacs use of a "kill ring" (ie it
remembers the last 30 things cut. The M-y (yank-pop, menu command
Paste Previous) allows you to recover old cuts):

- When you cut (or copy) something in emacs it is placed in the
clipboard.

- When you paste (yank) something in emacs, it checks the clipboard to
see if it contains anything new. If so, it pastes that.

[Note: It also checks the clipboard when you cut something, and saves
that in the kill-ring if necessary]

All this effort is used to make the clipboard appear to operate
transparently in emacs.

c) Window

By default, emacs runs in a window on the workbench screen using the
system default font and the standard colours. All this can be changed:

o The font can be specified with the -fn <font> <size> option when you
run emacs. You can also use the amiga-set-font command interactively,
or add a line like
   (amiga-set-font "topaz" 11)
to your s:.emacs file. The font must be non-proportional.

o The window size and screen can be changed with the
amiga-set-geometry function. It takes 4 or 5 parameters, the (x,y)
position of the window and its (width,height). The last optional
parameter specifies the screen: a string gives the name of a public
screen, t stands for the default public screen (normally the
workbench) and nil means keep the same screen. For example, the lisp code
  (amiga-set-geometry 0 0 640 400)
resizes the emacs window to 640x400. If the screen would be too small
given the current font (there must be room for 11x4 characters), the
change is refused.

To use the a public screen requires an utility to create them ... (I
known of none available).

o The foreground & background colours can be changed with the
amiga-set-foreground-color & amiga-set-background-color commands. You
specify the pen and not the actual colour (from 0 to 7 only,
because of restrictions in console.device).

o The emacs window can be iconified (onto the workbench) with the
amiga-iconify command. This is bound to shift-middle button on a 3
button mouse, and to C-z (which is normally bound to suspend-emacs,
which doesn't work on the Amiga).

To deiconify emacs, double click on the icon.

[Note: while emacs is iconified, it won't answer ARexx commands]

d) Menus

If you have installed emacs correctly (see the INSTALLATION file), it
will startup with some menus containing some useful basic
functions (the layout was inspired from that of TurboText, another
good editor which has the disadvantage of being more expensive than
emacs ...). Alongside each item is the emacs key sequence which
invokes that function, if any.

Using the Menu Help functionality of AmigaDOS 2.04, you can get help
on any menu item by highlighting it with the mouse and pressing the
Help key [This is easier if you're left handed :-)].

The menus are not fixed, they are defined by the s:.emacs-menu.el file
(which isn't human-readable). To modify them, edit s:.emacs-menu.menu.
This contains a lisp-like (but quite legible even for lisp-haters)
representation of the menus, which you can modify by adding items or
menus. The format should be obvious (just make sure that closing
brackets correspond to the correct opening ones, emacs always shows
the corresponding '(' when you type a ')'. Also the last bracket
should correspond with the first).

When you have finished your changes, type C-c C-c. This will save your
menus, and then generate a .el file from them (this takes several
seconds even on an A3000. Be patient). Then save the resulting file.
To have the new menus take effect immediately, type M-C-x while in the
.el file.

Enterprising lisp programmers can customise the menus even more by
modifying the functions amiga-menus-dispatch and/or amiga-menus-help
in lisp/amiga-mouse.el. This code basically receives a (menu-number
menu-item-number) list and must take the appropriate action
(currently, execute the command associated with that particular menu
item). The lack of comments will surely not deter these audacious
pionneers ...

e) Command line options

Beyond the standard emacs command line options (for which
documentation tends to be rather sketchy, not to say missing), you can
also use:

-prealloc <n>: Reserve n bytes of memory for emacs exclusively. This
option *must* be the first on the command line. On the A3000, chip
memory can't be used for emacs (the details are complicated ...), so
you will run out of memory sooner than expected. This option allows
you to reserve some for emacs before it gets eaten by other programs.

-fn <font> <size>: Set the font that emacs uses, like the
amiga-set-font command (see section c, on windows). Note that there
must be enough room for 11x4 characters in the standard 640x200
window. So avoid fonts bigger than 40 points ...

-nw: Don't use a window, use a serial port. See part 3, Using Emacs
over a serial line.

f) ARexx

[Note: This interface has changed slightly since V1.24]

Emacs has a full ARexx interface. It can execute scripts and commands
synchronously (waiting for the result) or asynchronously, and has an
ARexx port from which it accepts commands.

To execute a script, you use the amiga-arexx-do-command (synchronous)
or amiga-arexx-send-command (asynchronous) commands. These ask for the
script file name (the default extension is .elx). If you just want to
execute a simple ARexx command, you can prefix those commands with C-u
and specify the string to execute.

From lisp, you must use
  (amiga-send-command "<file>" nil) for a script, and
  (amiga-send-command "<commands>" t) for direct execution.
(and the same for amiga-do-command). The result of amiga-send-command
is an integer that can be passed to amiga-arexx-wait-command to wait
for the completion of the script or command. It can also be used with
amiga-arexx-check-command to check if the script has finished. For
example:

  (let ((arexx-id (amiga-send-command "start-fun" nil)))
    ... do something here ...
    ; and wait for arexx script to end
    (amiga-arexx-wait-command arexx-id))

Emacs's ARexx port accepts commands in lisp, and is usually called
EMACS1 (if you run emacs twice simulatenously, the second one will
have EMACS2, and so on). For example (from a shell),

  rx "address EMACS1 '(beginning-of-buffer)'"

will set point to the beginning of the buffer.

ARexx commands are only processed at certain times, so be careful how
you design your applications. These are:

o While waiting for commands from the keyboard (ie when emacs is
idle).
o While processing a synchronous (amiga-arexx-do-command) script.
o When the amiga-arexx-process function is called.

They also affect the user visible state by default (ie calling
beginning-of-buffer as above modifies the user's position). Avoid
sending random commands at random times, or use save-excursion.

As usual, all this behaviour can be modified to some extent. Look in
amiga-init.el for details [The source code is the documentation...].

I haven't written any significant examples yet, so ...


3. Using emacs over a serial line
---------------------------------

To use emacs over a serial port, you must do:

  setenv TERM <terminal type> (eg vt100)
  emacs -nw

The setenv line can be put in your User-Startup, so as to avoid typing
it every time.

Emacs cannot simply guess how your terminal works from its name, it
needs a description of it. This is found in a termcap file, which
emacs looks for in s:termcap. If you didn't install this file with emacs,
you can do so by typing (in a CLI):

  join gnuemacs:etc/termcap.ucb gnuemacs:etc/termcap.amiga as s:termcap

[Note: These files only come with the source version]

The -nw prevents the use of a window.

If you have several serial ports, you can type

  emacs -t ser2.device 2

to use port 2 of device ser2.device. Use of the -t option implies -nw.

These options (-t & -nw) *must* be specified at the start of the
command line.

The descriptions of the Clipboard, the command line options and the
ARexx port in part 2 above also apply to use over a serial port.


4. Redumping emacs [This section for expert users only]
-------------------------------------------------------

Enterprising users may want to change the lisp files which are loaded
into the Emacs dump file. The procedure for doing this is very similar
to that with the Unix version, except that the amount of pure storage
can be changed without recompiling emacs. This will allow users
without SAS C v5.10b to still make such changes.

The necessary lisp files are only included in the source distribution,
so you will have to get that first. Once that is available, that you
have made all your changes (eg adding some extra files to be dumped),
use the following sequence to redump emacs:

  cd gnuemacs:etc
  stack 20000
  /temacs -pure <n> -malloc <m> -nl -batch -l loadup dump

The -pure <n> and -malloc <m> options should only be necessary if you
add extra files to be dumped, see below how to choose values for n &
m. The above order for the parameters must be preserved. Specifying
dump without -nl & -batch will have unpredicatable consequences.

Once all the files are loaded, a new copy of gnuemacs:etc/EMACS-DATA
will be saved, and all should work correctly. If you get one of the
following messages:

  Pure Lisp storage exhausted

  Emacs dump: ran out of memory for malloc.

read the following description of the -pure & -malloc options:

When emacs is dumped, it saves (amongst other things) the copies of
two zones of memory, called the pure storage area and the malloc hunk.
These contain an internal representation of the lisp code, so the more
code you include in a dumped emacs, the bigger these need to be. The
default sizes of these are reasonable sizes for the standard lisp code
which is dumped, but you will probably need to increase them if you
add some more lisp modules. The best way to find the new values for n
(size of pure area) and m (size of the malloc hunk), is to run the
command

  cd gnuemacs:etc
  stack 20000
  /temacs -pure 200000 -malloc 200000 -nl -batch -l loadup dump

(these sizes should be largely sufficient, but if you still get one of
the two error messages above, increase them). Then run emacs as usual,
and look at the values of the 2 lisp variables

     pure-bytes-used
and  amiga-malloc-bytes-used

pure-bytes used contains the minimum value for n, and
amiga-malloc-bytes-used the minimum value for m. Add 1000 to these for
luck to get values for n and m, and redump emacs using these (For
reference, pure-bytes-used=127992 and amiga-malloc-bytes-used=86620 in
my version).

For those who are into modifying the C source, the default values are
130000 for n (see DEF_PURESIZE in s-amiga.h) and 87000 for m (see
MALLOC_HUNK_SIZE in amiga.h).


5. Problems
-----------

If you see any problems in the redisplay, type control-L. They should
go away (temporarily). If you can reproduce them, send me mail !!!

I am not aware of any other significant problems, but some features of
emacs are still missing (mainly asynchronous processes). I hope to
have some of these forthcoming in later releases.

Anyway, send any bug reports, enhancement requests, etc to:

Post:                E-mail:
David Gay            [e-mail]
19 Chemin de la Source
CH-1296 Coppet
Vaud
Switzerland

6. Ordering Information
-----------------------

I can provide a complete copy of my development directory, which
includes:

o the standard emacs-18.58 files
o modified and new lisp files
o Amiga-specific source, as text and in RCS format (highlighting the
changes from a standard unix distribution, and the different versions).
o assorted lisp packages hacked for the Amiga (I will be posting some
of these in due course):
  - a tags-like access to the 2.0 autodocs (you must already have a
    copy of these ...)
  - gnus (a news reader) for use with Matt Dillon's uucp package.
  - getris, a tetris clone for emacs

All these as a tar file on a QIC-150 tape, for $200 (the same price as
the FSF, so as not to undercut them), or 300SF. This price is valid
until the 31st December 1993, and includes shipping by surface mail.

Please send all orders, by postal mail, to

  David Gay
  19 Chemin de la Source
  CH-1296 Coppet
  Vaud
  Switzerland

  Tel: +(41)-22 776 35 81 [Evenings, Central European Time]
  Fax: +(41)-22 776 70 58

Include with your order:
- A cheque, in dollars or Swiss francs.
- Your *complete* address (don't forget the country, etc).
- A phone or fax number so I can contact you if I have any problems.

I will be glad to include, on request, and with full source, some
other pieces of software I have written:
- An HP11 calculator (this is an update to the version available on
fish disks, with some bug fixes and 2.0 specific features).
- A scheme compiler for the Amiga, currently in an alpha state.
- A fortune cookie program, including 1 megabyte of cookies (merged
from various sources).


Dvaid Gay
[e-mail]
Ecole Polytechnique Federale de Lausanne - Switzerland
Laboratoire d'Informatique Technique