%% %% 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 = } \item {EMACSLIB = } \item {EMACSDOC = } \item {HOME = } \item {UNIXMODE = .,/LAHdb} \end{itemize} } \vspace*{3mm} \noindent Optional Environment variables {\tt \begin{itemize} \item {TERMCAP = } \vspace*{-3mm} \item {TERM = } \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 }'' {\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 }'' you will be prompted for a command to execute in an inferior shell. An example of a command might be ``{\tt ls -la }''. 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 }'' 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 }''. 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 } as line terminators instead of the Unix standard {\tt }. 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 } 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 }'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 } or {\tt } as line delimiters. \item Paths in all environment variables may now be specified in either of the two formats, {\tt X:\verb#\#} or {\tt /dev/X/}. \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=``/.rLAHdb''} where {\tt and } 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 . & use as replacement for `.' in filenames \\ & with more than one `.' in their name. \\ \hline r & use 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/ in addition to : \\ \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 } as {\tt /dev//} 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 k temacs \rule{4in}{0in} \end{center} \noindent Where {\tt } is a number between 128 and 3500 representing the size (in k) of the stack. There is also the option of setting {\tt } 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 } 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 .elc}'' that have a corresponding ``{\tt .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.}'', where {\tt } 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}