aboutsummaryrefslogtreecommitdiffstats
path: root/lib/tools/doc/src/erlang_mode_chapter.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/tools/doc/src/erlang_mode_chapter.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/tools/doc/src/erlang_mode_chapter.xml')
-rw-r--r--lib/tools/doc/src/erlang_mode_chapter.xml251
1 files changed, 251 insertions, 0 deletions
diff --git a/lib/tools/doc/src/erlang_mode_chapter.xml b/lib/tools/doc/src/erlang_mode_chapter.xml
new file mode 100644
index 0000000000..cf043e3302
--- /dev/null
+++ b/lib/tools/doc/src/erlang_mode_chapter.xml
@@ -0,0 +1,251 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2003</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ 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 online 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.
+
+ </legalnotice>
+
+ <title>The Erlang mode for Emacs</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ <file>erlang_mode_chapter.xml</file>
+ </header>
+
+ <section>
+ <title>Purpose</title>
+ <p>The purpose of this user guide is to introduce you to the
+ Erlang mode for Emacs and gives some relevant background
+ information of the functions and features. See also <seealso marker="erlang.el">Erlang mode reference manual</seealso> The
+ purpose of the Erlang mode itself is to facilitate the developing
+ process for the Erlang programmer.</p>
+ </section>
+
+ <section>
+ <title>Pre-requisites</title>
+ <p>Basic knowledge of Emacs and Erlang/OTP. </p>
+ </section>
+
+ <section>
+ <title>Elisp</title>
+ <p>There are two Elsip modules include in this tool package
+ for Emacs. There is erlang.el that defines the actual erlang mode
+ and there is erlang-start.el that makes some nice initializations.</p>
+ </section>
+
+ <section>
+ <title>Setup on UNIX</title>
+ <p>To set up the Erlang Emacs mode on a UNIX systems, edit/create
+ the file <c>.emacs</c> in the your home directory.</p>
+ <p>Below is a complete example of what should be added to a user's
+ <c>.emacs</c> provided that OTP is installed in the directory
+ <c>/usr/local/otp </c>: </p>
+ <code type="none"><![CDATA[
+ (setq load-path (cons "/usr/local/otp/lib/tools-<ToolsVer>/emacs"
+ load-path))
+ (setq erlang-root-dir "/usr/local/otp")
+ (setq exec-path (cons "/usr/local/otp/bin" exec-path))
+ (require 'erlang-start)
+ ]]></code>
+ </section>
+
+ <section>
+ <title>Setup on Windows </title>
+ <p>To set up the Erlang Emacs mode on a Windows systems,
+ edit/create the file <c>.emacs</c>, the location of the file
+ depends on the configuration of the system. If the <em>HOME</em>
+ environment variable is set, Emacs will look for the
+ <c>.emacs</c> file in the directory indicated by the
+ <em>HOME</em> variable. If <em>HOME</em> is not set, Emacs
+ will look for the <c>.emacs</c> file in <c>C:\\ </c>.</p>
+ <p>Below is a complete example of what should be added to a user's
+ <c>.emacs</c> provided that OTP is installed in the directory
+ <c><![CDATA[C:\\Program Files\\erl<Ver>]]></c>: </p>
+ <code type="none"><![CDATA[
+ (setq load-path (cons "C:/Program Files/erl<Ver>/lib/tools-<ToolsVer>/emacs"
+ load-path))
+ (setq erlang-root-dir "C:/Program Files/erl<Ver>")
+ (setq exec-path (cons "C:/Program Files/erl<Ver>/bin" exec-path))
+ (require 'erlang-start)
+ ]]></code>
+ <note>
+ <p>In .emacs, the slash character "/" can be used as path
+ separator. But if you decide to use the backslash character "\\",
+ please not that you must use double backslashes, since they are
+ treated as escape characters by Emacs.</p>
+ </note>
+ </section>
+
+ <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>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 type="bulleted">
+ <item>Code using the same layout is easy to read and maintain. </item>
+ <item>Since several features of Erlang mode is based on the
+ standard layout they might not work correctly if a nonstandard layout
+ is used. </item>
+ </list>
+ <p>The indentation features can be used to reindent large sections
+ of a file. If some lines use nonstandard indentation they will
+ be reindented.</p>
+ </section>
+
+ <section>
+ <title>Editing</title>
+ <list type="bulleted">
+ <item><em><c>M-x erlang-mode RET</c></em> - This command activates
+ the Erlang major mode for the current buffer. When this
+ mode is active the mode line contain the word "Erlang".</item>
+ </list>
+ <p>When the 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.</p>
+ <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>
+ <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. The electric
+ commands are as follows: </p>
+ <list type="bulleted">
+ <item><em><c>erlang-electric-comma</c></em> - Insert a comma
+ character and possibly a new indented line. </item>
+ <item><em><c>erlang-electric-semicolon</c></em> - Insert a
+ semicolon character and possibly a prototype for the next line.</item>
+ <item><em><c>erlang-electric-gt</c></em> - "Insert a '>'-sign
+ and possible a new indented line.</item>
+ </list>
+ <p>To disable all electric commands set the variable
+ <c>erlang-electric-commands</c> to the empty list. In short,
+ place the following line in your <c>.emacs</c>-file:</p>
+ <code type="none">
+ (setq erlang-electric-commands '())</code>
+ </section>
+
+ <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>
+ </section>
+
+ <section>
+ <marker id="tags"></marker>
+ <title>Tags</title>
+ <p>Tags is a standard Emacs package used to record information
+ about source files in large development projects. In addition to
+ listing the files of a project, a tags file normally contains
+ information about all functions and variables that are defined.
+ By far, the most useful command of the tags system is its ability
+ to find the definition of functions in any file in the project.
+ However the Tags system is not limited to this feature, for
+ example, it is possible to do a text search in all files in a
+ project, or to perform a project-wide search and replace.</p>
+ <p>In order to use the Tags system a file named <c>TAGS</c> must be
+ created. The file can be seen as a database over all functions,
+ records, and macros in all files in the project. The
+ <c>TAGS</c> file can be created using two different methods for
+ Erlang. The first is the standard Emacs utility "etags", the
+ second is by using the Erlang module <c>tags</c>.</p>
+ </section>
+
+ <section>
+ <title>Etags</title>
+ <p><c>etags</c> is a program that is part of the Emacs
+ distribution. It is normally executed from a command line, like
+ a unix shell or a DOS box.</p>
+ <p>The <c>etags</c> program of fairly modern versions of Emacs and XEmacs
+ has native support for Erlang. To check if your version does include
+ this support, issue the command <c>etags --help</c> at a the command
+ line prompt. At the end of the help text there is a list of supported
+ languages. Unless Erlang is a member of this list I suggest that you
+ should upgrade to a newer version of Emacs.</p>
+ <p>As seen in the help text -- unless you have not upgraded your
+ Emacs yet (well, what are you waiting around here for? Off you go and
+ upgrade!) -- <c>etags</c> associate the file extensions <c>.erl</c>
+ and <c>.hrl</c> with Erlang.</p>
+ <p>Basically, the <c>etags</c> utility is ran using the following form:</p>
+ <code type="none">
+ etags file1.erl file2.erl</code>
+ <p>This will create a file named <c>TAGS</c> in the current directory.</p>
+ <p>The <c>etags</c> utility can also read a list of files from its
+ standard input by supplying a single dash in place of the file
+ names. This feature is useful when a project consists of a
+ large number of files. The standard UNIX command <c>find</c>
+ can be used to generate the list of files, e.g:</p>
+ <code type="none">
+ find . -name "*.[he]rl" -print | etags -</code>
+ <p>The above line will create a <c>TAGS</c> file covering all the
+ Erlang source files in the current directory, and in the
+ subdirectories below.</p>
+ <p>Please see the GNU Emacs Manual and the etags man page for more
+ info.</p>
+ </section>
+
+ <section>
+ <title>Shell</title>
+ <p>The look and feel on an Erlang shell inside Emacs should be the
+ same as in a normal Erlang shell. There is just one major
+ difference, the cursor keys will actually move the cursor around
+ just like in any normal Emacs buffer. The command line history
+ can be accessed by the following commands: </p>
+ <list type="bulleted">
+ <item><em><c>C-up </c></em> or <em><c>M-p </c></em>
+ (<c>comint-previous-input</c>) -
+ Move to the previous line in the input history.</item>
+ <item><em><c>C-down </c></em> or <em><c>M-n </c></em>
+ (<c>comint-next-input</c>) - Move to the next line in the
+ input history.</item>
+ </list>
+ <p>If the Erlang shell buffer would be killed the command line
+ history is saved to a file. The command line history is
+ automatically retrieved when a new Erlang shell is started.</p>
+ </section>
+
+ <section>
+ <title>Compilation</title>
+ <p>The classic edit-compile-bugfix cycle for Erlang is to edit the
+ source file in an editor, save it to a file and switch to an
+ Erlang shell. In the shell the compilation command is given.
+ Should the compilation fail you have to bring out the editor and
+ locate the correct line.</p>
+ <p>With the Erlang editing mode the entire edit-compile-bugfix cycle can
+ be performed without leaving Emacs. Emacs can order Erlang to compile
+ a file and it can parse the error messages to automatically place the
+ point on the erroneous lines.</p>
+ </section>
+</chapter>
+