%%
%% Guidelines for using Emacs 18.58 on the Atari ST/TT family of 
%%  personal computers.
%%
%% Revision : 3
%%
%% Author   : Scott J. Kolodzieski
%%
%% Last Mod : 7/15/92
%%
\documentstyle[12pt,fullpage,titlepage]{article}
\pagestyle{titlepage}

\begin{document}

\title {Using Emacs 18.58\\ on the Atari ST/TT\\ family of\\ 
	Personal Computers}
\author{Scott J. Ko{\l}odzieski
 \thanks{I am greatly in debt to a number of 
 people who have made Emacs a real winner on the ST/TT\@.
 They are Jwahar Bammi, Edgar R{\"o}eder, Micha{\l} Jaegermann, Lewis Lasser 
 and  many other people in the ST(internet) community who have given me a 
 great deal of technical assistance, bug reports, and general suggestions.}
\\(scott@sparc1.stevens-tech.edu)}
\date  {July 12, 1992}

\maketitle
\tableofcontents


\pagebreak

\section{Prerequisites}
This brief document is intended as an introduction to the {\sc Emacs}
editor, including its installation and usage, on the Atari ST/TT
family of computers.
It is written for users who have some
familiarity with ideas and concepts such as
{\sc Unix, Command Line Interpreter,
Shell, Environment Variables } and the like. If you are not familiar
with these concepts then I am afraid that this document may not
be self explanatory.

\vspace*{2mm}
At the end of this manual there is a brief introduction to the
{\sc Unixmode} extended file naming convention (Appendix I).
It is a good idea to become familiar with this extension to the Atari 
filesystem (it can be very useful), so it is suggested that you read 
\underline{Appendix I} on the {\sc Unixmode} standard before continuing.

\section {Introduction}
{\sc Emacs} is a totally customizable, self documenting editor that
was developed in the mid-seventies by Richard M. Stallman (rms) at 
MIT\@. Because of its extreme flexibility and power it quickly became the
editor of choice at a large number of college and university computing
centers. Over the past two decades {\sc Emacs} has grown and changed
to adapt to the needs of programmers worldwide.
The most popular of the many versions of {\sc Emacs} is known as GNU-Emacs,
and is freely distributed by the Free Software Foundation (FSF).
GNU-Emacs is currently at version 18.58, and that is the version that
has been ported to the Atari ST/TT, and is described in this
document. From this point on \underline{\sc Emacs} will refer to the
Atari ST/TT port of GNU-Emacs \underline{18.58}.
(See the section on changes from previous versions, mainly 
version 18.57)

\vspace*{2mm}
{\sc Emacs} allows simple editing of files, and much more. One can
simultaneously edit several files, each in separate windows, 
manipulate characters, words, lines, and paragraphs all with relative ease.
{\sc Emacs} also has custom modes that enable programmers to edit
text files containing source code written in any of the more
popular programming languages in a language sensitive manner.
It allows the programmer the flexibility of
compiling programs without leaving the editor, and of having compiler
error messages appear, along with the corresponding source code
to a program currently under development, in a split window
environment. If all this is not enough {\sc Emacs} allows the user
almost infinite flexibility in defining new modes and commands to
customize the editor in any way that one desires. It should be made
clear that, in general, this is not a skill that one can learn
overnight. While the basics of editing in {\sc Emacs} (it comes with a
tutorial) can be mastered rather quickly, the advanced features and
the customization of {\sc Emacs} requires serious study of the editor.

\section{The Design Philosophy of Emacs}

\subsection{Implementation}
{\sc Emacs} is implemented using a two tier program structure. The most
fundamental parts of {\sc Emacs} are written in C, while many of the
more sophisticated editor commands and language-mode extensions are
written in ``e-lisp''. ``e-lisp'' is a dialect of the programming
language Lisp that is particularly well suited for data handling.
One can argue that {\sc Emacs} is actually a fast ``e-lisp'' interpreter
that was designed with the handling of windows and screens in mind.
It is this two tier design philosophy, basic commands in the C source,
and most editor features written in ``e-lisp'', that makes {\sc Emacs}
so powerful and easy to extend.

\vspace*{2mm}
One should not have to modify the C source code to do customizations,
that would necessitate a recompilation of the source code for the changes
to take effect.  Instead the run-time loadable ``e-lisp'' functions allow
for the extension and embellishment of {\sc Emacs} without the need to deal
directly with the compilation process.

\subsection {The ``dumping'' concept}
Many of the more sophisticated commands in {\sc Emacs} are implemented
in ``e-lisp'' code and are not part of the actual {\sc Emacs} source
code.  For example the incremental search command of {\sc Emacs} is
nothing but a call to an ``e-lisp'' function defined in the
``isearch.el'' file.  Since such a large part of {\sc Emacs}, roughly
150k, is external ``e-lisp'' functions which are not part of the basic
{\sc Emacs} executable, the loading of these functions at run-time can
take a considerable amount of time and system resources.  For this
reason {\sc Emacs} must be {\bf Dumped}. This dumping process need
only be performed once during the installation of the editor.

\vspace*{2mm}
Dumping is a process where {\sc Emacs} is run non-interactively, then
after it has loaded all the supporting ``e-lisp'' code, a complete
dump of the memory occupied by {\sc Emacs}, and all the ``e-lisp'' code it
loaded, is written out to disk. Ideally one would like to now be able
to execute this dumped image of {\sc Emacs} since it contains all the
pre-loaded ``e-lisp'' code. This is in fact what happens, but with one
small proviso. For technical reasons (the relocation of addresses), this
dumping procedure must be done twice.  Then the two resulting memory
images will be compared to produce a executable {\sc Emacs} that has
all the required ``e-lisp'' code built into it.  This at first may
seem like a rather sizable task for the installation of an editor, but it
is a small price to pay for the host of advanced features that are
available in {\sc Emacs}.  With the Atari ST/TT version of {\sc Emacs}
come two support programs that actually make this dumping process
almost effortless for the end user.  Instructions on how to use these
programs to produce a working dumped {\sc Emacs} are found in the next
section ``Installing Emacs''.

\section{Installation of Emacs}
This section will lead you through all the steps needed to get a
working, dumped {\sc Emacs} up and running on the Atari ST/TT\@.  Once
again I suggest you read the appendix on the {\sc Unixmode} standard
since I will use many of its features in the following examples and
descriptions. [Note: the two main {\sc Unixmode} features that I use
are: (1) the use of ``/'' instead of ``\verb#\#'' as a
directory separator, and (2) the use of {\tt /dev/X} instead of
{\tt X:} to reference drive X.]

\subsection{Required Files and Directories}
{\sc Emacs} uses three subdirectories to store all of its related
files.  I shall call these directories {\tt e-bin/}, {\tt e-lisp/},
and {\tt e-etc/} in this manual. In the next section you will see how
to name these directories in environment variables so they can be
rooted on any filesystem (drive) and have whatever names you choose.\\

\begin{itemize}
\item {\tt e-bin/}  - This directory holds the undumped raw {\sc Emacs}
executable file called ``{\tt temacs}''.
The two support files ``{\tt dumpemac.ttp}'' and
``{\tt dumpfix.ttp}'', that are only used in the dumping process, are
also stored here.

\item {\tt e-lisp/} - This directory and it subdirectories, {\tt
e-lisp/term/} and {\tt e-lisp/st/}, hold all the ``e-lisp'' code that
defines both the basic and advanced features found in the {\sc Emacs}
editor. It should be noted that some of the files in this directory
are only used in the dumping of {\sc Emacs} but others are loaded and
used in the normal execution of the dumped {\sc Emacs} image. If you 
are short on disk space some of these ``e-lisp'' files may be deleted
(see Appendix III-Disk Space Requirements).

\item {\tt e-etc/} - This directory holds the on-line {\sc Emacs}
documentation file along with a number of other document files and
utility programs for document generation.
\end{itemize}

It should be noted that the binary distribution of {\sc Emacs 18.58}
contained in the distribution archive ``{\tt 1858b-d3.zoo}'', has
 the above directory
structure built into it, and all files will be placed in the correct
directories if extracted with the command ``{\tt zoo -extract 1858b-d3.zoo}''. 

\subsection{Setting the Environment}

Essential Environment Variables
{\tt
\begin{itemize}
\item {EMACSLOADPATH = <full path to e-bin/ directory>}
\item {EMACSLIB      = <full path to e-lisp/ directory>}
\item {EMACSDOC      = <full path to e-etc/ directory>}
\item {HOME          = <full path to users home directory>}
\item {UNIXMODE      = .,/LAHdb}
\end{itemize}
}
\vspace*{3mm} 

\noindent
Optional Environment variables
{\tt
\begin{itemize}
\item {TERMCAP  = <full path to termcap file>} \vspace*{-3mm}
\item {TERM     = <an entry in the above termcap file>} \vspace*{-3mm}
\end{itemize}
}
\vspace*{3mm}

The reason that the {\tt TERM} and {\tt TERMCAP} variables are
optional is that {\sc Emacs}, by default, has a built-in {\tt vt52}
terminal description that was designed to work with the Atari.
However, if you like, you can set these variables to use your personal
terminal descriptions, a feature which can be rather useful for the
advanced user. There is a sample termcap file distributed with {\sc
Emacs} (directory {\tt examples/}) to serve as an example of some of
the possible customizations.

\vspace*{2mm}
As an example, I use the following environment variable setting on my
system. In fact they are set in my login script under {\sc Bash} so
that whenever I enter my shell {\sc Emacs} is ready to go.

\noindent
{\tt
\hspace*{1cm} EMACSLOADPATH=/dev/D/gnu/e-bin\\
\hspace*{1cm}      EMACSLIB=/dev/D/gnu/e-lisp\\
\hspace*{1cm}      EMACSETC=/dev/D/gnu/e-etc\\
\hspace*{1cm}       TERMCAP=/dev/C/etc/termcap\\
\hspace*{1cm}          TERM=vt52\\
\hspace*{1cm}      UNIXMODE=/.,rCLAHdb\\
\hspace*{1cm}           HOME=/dev/F/usr/sjk
}

\subsection{Creating a Dumped Emacs}
Please now read \underline{Appendix II} on memory usage so you can
determine an appropriate stack size for your dumped {\sc Emacs}.  The
stack size may be altered before dumping.

\vspace*{2mm}
Once the correct environment variables are set, it is very easy to
create a dumped version of {\sc Emacs}. Just change to the directory
{\tt e-bin/} and run the program ``{\tt dumpemac.ttp}''. This program
will do the two dumps of {\sc Emacs} then call ``{\tt dumpfix.ttp}'',
which must also be in this directory, to produce a fully functional
executable version of {\sc Emacs}.

\vspace*{2mm}
After ``{\tt dumpemac.ttp}'' is finished there will be three new files
in your binary directory, ``{\tt emacs.ttp}'', ''{\tt xemacs.1}'', and
``{\tt xemacs.2}''.  The latter two may be deleted as they were
created by the dump procedure and are no longer needed. The file
``{\tt emacs.ttp}'' is the fully functional {\sc Emacs} executable.

\subsection {Running Emacs}
The {\tt HOME} environment variable must be set in order for {\sc
Emacs} to find its default customization file.  Whenever {\sc Emacs}
is executed it attempts to load and execute the user customizations
found in the file ``{\tt \$HOME/emacs.rc}''.  In the directory {\tt
examples/} is a sample ``{\tt emacs.rc}'' file that should be copied
into your home directory before you execute {\sc Emacs}. See the
section on customization for more information concerning the contents
of the ``{\tt emacs.rc}'' file.

\vspace*{2mm}
It should be mentioned that the ``{\tt .rc}'' in ``{\tt emacs.rc}'' stands for 
``read commands'' and is a subject of Unix folklore. Also it is possible
do customizations in a slightly different place.
If there is a file called ``{\tt e-lisp/default.el}'', then any
commands contained in this file will be executed as soon as
{\sc Emacs} starts and before ``{\tt emacs.rc}'' is read.
The difference between the two methods is that with the ``{\tt emacs.rc}'' 
one has slightly more control over the customizations in that one may have 
several ``{\tt emacs.rc}'' files in different directories and choose the one 
to load before executing {\sc Emacs} by setting the {\tt HOME} environment
variable to point to the correct place.

\vspace*{2mm}
Now all you have to do is execute the file ``{\tt emacs.ttp}'' and you
should be set.  I usually create an alias in my shell of the form
``{\tt alias emacs=/dev/D/gnu/e-bin/emacs.ttp}'' so that I do not have
to add the {\tt e-bin/} directory to my path. As an alternative, you
can copy ``{\tt emacs.ttp}'' into a directory you have in your shells
{\tt PATH} environment variable, or add the {\tt e-bin/} directory to
your path.

\vspace*{2mm}
{\bf NOTE:} I have not tried to run ``{\tt emacs.ttp}'' from the
desktop directly, nor do I ever intend to try this. It should work if
all the correct environment variables are set, however I make no
promises or guarantees.

\section {Customization}
There is a complete description of all the ``e-lisp'' commands that
are available for customization of the editor along with a description
of the internal workings of the ``e-lisp'' interpreter in a 500+ page
``{\sc Emacs Lisp Reference Manual}'' that is available from the public
internet site {\tt prep.ai.mit.edu}. Also at this site is the raw (non
ST/TT specific) source code to {\sc Emacs} and a ``{\sc Emacs Users
Manual}''.

\vspace*{2mm}
There are several ST/TT specific ``e-lisp'' functions that have been
written to take advantage of certain facets of the Atari ST/TT\@. These
ST/TT specific extensions are covered in the section on advanced
features, however simple customizations may be done in the ``{\tt
emacs.rc}'' file. Most often these customizations take the form of
simple key bindings.  Let us look at a sample ``{\tt emacs.rc}'' file
before discussing key bindings any further.

\subsection{Example ``emacs.rc'' file}
\vspace*{2mm}
{\footnotesize
\input emacsrc.tex
\normalsize
}

Unless one is familiar with the Lisp programming language then most 
of the preceding file will not make much sense. However one important 
part of this file is the binding of arbitrary commands to the function
keys.
This will be discussed in the next section.

\subsection{Hard Key Bindings}
In this section we will discuss how hard keys, i.e.\  the function keys,
arrow keys and right keypad keys, may be easily bound to any command available 
in {\sc Emacs}. 

\vspace*{2mm}
The first thing to do is to examine the
 file ``{\tt e-lisp/term/atari.el}'', 
which is autoloaded by the sample ``{\tt emacs.rc}'' file. In this file the 
only important thing to note is the one character code that is assigned to 
each hard key. The code is the character following the {\tt ?} in the section 
that starts with the command ``{\tt setup-terminal-keymap st-map }''. 
An excerpt from this file looks likes this:

{\tt \footnotesize
\begin{verbatim}
     (setup-terminal-keymap st-map
            '(("H" . ?u)                ; up arrow
              ("P" . ?d)                ; down-arrow
              ("M" . ?r)                ; right-arrow
              ("K" . ?l)                ; left-arrow
              ("G" . ?h)                ; Home

                  ...                   

              (";" . ?\C-a)             ; F1
              ("<" . ?\C-b)             ; F2
 
                  ...

              ("\C-r" . ?A)            ; C-Insert -> insert line key
              ("R"    . ?I)            ; Insert
              ("\C-p" . ?N)            ; C-downarrow -> next page key
              ("\C-h" . ?P)            ; C-uparrow -> previous page key
              ("a"    . ?U)))          ; Undo
\end{verbatim}
}

Note that the entry for the {\tt Insert} key
is {\tt (}``{\tt R}''{\tt . ?I)} so the 
assigned code {\tt (It is an internal {\sc Emacs} code)}, is ``{\tt I}''. 

\vspace*{2mm}
Secondly we will examine an excerpt from the ``{\tt emacs.rc}'' file. At the 
bottom of the file you will see some code that looks like:

{\footnotesize \tt
\begin{verbatim}
   (define-key function-keymap  "\C-a" 'display-mem)     ; F1  key 
   (define-key function-keymap  "\C-b" 'goto-line)       ; F2  key
   (define-key function-keymap  "\C-c" 'what-line)       ; F3  key
   (define-key function-keymap  "\C-j" 'toggle-dos-mode) ; F10 key
   (define-key function-keymap  "I"    'overwrite-mode)  ; Insert key
\end{verbatim}
}

These {\tt (define-key \ldots)} statements are used to bind 
{\sc Emacs } commands to {\tt hard-keys}. The general syntax for a
 command of this form is:\\
% \vspace*{2mm}
\begin{center}
{\tt (define-key function-keymap }``{\tt <internal code>}'' {\tt 'command)}
\end{center}
\vspace*{2mm}
The sample from ``{\tt emacs.rc}'' given above shows five examples of
bindings of this sort.  So to bind a key add a line to the bottom of
the ``{\tt emacs.rc}'' file with the correct values for the internal
code and the command.

\vspace*{2mm}
The general rule for customizations is, ``Get the E-Lisp Reference
Manual'', read, and experiment.  The manual contains a vast wealth of
useful commands and is essential for any serious and nontrivial
customizations.

\section{Differences from UNIX Emacs}
The only real difference between {\sc Emacs} running on a Unix based
system and one running on the the Atari ST/TT is the lack of support
for asynchronous processes.  This means that {\sc Emacs} cannot start
a process (another program) and do input \underline{\bf and} output
with the process at the same time. The Atari ST/TT version of {\sc
Emacs} can, however, start an external process and receive output from
it, optionally placing this output in an {\sc Emacs} buffer. This will
be elaborated in the next section on advanced features. There is another 
totally transparent difference. The personal customization file for 
{\sc Emacs} on a Unix system is named ``{\tt .emacs}'', while on the 
Atari ST/TT it is called ``{\tt emacs.rc}''. This renaming was done to 
make the initialization file name conform to the TOS file naming rules. 

\section{Advanced ST/TT features}
There are several advanced features of {\sc  Emacs} that have been shaped into
a more Atari friendly form. For {\sc Emacs} to take advantage of these 
features one must use the ``e-lisp'' files that are distributed with this 
Atari ST/TT port of {\sc Emacs}. There have been numerous changes and 
additions to the standard ``e-lisp'' files that come with the raw FSF version 
of {\sc Emacs}.
Also, several ``e-lisp'' files have changed since my last port 
of {\sc Emacs} 18.57 for the Atari ST/TT, so be sure to install the
``e-lisp'' files that come in the
distribution archive ``{\tt 1858b-d3.zoo}''.

\subsection{Spawning External commands with output to a buffer}
This is done via the ``{\tt M-x shell-command}'' command. After typing 
``{\tt M-x shell-command <return>}'' you will be prompted for a command to
execute in an inferior shell. An example of a command might be 
``{\tt ls -la <return>}''.
After doing this, {\sc Emacs} should launch the 
command in the inferior shell, and when the command has finished, put all 
of its output into a {\sc Emacs} buffer
named ``{\tt *Shell Command Output*}''.
A requirement for this feature to work is that you set the environment 
variable {\tt SHELL} to be the full path, including file name, of a valid 
command line interpreter. I personally use the command:
\begin{center}
\tt 
export SHELL=/dev/D/gnu/bin/bash.ttp
\end{center}

The power of executing shell commands from within {\sc Emacs} should
not be underestimated. The only thing that you must be aware of is
that the command that you execute should not require any interactive
input or {\sc Emacs} will become terminally confused.

\subsection{Compilation of source code from within Emacs}
This feature is most useful if you have at least four megabytes of memory 
and do a lot of programming in C. There is a command for compiling a 
C program that you are currently working on in {\sc Emacs}. The beauty 
of this is that not only do you not have to leave the editor but {\sc Emacs}
will put all compilation error messages on the bottom of the {\sc Emacs} 
screen while the source code to your program resides in the upper portion 
of the screen. In addition, there is also a command that examines 
the errors reported by the C compiler and places the cursor on the 
offending line in your source code. All of this is best illustrated by an 
example. 

\vspace*{2mm}
First make sure your shell is set up correctly so that the compiler would
run in a normal fashion if invoked from the shell.
This usually involves correctly setting certain environment variables.

\vspace*{2mm}
Now suppose that you are editing a a C program called ``{\tt test.c}''
and you want to compile it from within {\sc Emacs}. Just type the
command ``{\tt M-x compile <return>}'' and you will be prompted by a
line of the form :
\begin{center}
\tt 
Compile Command: gcc \rule{3in}{0in}
\end{center}
Just type the command line to ``{\tt gcc}'' that you would type from
your {\tt SHELL}, e.g. ``{\tt Compile Command: gcc -o test test.c
-lpml <return>}''.  This should immediately create a new window that
states that the compilation is in progress. When compilation is
complete, the new window will either contain the error messages
generated by the compiler, or a message saying that compilation was
successful. In the former case the cursor will be left on the
offending line in the source window.
To move to the next error use the command ``{\tt M-x next-error}''.

\vspace*{2mm}
At the ``{\tt Compile Command: gcc}'' prompt one can delete the 
``{\tt gcc}'' part and instead type ``{\tt make}'' if that option is
required.

\subsection {Suspending Emacs}
If your {\tt SHELL} environment variable is correctly set to a valid
command line interpreter, {\sc Emacs} may be temporarily suspended at
any time during editing by simple hitting the ``\verb#^#z'' key.  This
will launch a new copy of your shell and leave you in it. You may
operate in this subshell for as long as you want, then simply exit the
shell to return to {\sc Emacs}.

\subsection{Dos-Mode files}

\vspace*{2mm}
Many people in the Atari ST/TT community use text files that use {\tt
<cr><lf>} as line terminators instead of the Unix standard {\tt <lf>}.
There is a compatibility mode that allows almost effortless conversion
between the two modes. In the ``{\tt emacs.rc}'' file that comes with
this distribution of {\sc Emacs} there is a file called ``{\tt
dos-mode.el}'' that is always loaded on startup. This file supports an
automatic detection of files that are line delimited by {\tt <cr><lf>}
and sets up {\sc Emacs} to handle such files in a transparent manner.
If you load such a file it will look normal in the editor window, but
in the {\sc Emacs} status line on the bottom of the screen you will
see the word {\tt DOS}. It is possible to manually force a file to be
written with {\tt <cr><lf>}'s as end of line delimiters by entering
DOS mode manually once the file is loaded into {\sc Emacs}. There is a
convenient key binding in the distributed ``{\tt emacs.rc}'' file that
does this, the binding is ``F10'', and this function key toggles
between standard and DOS modes.

\section{Changes from previous versions}
Since this document describes {\sc Emacs} version 18.58, I will
enumerate the major differences from previous versions.
For the technical details on the changes made to the
C source code, get the source distribution archive and read the file 
``{\tt chng-log}'' from the source code directory.
For changes in the ``e-lisp'' code see the file ``{\tt e-lisp/chng-log}''.

\subsection{Since version 18.57}
\begin{itemize}
\item Screen update speed has been improved by a factor of three.
\item Much improved memory management. This includes {\sc Emacs} tracking used 
	and available memory and reporting warnings to the user at the
	75, 85, and 95 percent used levels.
\item All support files found in the {\tt e-lisp/ } directory, have 
	had their names truncated to meet the 8.3 specifications of the Atari 
	file system. This should ensure that {\sc Emacs} runs even if 
	{\sc Unixmode} is not active.
\item A bug has been fixed where spawned external commands that wrote to 
	{\tt stderr} were not being redirected properly. 
\item Support for ``{\tt M-x compile}'' and ``{\tt M-x grep}'' commands, 
	along with general support for launching external programs directly,
	without the need for an interactive shell. See the support files 
	``{\tt e-lisp/st/compile.el}'' and {\tt e-lisp/st/process.el} for 
	in depth information.
\item Switch {\tt Termcap} support from {\sc Emacs} internal routines to the 
	``{\tt termcap.olb}'' that comes with the port of Gnu C for the 
	Atari ST/TT\@.  This has the advantage
        of having a default {\tt termcap}
	entry built in. Also this termcap library supports {\tt termcap} files
	that have either {\tt <lf>} or {\tt <cr><lf>} as line delimiters. 
\item Paths in all environment variables may now be specified in either of the 
	two formats, {\tt X:\verb#\#<path>} or {\tt /dev/X/<path>}. 
\item When {\sc Emacs} launches external executables it now searches for the 
	files along the {\tt PATH} environment variable and checks for files 
	with the standard Atari ST/TT extensions (``.ttp'', ``.tos'', and ``
	.prg''). 
\item ``{\tt .emacs}'' initialization file has been renamed to 
	``{\tt emacs.rc''} which is a valid TOS file name.
\end{itemize}

 
\section{Suggestions, Comments and Bug Reports} 
I will entertain most suggestions and comments that are not of the
form: ``{\sc Emacs} should more fully support the special features of
MiNT.''.  A fully MiNT and {\sc Unixmode} aware version of {\sc
Emacs} would be ideal, thus this is the direction that this port will
most likely move in.  However there is no rush for me to do this, as
this version of {\sc Emacs} works perfectly under MiNT, although there
is no support for MiNT's ability to handle asynchronous processes.

\vspace*{2mm}
Please send me a report on any bugs that you find.  If it is truly a
bug and not a feature then I will do my best to fix it.  I find {\sc
Emacs} to be very stable. I use it extensively for program
development, text entry and even some lisp programming and find that
it is relatively easy to use and customize.

\section{Wish list for future versions}

\begin{itemize}
\item Make {\sc Emacs} run in TT-ram. It is a puzzle to me why this does not
currently work. I will however continue to look into this and hopefully have 
a solution in the not so distant future. 
\item Add some sort of mouse support to {\sc Emacs} on the Atari. This 
should not be too hard, but I am not so sure as to what the mouse buttons 
should do? Any comments would be appreciated. 
\item Make {\sc Emacs} auto detect MiNT, thus do the right thing when the 
multitasking kernel is loaded but remain backward compatible to plain TOS\@.
Note that keeping {\sc Emacs Unixmode} aware is a big plus in my eyes. 
\item Get a TeX mode up and running. It would be easy if one could run 
TeX with a switch that only prints errors and does not stop for input on
errors. 
\end{itemize}

\section{References}
The following references may prove helpful:
\vspace*{2mm}
\begin{itemize}
\item {\bf ``GNU Emacs Manual, Sixth Edition, Version 18 for Unix Users''},
	February 1988, {\em Richard Stallman}.
\item {\bf ``Emacs Lisp Reference Manual, Version 18 for Unix Users''}, 
	June 1989, Edition 0.1 beta, {\em Bil Lewis, Dan LaLiberte, and the 
	GNU Manual Group}.
\item {\bf ``Reference Card for GNU Emacs Version 18 on Unix Systems''},
        1987, {\em Stephen Gildea}.
\end{itemize}

\section*{Appendices}
\addcontentsline{toc}{section}{Appendices}

\subsection*{Appendix I - The Unixmode standard}
\addcontentsline{toc}{subsection}{\protect\numberline{}{Appendix I - 
Unixmode}}
Because the native TOS operating system on the Atari ST/TT limits the
naming of files to a maximum of 11 characters, (an 8 character file
name, followed by a `.', then an optional 3 character extension), a
software extension to this file system has been implemented in the
{\sc Gnu C} run time support library (hereby referred to as the RTL).
What this amounts to is the following, when a program that has been
compiled with the RTL is executed, the C startup code checks the
system for the presence of an environment variable named {\sc
Unixmode}. If found, it then modifies the standard C
file/directory functions based on the contents of the {\sc Unixmode}
environment variable. The {\sc Unixmode} environment variable may
contain a series of characters, each character (or sequence of
characters) indicates how the standard C file/directory functions
are modified.  A complete specification of the {\sc Unixmode}
environment variable looks as follows : {\tt
UNIXMODE=``/.<x>r<y>LAHdb''} where {\tt <x> and <y>} represent single
characters. The meanings of these options are described briefly in the
following table.\\ \vspace*{3mm}

{\tt
\begin{tabular}{||c|l||} \hline
character sequence & meaning \\ \hline 
  /	           & allow / or \verb+\+ to separate subdirectories.\\ \hline 
.<x>		   & use <x> as replacement for `.' in filenames \\
  		   & with more than one `.' in their name.  \\ \hline 
r<y>		   & use <y> as the root drive.  \\ \hline 
L		   & allow symbolic links.  \\ \hline 
A		   & allow auto creation of links.  \\ \hline
H		   & hide the special `.dir' file.  \\ \hline
d		   & allow /dev/<x> in addition to <x>: \\ \hline 
b                  & open files in binary mode	\\ \hline
\end{tabular}
}

\vspace*{3mm} 
A few points should be made before continuing with our discussion of
the {\sc Unixmode} extension. First, all of these options need not
always be set. One usually just picks the extensions that are
required, puts the relevant characters into the {\sc Unixmode}
variable and then executes the desired program. Of course there is no
harm in setting {\sc Unixmode} once, with all possible options. In
fact one can set up {\sc Unixmode} for maximum {\sc Unix}
compatibility and forget about it.  The second point that should be
made is that the entire {\sc Unixmode} standard is implemented in
software, {\bf It is only an extension to the high level i/o subsystem
of the C runtime library.} The TOS level bios/gemdos calls do not
know about the {\sc Unixmode} extensions! This is not a problem as
{\sc Emacs 18.58} is fully {\sc Unixmode} aware. This port of {\sc
Emacs} will create/edit long file names, and follow {\sc Unixmode}
symbolic links with no difficulty. However for ease of installation
all file required by {\sc Emacs} have been renamed in a consistent
manner so they conform to the ST/TT's native 8+3 file naming
requirement.

\vspace*{3mm}

The above options are best described by an example. Suppose {\sc
Unixmode} is set to the string ``{\tt /.,rCLAHdb}'', before one starts
some program compiled with the RTL\@. That program may now use extended
file names, even those with multiple occurrences of the `.' character,
the RTL will do the necessary file name conversions to keep TOS happy.
Because of the presence of the ``{\tt /}'' character one may refer to
files as ``{\tt c:\verb+\+path\verb+\+foo}'' as ``{\tt c:/path/foo}'',
also because of the ``C'' following the ``r'', ``C:'' was selected as
the root drive, thus the above path could even be abbreviated as
``{\tt /path/foo}''. The presence of the ``d'' character in the {\sc
Unixmode} variable allows one to access drive {\tt <X>} as {\tt
/dev/<x>/} instead of the more conventional {\tt X:\verb+\+}.

\vspace*{2mm}
For the other options that are not described in the above example I
refer you to the documentation that comes with the RTL source code.
This source is freely available from {\tt atari.archive.umich.edu}


\subsection*{Appendix II - Memory Usage}
\addcontentsline{toc}{subsection}{\protect\numberline{}{Appendix II - 
Memory Usage}}
{\sc Emacs} is big. There is nothing that can be done about that. There is 
absolutely no hope of running it in 512k of ram.
One megabyte is the absolute minimum
memory configuration. The executable is 550k and may eat up between 128k and 
3500k in additional space depending on the memory configuration you choose. 

\vspace*{2mm}
The raw undumped ``{\tt temacs}'' executable is set to have a 512k
stack space.  If nothing fancy is being done in {\sc Emacs} this
should be adequate and it can be left unmodified. If you like you may
use the program ``{\tt fixstk.ttp}'' distributed with {\sc Emacs} to
change the stack size before you create your dumped version. The
format for this command is:
\begin{center}
\tt fixstk <xxx>k temacs \rule{4in}{0in}
\end{center}
\noindent
Where {\tt <xxx>} is a number between 128 and 3500 representing the
size (in k) of the stack.  There is also the option of setting {\tt
<xxx>} to -1 thus telling {\sc emacs} to use all the available memory for
its stack when it is run.  This option (-1), does not allow any
process creation to be done by {\sc Emacs} so most of the items in the
section on Advanced Features will not work. I personally suggest a
stack size of 512k, if you have at least two megabytes of ram.

\vspace*{2mm}
There is a memory tracking feature built into {\sc Emacs}. It will provide
warnings to you if, in the course of editing a large document, you use up the 
majority of the working memory. The warnings are issued at the 75, 85, and 95 
percent used levels. If you get one of these warnings follow the instructions 
printed on the screen. 

\vspace*{2mm}
Also in the distributed ``{\tt emacs.rc}'' file the {\tt <F1>} is bound to 
a command that displays the amount of memory available and the amount used. 
This can be an  invaluable tool.


\subsection*{Appendix III - Disk Space Requirements}
\addcontentsline{toc}{subsection}{\protect\numberline{}{Appendix III - 
Disk Space Requirements}}

The distribution file ``{\tt 1858b-d3.zoo}'' when unpacked, expands to 
roughly two and a half megabytes on disk. The whole installation process 
requires approximately another one and a half megabytes, but most of
 that is reclaimed 
after the installation is complete (in the installation
 section it is mentioned 
that some files can be deleted after the run of ``{\tt dumpemac.ttp}'').

If you do not have enough free space then you may be forced to prune back 
the number of ``e-lisp'' files in the ``{\tt e-lisp/}'' directory.
First delete any files 
named ``{\tt <something>.elc}'' that have 
a corresponding ``{\tt <something>.el}'' version also. The ``{\tt .elc}''
version is a byte compiled version of the ``{\tt .el}'' files. They are 
functionally equivalent, but the ``{\tt .elc}'' loads and executes a bit 
faster. As a note any ``{\tt .el}'' can be used to produce a byte compiled
version ``{\tt .elc}'' from within {\sc Emacs} by using the 
``{\tt M-x byte-compile-file}'' command. If you still do not have enough 
space, then read the next appendix on manually dumping {\sc Emacs}.

\subsection*{Appendix IV - Manual Dumping}
\addcontentsline{toc}{subsection}{\protect\numberline{}{Appendix IV - 
Manual Dumping}}

This appendix is to help out those who are really tight on disk space.
The process of dumping {\sc Emacs}, as described in the body of this
document, makes use of a program called ``{\tt dumpemac.ttp}''. This
program is called two times, each time reading in the file ``{\tt
temacs}'' and producing a file called ``{\tt xemacs.<x>}'', where {\tt
<x>} is either a ``1'' or a ``2'' depending on which dump it is
doing. After ``{\tt dumpemac.ttp}'' finishes producing these two
memory dumps, it calls a program called ``{\tt dumpfix.ttp}'' that
reads in the two memory dumps, ``{\tt xemacs.1}'' and ``{\tt
xemacs.2}'' to produce the final
executable file ``{\tt emacs.ttp}''. 
The only problem with using ``{\tt dumpemac.ttp}'' is that it requires
an additional one and a half megabytes of
storage (roughly 600k for ``{\tt xemacs.1}'' and ``{\tt xemacs.2}'' 
and a little less for ``{\tt emacs.ttp}'') in order to create {\sc Emacs}.

It is possible to dump {\sc Emacs} manually with as little as 700k of free
space on your hard disk, however one must perform all the above steps 
manually. Here is an outline of how to do proceed:\\

\begin{enumerate}

\item Change directory to ``{\tt e-bin/}''.
\item Execute the command
        ``{\tt .\verb#\#temacs -batch -l loadup.el dump}'',
	this will produce a file roughly 600k in size called ``{\tt xemacs}''.
\item Rename the file ``{\tt xemacs}'' to ``{\tt xemacs.1}'' and place it 
	on a blank diskette. It may now be deleted  from your hard disk. 
\item Start a new copy of whatever shell you are using. Yes, this sounds
	strange, but you must do it.
\item Repeat step 2, producing another ``{\tt xemacs}'' file. 
\item Rename the file ``{\tt xemacs}'' to ``{\tt xemacs.2}''. You should 
	now move the file ``{\tt temacs}'' to another blank disk as it 
	is not needed any more. It is not a good idea to delete the file 
	``{\tt temacs}'' as you never know when you may want to again 
	dump an {\sc Emacs}.
\item Now exit from the second shell you started in step 4.
\item Execute the command
        ``{\tt .\verb#\#dumpfix -n a:\verb#\#xemacs.1 xemacs.2 emacs.ttp}''.
        This will produce a fully dumped version of {\sc Emacs}
	called ``{\tt emacs.ttp}''. 
\item Remove the file ``{\tt xemacs.2}'' from you hard disk, and now you 
	are done.
\item Go to the store and buy a larger hard disk.

\end{enumerate}

\end{document}

