emacs.sgml

OTP是开放电信平台的简称

<LIST>

<ITEM><EM> Variable: </EM> <C>erlang-indent-level</C>  (default 4)<BR>

<P>
The amount of indentation for normal Erlang functions and complex
expressions.  Should, for example, the value of this variable be 2 the
example above would be indented like:
</P>

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


<ITEM><EM> Variable: </EM> <C>erlang-indent-guard</C> (default 2)<BR>

<P>The amount of indentation for Erlang guards.</P>


<ITEM><EM> Variable: </EM> <C>erlang-argument-indent</C> (default 2)<BR>

<P>The amount of indentation for function calls that span several lines.</P>

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

<CODE>
foo() ->
    a_very_long_function_name(
      AVeryLongVariableName),
</CODE>


<ITEM><EM> Variable: </EM> <C>erlang-tab-always-indent</C>
(default <C>t</C>)<BR>

<P>
When non-<C>nil</C> the <C>TAB</C> command always indents the line
(this is the default).  When <C>nil</C>, the line will be indented
only when the point is in the beginning of any text on the line,
otherwise it will insert a tab character into the buffer.
</P>

</LIST>

</SECTION>
</SECTION>


<!-- CHAPTER -->

<SECTION>

<TITLE> General Commands </TITLE>

<P>
This chapter contains a group of commands that are not found in any
other category.  Unlike most other books we do not have a chapter named
"Miscellaneous xxx" found at the end of most books.  This chapter is
placed near the beginning to reflect the importance and usefulness of
the commands.
</P>

<SECTION>

<TITLE>Filling comments</TITLE>

<P>
How many times have you edited a section of text in a comment only to
wind up with a unevenly formatted paragraph?  Or even worse, have you
ever decided not to edit a comment just because the formatting would
look bad?
</P>

<P>
When editing normal text in text mode you can let Emacs reformat the
text by the <C>fill-paragraph</C> command.  This command will not work
for comments since it will treat the comment characters as words.
</P>

<P>
The Erlang editing mode provides a command that known about the Erlang
comment structure and can be used to fill text paragraphs in comments.
</P>


<LIST>
<ITEM><C>M-q</C>  (<C>erlang-fill-paragraph</C>)<BR>

Fill the text in an Erlang comment.  This command known about the
Erlang comment characters.  The column to perform the word wrap is
defined by the variable <C>fill-column</C>.

</LIST>

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

<P>
For the sake of this example, let's assume that <C>fill-column</C> is set
to column 30.  Assume that we have an Erlang comment paragraph on the
following form:
</P>

<CODE>
%% This is just a test to show
%% how the Erlang fill 
%% paragraph command works.
</CODE>

<P>
Assume that you would add the words "very simple" before the word
"test":
</P>

<CODE>
%% This is just a very simple test to show
%% how the Erlang fill
%% paragraph command works.
</CODE>

<P>
Clearly, the text is badly formatted.  Instead of formatting this
paragraph line by line, let's try <C>erlang-fill-paragraph</C> by
pressing <C>M-q</C>.  The result is:
</P>

<CODE>
%% This is just a very simple
%% test to show how the Erlang
%% fill paragraph command
%% works.
</CODE>

<P>
As you can see the paragraph is now evenly formatted.
</P>

</SECTION>

<SECTION>
<TITLE> Creating Comments </TITLE>

<P>
In Erlang it is possible to write comments to the right of the code.
The indentation system described in the chapter "Indentation" above is
able to indent lines containing only comments, and gives support for
end-of-the-line comments.
</P>

<LIST>

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

This command will create, or reindent, a comment to the right of the
code.  The variable <C>comment-column</C> controls the placement of the
comment character.

</LIST>
</SECTION>

<SECTION>

<TITLE> Comment Region </TITLE>

<P>
The standard command <C>comment-region</C> can be used to comment out
all lines in a region.  To uncomment the lines in a region precede
this command with <C>C-u</C>.
</P>

</SECTION>
</SECTION>

<!-- CHAPTER -->

<SECTION>
<TITLE>Syntax Highlighting</TITLE>

<P>
It is possible for Emacs to use colors when displaying a buffer.  By
"syntax highlighting", we mean that syntactic components, for example
keywords and function names, will be colored.
</P>

<P>
The basic idea of syntax highlighting is to make the structure of a
program clearer.  For example, the highlighting will make it easier to
spot simple bugs.  Have not you ever written a variable in lower-case
only?  With syntax highlighting a variable will colored while atoms
will be shown with the normal text color.
</P>

<P>
The syntax highlighting can be activated from the Erlang menu.  There
are four different alternatives:
</P>

<LIST>

<ITEM> Off: Normal black and white display.

<ITEM> Level 1: Function headers, reserved words, comments, strings, quoted
atoms, and character constants will be colored.

<ITEM> Level 2: The above, attributes, Erlang bif:s, guards, and words
in comments enclosed in single quotes will be colored.

<ITEM> Level 3: The above, variables, records, and macros will be colored.
(This level is also known as the Christmas tree level.)

</LIST>


<P>
The syntax highlighting is based on the standard Emacs package
"font-lock".  It is possible to use the font-lock commands and
variables to enable syntax highlighting.  The commands in question
are:
</P>

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

<P>
This command activates syntax highlighting for the current buffer.
</P>


<ITEM><C>M-x global-font-lock-mode RET</C><BR>

<P>
Activate syntax highlighting for all buffers.
</P>

</LIST>

<P>
The variable <C>font-lock-maximum-decoration</C> is used to specify
the level of highlighting.  If the variable is bound to an integer,
that level is used; if it is bound to <C>t</C> the highest possible
level is used.  (It is possible to set different levels for different
editing modes; please see the font-lock documentation for more
information.)
</P>

<P>
It is possible to change the color used.  It is even possible to use
bold, underlined, and italic fonts in combination with colors.
However, the method to do this differs between Emacs and XEmacs; and
between different versions of Emacs.  For Emacs 19.34, the variable
<C>font-lock-face-attributes</C> controls the colors.  For version 20 of
Emacs and XEmacs, the faces can be defined in the interactive custom
system.
</P>

<SECTION>
<MARKER ID="font-lock">
<TITLE>Customization</TITLE>

<P>
Font-lock mode is activated in different ways in different versions of
Emacs.  For modern versions of GNU Emacs place the following lines in
your <C>~/.emacs</C> file:
</P>

<CODE>
(setq font-lock-maximum-decoration t)
(global-font-lock-mode 1)
</CODE>

<!-- TODO: Check this -->
<P>
For modern versions of XEmacs the following code can be used:
</P>

<CODE>
(setq auto-font-lock-mode 1)
</CODE>

<P>
For older versions of Emacs and XEmacs, font-lock mode must be
activated individually for each buffer.  The following will add a
function to the Erlang mode hook that activates font-lock mode for all
Erlang buffers.
</P>

<CODE>
(defun my-erlang-font-lock-hook ()
  (font-lock-mode 1))

(add-hook 'erlang-mode-hook 'my-erlang-font-lock-hook)
</CODE>

</SECTION>

<SECTION>
<TITLE>Known Problems</TITLE>

<P>
Emacs has one problem with the syntactic structure of Erlang, namely
the <C>$</C> character.  The normal Erlang use of the $ character is
to denote the ASCII value of a character, for example:
</P>

<CODE>
ascii_value_of_a() -> $a.
</CODE>

<P>
In order to get the font-lock mechanism to work for the next example,
the $ character must be marked as an "escape" character that changes
the ordinary Emacs interpretation of the following double-quote
character.
</P>

<CODE>
ascii_value_of_quote() -> $".
</CODE>


<P>
The problem is that Emacs will also treat the <C>$</C> character as an
"escape" character at the end of strings and quoted atoms.
Practically, this means that Emacs will not detect the end of the
following string:
</P>
      
<CODE>
the_id() -> "$id: $".
</CODE>

<P>
Fortunately, there are ways around this.  From Erlang's point of view
the following two strings are equal: <C>"test$"</C> and
<C>"test\$"</C>.  The <C>\</C>-character is also marked as an Emacs "escape"
character, hence it will change the Emacs interpretation of the
<C>$</C>-character.
</P>

<P>
This work-around cannot always be used. For example, when the string is
used by an external version control program.  In this situation we can
try to avoid placing the <C>$</C>-character at the end of the string, for
example:
</P>

<CODE>
-vsn(" $Revision: 1.1 $ ").
</CODE>

<P>
Should this not be possible we can try to create an artificial end of
the string by placing an extra quote sign in the file. We do this as a
comment:
</P>

<CODE>
-vsn("$Revision: 1.1 $").    % "
</CODE>


<P>
The comment will be ignored by Erlang since it is a comment.  From
Emacs point of view the comment character is part of the string.
</P>

<P>
This problem is a generic problem for languages with similar syntax.
For example, the major mode for Perl suffers from the same problem.
</P>

</SECTION>
</SECTION>

<!-- CHAPTER -->

<SECTION>
<TITLE>Electric Commands</TITLE>

<P>
An "electric" command is a character that in addition to just
inserting the character performs some type of action.  For example the
";" character is typed in a situation where is ends a function clause
a new function header is generated.
</P>

<P>
Since some people find electric commands annoying they can be
deactivated, see section "<SEEALSO MARKER="#unplug_elec">Unplugging
the Electric Commands</SEEALSO>" below.
</P>

<SECTION>

<TITLE>The Commands</TITLE>

<LIST>
<ITEM><C> ; </C> (<C>erlang-electric-semicolon</C>)<BR>

<P>
Insert a semicolon.  When ending a function or the body of a
case clause, and the next few lines are empty, the special action will
be performed.  For functions, a new function header will be generated
and the point will be placed between the parentheses.  (See the
command <C>erlang-clone-arguments</C>.)  For other clauses the string
"<C> -&gt;</C>" will be inserted and the point will be placed in from of
the arrow.
</P>

<ITEM><C> , </C> (<C>erlang-electric-comma</C>)<BR>

<P>
Insert a comma. If the point is at the end of the line
and the next few lines are empty, a new indented line is created.
</P>

<ITEM><C> > </C> (<C>erlang-electric-arrow</C>)<BR>

<P>
Insert a <C>></C> character.  If it is inserted at the end of a line
after a <C>-</C> character so that an arrow "<C>-></C>" is being
formed, a new indented line is created. This requires that the next
few lines are empty.

<ITEM><C> RET </C> (<C>erlang-electric-newline</C>)<BR>

<P>
The special action of this command is normally off by default.  When
bound to the return key the following line will be indented.  Should
the current line contain a comment the initial comment characters will
be copied to the new line.  For example, assume that the point is at
the end of a line (denoted by "<C>&lt;point&gt</C>" below).
</P>

<CODE>
    %% A comment<point>
</CODE>

<P>
When pressing return (and <C>erlang-electric-newline</C> is active)
the result will be:
</P>

<CODE>
    %% A comment
    %% <point>
</CODE>

<P>
This command has a second feature.  When issued directly after another
electric command that created a new line this command does nothing.
The motivation is that it is in the fingers of many programmers to hit
the return key just when they have, for example, finished a function
clause with the <C>;</C> character.  Without this feature both the
electric semicolon and this command would insert one line each which
is probably not what the user wants.
</P>

</LIST>

</SECTION>

<SECTION>
<TITLE> Undo </TITLE>

<P>
All electric command will set an undo marker after the initial
character has been inserted but before the special action has been
performed.  By executing the undo command (<C>C-x u</C>) the effect of
the special action will be undone while leaving the character.
Execute undo a second time to remove the character itself.
</P>

</SECTION>

<SECTION>
<TITLE> Variables </TITLE>

<P>
The electric commands are controlled by a number of variables.
</P>

<LIST>
  <ITEM><C>erlang-electric-commands</C><BR>

<P>
This variable controls if an electric command is active or not.  This
variable should contain a list of electric commands to be active.  To
activate all electric commands bind this variable to the atom
<C>t</C>.
</P>


  <ITEM><C>erlang-electric-newline-inhibit</C><BR>

<P>
When non-<C>nil</C> when <C>erlang-electric-newline</C> should do
nothing when preceded by a electric command that is member of the
list <C>erlang-electric-newline-inhibit-list</C>.
</P>