changeset 25906:3a06267f733d

New file.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/ada-mode.texi	Thu Oct 07 14:46:58 1999 +0000
@@ -0,0 +1,1183 @@
+\input texinfo  @c -*-texinfo-*-
+@setfilename ada-mode.info
+@settitle Ada Mode
+
+@ifinfo
+This file documents Ada mode.
+
+Permission is granted to make and distribute verbatim copies of this
+manual provided the copyright notice and this permission notice are
+preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission notice
+identical to this one except for the removal of this paragraph (this
+paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under same conditions as for modified versions.
+@end ifinfo
+
+@titlepage
+@sp 10
+@title{Ada Mode}
+@sp 2
+@subtitle An Emacs major mode for programming Ada 95 with GNAT
+@subtitle July 1998 for Ada Mode Version 3.0
+@sp 2
+
+@comment This is for the copyright page.
+@page
+@vskip 0pt plus 1filll
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the entire
+resulting derived work is distributed under the terms of a permission
+notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the same conditions as for modified versions.
+
+@end titlepage
+
+@node Top, Overview, (dir), (dir)
+
+@menu
+* Overview::
+* Installation::                  Installing the Ada mode on your system
+* Customization::                 Setting up the Ada mode to your taste
+* Project files::                 Describing the organization of your project
+* Syntax highlighting::           Using specific colors and fonts to highlight
+                                    the structure of your files
+* Moving Through Ada Code::       Moving easily through Ada sources
+* Identifier completion::         Finishing words automatically
+* Index Menu of Subprograms::     A menu of all the types and subprograms
+                                     defined in your application
+* File Browser::                  Easy access to your files
+* Automatic Smart Indentation::   Indenting your code automatically as you type
+* Formatting Parameter Lists::    Formating subprograms parameter lists
+                                     automatically
+* Automatic Casing::              Adjusting the case of words automatically
+* Statement Templates::           Inserting code templates
+* Comment Handling::              Reformatting comments easily
+* Compiling Executing::           Working with your application within Emacs
+* Debugging::                     Debugging your application
+* Using non-standard file names:: Configuring Emacs for special file names
+* Working Remotely::              Working on a different machine
+@end menu
+
+
+@c -----------------------------------------------------------------------
+@node Overview, Installation, Top, Top
+@chapter Overview
+@c -----------------------------------------------------------------------
+
+The Emacs mode for programming in Ada 95 with GNAT helps the user in
+understanding existing code and facilitates writing new code.  It
+furthermore provides some utility functions for easier integration of
+standard Emacs features when programming in Ada.
+
+@section General features:
+
+@itemize @bullet
+@item full Integrated Development Environment :
+@itemize @bullet
+@item support of 'project files' for the configuration (directories,
+compilation options,...)
+@item compiling and stepping through error messages.
+@item running and debugging your applications within Emacs.
+@end itemize
+@item easy to use for beginners by pull-down menus,
+@item user configurable by many user-option variables.
+@end itemize
+
+@section Ada mode features that help understanding code:
+
+@itemize @bullet
+@item functions for easy and quick stepping through Ada code,
+@item getting cross reference information for identifiers (e.g. find the
+defining place by a keystroke),
+@item displaying an index menu of types and subprograms and move point to
+the chosen one,
+@item automatic color highlighting of the various entities in Ada code.
+@end itemize
+
+@section Emacs support for writing Ada code:
+
+@itemize @bullet
+@item switching between spec and body files with eventually
+auto-generation of body files,
+@item automatic formating of subprograms parameter lists.
+@item automatic smart indentation according to Ada syntax,
+@item automatic completion of identifiers,
+@item automatic casing of identifiers, keywords, and attributes,
+@item insertion of statement templates,
+@item filling comment paragraphs like filling normal text,
+@end itemize
+
+@c -----------------------------------------------------------------------
+@node Installation, Customization, Overview, Top
+@chapter Installation
+@c -----------------------------------------------------------------------
+
+If you  got the Ada mode as  a separate distribution, you  should have a
+look at the  @file{README} file.  It explains the  basic steps necessary
+for a good installation of the emacs Ada mode.
+
+Installing the  Ada mode  is basically  just a matter  of copying  a few
+files into  the Emacs  library directories. Every  time you open  a file
+with  a  file  extension  of  @file{.ads}  or  @file{.adb},  Emacs  will
+automatically load and activate the Ada mode.
+
+See the  section @xref{Using non-standard  file names} if your  files do
+not use these extensions and if you want Emacs to automatically start the
+Ada mode every time you edit an Ada file.
+
+See also the Emacs documentation @xref{(emacs)} for general usage
+variables that you might want to set.
+
+@c ---------------------------------------------------------------------
+@section Required files
+@c ---------------------------------------------------------------------
+
+This Ada  mode works best  with Emacs 20.3  or higher (the  easy editing
+features for the  project files won't work with  any older version), but
+most of the commands should work  with older versions too. Please try to
+install  the  most  recent  version  of  Emacs  on  your  system  before
+installing the Ada mode.
+
+Although part of the Ada mode is compiler independent, the most advanced
+features are specific to the Gnat compiler @url{http://www.gnat.com}.
+
+The following files are provided with the Ada mode distribution:
+
+@itemize @bullet
+
+@item @file{ada-mode.el}: The main file for the Ada mode.
+This  is the  only file  which does  not require  Gnat. It  contains the
+functions  for  indentation,  formatting  of parameter  lists,  stepping
+through  code, comment  handling and  automatic casing.   Emacs versions
+20.2 and higher already contain Ada mode version 2.27, which is an older
+version of this file  and should be replaced. Loading @file{ada-mode.el}
+from the current distribution supersedes the standard installation.
+
+@item @file{ada-stmt.el}: Contains the statement templates feature.
+
+@item @file{ada-xref.el}: This file provides the main support for Gnat.
+This  is  where  the   functions  for  cross-references,  completion  of
+identifiers,  support   for  project  files  and   compilation  of  your
+application are defined.
+
+@item @file{ada-prj.el}: The functions to use for easy-edition of the
+project files.  This file is the only one which really requires Emacs at
+least 20.2. It uses the new widget features from Emacs.
+
+@end itemize
+
+@c --------------------------------------------------------------------
+@node Customization, Project files, Installation, Top
+@chapter Customizing the Ada mode
+@c ---------------------------------------------------------------------
+
+The ada-mode is  fully customizable. Everything, from the  file names to
+the automatic  indentation and  the automatic casing  can be  adapted to
+your own needs.
+
+There  are   two  different  kinds   of  variables  that   control  this
+customization, both are easy to modify.
+
+The first set of variables are standard Emacs variables. Of course, some
+are defined  only for the Ada  mode, whereas others have  a more general
+meaning  in   Emacs.  Please  see  the  Emacs   documentation  for  more
+information on the latest. In this documentation, we will detail all the
+variables that are specific to the Ada mode, and a few others. The names
+will be given, as in @code{ada-case-identifier}.
+
+Emacs provides an easy way to modify them, through a special mode called
+customization.    To    access    this    mode,    select    the    menu
+@kbd{Ada->Customize}.  This will open a new buffer with some fields that
+you can edit.  For instance, you will get something like:
+@example
+Put below the compiler switches.
+comp_opt= _____________________________________
+@end example
+The first  line gives a brief  description of the  variable.  The second
+line is  the name of  the variable  and the field  where you can  give a
+value for this variable. Simply type what you want in the field.
+
+When you are  finished modifying the variables, you  can simply click on
+the @b{Save for future sessions} button  at the top of the buffer (click
+with  the  middle mouse  button).  This will  save  the  values in  your
+@file{.emacs} file, so that next time you start Emacs they will have the
+same values.
+
+To modify a specific variable, you can directly call the function
+@code{customize-variable} from Emacs (just type @key{M-x
+customize-variable RET} and then type the variable name.
+
+Some users might prefer to modify the variables directly in their
+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
+
+The second set of variables for customization are set through the use of
+project files. These variables are  specific to a given project, whereas
+the  first   set  was  more   general.  For  more   information,  please
+@xref{Project files}.
+
+@c ---------------------------------------------------------------------
+@node Project files, Syntax highlighting, Customization, Top
+@chapter Project files
+@c ---------------------------------------------------------------------
+
+@c ---------------------------------------------------------------------
+@section General overview
+@c ---------------------------------------------------------------------
+
+Emacs provides a full Integrated Development Environment for GNAT and
+Ada programmers. That is to say, editing, compiling, executing and
+debugging can be performed within Emacs in a convenient and natural way.
+
+To take full advantage of this features, it is possible to create a file
+in  the main  directory of  your application,  with a  '.adp' extension.
+This  file contain  all needed  information  dealing with  the way  your
+application is  organized between directories, the  commands to compile,
+run and debug it etc. Creating this file is not mandatory and convenient
+defaults are  automatically provided for simple setups.  It only becomes
+necessary when those above mentioned defaults need customizing.
+
+A simple way to edit this file is provided for Emacs 20.2 or newer, with
+the  following functions,  that  you  can access  also  through the  Ada
+menu. It  is also possible  to edit the  project file as a  regular text
+file.
+
+Once  in the  buffer for  editing the  project file,  you can  save your
+modification using  the '[OK]'  button at the  bottom of the  buffer, or
+simply   use  the  usual   @kbd{C-x  C-s}   binding.   To   cancel  your
+modifications, simply kill the buffer  or click on the '[CANCEL]' button
+at the button.
+
+Each buffer using Ada mode will be associated with one project file when
+there  is one  available,  so  that Emacs  can  easily navigate  through
+related source files for instance.
+
+The exact algorithm to determine which project file should be used is
+described in the next section, but you can force the project file you
+want to use by setting one or two variables in your @file{.emacs} file.
+
+@itemize @bullet
+@item To set up a default project file to use for any directory, anywhere
+on your system, set the variable @code{ada-prj-default-project-file} to
+the name of that file.
+@example
+  (set 'ada-prj-default-project-file "/dir1/dir2/file")
+@end example
+
+@item For a finer controlled, you can set a per-directory project file.
+This is done through the variable @code{ada-xref-default-prj-file}.
+@example
+  (set 'ada-xref-default-prj-file
+       '(("/dir1/dir2" . "/dir3/file1")
+         ("/dir4/dir5" . "/dir6/file2")))
+@end example
+Note: This has a higher priority than the first variable, so the first
+choice is to use this variable settings, and otherwise
+@code{ada-prj-default-project-file}.
+@end itemize
+
+
+@table @kbd
+@item C-c u   ada-customize   menu: Ada->Project->New/Edit
+Create or edit the project file for the current buffer.
+@item C-c c   ada-change-prj
+Change the project file associated with the current Ada buffer.
+@item C-c d
+Change the  default project  file for the  current directory.  Every new
+file opened  from this  directory will be  associated with that  file by
+default.
+@item ada-set-default-project-file  menu: Ada->Project->Set Default
+Set the default  project file to use for *any*  Ada file opened anywhere
+on your system. This sets this file only for the current Emacs session.
+@end table
+
+@c ---------------------------------------------------------------------
+@section Project file variables
+@c ---------------------------------------------------------------------
+
+The following variables can be defined in a project file.  They all have
+a default value, so that small  projects do not need to create a project
+file.
+
+Some  variables below  can be  referenced  in other  variables, using  a
+shell-like  notation.   For instance,  if  the variable  @code{comp_cmd}
+contains a sequence like @code{$@{comp_opt@}}, the value of that variable
+will be substituted.
+
+Here is the list of variables:
+
+@table @code
+@item src_dir          [default: "./"]
+This is  a list of directories where  the Ada mode will  look for source
+files. These directories are used mainly  in two cases, both as a switch
+for the compiler and for the cross-references.
+
+@item obj_dir             [default: "./"]
+This  is a  list of  directories where  to look  for object  and library
+files.  The library files are the  .ali files generated by Gnat and that
+contain cross-reference informations.
+
+@item comp_opt            [default: ""]
+Creates a  variable which can be  referred to subsequently  by using the
+@code{$@{comp_opt@}} notation.   This is  intended to store  the default
+switches given to `gnatmake' and `gcc'.
+
+@item bind_opt=SWITCHES   [default: ""]
+Creates a  variable which can be  referred to subsequently  by using the
+@code{$@{bind_opt@}} notation.   This is  intended to store  the default
+switches given to `gnatbind'.
+
+@item link_opt=SWITCHES   [default: ""]
+Creates a  variable which can be  referred to subsequently  by using the
+@code{$@{link_opt@}} notation.   This is  intended to store  the default
+switches given to `gnatlink'.
+
+@item main=EXECUTABLE     [default: ""]
+Specifies the name of the  executable for the application. This variable
+can be referred to in  the following lines by using the @code{$@{main@}}
+notation.
+
+@item cross_prefix=PREFIX [default: ""]
+This variable  should be set if  you are working  in a cross-compilation
+environment. This is the prefix used in front of the gnatmake commands.
+
+@item remote_machine=MACHINE [default: ""]
+This  is  the  name of  the  machine  to  log  into before  issuing  the
+compilation command. If this variable  is empty, the command will be run
+on the local  machine. This will not work on  Windows NT machines, since
+the Ada  mode will simply precede  the compilation command  with a 'rsh'
+command, unknown on Windows.
+
+@item comp_cmd=COMMAND    [default: "$@{cross_prefix@}gcc -c -I$@{src_dir@} -g -gnatq"]
+Specifies the command used to compile a single file in the application.
+The name of the file will be added at the end of this command.
+
+@item make_cmd=COMMAND    [default: "$@{cross_prefix@}gnatmake $@{main@} -aI$@{src_dir@} -aO$@{obj_dir@} -g -gnatq -cargs $@{comp_opt@} -bargs $@{bind_opt@} -largs $@{link_opt@}"]'
+Specifies the command used to recompile the whole application.
+
+@item run_cmd=COMMAND     [default: "$@{main@}"]
+Specifies the command used to run the application.
+
+@item debug_cmd=COMMAND   [default: "$@{cross_prefix@}gdb $@{main@}"]
+Specifies the command used to debug the application
+
+@end table
+
+@c ---------------------------------------------------------------------
+@section Detailed algorithm
+@c ---------------------------------------------------------------------
+
+This section gives more details on the project file setup and is only of
+interest for advanced users.
+
+Usually, an Ada file is part  of a larger application, whose sources and
+objects can be spread over multiple directories. The first time emacs is
+asked to compile, run or debug an application, or when a cross reference
+function is  used (goto declaration  for instance), the  following steps
+are taken:
+
+@itemize @bullet
+@item find the appropriate project file, open and parse it.
+All  the fields  read  in the  project  file are  then  stored by  emacs
+locally.  Finding the project file requires a few steps:
+
+@itemize @minus
+@item if a file from the same directory was already associated with
+a project file, use the same one. This is the variable
+@code{ada-xref-default-prj-file} described above.
+@item if the variable @code{ada-prj-default-project-file} is set,
+use the project file specified in this variable.
+@item if there is a project file whose name is the same as the source file
+ except for the suffix, use this one.
+@item if  there's only one project file in the source directory, use
+that one.
+@item if there are more than one project file in the source directory,
+ask the user.
+@item if there are no project files in the source directory use standard
+default values.
+@end itemize
+
+The first project file that is selected in a given directory becomes the
+default project file for this directory and is used implicitly for other
+sources unless specified otherwise by the user.
+
+@item  look for the corresponding .ali file in the @code{obj_dir} defined
+in the project  file.  If this file can not be  found, emacs proposes to
+compile the source using the @code{comp_cmd} defined in the project file
+in order to create the ali file.
+
+@item when cross referencing is requested, the .ali  file is parsed to
+determine  the  file and  line  of  the  identifier definition.   It  is
+possible for  the .ali file to be  older than the source  file, in which
+case it will be recompiled if the variable @code{ada-xref-create-ali} is
+set, otherwise the  reference is searched in the  obsolete ali file with
+possible inaccurate results.
+
+@item look  for   the file containing the declaration using the source
+path @code{src_dir} defined in the  project file.  Put the cursor at the
+correct position and display this new cursor.
+@end itemize
+
+@c -----------------------------------------------------------------------
+@node Syntax highlighting, Moving Through Ada Code, Project files, Top
+@chapter Syntax highlighting
+@c -----------------------------------------------------------------------
+
+The Ada mode is made to help you understand the structure of your source
+files. Some  people like having  colors or different fonts  depending on
+the  context: commands  should be  displayed differently  than keywords,
+which should also be different from strings, ...
+
+Emacs is able to display in a different way the following syntactic
+entities:
+
+@itemize @bullet
+@item keywords
+@item commands
+@item strings
+@item gnatprep statements (preprocessor)
+@item types (under certain conditions)
+@item other words
+@end itemize
+
+This  is not  the default  behavior for  Emacs. You  have  to explicitly
+activate it. This requires that you add a new line in your @file{.emacs}
+file (if this file does not exist, just create it).
+
+@example
+  (global-font-lock-mode t)
+@end example
+
+But  the default colors  might not  be the  ones you  like. Fortunately,
+there  is  a  very  easy  way  to change  them.  Just  select  the  menu
+@kbd{Help->Customize->Specific  Face...}  and  press @kbd{Return}.  This
+will display a buffer will all the "faces" (the colors) that Emacs knows
+about. You can change any of them.
+
+
+@c -----------------------------------------------------------------------
+@node Moving Through Ada Code, Identifier completion, Syntax highlighting, Top
+@chapter Moving Through Ada Code
+@c -----------------------------------------------------------------------
+
+There are several  easy to use commands to stroll  through Ada code. All
+these functions are available through the Ada menu, and you can also use
+the following key bindings or the command names:
+
+@table @kbd
+@item M-C-e    ada-next-procedure
+Move to the next function/procedure/task, which ever comes next.
+@item M-C-a    ada-previous-procedure
+Move to previous function/procedure/task.
+@item          ada-next-package
+Move to next package.
+@item          ada-prev-package
+Move to previous package.
+@item C-c C-a  ada-move-to-start
+Move  to matching start  of @code{end}.   If point  is at  the end  of a
+subprogram, this command jumps  to the corresponding @code{begin} if the
+user option  @code{ada-move-to-declaration} is @code{nil}  (default), it
+jumps to the subprogram declaration otherwise.
+@item C-c C-e  ada-move-to-end
+Move point to end of current block.
+@item C-c o    ff-find-other-file
+Switch between corresponding spec and body  file.  If the cursor is on a
+subprogram, switch between declaration and body.
+@item C-c c-d
+Move  from   any  reference  to  its  declaration   and  switch  between
+declaration  and body  (for  procedures, tasks,  private and  incomplete
+types).
+@item C-c C-r  ada-find-references
+runs the  @file{gnatfind} command  to search for  all references  to the
+entity pointed  by the cursor. Use  'next-error' function, or  C-x `, to
+visit each reference (as for compilation errors).
+@end table
+
+These  functions use  the  information in  the  output of  the Gnat  Ada
+compiler.   However,   if  your   application  was  compiled   with  the
+@code{-gnatx}  switch, these  functions will  not work,  since  no extra
+information  is generated by  GNAT. See  GNAT documentation  for further
+information.
+
+Emacs will  try to  run    Gnat for  you whenever the    cross-reference
+informations  are     older   than your   source   file   (provided  the
+@code{ada-xref-create-ali} variable is  non nil).  Gnat  then produces a
+file with the same name  as the current  Ada file but with the extension
+changed to @code{.ali}. This files are normally used  by the binder, but
+they will also contain additional cross-referencing information.
+
+@c -----------------------------------------------------------------------
+@node Identifier completion, Index Menu of Subprograms, Moving Through Ada Code, Top
+@chapter Identifier completion
+@c -----------------------------------------------------------------------
+
+@c -----------------------------------------------------------------------
+@section Overview
+@c -----------------------------------------------------------------------
+
+Emacs and  the Ada mode provide  two general ways for  the completion of
+identifiers. This is  an easy way to type faster: you  just have to type
+the first few  letters of an identifiers, and then  loop through all the
+possible completions.
+
+The  first method  is general  for  Emacs. It  will work  both with  Ada
+buffers, but also in C buffers,  Java buffers, ...  The idea is to parse
+all the opened buffers for possible completions.
+
+For instance,  if the following words  are present in any  of the opened
+files: my_identifier, my_subprogam, then you will have this scenario:
+@example
+You type:  my@key{M-/}
+Emacs will display:  my_identifier
+If you press @key{M-/} once again, Emacs will replace my_identifier with
+my_subprogram.
+Pressing @key{M-/} once more will bring you back to my_identifier.
+@end example
+
+This is a very  fast way to do completion, and the  casing of words will
+also be respected.
+
+The second  method is specific to Ada  buffer, and even to  users of the
+Gnat compiler. Emacs will search the cross-information found in the .ali
+files generated by Gnat for possible completions.
+
+The  main advantage  is  that  this completion  is  more accurate:  only
+existing identifier  will be  suggested, you don't  need to have  a file
+opened that already contains this identifiers,...
+
+On the other  hand, this completion is a little  bit slower and requires
+that you  have compiled your file  at least once since  you created that
+identifier.
+
+@c -----------------------------------------------------------------------
+@section Summary of commands
+@c -----------------------------------------------------------------------
+
+@table @kbd
+@item C-TAB  ada-complete-identifier
+complete accurately current identifier using information in .ali file
+@item M-/
+complete identifier using buffer information (not ada specific)
+@end table
+
+@c -----------------------------------------------------------------------
+@node Index Menu of Subprograms, File Browser, Identifier completion, Top
+@chapter Index Menu of Subprograms
+@c -----------------------------------------------------------------------
+
+You  can   display  a  choice  menu   with  all  procedure/function/task
+declarations in the file and choose an item by mouse click to get to its
+declaration.  This function is  accessible through  the 'Ada'  menu when
+editing a Ada file, or simply through the following key binding :
+
+@table @kbd
+@item C-S-mouse-3
+display index menu
+@end table
+
+@c -----------------------------------------------------------------------
+@node File Browser, Automatic Smart Indentation, Index Menu of Subprograms, Top
+@chapter File Browser
+@c -----------------------------------------------------------------------
+
+Emacs provides a special mode, called @code{speedbar}. When this mode is
+activated, a new frame is displayed, with a file browser. The files from
+the current  directory are displayed, and  you can click on  them as you
+would with any file browser. The following commands are then available.
+
+You can click  on a directory name  or file name to open  it. The editor
+will  automatically  select  the  best  possible  mode  for  this  file,
+including of course the ada-mode for files written in Ada
+
+If you click on the [+] symbol near a file name, all the symbols (types,
+variables and subprograms)  defined in that file will  be displayed, and
+you  can directly click  on them  to open  the right  file at  the right
+place.
+
+You can activate  this mode by typing @key{M-x  speedbar} in the editor.
+This  will open  a new  frame. A  better way  might be  to  assicate the
+following key binding
+
+@example
+(global-set-key [f7]  'speedbar-get-focus)
+@end example
+
+Every time you press @key{f7},  the mouse will automatically move to the
+speedbar frame (which will be created if it does not exist).
+
+@c -----------------------------------------------------------------------
+@node Automatic Smart Indentation, Formatting Parameter Lists, File Browser, Top
+@chapter Automatic Smart Indentation
+@c -----------------------------------------------------------------------
+
+The Ada mode  comes with a full set of  rules for automatic indentation.
+You can of course configure the  indentation as you want, by setting the
+value of a few variables.
+
+As  always,  the  preferred  way  to  modify variables  is  to  use  the
+@code{Ada->Customize} menu  (don't forget  to save your  changes!). This
+will also show you some example of code where this variable is used, and
+hopefully make things clearer.
+
+The relevant variables are the following:
+
+@table @code
+@item ada-broken-indent           (default value: 2)
+Number of columns to indent the continuation of a broken line
+
+@item ada-indent                  (default value: 3)
+Width of the default indentation
+
+@item ada-indent-record-rel-type  (default value: 3)
+Indentation for 'record' relative to 'type' or 'use'
+
+@item ada-indent-return           (default value: 0)
+Indentation for 'return' relative to 'function' (if ada-indent-return
+is greater than 0), or the open parenthesis (if ada-indent-return is
+negative or null). Note that in the second case, when there is no
+open parenthesis, the indentation is done relative to 'function' with
+the value of ada-broken-indent.
+
+@item ada-label-indent            (default value: -4)
+Number of columns to indent a label
+
+@item ada-stmt-end-indent         (default value: 0)
+Number of columns to indent a statement 'end' keyword on a separate line
+
+@item ada-when-indent             (default value: 3)
+Indentation for 'when' relative to 'exception' or 'case'
+
+@item ada-indent-is-separate      (default value: t)
+Non-nil means indent 'is separate' or 'is abstract' if on a single line
+
+@item ada-indent-to-open-paren    (default value: t)
+Non-nil means indent according to the innermost open parenthesis
+
+@item ada-indent-after-return     (default  value: t)
+Non-nil  means that  the current  line will  also be  re-indented before
+inserting a newline, when you press @kbd{Return}.
+
+@end table
+
+Most of the  time, the indentation will be automatic,  i.e when you will
+press @kbd{Return},  the cursor will move  to the correct  column on the
+next line.
+
+However, you might want or  need sometimes to re-indent the current line
+or a set of  lines. For this, you can simply go  to that line, or select
+the lines,  and then press @kbd{TAB}. This  will automatically re-indent
+the lines.
+
+Another  mode  of indentation  exists  that helps  you  to  set up  your
+indentation scheme. If you press @kbd{C-c TAB}, the ada-mode will do the
+following:
+@itemize @bullet
+@item Reindent the current line, as @kbd{TAB} would do
+@item Temporarily move the cursor to a reference line, i.e the line that
+  was used to calculate the current indentation
+@item Display at the bottom of the window the name of the variable that
+  provided the offset for the indentation
+@end itemize
+
+The exact indentation of the current line is the same as the one for the
+reference line, plus an offset given by the variable.
+
+Once you know the name of the variable, you can either modify it through
+the   usual   @key{Ada->Customize}   menu,   or   by   typing   @key{M-x
+customize-variable RET} in the Emacs window, and then give the name of
+the variable.
+
+@table @kbd
+@item TAB
+indent the current line or the current region.
+@item M-C-\
+indent lines in the current selected block.
+@item C-c TAB
+indent the current line and prints the name of the variable used for
+indentation.
+@end table
+
+
+
+@c -----------------------------------------------------------------------
+@node Formatting Parameter Lists, Automatic Casing, Automatic Smart Indentation, Top
+@chapter Formatting Parameter Lists
+@c -----------------------------------------------------------------------
+
+To help you correctly align fields in a subprogram parameter list, Emacs
+provides  one function  that will  do  most of  the work  for you.  This
+function  will align  the  declarations on  the  colon (':')  separating
+argument names  and argument types, plus  align the 'in',  'out' and 'in
+out' keywords if required.
+
+@table @kbd
+@item C-c C-f  ada-format-paramlist
+Format the parameter list.
+@end table
+
+@c -----------------------------------------------------------------------
+@node Automatic Casing, Statement Templates, Formatting Parameter Lists, Top
+@chapter Automatic Casing
+@c -----------------------------------------------------------------------
+
+Casing  of   identifiers,  attributes  and   keywords  is  automatically
+performed while  typing when  the variable @code{ada-auto-case}  is set.
+Every  time   you  press  a   word  separator,  the  previous   word  is
+automatically cased.
+
+You  can  customize  the  automatic  casing  differently  for  keywords,
+attributes and  identifiers. The  relevant variables are  the following:
+@code{ada-case-keyword},          @code{ada-case-attribute}          and
+@code{ada-case-identifier}.
+
+All these variables can have one of the following values:
+
+@table @kbd
+@item downcase-word
+The  previous word  will simply  be in  all lower  cases.   For instance
+@code{My_vARIable} is converted to @code{my_variable}.
+
+@item upcase-word
+The previous word will be  fully converted to upper cases.  For instance
+@code{My_vARIable} is converted to @code{MY_VARIABLE}.
+
+@item ada-capitalize-word
+All letters, except the first one of the word and every letter after the
+'_'  character are  lower cased.  Other  letters are  upper cased.   For
+instance @code{My_vARIable} is converted to @code{My_Variable}.
+
+@item ada-loose-case-word
+No letters is  modified in the previous word, except  the ones after the
+'_' character that are  upper cased.  For instance @code{My_vARIable} is
+converted to @code{My_VARIable}.
+@end table
+
+These  functions, although they  will work  in most  cases, will  not be
+accurate sometimes. The  Ada mode allows you to  define some exceptions,
+that will always be cased the same way.
+
+The idea  is to  create a dictionary  of exceptions,  and store it  in a
+file. This file should contain  one identifier per line, with the casing
+you   want   to   force.   The   default   name   for   this   file   is
+@file{~/.emacs_case_exceptions}.  You can  of course  change  this name,
+through the variable @code{ada-case-exception-file}.
+
+Note that  each line  in this file  must start  with the key  word whose
+casing  you want  to  specify. The  rest of  the  line can  be used  for
+comments  (explaining  for  instance  what  an  abbreviation  means,  as
+recommended in the Ada 95  Quality and Style, paragrpah 3.1.4).  Thus, a
+good example for this file could be:
+
+@example
+DOD        Department of Defense
+Text_IO
+GNAT       The GNAT compiler from Ada Core Technologies
+@end example
+
+When  working on  project involving  multiple programmers,  we recommend
+that every  member of  the team  sets this variable  to the  same value,
+which  should  point  to  a  system-wide  file that  each  of  them  can
+write.  That  way,  you  will  ensure  that  the  casing  is  consistent
+throughout your application(s).
+
+There are two ways to add new items to this file: you can simply edit it
+as you  would edit any  text file, and  add or suppress entries  in this
+file.  Remember that  you should  put one  entity per  line.  The other,
+easier way, is to position the cursor  over the word you want to add, in
+an Ada buffer.  This word should have the casing  you want.  Then simply
+select  the  menu @kbd{Ada->Edit->Create  Case  Exception},  or the  key
+@kbd{C-c C-y}. The word will  automatically be added to the current list
+of exceptions and to the file.
+
+It  is sometimes  useful to  have multiple  exception files  around (for
+instance,  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.
+
+However, when  you save a new  exception through the  menu, as described
+above, the  new exception will  be added to  the first file in  the list
+only.  You  can not automatically add  an exception to one  of the other
+files, although you can of course edit the files by hand at any time.
+
+Automatic casing can be performed on port or whole buffer using:
+@table @kbd
+@item C-c C-b
+Adjust case in the whole buffer.
+@item C-c C-y
+Create a new entry in the exception dictionary, with the word under
+the cursor
+@item C-c C-t
+Rereads the exception dictionary from the file
+@code{ada-case-exception-file}.
+@end table
+
+@c -----------------------------------------------------------------------
+@node Statement Templates, Comment Handling, Automatic Casing, Top
+@chapter Statement Templates
+@c -----------------------------------------------------------------------
+
+NOTE:  This features  are  not available  on  VMS for  Emacs 19.28.  The
+functions used here do not exist on Emacs 19.28.
+
+Templates exist  for most  Ada statements. They  can be inserted  in the
+buffer using the following commands:
+
+@table @kbd
+@item C-c t b
+exception Block
+@item C-c t c
+case.
+@item C-c t d
+declare Block.
+@item C-c t e
+else.
+@item C-c t f
+for Loop.
+@item C-c t h
+Header.
+@item C-c t i
+if.
+@item C-c t k
+package Body.
+@item C-c t l
+loop.
+@item C-c t t
+task Body.
+@item C-c t w
+while Loop.
+@item C-c t u
+use.
+@item C-c t x
+exit.
+@item C-c t C-a
+array.
+@item C-c t C-e
+elsif.
+@item C-c t C-f
+function Spec.
+@item C-c t C-k
+package Spec.
+@item C-c t C-p
+procedure Spec.
+@item C-c t C-r
+record.
+@item C-c t C-s
+subtype.
+@item C-c t C-t
+task Spec.
+@item C-c t C-u
+with.
+@item C-c t C-v
+private.
+@item C-c t C-w
+when.
+@item C-c t C-x
+exception.
+@item C-c t C-y
+type.
+@end table
+
+@c -----------------------------------------------------------------------
+@node Comment Handling, Compiling Executing, Statement Templates, Top
+@chapter Comment Handling
+@c -----------------------------------------------------------------------
+
+By default, comment lines get indented like Ada code. There are a few
+additional functions to handle comments:
+
+
+@table @kbd
+@item M-;
+Start a comment in default column.
+@item M-j
+Continue comment on next line.
+@item C-c ;   comment-region
+Comment the selected region (add -- at the beginning of lines).
+@item C-c :
+Uncomment the selected region
+@item M-q
+autofill the current comment.
+@end table
+
+@c -----------------------------------------------------------------------
+@node Compiling Executing, Debugging, Comment Handling, Top
+@chapter Compiling Executing
+@c -----------------------------------------------------------------------
+
+Ada mode  provides a much complete environment  for compiling, debugging
+and running an application within Emacs.
+
+All the  commands used  by Emacs to  manipulate your application  can be
+customized in  the project file.  Some default values are  provided, but
+these will  likely not  be good  enough for a  big or  even medium-sized
+project.  See the section on the  project file for an explanation on how
+to set up the commands to use.
+
+One   of   the  variables   you   can   set   in  your   project   file,
+@code{cross_prefix}, indicates whether you are using a cross-compilation
+environment, and if  yes for which target. The  default command used for
+compilation  will add  this @code{cross_prefix}  in front  of  the name:
+@code{gcc}  will become  @code{cross_prefix}-@code{gcc}, @code{gnatmake}
+will become @code{cross_prefix}-@code{gnatmake}, ...
+
+This  will also modify  the way  your application  is run  and debugged,
+although this is not implemented at the moment.
+
+Here are the commands for building and using an Ada application
+
+@itemize @bullet
+
+@item Compiling the current source
+This command is issued when  issuing the @code{compile} command from the
+Ada  menu. It  compiles  unconditionally the  current  source using  the
+@code{comp_cmd} variable of the project file. Compilation options can be
+customized with the variable @code{comp_opt} of the project file.
+
+Emacs  will  display  a new  buffer  that  contains  the result  of  the
+compilation.  Each line associated with an error will become active: you
+can simply click on it with the  middle button of the mouse, or move the
+cursor  on  it and  press  @kbd{Return}.  Emacs  will then  display  the
+relevant source file and put the cursor on the line and column the error
+was found at.
+
+You can also simply press the @kbd{C-x `} key 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 might also include references to some files. These
+references are also clickable in the same way.
+
+
+@item (Re)building the whole application
+This command is issued when you select the @code{build} command from the
+Ada menu.   It compiles  all obsolete units  of the  current application
+using  the @code{make_cmd}  variable  of the  project file.  Compilation
+options  can be  customized  with the  variable  @code{comp_opt} of  the
+project  file, binder  options with  @code{bind_opt} and  linker options
+with @code{link_opt}. The main unit  of the application may be specified
+with @code{main}.
+
+The compilation buffer is also active in the same way it was for the above
+command.
+
+@item Running the application
+This command is  issued when you select the  @code{run} command from the
+Ada   menu.   It   executes  the   current  application   in   an  emacs
+buffer. Arguments can be  passed through before executing. The execution
+buffer allows for interactive input/output.
+
+This   command   is   not   yet   available   in   a   cross-compilation
+toolchain. Emacs  would first need to  log on the  target before running
+the application. This will be implemented in a future release of Gnat.
+
+@end itemize
+
+@c ---------------------------------------------------------------------
+@node Debugging, Using non-standard file names, Compiling Executing, Top
+@chapter Debugging your application
+@c ---------------------------------------------------------------------
+
+You  can set  up in  the project  file a  command to  use to  debug your
+application. Emacs is compatible with a lot of debuggers, and provide an
+easy interface to them.
+
+This selection will focus on the  gdb debugger, and two of the graphical
+interfaces that exist for it.
+
+In all  cases, the main  window in  Emacs will be  split in two:  in the
+upper  buffer,  the  source  code  will  appear,  whereas  the  debugger
+input/output  window is  displayed at  the  bottom.  You  can enter  the
+debugger  commands as  usual in  the command  window. Every  time  a new
+source file is  selected by the debugger (for instance as  a result of a
+@code{frame} command),  the appropriate source file is  displayed in the
+upper buffer.
+
+The source window is interactive: you can click on an identifier with the
+right mouse button, and print its value in the debugger window. You can
+also set a breakpoint simply by right-clicking on a line.
+
+You  can easily use  Emacs as  the source  window when  you are  using a
+graphical  interface for the  debugger. The  interesting thing  is that,
+whereas  you still  have the  graphical nifties,  you can  also  you the
+cross-references  features that  the ada-mode  provides to  look  at the
+definition for the identifiers,...
+
+Here is how you  can set up gdbtk and ddd for  use with Emacs (These are
+the commands you should setup in the project file):
+
+@itemize @bullet
+@item gdbtk
+should  be used  with  the  switch --emacs_gdbtk.   It  provides a  nice
+backtrace window, as well as a tasks window. You can click interactively
+on both of  them, and Emacs will display the source  file on the correct
+line.
+
+@item ddd (Data Display Debugger)
+should be used with the switches --tty and -fullname. Whenever you
+print a variable from Emacs, it will be displayed graphically in the
+data window.
+
+@end itemize
+
+
+@c ---------------------------------------------------------------------
+@node Using non-standard file names, Working Remotely, Debugging, Top
+@chapter Using non-standard file names
+@c ---------------------------------------------------------------------
+
+By default, Emacs is configured to  use the GNAT style file names, where
+file names are the package names,  and the extension for spec and bodies
+are respectively .ads and .adb.
+
+If you  want to  use other  types of file  names, you will need to modify
+your .emacs configuration file.
+
+Adding new possible extensions is easy. Since the ada-mode needs to know
+how to  go from  the body  to the spec  (and back),  you always  have to
+specify  both. A  function  is provided  with  the ada-mode  to add  new
+extensions.
+
+For  instance, if your  files are  called <unit>_s.ada  and <unit>_b.ada
+respectively for spec and bodies, you  need to add the following to your
+@file{.emacs} :
+
+@example
+(ada-add-extensions "_s.ada" "_b.ada")
+@end example
+
+Note that it is possible to redefine the extension, even if they already
+exist, as in:
+
+@example
+(ada-add-extensions ".ads" "_b.ada")
+(ada-add-extensions ".ads" ".body")
+@end example
+
+This simply means that whenever the  ada-mode will look for the body for
+a file whose extension is  @file{.ads}, it will take the first available
+file  that ends  with  either @file{.adb}  (standard), @file{_b.ada}  or
+@file{.body}.
+
+If the  filename is  not the unit  name, then  things are a  little more
+complicated.     You    then    need    to    rewrite    the    function
+ada-make-filename-from-adaname (see  the file @file{ada-mode.el}  for an
+example).
+
+@c ---------------------------------------------------------------------
+@node Working Remotely, ,Using non-standard file names, Top
+@chapter Working Remotely
+@c ---------------------------------------------------------------------
+
+When  you work  on project  that  involve a  lot of  programmers, it  is
+generally the case that you will edit the files on your own machine, but
+you want to compile, run and debug your application in another buffer.
+
+Fortunately, here too Emacs provides a very convenient way to do this.
+
+@c ---------------------------------------------------------------------
+@section Remote editing
+@c ---------------------------------------------------------------------
+
+First of  all, the files do  not need to  be on your machine.  Emacs can
+edit any  remote file,  by doing transparent  FTP sessions  between your
+machine and the remote machine that stores your files. This is a special
+Emacs mode, called @code{ange-ftp}. To use it, you just have to use a
+slightly different syntax when you open a file.
+
+@example
+For instance, if you want to  open the file /work/foo.adb on the machine
+aleph.gnu.org, where you log in as qwe, you would simply do this:
+
+@key{C-x C-f} /qwe@@aleph.gnu.org:/work/foo.adb @key{Return}
+
+i.e put your name, the name of the machine and the name of the file.
+@end example
+
+The first time, Emacs will ask  you for a password that it will remember
+until you  close the current Emacs.  Even if the ftp  session times out,
+you won't need to reenter your password.
+
+Every time you save the file, Emacs will upload it to the remote machine
+transparently. No file is modified on the local machine.
+
+@c ---------------------------------------------------------------------
+@section Remote compiling
+@c ---------------------------------------------------------------------
+
+If the  machine you  want to  compile on is  not the  one your  Emacs is
+running  on,  you can  set  the  variable  @code{remote_machine} in  the
+project file for your application.
+
+This  will force  Emacs  to issue  a  rsh command  for the  compilation,
+instead of  running it on  the local machine. Unfortunately,  this won't
+work on Windows workstations, since this protocol is not supported.
+
+@example
+If  your   @code{remote_machine}  is  aleph.gnu.org   and  the  standard
+compilation command is @code{cd /work/ && gnatmake foo}, then Emacs will
+actually  issue  the  command  @code{rsh  aleph.gnu.org  'cd  /work/  &&
+gnatmake foo'}.
+@end example
+
+The advantage of using the  @code{remote_machine} variable is that it is
+easier to change  that machine without having to  modify the compilation
+command.
+
+Note that if you need to set up some environment variables before the
+compilation, you need to insert a call to the appropriate initialization
+script in the compilation command, for instance:
+
+@example
+build_cmd= initialization_script ; cd /work/ && gnatmake foo
+@end example
+
+@c ---------------------------------------------------------------------
+@section Remote running and debugging
+@c ---------------------------------------------------------------------
+
+This feature is not completely implemented yet.
+
+However, most of the time, you will be able to run your application
+remotely simply by replacing it with a 'rsh' call on Unix.
+
+@example
+For instance, if your command was '$@{main@}', you could replace it with
+'rsh aleph.gnu.org $@{main@}'.
+@end example
+
+However, this would not fully work for instance on vxworks, where rsh
+is not supported.
+
+@contents
+@bye