+\input texinfo @c -*-texinfo-*-
+@setfilename ../../info/ada-mode
+@settitle Ada Mode
+
+@copying
+Copyright @copyright{} 1999 - 2014 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
+and with the Back-Cover Texts as in (a) below. A copy of the license
+is included in the section entitled ``GNU Free Documentation License''.
+
+(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
+modify this GNU manual. Buying copies from the FSF supports it in
+developing GNU and promoting software freedom.''
+@end quotation
+@end copying
+
+@dircategory Emacs editing modes
+@direntry
+* Ada mode: (ada-mode). Emacs mode for editing and navigating Ada code.
+@end direntry
+
+@titlepage
+@sp 10
+@title Ada Mode
+@sp 2
+@subtitle An Emacs major mode for programming in Ada
+@subtitle Ada Mode Version 5.1.5
+@sp 2
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@contents
+
+@node Top, Overview, (dir), (dir)
+
+@ifnottex
+@insertcopying
+@end ifnottex
+
+@menu
+* Overview::
+* Installation:: Installing Ada mode on your system
+* Customization:: Setting up Ada mode to your taste
+* Compiling Executing:: Working with your application within Emacs
+* Project files:: Describing the organization of your project
+* Moving Through Ada Code:: Moving easily through Ada sources
+* Identifier completion:: Finishing words automatically
+* Indentation:: Indenting your code automatically as you type
+* Statement skeletons:: Some code is written for you
+* Aligning code:: Making it pretty
+* Automatic casing:: Adjusting the case of words automatically
+* Comment Handling:: Reformatting comments easily
+* Key summary::
+* Developer overview::
+* GNU Free Documentation License::
+* Index::
+@end menu
+
+@node Overview, Installation, Top, Top
+@chapter Overview
+
+The Emacs mode for programming in Ada helps the user in reading
+existing code and facilitates developing new code.
+
+Cross-reference information output by the compiler is used to provide
+powerful code navigation (jump to definition, find all uses, etc).
+
+When you open a file with a file extension of @file{.ads} or
+@file{.adb}, Emacs will automatically load and activate Ada
+mode.
+
+Ada mode works without any customization, if you are using the GNAT
+compiler (@url{https://libre2.adacore.com/}) and the GNAT default
+naming convention.
+
+You must customize a few things if you are using a different file
+naming convention or compiler; @xref{Non-standard file names},
+@xref{Other compiler}.
+
+In addition, you may want to customize the indentation,
+capitalization, and other things; @xref{Other customization}.
+
+Finally, for large Ada projects, you will want to set up an Emacs Ada
+mode project file for each project; @xref{Project files}. Note that
+these are different from the GNAT project files used by the GNAT
+tools.
+
+@xref{Debuggers,,Debuggers,emacs,Emacs User Guide}, for general
+information on debugging.
+
+@node Installation, Customization, Overview, Top
+@chapter Installation
+
+Ada mode requires Emacs 24.2 or greater; it also requires the Emacs
+lisp sources (not just the compiled binaries).
+
+Ada mode is distributed in the Gnu ELPA package archive; it can be
+installed via @code{M-x list-packages} (@pxref{Packages,,,emacs,Emacs
+User Guide}). You must first enable packages in your @file{~/.emacs},
+@emph{after} customizing @code{Info-default-directory-list} (if you do
+that):
+
+@example
+(package-initialize)
+@end example
+
+Ada mode is also available as a separate distribution, from the Emacs
+Ada mode website
+@uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html}.
+
+For installing the separate distribution, see the @file{README} file
+in the distribution.
+
+To see what version of Ada mode you have installed, invoke @kbd{M-x
+ada-mode-version}.
+
+@menu
+* gnatinspect::
+* Upgrading::
+@end menu
+
+@node gnatinspect, Upgrading, Installation, Installation
+@section gnatinspect
+Ada mode has experimental support for the new AdaCore cross reference
+tool @code{gnatinspect}, which supports Ada, C, C++, and any other
+language for which gcc provices the @code{-fdump-xref}.
+
+@code{gnatinspect} is distributed as part of @code{gnatcoll}. Ada mode
+requires the very latest version, in @code{gnatcoll 1.7w} distributed
+with GNAT GPL 2014.
+
+To build @code{gnatinspect}, assuming GNAT GPL 2014 is installed in
+@file{/usr/gnat-gpl-2014}, and @file{/usr/gnat-gpl-2014/bin} is in
+PATH:
+
+@example
+tar xf ~/Downloads/gnatcoll-1.7x-src.tgz
+cd gnatcoll-1.7w-src
+./configure --prefix=/usr/gnat-gpl-2014
+make Gnatcoll_Build=Debug
+sudo make Gnatcoll_Build=Debug install
+@end example
+
+To build an sqlite3 executable that is compatible with the database
+created by gnatinspect:
+
+@example
+cd gnatcoll-1.7w-src/src/sqlite/amalgamation/
+gcc -O2 -o sqlite3 shell.c sqlite3.c -ldl -lpthread
+@end example
+
+@node Upgrading, , gnatinspect, Installation
+@section Upgrading from previous versions
+
+See the file NEWS for more details; here we summarize only important
+user interface changes.
+
+@table @samp
+@item from 5.0.1
+ Nothing to do.
+
+@item from 4.01
+There are many user interface and API changes between 4.01 and 5.0.1;
+we only document those that may be hard to diagnose here.
+
+@code{prog-mode-hook} is no longer run by @code{ada-mode};
+@code{ada-mode} is no longer derived from @code{prog-mode}. Use
+@code{ada-mode-hook} instead.
+
+
+@end table
+
+@node Customization, Compiling Executing, Installation, Top
+@chapter Customizing Ada mode
+
+Here we assume you are familiar with setting variables in Emacs,
+either thru 'customize' or in elisp (in your @file{.emacs} file). For
+a basic introduction to customize, elisp, and Emacs in general, see
+the tutorial (@kbd{C-h t}).
+
+@menu
+* Non-standard file names::
+* Other compiler::
+* Other cross-reference::
+* Other customization::
+@end menu
+
+@node Non-standard file names, Other compiler, Customization, Customization
+@section Non-standard file names
+
+By default, Ada mode is configured to use the GNAT file naming
+convention, where file names are a simple modification of the Ada
+names, and the extension for specs and bodies are
+@samp{.ads} and @samp{.adb}, respectively.
+
+Emacs uses the file extension to enable Ada mode; Ada mode uses the
+file extentions to allow moving from a package body to the
+corresponding spec and back.
+
+Emacs and Ada mode support ways to use alternative file extensions for
+specs and bodies. Note that you must also tell the compiler about
+these extensions; doing that is beyond the scope of this manual.
+
+For instance, if your spec and bodies files are called
+@file{@var{unit}_s.ada} and @file{@var{unit}_b.ada}, respectively, you
+can add the following to your @file{.emacs} file:
+
+@example
+;; Tell Ada mode about spec and body extensions
+(ada-add-extensions "_s.ada" "_b.ada")
+
+;; Tell Emacs to use Ada mode for those extensions
+(add-to-list 'auto-mode-alist '("\\.ada\\'" . ada-mode))
+@end example
+
+You can define additional extensions:
+
+@example
+(ada-add-extensions ".ads" "_b.ada")
+(ada-add-extensions ".ads" ".body")
+@end example
+
+This means that whenever Ada mode looks for the body for a file
+whose extension is @file{.ads}, it will take the first available file
+that ends with either @file{.adb}, @file{_b.ada} or
+@file{.body}.
+
+Simililarly, if Ada mode is looking for a spec, it will look for
+@file{.ads} or @file{_s.ada}.
+
+If the filename excluding the extension is not derived from the Ada
+name following the GNAT convention, you need to provide an alternate
+function for @code{ada-file-name-from-ada-name}. Doing that is beyond
+the scope of this manual; see the current definitions in
+@file{ada-mode.el} and @file{ada-gnat-xref.el} for examples.
+
+@node Other compiler, Other cross-reference, Non-standard file names, Customization
+@section Other compiler
+The project variable @code{ada_compiler} (default elisp variable
+@code{ada-compiler}) is used to index several variables that point to
+the compiler-specific functions for corresponding Ada mode operations.
+
+To use a compiler other than GNAT, you must write Emacs lisp code that
+provides the interface to the compiler, and set @code{ada-compiler} and
+the indirection variables.
+
+See @file{ada-gnat-compile.el} for an example.
+
+@node Other cross-reference, Other customization, Other compiler, Customization
+@section Other cross-reference
+The project variable @code{ada_xref} (default elisp variable
+@code{ada-xref-tool}) is used to index several variables that point to
+the cross-reference-tool-specific functions for corresponding Ada mode
+operations.
+
+To use a cross reference tool other than gnatxref, you must write
+Emacs lisp code that provides the interface to the compiler, and set
+@code{ada-xref-tool} and the indirection variables. This has already
+been done for @code{gnatinspect}; set @code{ada-xref-tool} to
+@code{'gnat_inspect}.
+
+See @file{ada-gnat-xref.el} and @file{gnat-inspect.el} for examples.
+
+@node Other customization, , Other cross-reference, Customization
+@section Other customization
+
+All user-settable Ada mode variables can be set via the menu
+@samp{Ada | Customize}. Click on the @samp{Help} button there for help
+on using customize.
+
+To modify a specific variable, you can directly call the function
+@code{customize-variable}; just type @kbd{M-x customize-variable
+@key{RET} @var{variable-name} @key{RET}}).
+
+Alternately, you can specify variable settings in the Emacs
+configuration file, @file{~/.emacs}. This file is coded in Emacs lisp,
+and the syntax to set a variable is the following:
+@example
+(setq variable-name value)
+@end example
+
+Some general Emacs settings that are useful for Ada files:
+@table @code
+@item delete-trailing-whitespace
+Deletes space, tab at end of line and blank lines at end of buffer.
+@item untabify
+Deletes tab characters that have crept into the file.
+@item indent-tabs-mode
+Don't insert tab characters when indenting.
+@item copyright-update
+Updates the copyright date in the file header comment, to the current
+year.
+@item electric-pair-mode
+Insert a matching right paren when you type a left paren.
+@item hippie-expand
+Bind @code{hippie-expand} to a key; it expands the word before point, using
+words from current buffer, other buffers, file names, etc; see
+@code{hippie-expand-try-functions-list}. You can also add
+@code{ada-skel-hippie-try} to that list. Note that @code{ada-expand},
+which defaults to @code{ada-skel-expand}, is bound to @key{C-c C-e}
+(@pxref{Statement skeletons}).
+@item imenu
+@item which-func
+@end table
+
+The above can all be set by the following code in your
+@file{~/.emacs}. Note that some are functions are added to
+@code{before-save-hook}; they run just before a buffer is written to
+disk. Also, the order is important; ada-mode does not set up the
+Ada-specific features of imenu and which-func unless they are loaded
+first.
+
+@example
+(setq-default indent-tabs-mode nil)
+(electric-pair-mode 1)
+(require 'imenu)
+(require 'which-func)
+(require 'ada-mode)
+(add-to-list 'hippie-expand-try-functions-list 'ada-skel-hippie-try)
+(define-key ada-mode-map "\C-e" 'hippie-expand)
+(add-hook 'ada-mode-hook
+ (lambda ()
+ (add-hook 'before-save-hook 'delete-trailing-whitespace nil t)
+ (add-hook 'before-save-hook 'copyright-update nil t)
+ (add-hook 'before-save-hook
+ (lambda () (untabify (point-min) (point-max)))
+ nil t)))
+@end example
+
+@node Compiling Executing, Project files, Customization, Top
+@chapter Compiling Executing
+
+Ada projects can be compiled, linked, and executed using commands on
+the Ada menu. All of these commands can be customized via a project
+file (@pxref{Project files}), but the defaults are sufficient for using
+the GNAT compiler for simple projects (single files, or several files
+in a single directory).
+
+For complex projects, you will want to use @code{make} or some other
+build tool; in that case, you will need an Emacs Ada mode project file
+to tell Emacs about the project directory tree and other settings.
+
+@menu
+* Compile commands::
+* Compiling Examples::
+* Compiler errors::
+@end menu
+
+@node Compile commands, Compiling Examples, Compiling Executing, Compiling Executing
+@section Compile commands
+
+Here are the commands for building an Ada project and running the main
+program.
+
+In multi-file projects, there must be one file that is the main
+program. That is given by the @code{main} project file variable;
+it defaults to the current file if not yet set, but is also set by the
+``set main and build'' command.
+@c IMPROVEME: get main from gpr via gnatinspect? not in gnatcoll 1.6w
+
+@table @code
+
+@item Check file
+Compiles the current file in syntax check mode, by running
+@code{check_cmd} defined in the current project file. This typically
+runs faster than full compile mode, speeding up finding and fixing
+compilation errors.
+
+This sets @code{main} only if it has not been set yet.
+
+@item Compile file
+Compiles the current file, by running @code{comp_cmd} from the current
+project file.
+
+This does not set @code{main}.
+
+@item Set main and Build
+Sets @code{main} to the current file, then executes the Build
+command.
+
+@item Show main
+Display @code{main} in the message buffer.
+
+@item Build
+Compiles all obsolete units of the current @code{main}, and links
+@code{main}, by running @code{make_cmd} from the current project.
+
+This sets @code{main} only if it has not been set yet.
+
+@item Run
+Executes the main program in a shell, displayed in a separate Emacs
+buffer. This runs @code{run_cmd} from the current project. The
+execution buffer allows for interactive input/output.
+
+To modify the run command, in particular to provide or change the
+command line arguments, type @kbd{C-u} before invoking the command.
+
+This command is not available for a cross-compilation toolchain.
+
+@end table
+It is important when using these commands to understand how
+@code{main} is used and changed.
+
+Build runs 'gnatmake' on the main unit. During a typical edit/compile
+session, this is the only command you need to invoke, which is why it
+is bound to @kbd{C-c C-c}. It will compile all files needed by the
+main unit, and display compilation errors in any of them.
+
+Note that Build can be invoked from any Ada buffer; typically you will
+be fixing errors in files other than the main, but you don't have to
+switch back to the main to invoke the compiler again.
+
+Novices and students typically work on single-file Ada projects. In
+this case, @kbd{C-c C-m} will normally be the only command needed; it
+will build the current file, rather than the last-built main.
+
+There are three ways to change @code{main}:
+
+@enumerate
+@item
+Invoke @samp{Ada | Set main and Build}, which sets @code{main} to
+the current file.
+
+@item
+Invoke @samp{Ada | Project | Edit}, edit @code{main} and
+@code{main}, and click @samp{[save]}
+
+@item
+Invoke @samp{Ada | Project | Load}, and load a project file that specifies @code{main}
+
+@end enumerate
+
+@node Compiling Examples, Compiler errors, Compile commands, Compiling Executing
+@section Compiling Examples
+
+We present several small projects, and walk thru the process of
+compiling, linking, and running them.
+
+The first example illustrates more Ada mode features than the others;
+you should work thru that example before doing the others.
+
+All of these examples assume you are using GNAT.
+
+The source for these examples is available on the Emacs Ada mode
+website mentioned in @xref{Installation}.
+
+@menu
+* No project files:: Just menus
+* Set compiler options:: A basic Ada mode project file
+* Set source search path:: Source in multiple directories
+* Use GNAT project file::
+* Use multiple GNAT project files::
+* Use a Makefile::
+@end menu
+
+@node No project files, Set compiler options, Compiling Examples, Compiling Examples
+@subsection No project files
+This example uses no project files.
+
+First, create a directory @file{Example_1}, containing:
+
+@file{hello.adb}:
+
+@example
+with Ada.Text_IO;
+procedure Hello
+is begin
+ Put_Line("Hello from hello.adb");
+end Hello;
+@end example
+
+Yes, this is missing ``use Ada.Text_IO;'' - we want to demonstrate
+compiler error handling.
+
+@file{hello_2.adb} has no errors:
+
+@example
+with Hello_Pkg;
+procedure Hello_2
+is begin
+ Hello_Pkg.Say_Hello;
+end Hello_2;
+@end example
+
+@file{hello_pkg.ads} has no errors:
+
+@example
+package Hello_Pkg is
+ procedure Say_Hello;
+end Hello_Pkg;
+@end example
+
+@file{hello_pkg.adb}:
+
+@example
+with Ada.Text_IO;
+package Hello_Pkg is
+ procedure Say_Hello
+ is begin
+ Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
+ end Say_Hello;
+end Hello_Pkg;
+@end example
+
+Yes, this is missing the keyword @code{body}; another compiler error
+example. However, note that the indentation engine parser accepts this
+code with no errors, making it easier to indent slightly illegal Ada
+code.
+
+In buffer @file{hello.adb}, invoke the menu entry @samp{Ada | Build |
+Check syntax}. You should get a @code{*compilation*} buffer containing
+something like (the directory paths will be different):
+
+@example
+-*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
+Compilation started at Fri Oct 18 04:23:54
+
+gnatmake -u -c -gnatc c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/hello.adb -cargs
+gcc -c -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/ -gnatc -I- c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/hello.adb
+hello.adb:4:04: "Put_Line" is not visible
+hello.adb:4:04: non-visible declaration at a-textio.ads:263
+hello.adb:4:04: non-visible declaration at a-textio.ads:259
+gnatmake: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/hello.adb" compilation error
+
+Compilation exited abnormally with code 4 at Fri Oct 18 04:23:54
+@end example
+
+The lines with actual errors (starting with @file{hello.adb}) are
+highlighted, with the file name in red.
+
+Now invoke @samp{Ada | Build | Next compilation error}. Or you can
+click the middle mouse button on the first error line, or use the key
+binding shown on the menu. The compilation buffer scrolls to put the
+first error on the top line, and point is put at the place of the
+error in the @file{hello.adb} buffer.
+
+To fix the error, invoke @samp{Ada | Build | Fix compilation error};
+this adds ``Ada.Text_Io.'' to the line:
+
+@example
+ Ada.Text_Io.Put_Line ("hello from hello.adb");
+@end example
+
+Now invoke @samp{Ada | Build | Show main}; this displays @samp{Ada mode main: hello}.
+
+Now (in buffer @file{hello.adb}), invoke @samp{Ada | Build | Build}. You are
+prompted to save the file (if you haven't already). Then the
+compilation buffer is displayed again, containing:
+
+@example
+-*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
+Compilation started at Fri Oct 18 20:39:33
+
+gnatmake -o hello hello -cargs -bargs -largs
+gcc -c hello.adb
+gnatbind -x hello.ali
+gnatlink hello.ali -o hello.exe
+
+Compilation finished at Fri Oct 18 20:39:34
+@end example
+
+The compilation has succeeded without errors; @file{hello.exe} now
+exists in the same directory as @file{hello.adb}.
+
+Now invoke @samp{Ada | Build | Run}. The @file{*compilation*} buffer
+is displayed, containing
+
+@example
+-*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_1/" -*-
+Compilation started at Fri Oct 18 20:41:53
+
+./hello
+Hello from hello.adb
+
+Compilation finished at Fri Oct 18 20:41:53
+@end example
+
+That completes the first part of this example.
+
+Now we will compile a multi-file project. Open the file
+@file{hello_2.adb}, invoke @samp{Ada | Build | Set main and
+Build}. This finds an error in @file{hello_pkg.adb}:
+
+@example
+hello_pkg.adb:2:08: keyword "body" expected here [see file name]
+@end example
+
+This demonstrates that gnatmake finds the files needed by the main
+program. However, it cannot find files in a different directory,
+unless you use an Emacs Ada mode project file or a GNAT project file
+to specify the other directories; @xref{Set source search path},
+@ref{Use GNAT project file}.
+
+Invoke @samp{Ada | Build | Show main}; this displays @file{Ada mode
+main: hello_2}.
+
+Move to the error with @kbd{C-x `}, and fix the error by adding @code{body}:
+
+@example
+package body Hello_Pkg is
+@end example
+
+Now, while still in @file{hello_pkg.adb}, invoke @samp{Ada | Build |
+Build}. gnatmake successfully builds @file{hello_2}. This
+demonstrates that Emacs has remembered the main file, in the project
+variable @code{main}, and used it for the Build command.
+
+Finally, again while in @file{hello_pkg.adb}, invoke @samp{Ada | Build
+| Run}. The @code{*compilation*} buffer displays @code{Hello from
+hello_pkg.adb}.
+
+One final point. If you switch back to buffer @file{hello.adb}, and
+invoke @samp{Ada | Build | Run}, @file{hello_2.exe} will be run. That
+is because @code{main} is still set to @code{hello_2}, as you can see
+when you invoke @samp{Ada | Build | Show main}.
+
+There are two ways to change @code{main}:
+
+@enumerate
+@item
+Invoke @samp{Ada | Build | Set main and Build}, which sets @code{main} to
+the current file.
+
+@item
+Invoke @samp{Ada | Build | Set Project ...}, and select a project file that
+specifies @code{main}.
+
+@end enumerate
+
+@node Set compiler options, Set source search path, No project files, Compiling Examples
+@subsection Set compiler options
+
+This example illustrates using an Emacs Ada mode project file to set a
+compiler option.
+
+If you have files from @file{Example_1} open in Emacs, you should
+close them so you don't get confused. Use menu @samp{File | Close
+(current buffer)}.
+
+In directory @file{Example_2}, create these files:
+
+@file{hello.adb}:
+
+@example
+with Ada.Text_IO;
+procedure Hello
+is begin
+ Put_Line("Hello from hello.adb");
+end Hello;
+@end example
+
+This is the same as @file{hello.adb} from @file{Example_1}. It has two
+errors; missing ``use Ada.Text_IO;'', and no space between
+@code{Put_Line} and its argument list.
+
+@file{hello.adp}:
+
+@example
+comp_opt=-gnatyt
+@end example
+
+This tells the GNAT compiler to check for token spacing; in
+particular, there must be a space preceding a parenthesis.
+
+In buffer @file{hello.adb}, invoke @samp{Ada | Build | Set main and
+Build}. This finds the project file @file{hello.adp}, uses it to set
+the compiler options, and builds the project. You should get a
+@code{*compilation*} buffer containing something like (the directory
+paths will be different):
+
+@example
+cd c:/Examples/Example_2/
+gnatmake -o hello hello -g -cargs -gnatyt -bargs -largs
+gcc -c -g -gnatyt hello.adb
+hello.adb:4:04: "Put_Line" is not visible
+hello.adb:4:04: non-visible declaration at a-textio.ads:264
+hello.adb:4:04: non-visible declaration at a-textio.ads:260
+hello.adb:4:12: (style) space required
+gnatmake: "hello.adb" compilation error
+@end example
+
+Compare this to the compiler output in @ref{No project files}; the
+gnatmake option @code{-cargs} has been replaced by @code{-cargs
+-gnaty}, and an additional error is reported in @file{hello.adb} on
+line 4. This shows that @file{hello.adp} is being used to set the
+compiler options.
+
+Fixing the error, linking and running the code proceed as in @ref{No
+project files}.
+
+@node Set source search path, Use GNAT project file, Set compiler options, Compiling Examples
+@subsection Set source search path
+
+In this example, we show how to deal with files in more than one
+directory, using an Emacs Ada mode project file to set the search
+path.
+
+Create the directory @file{Example_3}, containing:
+
+@file{hello_pkg.ads}:
+
+@example
+package Hello_Pkg is
+ procedure Say_Hello;
+end Hello_Pkg;
+@end example
+
+@file{hello_pkg.adb}:
+
+@example
+with Ada.Text_IO;
+package Hello_Pkg is
+ procedure Say_Hello
+ is begin
+ Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
+ end Say_Hello;
+end Hello_Pkg;
+@end example
+
+These are the same files from example 1; @file{hello_pkg.adb} has an
+error on line 2.
+
+In addition, create a directory @file{Example_3/Other}, containing these files:
+
+@file{Other/hello_3.adb}:
+
+@example
+with Hello_Pkg;
+with Ada.Text_IO; use Ada.Text_IO;
+procedure Hello_3
+is begin
+ Hello_Pkg.Say_Hello;
+ Put_Line ("From hello_3");
+end Hello_3;
+@end example
+
+There are no errors in this file.
+
+@file{Other/other.adp}:
+
+@example
+src_dir=..
+@end example
+
+Note that there must be no trailing spaces.
+
+In buffer @file{hello_3.adb}, invoke @samp{Ada | Project files | Find and
+set project...}, and select @file{Example_3/Other/other.adp}. This
+tells Emacs Ada mode to stop using the project file from
+@file{Example_2}, and use the one for @file{Example_3}. Also note that
+since this project file is not named @file{hello_3.adp}, it would not
+be found by default.
+
+Then, again in @file{hello_3.adb}, invoke @samp{Ada | Set main and
+Build}. You should get a @code{*compilation*} buffer containing
+something like (the directory paths will be different):
+
+@example
+cd c:/Examples/Example_3/Other/
+gnatmake -o hello_3 hello_3 -g -cargs -I.. -bargs -largs
+gcc -c -g -I.. hello_3.adb
+gcc -c -I./ -g -I.. -I- C:\Examples\Example_3\hello_pkg.adb
+hello_pkg.adb:2:08: keyword "body" expected here [see file name]
+gnatmake: "C:\Examples\Example_3\hello_pkg.adb" compilation error
+@end example
+
+Compare the @code{-cargs} option to the compiler output in @ref{Set
+compiler options}; this shows that @file{other.adp} is being used to
+set the compiler options.
+
+Move to the error with @kbd{C-x `}. Ada mode searches the list of
+directories given by @code{src_dir} for the file mentioned in the
+compiler error message.
+
+Fixing the error, linking and running the code proceed as in @ref{No
+project files}.
+
+@node Use GNAT project file, Use multiple GNAT project files, Set source search path, Compiling Examples
+@subsection Use GNAT project file
+
+In this example, we show how to use a GNAT project file, with no Ada
+mode project file.
+
+Create the directory @file{Example_4}, containing:
+
+@file{hello_pkg.ads}:
+
+@example
+package Hello_Pkg is
+ procedure Say_Hello;
+end Hello_Pkg;
+@end example
+
+@file{hello_pkg.adb}:
+
+@example
+with Ada.Text_IO;
+package Hello_Pkg is
+ procedure Say_Hello
+ is begin
+ Ada.Text_IO.Put_Line ("Hello from hello_pkg.adb");
+ end Say_Hello;
+end Hello_Pkg;
+@end example
+
+These are the same files from example 1; @file{hello_pkg.adb} has an
+error on line 2.
+
+In addition, create a directory @file{Example_4/Gnat_Project},
+containing these files:
+
+@file{Gnat_Project/hello_4.adb}:
+
+@example
+with Hello_Pkg;
+with Ada.Text_IO; use Ada.Text_IO;
+procedure Hello_4
+is begin
+ Hello_Pkg.Say_Hello;
+ Put_Line ("From hello_4");
+end Hello_4;
+@end example
+
+There are no errors in this file.
+
+@file{Gnat_Project/hello_4.gpr}:
+
+@example
+project Hello_4 is
+ for Source_Dirs use (".", "..");
+end Hello_4;
+@end example
+
+In buffer @file{hello_4.adb}, invoke @samp{Ada | Project | Load...}, and
+select @file{Example_4/Gnat_Project/hello_4.gpr}.
+
+Then, again in @file{hello_4.adb}, invoke @samp{Ada | Set main and
+Build}. You should get a @code{*compilation*} buffer containing
+something like (the directory paths will be different):
+
+@example
+-*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project/" -*-
+Compilation started at Mon Oct 21 11:28:31
+
+gnatmake -Pc:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project/hello_4.gpr -o hello_4 hello_4 -cargs -I. -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4 -Ic:/Apps/GNAT-7.1.2/lib/gcc/i686-pc-mingw32/4.7.3/adainclude -bargs -largs
+gcc -c -I. -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4 -Ic:/Apps/GNAT-7.1.2/lib/gcc/i686-pc-mingw32/4.7.3/adainclude -I- -gnatA C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb
+hello_pkg.adb:2:08: keyword "body" expected here [see file name]
+gnatmake: "C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb" compilation error
+
+Compilation exited abnormally with code 4 at Mon Oct 21 11:28:31
+@end example
+
+Compare the @code{gcc} options to the compiler output in @ref{Set
+compiler options}; this shows that @file{hello_4.gpr} is being used to
+set the compiler options.
+
+Fixing the error, linking and running the code proceed as in @ref{No
+project files}.
+
+@node Use multiple GNAT project files, Use a Makefile, Use GNAT project file, Compiling Examples
+@subsection Use multiple GNAT project files
+
+In this example, we show how to use multiple GNAT project files,
+specifying the GNAT project search path in an Ada mode project file.
+
+Create the directory @file{Example_4} as specified in @ref{Use GNAT
+project file}.
+
+Create the directory @file{Example_5}, containing:
+
+@file{hello_5.adb}:
+
+@example
+with Hello_Pkg;
+with Ada.Text_IO; use Ada.Text_IO;
+procedure Hello_5
+is begin
+ Hello_Pkg.Say_Hello;
+ Put_Line ("From hello_5");
+end Hello_5;
+@end example
+
+There are no errors in this file.
+
+@file{hello_5.adp}:
+
+@example
+ada_project_path=../Example_4/Gnat_Project
+gpr_file=hello_5.gpr
+@end example
+
+@file{hello_5.gpr}:
+
+@example
+with "hello_4";
+project Hello_5 is
+ for Source_Dirs use (".");
+ package Compiler is
+ for Default_Switches ("Ada") use ("-g", "-gnatyt");
+ end Compiler;
+end Hello_5;
+@end example
+
+In buffer @file{hello_5.adb}, invoke @samp{Ada | Project | Find and
+select project...}, and select @file{Example_5/hello_5.adp}. This
+would also be found by default if no previous project file had been
+selected.
+
+Then, again in @file{hello_5.adb}, invoke @samp{Ada | Build | Set main
+and Build}. You should get a @code{*compilation*} buffer containing
+something like (the directory paths will be different):
+
+@example
+-*- mode: compilation; default-directory: "c:/Projects/org.emacs.ada-mode.stephe-1/test/Example_5/" -*-
+Compilation started at Mon Oct 21 11:32:05
+
+gnatmake -Pc:/Projects/org.emacs.ada-mode.stephe-1/test/Example_5/hello_5.gpr -o hello_5 hello_5 -cargs -I. -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_5 -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4 -Ic:/Apps/GNAT-7.1.2/lib/gcc/i686-pc-mingw32/4.7.3/adainclude -bargs -largs
+gcc -c -I. -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_5 -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4/Gnat_Project -Ic:/Projects/org.emacs.ada-mode.stephe-1/test/Example_4 -Ic:/Apps/GNAT-7.1.2/lib/gcc/i686-pc-mingw32/4.7.3/adainclude -I- -gnatA C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb
+hello_pkg.adb:2:08: keyword "body" expected here [see file name]
+gnatmake: "C:\Projects\org.emacs.ada-mode.stephe-1\test\Example_4\hello_pkg.adb" compilation error
+
+Compilation exited abnormally with code 4 at Mon Oct 21 11:32:05
+@end example
+
+Now type @kbd{C-x `}. @file{Example_4/hello_pkg.adb} is shown,
+demonstrating that @file{hello_5.gpr} and @file{hello_4.gpr} are being
+used to set the compilation search path.
+
+@node Use a Makefile, , Use multiple GNAT project files, Compiling Examples
+@subsection Use a Makefile
+
+In this example, we show how to use a Makefile to build an Ada project
+with GNAT, run the result, and clean the build directories.
+
+Create the directories @file{Example_4, Example_5} as specified in @ref{Use GNAT
+project file}, @ref{Use multiple GNAT project files}.
+
+In @file{Example_5}, add the file:
+
+@file{Makefile}:
+
+@example
+# build and run hello_5 project
+
+all : build run
+
+.PHONY : force
+
+build : force
+ gprbuild -Phello_5.gpr hello_5
+
+run :
+ ./hello_5
+
+clean :
+ gnatclean -r -Phello_5
+
+export GPR_PROJECT_PATH = ../Example_4/Gnat_Project
+
+# Local Variables:
+# eval:(ada-parse-prj-file "hello_5.adp")
+# eval:(ada-select-prj-file "hello_5.adp")
+# End:
+@end example
+
+Close and re-open @file{Makefile}; the @samp{Local Variables} section
+sets the project file to @file{hello_5.adp} when the @file{Makefile}
+is opened. You can also use @key{C-x C-e} to execute the select line
+after the @file{Makefile} is opened, to change the project file back
+to @file{hello_5.adp}.
+
+In @file{Makefile}, invoke @samp{Tools | Compile...}, and accept the
+default make command. This runs the @samp{all} target, which builds
+@file{hello_5} and runs it.
+
+@node Compiler errors, , Compiling Examples, Compiling Executing
+@section Compiler errors
+
+The @code{Check syntax} and @code{Build} commands, or running
+@code{make}, place compilation errors in a separate buffer named
+@code{*compilation*}.
+
+Each line in this buffer will become active: you can simply click on
+it with the middle button of the mouse, or move point to it and press
+@key{RET}. Emacs will then display the relevant source file and put
+point on the line and column where the error was found.
+
+You can also press the @kbd{C-x `} key (@code{next-error}), and Emacs
+will jump to the first error. If you press that key again, it will
+move you to the second error, and so on.
+
+Some error messages also include references to other files. These
+references are accessed via @kbd{C-c `}.
+
+@node Project files, Moving Through Ada Code, Compiling Executing, Top
+@chapter Project files
+
+An Emacs Ada mode project file specifies what directories hold sources
+for your project, and allows you to customize the compilation commands
+and other things on a per-project basis.
+
+The default file extension for Ada mode project files is @file{*.adp}
+or @file{*.prj}. You can use a different extension by adding it to
+@code{ada-prj-file-extensions}, and a different syntax by adding a
+parser function to @code{ada-prj-parser-alist}.
+
+Note that Ada mode project files @file{*.adp} are different than GNAT
+compiler project files @samp{*.gpr}. However, Emacs Ada mode can use a
+GNAT project file to specify the project directories. If no
+other customization is needed, a GNAT project file can be used without
+an Emacs Ada mode project file.
+
+If no Emacs Ada mode project file is specified, some Ada mode
+functions are not available.
+
+@menu
+* Project file overview::
+* Project file variables::
+@end menu
+
+@node Project file overview, Project file variables, Project files, Project files
+@section Project file overview
+
+Project files have a simple syntax; they may be edited directly. Each
+line specifies a project variable name and its value, separated by
+``='' (spaces not allowed):
+@example
+src_dir=/Projects/my_project/src_1
+src_dir=/Projects/my_project/src_2
+@end example
+
+Any line that does not have an ``='' is a comment.
+
+Some variables (like @code{src_dir}) are lists; multiple occurrences
+are concatenated.
+
+There must be no space between the variable name and ``='', and no
+trailing spaces.
+
+The current project file is given by the lisp variable
+@code{ada-prj-default-project-file}, and shown by the menu command
+@key{Ada | Project Files | Show project}.
+
+To set the project file, use the menu command @samp{Ada | Set Project
+...}, or the elisp functions @code{ada-parse-prj-file,
+ada-select-prj-file}. The latter can be added to a Makefile:
+
+@example
+# Local Variables:
+# eval: (ada-parse-prj-file "ada-mode.prj")
+# eval: (ada-select-prj-file ada-mode.prj")
+# End:
+@end example
+
+You specify either a GNAT project file or an Emacs Ada mode project
+file; if the file extension is @code{.gpr}, the file is treated as a
+GNAT project file. Extensions given by @code{ada-prj-file-extensions}
+(default @file{.adp, .prj}) are treated as an Emacs Ada mode
+project file.
+
+After a project file is parsed, you can make it current again with
+just @code{ada-select-prj-file}, or by selecting it from the menu.
+
+@node Project file variables, , Project file overview, Project files
+@section Project file variables
+
+To set a project variable that is a list, specify each element of the
+list on a separate line in the project file.
+
+Process environment variables can be referenced using the
+normal @code{$var} syntax.
+
+Most project variables have defaults that can be changed by setting
+elisp variables; the table below identifies the elisp variable for each
+project variable. Elisp variables corresponding to project variables
+that are lists are elisp lists.
+
+In general, project variables are evaluated when referenced in Emacs
+Ada mode commands. Relative file paths are expanded relative to the
+directory containing the project file.
+
+Ada mode defines some project variables; others are defined by the
+compiler.
+
+Here is the list of variables valid for all compilers. In the default
+values, the current directory @code{"."} is the directory containing
+the project file.
+
+@table @asis
+@c These are the names that appear in the .adp file, which are the
+@c same as the symbols used with ada-prj-get
+@c
+@c defined in ada-mode.el ada-prj-parse-file-1; alphabetical order
+@c defaults defined in ada-mode.el ada-prj-default
+
+@item @code{ada_compiler} [default: @code{ada-compiler, gnat}]
+Ada compiler for this project. It must occur in the project file
+before any compiler-specific project variable.
+
+@item @code{auto_case} [default: @code{ada-auto-case, t}]
+Non-nil means automatically change case of preceding word while typing.
+
+@item @code{case_identifier} [default: @code{ada-case-identifier, ada-mixed-case}]
+Function to call to adjust the case of an Ada identifier.
+
+@item @code{case_keyword} [default: @code{ada-case-keyword, downcase-word}]
+Function to call to adjust the case of an Ada keyword.
+
+@item @code{case_strict} [default: @code{ada-case-strict, t}]
+If non-nil, @code{ada-mixed-case} forces @code{Mixed_Case} for identifiers.
+Otherwise, @code{ada-mixed-case} allows @code{UPPERCASE} for identifiers.
+
+@item @code{casing} [default: @code{ada-case-exception-file, nil}]
+List of files containing casing exceptions. @xref{Automatic casing}.
+
+@item @code{el_file} [default: ]
+The value is a file name, which is loaded as an elisp file when the
+project file is parsed or selected. This allows setting Ada mode indentation
+variables, and any arbitrary elisp code used to customize the project.
+
+@item @code{path_sep} [default: @code{path-separator}]
+Separator character used in compiler search paths.
+
+@item @code{src_dir} [default: @code{"."}]
+A list of directories to search for source files.
+
+@item @code{xref_tool} [default: @code{ada-xref-tool, gnat-xref}]
+Cross reference tool for this project.
+
+@end table
+
+The following variables are valid with the GNAT compiler:
+
+@table @asis
+@c defined in ada-gnat.el ada-gnat-prj-parse-emacs-file; alphabetical order
+@item @code{ada_project_path} [default: @code{""}]
+@c ada-prj-get 'prj_dir, 'proc_env
+A list of directories to search for GNAT project files.
+
+If set, the @code{GPR_PROJECT_PATH} process environment variable is
+set to this value in the child process that runs GNAT tools. If not
+set, @code{GPR_PROJECT_PATH} in the child process is inherited from
+the Emacs process.
+
+If you have the @code{GPR_PROJECT_PATH} or @code{ADA_PROJECT_PATH}
+environment variable set in the Emacs process correctly for all of
+your projects, you do not need to set this project variable.
+
+The project search path can also be set in GNAT aggregate
+projects. However, the gnat tools do not make that path available to
+Emacs, so you must duplicate it in an Emacs Ada project file.
+
+@item @code{gpr_file} [default: @code{""}]
+The GNAT project file.
+
+If set, the source and project directories specified in the GNAT
+project file are appended to @code{src_dir} and
+@code{ada_project_path}. This allows specifying Ada source directories
+with a GNAT project file, and other source directories with the Emacs
+project file.
+
+@item @code{gpr_project_path} [default: @code{""}]
+Same as @code{ada_project_path}.
+
+@end table
+
+@node Moving Through Ada Code, Identifier completion, Project files, Top
+@chapter Moving Through Ada Code
+
+There are several commands to navigate through Ada code. All
+these functions are available through the Ada menu and keybindings.
+
+Some of these commands rely on cross reference facilities provided by
+the compiler; the standard Emacs Ada mode only supports the GNAT
+compiler, but others can be added (@pxref{Other cross-reference}).
+
+@table @kbd
+@item C-c C-d
+@findex ada-goto-declaration
+Move from any use of an identifier to its declaration, for from a declaration to
+its body (if there is one).
+
+@item C-c M-d
+@findex ada-goto-declaration-parent
+Move from a child type declaration to the parent type declaration;
+display a list of references if there is more than one parent.
+
+@item C-c C-n
+@findex ada-next-statement-keyword
+Move to the next keyword in the current statement.
+
+For example, if point is on @samp{if}, move to @samp{then}.
+
+@item C-c C-p
+@findex ada-prev-statement-keyword
+Move to the previous keyword in the current statement.
+
+For example, if point is on @samp{then}, move to @samp{if}.
+
+@item C-c C-o
+@findex ada-find-other-file
+Switch between corresponding spec and body. There are several special
+cases:
+
+@itemize @bullet
+@item
+If the region is active, it is assumed to contain an Ada package
+name; position point on the corresponding package declaration.
+
+@item
+If point is in the start line of a top level child package
+declaration (but not package body), or a child subprogram spec or
+body, position point on the corresponding parent package
+declaration.
+
+@item
+If point is in the start line of a top level separate body,
+position point on the corresponding separate stub declaration.
+
+@item
+If point is in a subprogram declaration or body, position point on the
+corresponding body or declaration in the other file.
+
+@item
+If point is on a @code{with} clause, position point on the
+corresponding declaration.
+
+@end itemize
+
+@item C-c C-r
+@findex ada-show-references
+Show all references to the identifier surrounding point. Use
+@kbd{C-x `} (@code{next-error}) to visit each reference (as for
+compilation errors).
+
+@item C-c C-x
+@findex ada-show-overriding
+Show all declarations that override the primitive procedure at
+point. Use @kbd{C-x `} (@code{next-error}) to visit each reference (as
+for compilation errors).
+
+@item C-c M-x
+@findex ada-show-overridden
+Show the declaration that the declaration at point overrides.
+
+@item C-u SPACE
+Jump back to the previous location.
+
+@item Ada | Misc | Refresh cross reference cache
+Cross reference information is loaded from the compiler output when
+the first cross reference command is issued. If the code is recompiled
+after that, the cross reference information is reloaded by invoking
+this menu command.
+
+@end table
+
+@node Identifier completion, Indentation, Moving Through Ada Code, Top
+@chapter Identifier completion
+
+Emacs provides a general way of completing identifiers: @kbd{M-/}
+(bound to @code{dabbrev-expand}). This is an easy way to type faster:
+you just have to type the first few letters of an identifier, and then
+loop through all the possible completions.
+
+@kbd{M-/} works by parsing all open Ada files for possible
+completions.
+
+For instance, if the words @samp{my_identifier} and @samp{my_subprogram}
+are the only words starting with @samp{my} in any of the open Ada files,
+then you will have this scenario:
+
+@example
+You type: my@kbd{M-/}
+Emacs inserts: @samp{my_identifier}
+If you press @kbd{M-/} once again, Emacs replaces @samp{my_identifier} with
+@samp{my_subprogram}.
+Pressing @kbd{M-/} once more will bring you back to @samp{my_identifier}.
+@end example
+
+This is a very fast way to do completion, and the casing of words will
+also be respected.
+
+@node Indentation, Statement skeletons, Identifier completion, Top
+@chapter Indentation
+
+Ada mode comes with a full set of rules for automatic indentation. You
+can also configure the indentation, via the following variables:
+
+@table @asis
+@item @code{ada-indent} (default value: 3)
+Number of columns for default indentation.
+
+@item @code{ada-indent-broken} (default value: 2)
+Number of columns to indent the continuation of a broken line.
+
+@item @code{ada-indent-comment-col-0} (default value: nil)
+If non-nil, comments currently starting in column 0 are left in column
+0. Otherwise, they are indented with previous comments or code.
+
+@item @code{ada-indent-label} (default value: -3)
+Number of columns to indent a label.
+
+@item @code{ada-indent-record-rel-type} (default value: 3)
+Indentation for @code{record} relative to @code{type} or @code{use}.
+
+@item @code{ada-indent-renames} (default value: 2)
+Indentation for @code{renames} relative to the matching subprogram keyword.
+
+If the subprogram has parameters then if @code{ada-indent-renames} is
+zero or less the indentation is abs @code{ada-indent-renames} relative
+to the open parenthesis; if @code{ada-indent-renames} is one or more
+the indentation is relative to the line containing the keyword.
+
+If the subprogram has no parameters then @code{ada-indent-broken} the
+indentation is relative to the indentation of the line containing
+the keyword.
+
+@item @code{ada-indent-return} (default value: 0)
+Indentation for @code{return} relative to the matching
+ @code{function}.
+
+If the function has parameters, then if @code{ada-indent-return} is
+zero or less the indentation is abs @code{ada-indent-return} relative
+to the open parenthesis; if @code{ada-indent-return} is one or more,
+indentation is relative to line containing @code{function}.
+
+If the function has no parameters, @code{ada-indent-broken} is used
+relative to line containing @code{function}.
+
+@item @code{ada-indent-use} (default value: ada-indent-broken)
+Indentation for the lines in a @code{use} statement.
+
+@item @code{ada-indent-when} (default value: 3)
+Indentation for @code{when} relative to @code{exception}, @code{case},
+or @code{or} in @code{select}.
+
+@item @code{ada-indent-with} (default value: ada-indent-broken)
+Indentation for the lines in a @code{with} context clause.
+
+@end table
+
+The indentation variables are buffer local; the global value may be
+overridden in an elisp file invoked by an @code{el_file} Emacs Ada
+mode project file statement, or in a file local variable section.
+
+The following keys indent portions of the text:
+@table @kbd
+
+@item RET
+Insert and indent a new line.
+
+@item TAB
+Indent the current line, or the current region.
+
+@item C-c TAB
+Indent the current statement or declaration.
+
+@end table
+
+The indentation algorithm relies on a grammar parser to identify the
+syntactic role for keywords and other words in the code. If the code
+is accepted by the parser, the indentation is done according to the
+rules in the indentation engine.
+
+If the code is not accepted (because it is partially complete during
+editing), the indentation engine falls back to the trivial algorithm
+of indenting each new line the same as the previous line. Once enough
+new text has been entered to make the code acceptable to the parser,
+the statement or declaration is properly indented.
+
+For example, if you are entering this code:
+
+@example
+if A then
+ B;
+end if;
+@end example
+
+when you type @kbd{RET B}, @code{B} is indented to the same column as
+@code{if}, because the parser does not find @code{end if;}. Then when
+you type the final @code{;} followed by @key{TAB}, all three lines are
+indented, putting @code{B} where it belongs.
+
+To be more user friendly, the parser accepts a superset of the Ada
+grammer. For example, the parser accepts this code for an @code{if}
+statement:
+
+@example
+if then
+end if;
+@end example
+
+In general, any sequence of statements, and many expressions, may be
+omitted.
+
+One way to easily insert empty statements like this is using
+@ref{Statement skeletons}.
+
+In rare cases, the parser gets confused; it can be reset by invoking
+menu @key{Ada | Misc | Reset parser}. Please report such cases as a
+bug.
+
+@node Statement skeletons, Aligning code, Indentation, Top
+@chapter Statement skeletons
+
+@kbd{C-c C-e} expands the previous one or two words into a statment
+skeleton. For example, @kbd{i f C-c C-e} expands to:
+
+@example
+if then
+elsif then
+else
+end if;
+@end example
+
+All skeleton expansions are accepted by the indentation parser, so
+this is a convenient way to insert statements with correct
+indentation.
+
+For named statements (packages, loops, etc), the name is taken from
+the word before point, and the name of the statement from the word
+before that.
+
+Some expansions prompt for more information, such as
+whether a spec or body is desired. For example, @kbd{package A_Package
+C-c C-e} first prompts for ``body'' or ``spec''. If ``spec'' is
+selected, the following code is inserted:
+
+@example
+package A_Package is
+private
+end A_Package;
+@end example
+
+Named blocks work similarly: @kbd{declare A_Block C-c C-e} expands
+(without prompting) to:
+
+@example
+A_Block:
+ declare
+ begin
+ exception
+ end A_Block;
+@end example
+
+Note that the order of the keyword @code{declare} and the name
+@code{A_Block} are reversed in the expansion; this may take some
+getting used to. Alternately, if no name is present in the buffer, you
+are prompted for a name: @kbd{declare C-c C-e} first prompts for a
+name, then expands to the above.
+
+The variable @code{ada-skel-initial-string} defines what to insert in
+a newly created empty buffer. It defaults to @code{@{header@}}, which
+is a placeholder defined by @code{ada-skel-header}, which inserts a
+typical header with a copyright license (choice of GPL or
+restricted). Users will typically want to override the definition of
+@code{ada-skel-initial-string} and/or @code{ada-skel-header}, or
+provide more choices of copyright license.
+
+@node Aligning code, Automatic casing, Statement skeletons, Top
+@chapter Aligning code
+
+Aligning code adds space in each line so that similar parts of
+successive lines are aligned vertically. For example, a sequence of
+declarations:
+
+@example
+A : Integer;
+Another : Float := 1.0;
+More : Integer := 2;
+@end example
+
+changes to this when aligned:
+
+@example
+A : Integer;
+Another : Float := 1.0;
+More : Integer := 2;
+@end example
+
+Alignment is invoked by @kbd{C-c C-a}, which aligns the sequence of
+statements surrounding point, or within the selected region.
+
+Parameter lists are also aligned:
+
+@example
+ procedure Foo
+ (A : in Integer;
+ Another : out Float := 1.0;
+ More : in out Integer := 2);
+@end example
+
+is aligned to:
+
+@example
+ procedure Foo
+ (A : in Integer;
+ Another : out Float := 1.0;
+ More : in out Integer := 2);
+@end example
+
+@node Automatic casing, Comment Handling, Aligning code, Top
+@chapter Automatic casing
+
+Casing of identifiers, attributes and keywords is automatically
+performed while typing when the variable @code{ada-auto-case} is
+non-nil (the default). Every time you type a word separator, the
+previous word is automatically cased.
+
+You can customize the automatic casing with the following variables:
+
+@table @code
+@item ada-case-keyword
+Value must be one of:
+@table @code
+@item downcase-word
+Ada keywords will be lowercase.
+
+@item upcase-word
+Ada keywords will be uppercase.
+@end table
+
+@item ada-case-strict
+If non-nil, all identifiers are forced to @code{Mixed_Case}; first
+letter, and letter following ``_'' are uppercase; rest are
+lowercase.
+
+If nil, the mixed case characters in identifiers are forced to upper
+case, but the other characters are not modified. That allows typing
+all uppercase identifiers without defining a casing exception.
+@end table
+
+You can define exceptions to these rules, in files specified by the
+variable @code{ada-case-exception-file}. Each line in a case exception
+file specifies the casing of one word or word fragment. If an
+exception is defined in multiple files, the first occurrence is used.
+
+If the word starts with an asterisk (@code{*}), it defines the casing
+of a word fragemnt (or ``substring''); part of a word between two
+underscores or word boundary.
+
+For example:
+
+@example
+DOD
+*IO
+GNAT
+@end example
+
+The word fragment @code{*IO} applies to any word containing ``_io'';
+@code{Text_IO}, @code{Hardware_IO}, etc.
+
+@findex ada-case-create-exception
+There are two ways to add new items to this file: you can simply edit
+it as you would edit any text file. Or you can position point on the
+word you want to add, and select menu @samp{Ada | Casing | Create full
+exception} or @samp{Ada | Casing | Create partial exception}. The
+word will be added to the current list of exceptions and to the file.
+
+It is sometimes useful to have multiple exception files. For
+example, one could be the standard Ada acronyms, the second some
+company specific exceptions, and the last one some project specific
+exceptions. If you set up the variable @code{ada-case-exception-file}
+as a list of files, each of them will be parsed and used in your emacs
+session. When you create a new exception, you are prompted for the
+file to save it in.
+
+Other keys and menu entries are defined:
+
+@table @kbd
+@item C-c C-w
+@findex ada-case-adjust-at-point
+Adjust case of the word at point. With prefix arg, adjust case even if
+in comment. Normally, comments are not affected by case adjust.
+
+@item Ada | Casing | Adjust case region
+Adjust case in the active region.
+
+@item Ada | Casing | Adjust case buffer
+Adjust case in the active buffer.
+
+@end table
+
+@node Comment Handling, Key summary, Automatic casing, Top
+@chapter Comment Handling
+
+By default, comment lines get indented like Ada code. There are a few
+additional functions to handle comments:
+
+@table @kbd
+@item M-;
+@findex comment-dwim
+If the region is active, comment or uncomment it.
+
+If the current line is empty, start a comment.
+
+Otherwise, add a comment at the end of the line, in a column given by
+@code{comment-column}.
+
+@item M-q
+@findex fill-paragraph
+Fill the current comment paragraph.
+@end table
+
+@node Key summary, Developer overview, Comment Handling, Top
+@chapter Key summary
+@c search for @kbd and @key. Alphabetical by key sequence
+
+This table summarizes the keys described in this manual. Other keys
+are bound by Ada mode; see @key{C-h b} for a complete list. The
+Ada menu also displays keys bound to menu operations.
+
+@table @kbd
+@item M-/
+@xref{Identifier completion}.
+Complete the word before point; repeat to cycle thru possible
+completions.
+
+@item M-;
+@xref{Comment Handling}.
+If the region is active, comment or uncomment it.
+
+@item M-q
+@xref{Comment Handling}.
+Fill the current comment paragraph.
+
+@item RET
+@xref{Indentation}.
+Insert and indent a new line.
+
+@item TAB
+@xref{Indentation}.
+Indent the current line, or the current region.
+
+@item C-c TAB
+@xref{Indentation}.
+Indent the current statement or declaration.
+
+@item C-c `
+@xref{Compiler errors}.
+Move to the location of the secondary reference in the current compilation error.
+
+@item C-c C-a
+@xref{Aligning code}.
+Align code.
+
+@item C-c C-c
+@xref{Compile commands}.
+Build the current main program.
+
+@item C-c C-d
+@xref{Moving Through Ada Code}.
+Move from any use of an identifier to its declaration, for from a declaration to its body.
+
+@item C-c M-d
+@xref{Moving Through Ada Code}.
+Move from a child type declaration to the parent type declaration.
+
+@item C-c C-e
+@xref{Statement skeletons}.
+Expand previous one or two words into a statement or declaration
+skeleton.
+
+@item C-c C-c
+@xref{Compile commands}.
+Build the current file.
+
+@item C-c C-n
+@xref{Moving Through Ada Code}.
+Move to the next keyword in the current statement.
+
+@item C-c C-o
+@xref{Moving Through Ada Code}.
+Switch between corresponding spec and body, or find other spec.
+
+@item C-c C-p
+@xref{Moving Through Ada Code}.
+Move to the previous keyword in the current statement.
+
+@item C-c C-r
+@xref{Moving Through Ada Code}.
+Show all references to the identifier surrounding point.
+
+@item C-c C-w
+@xref{Automatic casing}.
+Adjust case of the word at point. With prefix arg, adjust case even if
+in comment.
+
+@item C-c C-x
+@xref{Moving Through Ada Code}.
+Show all declarations that override the primitive procedure at
+point.
+
+@item C-c C-y
+@xref{Automatic casing}.
+Create case exception.
+
+@item C-c `
+@xref{Compiler errors}.
+Move to the location of the next secondary compilation error.
+
+@item C-x `
+@xref{Compiler errors}.
+Move to the location of the next compilation error or show result.
+
+@item M-q
+@xref{Comment Handling}.
+Fill the current comment paragraph.
+
+@end table
+
+@node Developer overview, GNU Free Documentation License, Key summary, Top
+@chapter Developer overview
+If you'd like to contribute to Ada mode, or just understand the
+sources, here's an overview.
+
+@menu
+* Directory structure::
+* Package organization::
+* OpenToken::
+* ELPA::
+@end menu
+
+@node Directory structure, Package organization, Developer overview, Developer overview
+@section Directory structure
+@table @file
+@item org.emacs.ada-mode
+Main source.
+
+File extensions:
+@table @file
+@item *.el
+Elisp files; main code.
+
+@item *.elc
+Byte-compiled elisp files, not in the distribution. Generated by the
+Makefile target @code{byte-compile}, or by the Emacs package installer.
+
+Compiling the parse tables (@file{*-wy.el}) speeds up loading them
+significantly. Compiling other files speeds up parsing, but not
+noticeably.
+
+One reason to byte-compile files is to find errors; the byte compiler
+reports undefined variables, wrong argument counts, etc.
+
+@item *-wy.el
+Parse tables, generated from the corresponding grammar @file{*.wy} by
+the OpenToken tool @file{wisi-generate.exe}. These are in the tarball
+distribution and the monotone repository so users and Elisp developers
+don't have to install OpenToken.
+
+@item *-wy.output
+Diagnostic output from @file{wisi-generate.exe}, useful for tracing
+parses while debugging a grammar issue. Not in the tarball
+distribution or the monotone repository.
+
+@item *.wy
+Grammar files, specifying the language to be parsed. The syntax for
+these grammar files is similar to that for bison and wisent, but not
+the same; see the OpenToken documentation for more info.
+
+The wisi parser (in @file{wisi-parse.el}) is a generalized LALR
+parser, so it tolerates some conflicts and ambiguities. This makes the
+grammars easier to write, and in particular makes it possible to let
+the Ada grammar closely match Annex P of the Ada Language Reference
+Manual (the syntax summary).
+
+@item *.texi
+Texinfo source for the user guides.
+
+@item *.html
+Generated user guide in HTML format.
+
+@item *.info
+Generated user guide in Emacs info format.
+
+
+@end table
+
+@item build
+Makefile for building the user guides, publishing to the web page or
+Gnu ELPA. Test drivers.
+
+@item build/wisi
+Makefile for building and testing with the wisi-based
+parser. Separate from @file{build}, because there used to be a
+SMIE-based parser, and there might be another parser someday.
+
+The emacs used to byte-compile and run tests is given by the 'make'
+variable EMACS_EXE, which defaults to 'emacs'; it can be overridden on
+the make command line or by an environment variable.
+
+@item test
+All tests for Ada mode, gpr mode, parser.
+
+Each test is run in a separate invocation of Emacs, so it is
+completely independent of all other tests.
+
+The tests are driven by the elisp code in @file{build/*.el}.
+
+In general, the Ada mode tests open the file, execute test actions,
+re-indent, and re-captialize the entire file. The result is diffed
+with the original, and must match.
+
+The test actions are defined by comments with the prefix
+@code{--EMACSCMD:}; they are elisp forms that invoke Ada mode
+functions. This is used to test navigation features and other parser
+effects.
+
+@item test/Example_*
+Starting files for examples in user guide.
+
+@item test/gpr
+Tests for gpr mode.
+
+@item test/subdir
+More tests; allows testing path search features.
+
+@item test/wisi
+Tests of the elisp wisi grammar compiler and parser.
+@end table
+
+@node Package organization, OpenToken, Directory structure, Developer overview
+@section Package organization
+
+@menu
+* Ada mode::
+* gpr mode::
+* GNAT core::
+* Wisi::
+@end menu
+
+@node Ada mode, gpr mode, Package organization, Package organization
+@subsection Ada mode
+Ada mode consists of all files with @file{ada-} prefix in the file
+name.
+
+@table @file
+@item ada-mode.el
+The main file, implementing the keymap, menu, and top level
+functionality.
+
+It allows for different backend implementations for compiling,
+cross-referencing, and indenting. The functions for each of these
+backends dispatch thru global variables that are set by Emacs Ada mode
+project files. They default to the GNAT compiler, the gnatxref cross
+reference tool, and the ada-wisi indentation engine.
+
+@item ada-build.el
+Provides functions for compiling Ada files without a Makefile (or
+similar tool).
+
+@item ada-fix-error.el
+Provides an interface to utilities for automatically fixing errors
+reported by the compiler. It dispatches to a compiler-specific
+backend.
+
+@item ada-gnat-compile.el
+Implements the Ada mode compiler functions for the GNAT compiler.
+
+@item ada-gnat-xref.el
+Implements the Ada mode cross reference functions for the GNAT compiler.
+
+@item ada-grammar.*
+The Ada language grammar, and files generated from it by the OpenToken
+tool @file{wisi-generate.exe}.
+
+@item ada-indent-user-options.el
+All user-settable options for the Ada indentation engine.
+
+@item ada-mode-compat-23.4.el
+Defines functions used by Ada mode that are not in Emacs 23.4.
+
+Emacs Ada mode is written for Emacs 24.3. Emacs version 23.4 is
+partially supported. Earlier versions of Emacs are not supported.
+
+@item ada-mode.texi
+The Ada mode user guide source and compiled versions.
+
+@item ada-skel.el
+Skeletons for expansion of Ada syntax (@pxref{Statement
+skeletons}). Extends the Emacs skeleton functions with ``tokens'',
+inspired by the lamented Else package (which was inspired by DEC LSE).
+
+@item ada-wisi-opentoken.el
+Indentation functions useful when editing OpenToken code; an example
+of extending the Ada mode indentation engine for special
+circumstances.
+
+@item ada-wisi.el
+Implements the Ada mode indentation functions for the wisi indentation
+engine backend.
+
+@end table
+
+@node gpr mode, GNAT core, Ada mode, Package organization
+@subsection gpr mode
+
+gpr mode consists of all files with @file{gpr-} prefix in the file
+name. The functions in each file are similar to the similarly-named
+Ada mode files.
+
+@node GNAT core, Wisi, gpr mode, Package organization
+@subsection GNAT core
+@table @file
+
+@item gnat-core.el
+GNAT is actually a multi-language tool; it builds on top of the
+multi-language gcc.
+
+@file{gnat-core.el} is a start at a language-agnostic interface to the
+GNAT tools. It was first factored out from @file{ada-gnat.el} and
+@file{ada-mode.el} to support the multi-language
+@file{gnat-inspect.el}, which is still experimental.
+
+More code currently in @file{ada-mode.el} could be migrated to
+@file{gnat-core.el}, in particular the project file support.
+
+@item gnat-inspect.el
+Provides an experimental interface to the experimental multi-language
+cross-reference tool @file{gnatinspect} from AdaCore, which will
+supercede @file{gnatxref}.
+
+Implements the Ada mode cross-reference functions for the
+@file{gnatinspect} backend, and a minor mode providing similar
+functions for C++.
+
+@end table
+
+@node Wisi, , GNAT core, Package organization
+@subsection Wisi
+
+The ``wisi'' parser. ``wisi'' used to be an acronym, but now it's just
+a name.
+
+@table @file
+@item wisi.el
+Implements the lexer, the main parser driver,
+parser actions that cache parser information in text properties,
+utilities for indenting and navigating using the cached information,
+and general setup.
+
+@item wisi-compile.el
+Implements the parse table
+compiler. @file{wisi-generate.exe} processes the grammar source
+@file{*.wy} into an elisp source representation of a parse table
+@file{*-wy.el}. That is compiled into an internal structure containing
+the state transitions and executable actions. The actions can be any
+elisp form; the intent is that they be calls to the action functions
+provided by @file{wisi.el}. @file{wisi-compile.el} uses some features
+provided by @code{semantic}.
+
+@item wisi-parse.el
+Implements the generalized LALR parser.
+@end table
+
+@node OpenToken, ELPA, Package organization, Developer overview
+@section OpenToken
+Ada mode uses the OpenToken tool @file{wisi-generate.exe} to process
+the grammar sources into elisp parse tables. See
+@uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html} for
+current information about which version of OpenToken is required, and
+how to get it.
+
+The Makefile variable @code{WISI_OPENTOKEN} gives the path to the
+build directory for OpenToken; you probably need to override it with
+an external environment variable or on the @code{make} command line.
+
+@node ELPA, , OpenToken, Developer overview
+@section ELPA
+Ada mode is published via the Gnu ELPA archive. To test a new version
+of Ada mode, we use a local Gnu ELPA archive. That requires fetching
+Gnu ELPA via git:
+
+@example
+cd /Projects
+git clone git://git.savannah.gnu.org/emacs/elpa.git
+@end example
+
+If you have an Emacs Savannah developer account, you can use:
+
+@example
+cd /Projects
+git clone <login>@@git.savannah.gnu.org/emacs/elpa.git
+@end example
+
+@file{build/Makefile} contains targets for copying Ada mode source to
+the elpa workspace, and for building the elpa archive there.
+
+@node GNU Free Documentation License, Index, Developer overview, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Index, , GNU Free Documentation License, Top
+@unnumbered Index
+
+@printindex fn
+
+@bye