This file is part of the Amiga-IxEmul version of Emacs-20.2.

* Feedback

Please report undocumented, Amiga related, bugs via e-mail to: 
** Bert Winkelmann <bertw@knuut.de>

Note: There are some bugs already documented in file "./Todo".

Please don't mail any feature requests (except for Intuition code)
because this is a limited version of an UNIX program but not an
enhanced version.  Better send such feature requests to the maintainer
of the original version.

* Things which works different on Emacs for Amiga-OS

** Window Systems

There are two possible window systems you can choose by ../configure
options:

 --with-intui     Intuition
 --with-x         X  (you can choose between Xt (Lucid-Toolkit) and plain X)

To configure without any window system, you should use "--without-x".
Otherwise, configure will guessing the window system by looking for
installed X headers and libraries.

*** X11 (ADE/Ixemul port X11R6.3) 

If you have installed ADE-X11.R6 and let configure choose the window
system, you will end up with an Emacs using X as window system and
Lucid as toolkit.

(Note: Make shure that the linker knows about the directory which
contains the "lib<NAME>_ixlibrary" files.  I've changed the "*link:"
section in my "specs" file like this:

 *link:
 -L/gg/X11R6.3/lib %...
 ^^^^^^^^^^^^^^^^^^

It could also work to pass that directory to configure using
--x-libraries=/gg/X11R6.3/lib.  I've not tested this.)


*** Intuition (>= V39)

Note: To keep maximal compatibility with existing LISP packages, the
variable "window-system" is set to symbol 'x for both Intuition and X.
To check for Intuition, use: "(boundp 'amiga-i-windows)".

**** Things which work like in X for compatibility:

 - X font names must be used for commands like "set-frame-font":
   -Foundry-FamilyName-WeightName-Slant-SetwidthName-AddStyleName-PixelSize...
   (like "-misc-fixed-bold-i---15" 
           [meaning: fixed-system-font, bold-face, i=italic, height = 15]
    or   "-amiga-LetterGothic-medium-r---12" 
           [meaning: LetterGothic-12])
    (Note: You may also use 'amiga-set-font to set the frame font by
           font name and size.  That function works both on console
           and Intuition frames.)

 - X color names must be used in commands like "set-background-color":
    (like "red", "lightgrey", "gold", "navy blue", "spring green")
    (Try "help v x-colors RET" or "M-x list-colors-display RET" or
    "C-down-mouse-2 Display Colors".  Note:
    This list is not the complete built-in list of known colors.  The
    builtin list is taken from a standard rgb.txt file.  Use
    "amiga-load-color-file" to add new entries.  This is intended to  
    support non English color names.

  - The mouse buttons are not bound to work with 2 button Amiga
standard mouse.  You need a 3 button mouse or you have to redefine the
key maps by yourself.

**** Amiga input to emacs command mapping (currently hardcoded):

  Amiga Input                      Emacs Command
----------------------------------------------------------------------------
click window close button        iconify that frame
shift + click window close       delete-frame (or save-buffers-kill-emacs
                                               for last existing frame)
drop object on icon or window    find-file or dired


  Amiga Qualifier Key              Emacs Modifier Key
----------------------------------------------------------------------------
left Alt key                     Meta key "M-"
right Alt key                    Alt key "A-" (except compose (accent) keys)
left Amiga/command key           Hyper key "H-" (except arrow keys)
right Amiga/command key          Super key "s-" (except arrow keys)

**** Numeric keypad

To toggle NumLock use H-kp-numlock. (H- prefix key is bound to left
Amiga key. kp-numlock is bound to the leftmost uppermost key on
keypad.) On my machine that key is labelled as "left-bracket"/NumL)
(Note: acutally H-kp-numlock enables Num-Lock and H-[ disables it)

**** Controlling pop up menu

Note: the menus are both scrolling (mouse+keyboard) and cycling
(keyboard).  Cycling means that the select bar wraps to the opposite
end at the very last/first selectable item.

When holding down a mouse button at least a 3/4 second (750ms) after
the menu box is appeared, the menu selection is done by releasing the
holding mouse button over the selected item.  Otherwise the menu box
stays open until you click on a item or type ESC key/or click outside
the box to cancel.

***** Controlling menu by keyboard:
Arrow up/down - move selection bar.
Arrow right, Return - enter submenu.
Arrow left, Del, Backspace - leave sub-menu or close main menu.
Return - choose selected item or open submenu.
ESC - cancel and close menu.

**** Problems and unimplemented features:

 - Italic faces works not properly for editing (trashed by
cursor). There is problem even in read-only text, if italic is
followed by another style in the same line: The last italic character
is trashed.

 - The scroll-bar has X semantic (Read the chapter in the Info file).

 - In Emacs-20.2 the scroll bar is normally (you can change this) on
the left hand of a buffer.  The implementation of dragging scroll bars
cannot handle this.  You must click below a scroll-bar and then drag
the right (!) border of its associated window.  This problem is fixed
in Emacs-20.3.

**** Frames on named screens
 You may use the name of an existing public screen as DISPLAY name.
(e.g. as argument for menu item Files->Open_New_Display).

Note: After destroying all frames on a DISPLAY/SCREEN, this screen
remains locked until the Emacs process terminates or you apply the
LISP function `x-close-connection' on that DISPLAY/SCREEN.  Yes, that
is a bug and will be fixed.

** Invoking

*** Problems with --terminal and -t

"-t CON:": This doesn't allow resizing.  If you want "resizing" then
start Emacs without "-t" either from a shell or shell-startup script.
(but see topic "windowsize" below)

"-t AUX:" This is one way to use Emacs on serial line, but its more
powerful to invoke Emacs from inside a remote shell:

 1> newshell aux:

 1> copy s:shell-startup emacs-startup
 1> echo "bin:emacs" >>emacs-startup
 1> newshell aux: from emacs-startup

 $ ksh </aux >/aux 2>&1

Note: Using "ksh" instead CLI as remote shell allow using so called
subshells in Emacs' shell buffer and also for suspend-emacs.  (A
subshell starts usually much faster than a login shell.)

*** --data-file NAME -  map-in (!) data dump file [/PROGDIR/.emacs.data-20.2]
 Allow to start with different LISP environments (e.g.  programming,
newsreader, TeX, user dependent...).  It may also useful to allow
different emacs binaries (i.e. X, Intuition or Tty-only) which shares
both arch-dep and arch-indep files.
 (XXX-bw/15-Jan-98: what about DOC file?)
 (XXX-bw/15-Jan-98: We could use the executable name for dump file
select.  But such features usually confuse the user. It would also
depend on correct argv[0]/__progname)

** Environment

**** EMACS_INTUI_SMART - enables Intuition smart refresh (actually
no-care-refresh).  This may cause performance problems (Window cycling
has to wait for the synchronous refresh.  [XXX-bw/26-Jun-98: This may
be a problem of no-care-refresh rather than smart refresh (?)])

**** EMACS_DATA_FILE - alternative file used by map-in data
[PROGDIR:.emacs.data-20.2].  Note: This may overidden by command line
option `--data-file'.

**** EMACS_DEV - enables log messages for Emacs-implementors benefit.
**** EMACS_ASMA_LOG - contains filename to write some memory manager debug
                      mesages.
**** EMACS_ADMP_VERIFY - enables comparing the data segment after
		         patch+unpatch against a copy of the original.
**** TMPDIR - Contains path to temporary directory. [/tmp]

** Makefile variables

**** PURE_ADD_SIZE = N  passed to `-pure' option when dumping [0] 

**** LOADUP_ARGS = ARGS passed to lisp/loadup.el after "dump" arg.
Used to disable loading of mule files. For --with-intui "no-mule" is
the default.  (e.g. `make "LOADUP_ARGS="' would enable MULE again.
With X `make "LOADUP_ARGS=no-mule"' would disable MULE).

** Process stack
*** Main process stack size

 Emacs uses usually between 26000 and 30000. (TODO-bw/08-Jan-98: check
endless recursion, ... for emacs-20.2)

[ OBSOLETE-bw/08-Jan-98:
LISP-Error-Message: Variable binding depth exceeds max-specpdl-size
0/9> ixstack -s
  Usage   Total Program

   3434  400000 app:gnu/libexec/emacs/19.29/m68k-amigaos/wakeup
   5774  400000 app:gnu/libexec/emacs/19.29/m68k-amigaos/emacsserver
 200080  400000 app:gnu/bin/emacs
 ^^^^^^

(FIXME-bw: The regular expression (regex) code uses alloca(3).  I'm
not sure whether it needs some stack extending code or a bigger stack
like 60000 would suffice.  (Compiling regex.c without HAVE_ALLOCA
causes preallocate 2.7MB memory for `fail-stack'))
]

*** Sub process stack size
 Subprocesses inherit the stack size from the value which was used to
start Emacs.  Here is a workaround to decrease the stack size of
subprocesses:

1> bin:ixstack 350000 bin:emacs   [OBSOLET-bw/08-Jan-98: done by ../src/Makefile]
1> stack 20000
1> bin:emacs

Emacs itself runs now with 350000 byte stack (20000 bytes are wasted).
The subprocesses (like emacs-server, wakeup, shell, compilation) are
started with 20000 bytes.  Note: Don't forget to use ixstack on other
stack hungry programs too (cc1plus, ld, ...).

** Configuration via LISP flags

Note: There is a customize group "amiga" which contains all important
Amiga specific user options.  Try "M-x customize-group amiga" or
use menu-bar (Help==>Customize==>Specific-Group amiga).

(The values between square brackets are the default values)
**** amiga-working-killpg - Tells Emacs about implemented killpg(3). [nil]
**** amiga-working-job-ctrl - Tells Emacs about implemented SIGTSTP. [nil]
**** amiga-paths - Enable Amiga path syntax. [t]
**** amiga-expand-path - Enable expanding volumes in `substitute-in-file-name'. [nil]
**** amiga-exp-use-usg-jobctrl - Experimental code. Don't use it! [nil].

See the online help for more information (type `<HELP> v amiga- <TAB>')!

**** find-file-existing-other-name  - (See online  help) [nil]
  (Its useful on Amiga if you use assigns together with `next-error'.)

**** find-file-visit-truename - (See online help) [nil]
  (This could prevent major trouble on buggy file systems:  Emacs renames
   a file as backup file (suffix ~).  If you edit a file which is actually a
   symbolic linke, that renaming could trash your file system (ffs-41.1)

**** process-connection-type - (See online help) [nil] 
  (*Emacs seems to have problems with pty(4) implemented by ixemul-47.
 You would see lots of "^M" in the Shell buffer when setting it to `t'.
(See FAQ (help-F) for how to get rid of already printed "^M"
  Sending EOF via pty(4) seems not to work if "l:fifo.handler" runs
  with priority higher than the shell!)

** Process priority

Note-bw/14-Mar-98: There are communicaton problems between parent and
chilprocesses with different priorities.

Note: This feature is currently disabled. You can reanable it in
`../lisp/site-init.el'

This documents the current configuration of Emacs.  You can
reconfigure it.  See the online help for `emacs-priority'.

The Emacs main process increments its process scheduling priority by
one.  This change is not inherited to subprocesses like compilation,
shell-command, inferior shell.

If you prefer that Emacs keeps the inherited priority but the
subprocesses should run with a priority decremented by 1 you have to
use the nice(1) command like this:

$ nice -n1 emacs 

The nice command is part of GeekGadgets. (FIXME-bw: The problem with
nice(1) is: it cannot restore the old priority when returning to an
Amiga-CLI). You may also use `ChangeTaskPri -1' or the priority field
of ToolManager if you start Emacs from there.

Another (undocumented) possibility works with the current
implementation:  Do "(setq emacs-priority -1)" in your ~/.emacs
file.  That cause subprocesses to run with UNIX-priority 1 (- -1) which
is the same as AMIGA priority -1.

If you prefer no priority change at all then you have to remove the
`emacs-priority' setting in "lisp/site-init.el" and make a redump (see
below).

Note: On AmigaOS the priority feature is disabled for the batch
(noninteractive) mode.  The priority is also restored before exiting.

FIXME-bw: This feature works not really satisfying.  Some LISP
packages are running too long (hide-ifdefs, calendar, byte-compile,
Gnus).

** File path syntax

Emacs uses UNIX paths because we have `ixemul.library' which
allow us to use various ELisp front ends from the UNIX world (cvs,
diff, gcc, ...).

Amiga path syntax is supported for:
 - finding files
 - loading ELISP files
 - $HOME (emacs, emacsserver, emacsclient)
 - inside the password file.
 - (file locking mechanism) [obsolete -bw/07-Mar-98]

Amiga path syntax is not supported:
 - in $PATH
 - by ELISP packages (`M-x compile "cd /src; make"')

Note: Emacs converts Amiga paths syntax in user input as soon as
possible to UNIX syntax.  Therefore all output (like in
`list-processes' uses UNIX syntax always).

A short list of accepted path syntax:
         
UNIX syntax:
   /         -  root directory (contains volumes, FTP hosts)
   /abc:     -  ftp with login `ange-ftp-default-user', $USER or `whoami`. (*
   /mario@zz:/pub/wc  - FTP path with different user name.
   /wrk/     -  Volume or assign `wrk'  (UNIX syntax).
   ~/        -  Users home directory.
   ~luigi/   -  Home directory of user `luigi'.

   $MAIL/    -  The path contained in environment variable `MAIL'.

 *) Note: ange-ftp needs pty(4) and ftp(1) to work.  Please fetch the
GNU-Inetutils and the fifo-handler-38.4 from your preferred
Geek-Gadget mirror site.  You have to set the LISP variable
`process-connection-type' to t and run l:fifo.handler to enable pty(4)
procces-I/O.

Amiga syntax depends on the 2 config variables `amiga-paths' and
`amiga-expand-path':

If `amiga-paths' is non `nil':
   wrk:      -  Volume or assign `wrk'.
   :         -  Current volume.

If both `amiga-expand-path' and `amiga-paths' are non `nil':
  /abc/../  -  root directory or "sometimes" parent of assign `abc'.
  abc:../   -  Same like "/abc/../" using mixed syntax.

The environment variable HOME [/sys] is translated to UNIX syntax if
its not already.  This avoids problems with the `cd' command of
`compile' and inferior UNIX shells. (misfeature?)

** AREXX port [FIXME-bw/02-Apr-98]

*** The port names are EMACS1, EMACS2, EMACS3 and so on.

*** The command strings are passed to "read-from-string" (See online help).
**** Here are correct examples:
   ADDRESS "EMACS1"
 '(find-file "s:startup-sequence")' ; '(raise-frame)'
 '(prog1 (find-file "s:startup-sequence") (raise-frame))'

**** And this may be wrong, because the 2nd expression is not read in:
 '(find-file "s:startup-sequence") (raise-frame)'

 If you have enabled "OPTONS RESULTS" in tbe AREXX program, then the
 Variable RESULT will contain the result of the evaluation of your
 LISP expresssion

 '(+ 1 2 3)' => 6
 '(cdr ())' => nil
 '(format "Ein %s %S" "kleiner" "Test")' => "Ein kleiner \"Test\""

 If you send a command which cause an error, then the variable RC
 contains the error code and RESULT remains unchanged.

** Console/Terminal

*** Set font

 Emacs has a built-in function `amiga-set-font'.  That works for CON:
windows.  (Note: When exit emacs, the original font will restored.
However, we preseve any font change done by C:SetFont from within a
subshell created by `suspend-emacs'.

*** change windowsize
 When using -t/--terminal option (like bin:emacs -t con:") Emacs does
not notify any size changes of its console window.  A workaround would
be using "c:setfont" in a subshell created by `suspend-emacs'.

*** Termcap

 Note that we use Termcap, but not Terminfo.

This Emacs version provides default values for both environment
variables TERM [amiga] and TERCAP [a complete entry labeled "amiga"
for console].  This means you don't really need to define TERM nor
TERMCAP.

But usually you need the environment variables TERM, TERMCAP and a
proper termcap file because there are other programs which wanted it.
Here is the termcap entry working on my machine:

 Amiga termcap by Kent Polk and David Gay
AA|amiga|Amiga ANSIo:\
   :co#89:li#33:am:bs:bw:MT:\
   :AL=\E[%dL:DC=\E[%dP:DL=\E[%dM:DO=\E[%dB:IC=\E[%d@:\
   :LE=\E[%dD:RI=\E[%dC:SF=\E[%dS:SR=\E[%dT:UP=\E[%dA:\
   :ae=\017:al=\E[L:as=\016:bl=\007:bt=\E[Z:cd=\E[J:ce=\E[K:cl=\E[H\E[J:\
   :cm=\E[%i%d;%dH:dc=\E[P:dl=\E[M:do=\E[B:ho=\E[H:ic=\E[@:is=\E[20l:\
   :k1=\2330~:k2=\2331~:k3=\2332~:k4=\2333~:k5=\2334~:\
   :k6=\2335~:k7=\2336~:k8=\2337~:k9=\2338~:k0=\2339~:\
   :km:kb=\177:kD=\010:kd=\233B:kl=\233D:kr=\233C:ku=\233A:le=\233D:\
   :mb=\E[7;2m:md=\E[1m:me=\E[0m:mh=\E[2m:mk=\E[8m:mr=\E[7m:nd=\E[C:nl=\E[B:\
   :rs=\Ec:se=\E[0m:sf=\E[S:so=\E[7m:sr=\E[T:ue=\E[0m:up=\E[A:us=\2334m:\
   :ve=\E[\040p:vi=\E[\060\040p:xn:

You can copy it to a file, let TERMCAP point to this file and set TERM
to "amiga".  Its also possible to copy the above termcap entry
directly to env:TERMCAP (untested).

*** ../lisp/term/${TERM}.el

 There is a file "lisp/term/amiga.el" which assigns symbols to the
function + arrow keys.  This overwrites parts of the "amiga" termcap
entry.  The defined symbols are f1...f10, S-f1...S-f10, Help, left,
right, up, down, S-left, S-right, S-up, S-down, S-tab.  The shifted
arrow keys are bound to the not existent keys: prior, next, begin,
end.

"amiga.el" supports function keys introduced with both "\e[" or
"\233".

Note: The file "amiga.el" is only used if your environment variable TERM is
set to "amiga".  If you use a different terminal name you could try to
copy "amiga.el" and edit.

*** Problematic keys

On console we cannot use C-c, because it's always mapped to
SIGBREAK_CTRL_C internally by the console itself.  Therefore
"../lisp/term/amiga.el" do translate the key "C-z" to "C-c".
Furthermore the keys "backspace" and "Del" keys are swapped.

* Make a working installation from the source

(FIXME-bw/29-Nov-97: It's stupid to describe how to applying the diff
which contains this document)

Some differences to standard behavior as described in
`../README' and `../INSTALL'.

** Configuration, Compilation, Dumping, Installation:

*** Configure options
****  --with-intui      Amiga-OS (V39): use Intuition as window system [no]

****  --with-arexx      Amiga-OS (V37): support REXX port on Amiga-OS [yes]
 (AREXX does only work together with --with-intui!  But then it works for
 both TTYs and Intuition (FIXME-bw/25-May-98))

****  --enable-nsegs=N  Amiga-OS (V37): use 2**N (0..28) segments for LISP pointers [0]
  N=0 means no segmentation. (fast, but you can use only memory upto 28bit 
                               (i.e. 0x00000000...0x0FFFFFFF))
  N=1 means one big segment. (slower, you can only use menory within a 28bit "page"
     (i.e. the uppermost nibble have to be the same for all usable RAM)
  N>1  allow to use 2**N memory hunks of size 28/N bit.  This way an Emacs process
       is able to address low and high addresses with distance >28bit

 (--enable-nsegs is normally useless. Its sometimes useful for debugging however.)

*** Example

Assuming you have all of the following things:

 - the baseline (non-Amiga) distribution
 - the diff patch file containing the Amiga specific changes
 - an assign "dist:" containing the dist archive and the patch file
 - an assign "src:" for the source
 - an assign "build:" for building sub-dirs (needs ~ 10 MB free space with "-g")
 - an assign "gg:" for installing 
 - the GG-tools find, ksh, tar, patch, make, install, gcc + libs,
   xargs, less, rm, mkdir

... then you can make it like this:

1> ksh
$ ## turn baseline archive into Amiga-OS source directory
$ cd /src
$ tar -xzf /dist/emacs-20.2.tar.gz                    # extract archive
$ patch -p2 </dist/emacs-20.2-amigaos.diffs           # apply patch file
$ ### You better look after any rejected patches
$ find -name '*.rej' | xargs less                     # look for patch errors
$ find -name '*.orig' | xargs rm -f                   # save disk space
$
$ # (You have now an Amiga-OS source directory)
$
$ ## do configure (using Intuition), compile (for 68030) and dump
$ mkdir /build/emacs-20.2 ; cd /build/emacs-20.2     # make new build directory
$ ./configure m68k-amigaos --prefix=/gg --with-intui  --cache-file=/build/config.cache
$ make -k 'CFLAGS= -g -O2 -m68030'                  # optimized compile with debug info
$
$ make -k install-strip                             # install data and stripped binaries
$ # if that does not work than try this:
$ make -k install "INSTALL_PROGRAM=/bin/install -s -m755"


The result of dumping stage is a data dump file called
"./.emacs_20.2_(i|x|tty).data".  There will be also created a hardlink
between both files "./emacs" and "./temacs".

*** (Not only) for Programmers:
**** You can enable all sanity checks in the amiga specific modules
(storage manager, dumper, window system) by compiling with
-DFULLDEBUG.  Some checks are rather run time expensive (especially
the postcondition check in Amal_xpntr() (only used for --enable-nsegs
> 1)), so by default "only" the preconditions of non-static functions
are checked.  With defined FULLDEBUG the storage manager also fills
the storage Mungwall-like with DEADF00D and DEADBEAF.

**** The dump stage creates a file "amiga_dump.cands" which shows
possible unpatched pointers and pointers referring outside of process.
You can use "amigaos/find-sym.pl" to print the symbolic names of those
pointer objects.  This program requires perl(1) (at least version 5)
and nm(1).  Note: You have to define an ENV variable EMACS_DEV to
cause the producing of "amiga_dump.cands".


** Dump again:

If you have edited `/src/emacs-20.2/lisp/site-load.el' simply run
`make' `from /build/emacs-20.2/'.

[ Note: The makefile depends on time stamp of a directory (lisp/).  If
you use a symbolic link for that, you should also have a `make' which
reference the link to find the correct time stamp. (the dump targets
are "src/.emacs.data-20.2", "etc/DOC" and "etc/DOC-20.2.1". We have to
delete it manually to enforce a remake using a broken make program or
broken libc.a.) ]

	
** Dump manually:

Usage:  temacs [-pure N] [--data-file NAME] -nl -batch -l loadup dump [no-mule]

 * You must preserve the order of the arguments.

If you load plenty of extra packages in lisp/site-init.el or
lisp/site-load.el, then you have to increase the PURE storage.  With
the number N, you have to provide the number of bytes you wish
additionally allocated.  It's no fault to choose a rather big number
(e.g. 200000), because only the really used part will written to the
dumpfile.

Note: You should byte-compile packages loaded by site-init.el or
site-load.el.  Otherwise you will waste your RAM storage.

If you wisch to decrease the pure storage (normally senseless), you
can do this by using a negative N (Note: on Emacs-20.2 the standard
size for pure storage is currently 500000 bytes.


Local variables:
mode: outline
paragraph-separate: "[ 	]*$"
end:
