emacs.sgml

OTP是开放电信平台的简称

<!DOCTYPE CHAPTER PUBLIC "-//Stork//DTD chapter//EN">
<!-- 
 ``The contents of this file are subject to the Erlang Public License,
 Version 1.1, (the "License"); you may not use this file except in
 compliance with the License. You should have received a copy of the
 Erlang Public License along with this software. If not, it can be
 retrieved via the world wide web at http://www.erlang.org/.
 
 Software distributed under the License is distributed on an "AS IS"
 basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 the License for the specific language governing rights and limitations
 under the License.
 
 The Initial Developer of the Original Code is Ericsson Utvecklings AB.
 Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings
 AB. All Rights Reserved.''
 
     $Id$
-->
<CHAPTER><HEADER>
<TITLE> The Erlang editing mode for Emacs </TITLE>

<PREPARED>Anders Lindgren
    <RESPONSIBLE>
    <DOCNO>
    <APPROVED>
    <CHECKED>
    <DATE>1998-04-20
    <REV>C
    <FILE>emacs-user.sgml</HEADER>

<SECTION>
<TITLE> Introduction </TITLE>


<p>
If you want to get started immediately, the chapters
"<SEEALSO MARKER="#unix_dotemacs">An Example for UNIX</SEEALSO>"
and
"<SEEALSO MARKER="#win_dotemacs">An Example for Windows</SEEALSO>" 
gives you examples of the configurations you need to make to use the
Erlang Editing mode for Emacs.
</P>


<P>
Emacs has been the text editor of choice for programmers in the UNIX
community for many years.  Thanks to a continuing development process,
Emacs is the most powerful editor available.  Today, Emacs runs under
most operating systems including MS-Windows, OS/2, Macintosh, and
several dialects of UNIX.
</P>

<P>
Emacs has editing support for all major programming languages and
quite a lot of minor and unknown languages are supported as well.
</P>

<P>
Emacs is designed to be extendible.  In the unlikely event that you
would miss a feature in Emacs you can add it yourself, or you might
find it in the large number of add-on packages that people all over
the world have written.
</P>

<P>
This book is the documentation to the Emacs package <C> erlang.el</C>.
It provides support for the programming language Erlang.  The package
provides an editing mode with lots of bells and whistles, compilation
support, and it makes it possible for the user to start Erlang shells
that run inside Emacs.
</P>

<P>
Emacs is written by the Free Software Foundation and is part of the
GNU project.  Emacs, including the source code and documentation, is
released under the GNU General Public License.
</P>

<SECTION>

<TITLE>Overview of this Book</TITLE>


<P>This book can be divided into the following sections:

<LIST>
<ITEM><EM> Introduction. </EM>  This part introduces Emacs, the Erlang
editing mode, and this book.  In fact, this is the section you
currently are reading.

<ITEM><EM> The editing mode. </EM> Here the editing mode is described.
The editing mode contains a whole series of features including
indentation, syntax highlighting, electric commands, module name
verification, comment support including paragraph filling, skeletons,
tags support, and much more.

<ITEM><EM> Erlang shells. </EM> How to start and use an Erlang shell
that runs inside Emacs is described in this section.

<ITEM><EM> Compilation support. </EM> This package is capable of
starting compilations of Erlang module.  Should compilation errors
occur Emacs is capable of placing the cursor on the erroneous lines.

<ITEM><EM> Customization. </EM> The Erlang editing mode, like most
Emacs packages, supports extensive customization.  In this chapter we
demonstrate how you can bind your favorite functions to the hotkeys
on the keyboard.  It also introduces the concept of "hooks", a general
method for the user to add code that will be executed when a specific
situation occur, for example when an Erlang file is loaded into Emacs.

</LIST>

<P>
The terminology used in this book is the terminology used in the
documentation to Emacs.  The chapter "<SEEALSO
MARKER="#notation">Notation</SEEALSO>" contains a list of commonly
used words and their meaning in the Emacs world.
</P>

<P>
The intended readers of this book are Emacs users.  The book contains
some examples on how to customize this package using the Emacs
extension language Emacs Lisp.  You can safely skip those sections.
</P>

</SECTION>
</SECTION>

<SECTION>
<TITLE>Emacs</TITLE>

<P>
The first component needed to get this package up and running is, of
course, an Emacs editor.  You can use either the standard Emacs
distribution from FSF or XEmacs, an alternative distribution.  Both
brands have their advantages and disadvantages.
</P>

<P>
Regardless of the brand, it is recommended to use a modern version.
If an old version is used it is possible that some of the features
provided by the editing mode cannot be used.
</P>

<P>
The chapter "<SEEALSO MARKER="#distributions">Emacs
Distributions</SEEALSO>" below contains a short summary on the
differences between the Emacs brands, as well as instructions where to
get the distributions and how to install them.
</P>

</SECTION>

<SECTION>
<TITLE>Installing the Erlang Support Packages</TITLE>

<P>
Once Emacs has been installed, it must be informed about the presence
of the Erlang support packages.
</P>

<P>
If you do not know if the packages have been installed open, an Erlang
source file.  The mode line should contain the word "Erlang".  You can
check the version of the installed package by selecting the "version"
entry in the Erlang menu in Emacs.  Should no Erlang menu be present,
or if the menu does not contain a "Version" item, you are using an old
version.
</P>

<P>
The packages can either be installed for all users by the system
administrator, or each individual user can install it in their own
Emacs setup.  The chapter "<SEEALSO
MARKER="#installation">Installation of the Erlang Editing Mode</SEEALSO>"
 contains a description
on how to install the packages.
</P>

</SECTION>


<SECTION>
<TITLE> The Editing Mode </TITLE>

<P>
The Erlang editing for Emacs provides a number of features described
in this and the following chapters.  The editing mode can work with
either Erlang source mode or Mnesia database rules.  The Erlang
editing mode for Emacs is in Emacs terminology a <EM> Major mode </EM>.
</P>

<P>
When Erlang mode is correctly installed, it is automatically activated
when a file ending in <C>.erl</C> or <C>.hrl</C> is opened in Emacs.
It is possible to activate Erlang mode for other buffers as well.
</P>

<P>
The editing mode provides a menu containing a selection of commands
structured into logical subgroups.  The menu is designed to help new
users get an overview of the features provided by the Erlang packages
while still giving full power to more advanced users.
</P>

<P>
Erlang mode has got a local key map that contains keyboard bindings
for a number of commands.  In the chapter 
"<SEEALSO MARKER="#key_bindings">Custom Key Bindings</SEEALSO>" below,
we will demonstrate how the users can bind their favorite commands to
the local Erlang key map.
</P>

<P>
It is possible for the users to perform advanced customizations by
adding their own functions to the "hook" variables provided by this
package.  This will be described in the "<SEEALSO
MARKER="#customization">Customization</SEEALSO>" chapter below.
</P>


<SECTION>
<TITLE>The Mode</TITLE>

<LIST>
<ITEM><C>M-x erlang-mode RET</C><BR>

<P>
This command activates the Erlang major mode for the current buffer.
When this mode is active the mode line contain the word "Erlang".
</P>

</LIST>
</SECTION>

<SECTION>
<TITLE>The Version</TITLE>

<LIST>
<ITEM><C>M-x erlang-version RET</C><BR>

<P>
This command displays the version number of the Erlang editing mode.
Remember to always supply the version number when asking questions
about Erlang mode.
</P>

<P>
Should this command not be present in your setup (after Erlang mode
has been activated) you probably have a very old version of the Erlang
editing mode.
</P>

</LIST>
</SECTION>

<SECTION>
<TITLE>Module Name Check</TITLE>

<P>
When a file is saved the name in the <C>-module().</C> line is checked
against the file name.  Should they mismatch Emacs can change the
module specifier so that it matches the file name.  By default, the user
is asked before the change is performed.
</P>


<LIST>
<ITEM> <EM> Variable: </EM> <C>erlang-check-module-name</C> (default <C>ask</C>)<BR>

<P>
This variable controls the behavior of the module name check system.
When it is <C>t</C> Emacs changes the module specifier without asking
the user, when it is bound to the atom <C>ask</C> the user is asked.
Should it be <C>nil</C> the module name check mechanism is
deactivated.
</P>

</LIST>
</SECTION>

<SECTION>
<TITLE>Variables</TITLE>

<P>
There are several variables that control the behavior of the
Erlang Editing mode.
</P>

<LIST>
  <ITEM><EM> Variable: </EM> <C>erlang-mode-hook</C><BR>

<P>
Functions to run when the Erlang mode is activated.  See chapter
"<SEEALSO MARKER="#customization">Customization</SEEALSO>" below for
examples.
</P>


  <ITEM><EM> Variable: </EM> <C>erlang-new-file-hook</C><BR>

<P>
Functions to run when a new file is created.  See chapter "<SEEALSO
MARKER="#customization">Customization</SEEALSO>" below for examples.
</P>


  <ITEM><EM> Variable: </EM> <C>erlang-mode-load-hook</C><BR>

<P>
Functions to run when the <C>erlang</C> package is loaded into Emacs.
See chapter "<SEEALSO MARKER="#customization">Customization</SEEALSO>"
below for examples.
</P>

</LIST>

</SECTION>
</SECTION>

<!-- Chapter -->

<SECTION>
<TITLE>Indentation</TITLE>

<P>
The "Oxford Advanced Learners Dictionary of Current English" says the
following about the word "indent":
</P>

<QUOTE>
<P>
   "start (a line of print or writing) farther from
    the margin than the others".
</P>
</QUOTE>

<P>
Possibly the most important feature of an editor designed for
programmers is the ability to indent a line of code in accordance
with the structure of the programming language.
</P>

<P>
The Erlang mode does, of course, provide this feature.  The layout
used is based on the common use of the language.
</P>

<P>
It is strongly recommend to use this feature and avoid to indent lines
in a nonstandard way.  Some motivations are:
</P>

<LIST>

  <ITEM> Code using the same layout is easy to read and maintain.

  <ITEM> The indentation features can be used to reindent large sections of a
file.  If some lines use nonstandard indentation they will be
reindented.

  <ITEM> Since several features of Erlang mode is based on the
standard layout they might not work correctly if a nonstandard layout
is used.  For example, the movement commands (described in chapter
"<SEEALSO MARKER="#func_cmds">Function and clause commands</SEEALSO>"
below) will not work unless the function headers start in the first
column.

</LIST>

<SECTION>
<TITLE>The Layout</TITLE>

<P>
The basic layout is that the clause headers start in the first column,
and the bodies of clauses and complex expressions (e.g. "case" and
"if") are indented more that the surrounding code.  For example:
</P>

<CODE>
remove_bugs([]) ->
    [];
remove_bugs([X | Xs])
    case X of
        bug ->
            test(Xs);
        _ ->
            [X | test(Xs)]
    end.
</CODE>


<LIST>

<ITEM> <EM> Variable: </EM> <C>erlang-indent-level</C><BR>

<P>
The depth of the indentation is controlled by the variable
"erlang-indent-level", see section "<SEEALSO
MARKER="#customization">Customization</SEEALSO>" below.
</P>

</LIST>

</SECTION>

<SECTION>
<TITLE>Indentation of comments</TITLE>

<P>
Lines containing comment are indented differently depending on the
number of %-characters used:
</P>

<LIST>
<ITEM> Lines with one %-character is indented to the right of the
code.  The column is specified by the variable <C>comment-column</C>,
by default column 48 is used.

<ITEM> Lines with two %-characters will be indented to the same depth
as code would have been in the same situation.

<ITEM> Lines with three of more %-characters are indented to the left
margin.

</LIST>

<P>
<EM> Example: </EM>
</P>

<CODE>
%%%
%%% Function: remove_bugs
%%%

remove_bugs([]) ->
    [];
remove_bugs([X | Xs])
    case X of
        bug ->                                  % Oh no, a bug!
                                                % Remove it.
            test(Xs);
        %% This element is not a bug, let's keep it.
        _ ->
            [X | test(Xs)]
    end.
</CODE>
</SECTION>

<SECTION>

<TITLE>Indentation commands</TITLE>

<P>The following command are directly available for indentation.</P>

<LIST>
<ITEM><C>TAB</C> (<C>erlang-indent-command</C>)<BR>

<P>Indent the current line of code.</P>


<ITEM><C>M-C-\</C> (<C>indent-region</C>)<BR>

<P>Indent all lines in the region.</P>


<ITEM><C>M-l</C> (<C>indent-for-comment</C>)<BR>

<P>
Insert a comment character to the right of the code on the line (if
any).  The comment character is placed in the column specified by the
variable "comment-column", by default column 48 is used.
</P>


<ITEM><C>C-c C-q</C> (<C>erlang-indent-function</C>)<BR>

<P>
Indent the current Erlang function.
</P>


<ITEM><C> M-x erlang-indent-clause RET</C><BR>

<P>
Indent the current Erlang clause.</P>


<ITEM><C>M-x erlang-indent-current-buffer RET</C><BR>

<P>
Indent the entire buffer.
</P>

</LIST>

</SECTION>
<SECTION>
<MARKER ID="customization">
<TITLE>Customization</TITLE>

<P>
The most common customization of the indentation system is to bind the
return key to <C>newline-and-indent</C>.  Please see the chapter
"<SEEALSO MARKER="#key_bindings">Custom Key Bindings</SEEALSO>"
below for an example.
</P>

<P>
There are several Emacs variables that control the indentation system.
</P>