The R13B03 release.OTP_R13B03

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>
+