\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename sather-mode.info
@settitle The Sather Emacs Programming Environment
@setchapternewpage off
@c %**end of header

@ifinfo
This file describes the Emacs editing environment for the Sather
language.

Copyright (C) 1996 by International Computer Science Institute
This file is part of the GNU Sather package. It is free software; you may
redistribute  and/or modify it under the terms of the  GNU General Public
License (GPL)  as  published  by the  Free  Software  Foundation;  either
version 2 of the license, or (at your option) any later version.
This  program  is distributed  in the  hope that it will  be  useful, but
WITHOUT ANY WARRANTY without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See Doc/GPL for more details.
The license text is also available from:  Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
----------->  Please email comments to <bug-sather@@gnu.org>  <-----------
@end ifinfo

@titlepage
@sp 5
@center @titlefont{The Sather Emacs Programming Environment}
@sp 5
@center May 13, 1996
@c 1.7
@sp 5
@center Kevin K. Lewis
@center lewikk@@aud.alcatel.com
@sp 5
@center Alcatel Network Systems
@center 1225 N. Alma Road
@center Richardson, TX 75081-2206
@center M/S 408-200

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1996 by International Computer Science Institute

This file is part of the GNU Sather package. It is free software; you may
redistribute  and/or modify it under the terms of the  GNU General Public
License (GPL)  as  published  by the  Free  Software  Foundation;  either
version 2 of the license, or (at your option) any later version.

This  program  is distributed  in the  hope that it will  be  useful, but
WITHOUT ANY WARRANTY without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE. See Doc/GPL for more details.

The license text is also available from:  Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
@end titlepage

@node Top, , (dir), (dir)
@top

@ifinfo
This document describes the Sather Emacs Programming Environment,
intended for use with the Sather language as implemented by the Sather
1.0 and 1.1 Compilers, from the University of California, at Berkeley,
and the GNU Emacs programmable editor, version 19.
@end ifinfo

@menu
* Introduction::                Welcome to the Sather Emacs Environment.
* Getting Started::             Getting @code{sather-mode} up and running.
* Indenting::                   How code indentation works.
* Hiding and Showing Code::     Outlining with selective display.
* Minor Features::              Features that do small, but useful things.
* Inserting Code Stubs::        Some insertion functions that save you some
                                typing.
* Compiling Sather Code::       Compiling Sather code in @code{sather-mode}.
* Browsing Sather Code::        Running the Sather Browser from Emacs.
* Commenting Code::             Adding comments to Sather code.
* Highlighting::                Syntax highlighting for Sather code.
* Editing Module Files::        A major mode for editing Sather Module files.
* Library Functions::           Sundry library functions found in
                                @code{sather-lib}.
* Customization::               How to customize @code{sather-mode}.
* Bugs and Comments::           How to make comments and submit bug
                                reports on @code{sather-mode}
* Key Index::
* Function Index::
* Variable Index::
* Concept Index::
@end menu

@node Introduction, Getting Started, Top, Top
@chapter Introduction
@cindex Introduction

Welcome to the Sather Emacs Programming Environment!  In all honesty,
that's just a fancy title for some stuff built up around
@code{sather-mode}.  (But I like the name, so you're stuck with it.)

The Sather Emacs Programming Environment (;-) is composed of an Emacs
major mode for editing Sather code, @code{sather-mode}, an major mode
for editing Sather Module files, @code{sather-module-mode}, a set of
library convenience functions (contained in @file{sather-lib.el}), an
Info version of @emph{The Sather Specification}, (@pxref{Top, The Sather
Specification, The Sather Specification, sather, The Sather
Specification}), and, of course, the GNU Emacs (or GNU XEmacs) text
editor, version 19.

This manual covers the following major features of the Sather Emacs
Environment:

@itemize @bullet
@item
Customizable code indentation.

@item
Function sets to hide and unhide Sather classes and routines.

@item
A set of customizable minor features, including:

@itemize @minus
@item
a ``hungry'' delete key,

@item
automatic indentation,

@item
automatic newlines following the entry of a semi-colon (@code{;}),

@item
newline prefix indentation, that fixes the indentation of syntactically
ambiguous keywords (e.g. @code{else}).
@end itemize

@item
Documentation convenience functions, that supply customizable text for
commented headers.

@item
Syntax highlighting (through @code{hl319}, @code{hilit19}, or
@code{font-lock}), with customizable colors, and the ability to turn on
or off highlighting for a given syntactical element (@code{hl319} and
@code{font-lock} only).

@item
A set of general purpose library routines that help the Sather language
work better with a *IX-ish environment, or provide helpful functions
that may be used in many programming languages.

@item
Support for compiling Sather modules within Emacs, and parsing any
unlikely error messages.

@item
Support for launching the Sather browser within Emacs, and controlling
its initialization with customizable variables.

@item
An automated bug and comment reporter for reporting bugs or making
comments concerning the Sather Compiler, and the Sather Emacs
Programming Environment.
@end itemize

@node Getting Started, Indenting, Introduction, Top
@chapter Getting Started
@cindex Getting Started

Currently, the Sather Emacs Programming Environment consists of the
GNU Emacs editor and the following files:

@table @file
@item README
A text file explaining how to install the Sather Emacs Programming
Environment (you should read it).

@item sather.el
@itemx sather.elc
The ELisp source for @code{sather-mode}, and the compiled source.

@item sather-lib.el
@itemx sather-lib.elc
The ELisp source for the supplemental library functions, and the
compiled library source.

@item sather-module.el
@itemx sather-module.elc
The ELisp source for @code{sather-module-mode}, and the compiled source.

@item dir
A sample GNU Info directory file for the included Info files.

@item sather.texinfo
@itemx sather.info*
The Texinfo and Info versions of the Sather Specification
manual@footnote{Currently, only the 1.0 specification is available in
Texinfo format.  Hopefully a Texinfo version of the 1.1 specification is
on the way.  Please contact me or the compiler maintainer if you would
like to do this.}.

@item sather-mode.texinfo
@itemx sather-mode.info*
Texinfo and Info versions of the Sather Emacs Programming Environment
manual (which you are currently reading).

@item TODO
A text file listing the things that I would like to do, eventually, but
either can't figure out, or don't have the time to implement.  So: it
would be really cool if someone else took up the challenge.
@end table

The ELisp source files are intended for use with GNU Emacs 19.24 and GNU
XEmacs 19.12@footnote{I think I have corrected the highlighting when
using XEmacs.  Let me know if more exist.}  (including later versions of
each).  They are currently developed using GNU Emacs 19.30.  If you are
using a version of GNU Emacs earlier than 19.24, please send a bug
report if you have problems compiling or loading the ELisp files
(@pxref{Bugs and Comments}).  It is recommended, however, that you
upgrade to 19.30 (or the newest ``stable'' version), as that is a very
stable version.  Support for earlier versions of the supported flavors
of Emacs may be dropped in order to continue easy development (besides,
Emacs is free and generally easy to upgrade).

The @file{*.el} and @file{*.elc} files should be copied to a directory
in your Emacs @code{load-path}.  You can query Emacs for these paths
with @kbd{C-h v load-path RET}.

The @file{*.info*} files should be copied to a directory in your
@code{Info-directory-list} (@kbd{C-h v Info-directory-list RET}).
You'll need to edit the @file{dir} file in the same Info directory (or
use the supplied @file{dir}).  The syntax for doing this should be
obvious.

In order for @code{sather-mode} to be loaded and activated when you
visit Sather source files in Emacs, you must tell Emacs what files you
consider to be Sather files, and what to do when it finds them.

Adding the following lines to one of your initialization files will tie
@code{sather-mode} to files that end with the standard Sather source
extension, @file{.sa}:

@example
(autoload 'sather-mode "sather" "Sather Mode" t)
(setq auto-mode-alist
      (append '(("\\.sa$" . sather-mode)
                ) auto-mode-alist))
@end example

These lines may be added to a user's own @file{.emacs} file, another
personal initialization file, or to the site's @file{site-start.el}
file.

When @code{sather-mode} is run for a loaded file, the last thing it runs
on the buffer is the function, @code{sather-mode-hook}.  This is
intended for user customizations, and is covered in
@ref{Customization}.

Now, having done all of that, you should be ready to go through the rest
of the manual.  We'll start with indentation.

@node Indenting, Hiding and Showing Code, Getting Started, Top
@chapter Indenting
@cindex Indenting

@kindex TAB
@kindex RET
@kindex ;
@code{sather-mode} provides several customizable variables that control
indenting.  These variables are not intended to provide support for
different coding styles as you might find in a ``C'' programming mode
(placement of opening and closing braces, etc.).  They do, however,
control the number of spaces for an indent, and the way different keys
act for indenting code (e.g. @key{TAB}, @key{RET}, @key{;}).

@menu
* Indentation Variables::
* Indentation Functions and Keys::
* Indenting Blocks::
* Indenting Regions::
* Indenting S-expressions::
@end menu

@node Indentation Variables, Indentation Functions and Keys, Indenting, Indenting
@section Indentation Variables
@cindex Indenting, variables
@cindex Variables, indenting

There are two@footnote{Actually, there are six, but the others are only
for comments.  @xref{Commenting Code}, for explanations of the other
three.} variables that control the @emph{amount} of an indentation.
They are:

@defvar sather-indent
This controls how much code is indented relative to the surrounding
block.  Its default value is three (3) spaces.
@end defvar

@defvar sather-continued-line-indent
This controls the extra indentation for text that continues a statement
onto following lines.  Its value is twice @code{sather-indent}, by
default.  This causes continued code to be indented six spaces more than
the line it continues, because the value of
@code{sather-continued-line-indent} is added to that of
@code{sather-indent}.  If a statement is broken up onto more than two
lines, all lines that ``continue'' the statement will be indented to the
same level, so that the first line of the statement is emphasized.
@end defvar

The following examples illustrate the effect setting these variables has
on code indentation.

If, for example, you add the following line to your
@code{sather-mode-hook}:

@example
(setq sather-indent 5)
@end example

@noindent
Code which, by default, would indent like this:

@example
if a > b then
   #OUT + "`a' is greater than `b'.\n"
         + "Please inform the President.\n";
end;
@end example

@noindent
would instead be indented like this:

@example
if a > b then
     #OUT + "`a' is greater than `b'.\n"
               + "Please inform the President.\n";
end;
@end example

@noindent
Notice that, because @code{sather-continued-line-indent} is based on
@code{sather-indent}, its value changes as well (but only at
initialization).

However, if you instead added the following to your
@code{sather-mode-hook}:

@example
(setq sather-indent 5)
(setq sather-continued-line-indent 1)
@end example

@noindent
the above example would appear like this:

@example
if a > b then
     #OUT + "`a' is greater than `b'.\n"
      + "Please inform the President.\n";
end;
@end example

@emph{Note:} Because the two indentation variables are calculated
relative to the surrounding block of code, if that block is not indented
correctly, the containing block will not be indented correctly.
@code{sather-mode} relies on code context in order to speed up
indentation.

@node Indentation Functions and Keys, Indenting Blocks, Indentation Variables, Indenting
@section Indentation Functions and Keys
@cindex Indenting, functions
@cindex Functions, indenting with
@cindex Indenting, keys
@cindex Keys, indenting with

@kindex @key{TAB}
@kindex C-q
Indenting is performed using the @key{TAB} key, which is bound to the
@code{sather-indent-command} function.  This function analyzes the
context in which the key is entered, and indents to the appropriate
indentation level.  Each ``block'' adds a level of indentation.  Blocks
are begun by a block open clause.  These include: @code{fork},
@code{if}, @code{is}, @code{lock}, @code{loop}, @code{parloop},
@code{protect}, @code{case}, and @code{typecase}.  The @code{end}
keyword closes a block.  The @key{TAB} key has this effect no matter
where on the current line the point (@pxref{Point, Point, Point, emacs,
Point}, for an explanation of the Emacs point) is positioned, but the
line is only repositioned if the indentation of the line is not already
``correct''.  To enter a ``real'' tab character into the buffer, use
@kbd{C-q @key{TAB}}.

The number of spaces indented depends on the value of
@code{sather-indent}, or @code{sather-continued-line-indent}
(@pxref{Indentation Variables}).  The number of spaces of indentation
for a non-continued line is the value of @code{sather-indent} times the
block level.  The number of spaces of indentation for a continued line
is @code{sather-indent} times the block level, plus the value of
@code{sather-continued-line-indent}.

@kindex ;
The semi-colon (@key{;}) is bound the function,
@code{sather-electric-semi}.  Entering a semi-colon indents the current
line as if you had pressed the @key{TAB} key.  It may also enter a
newline character if the value of @code{sather-auto-newline} is
non-@code{nil}.

@node Indenting Blocks, Indenting Regions, Indentation Functions and Keys, Indenting
@section Indenting Blocks
@cindex Blocks, indenting
@cindex Indenting, blocks

@kindex M-C-q
The key sequence, @kbd{M-C-q} is bound to @code{sather-indent-block},
which indents a block of Sather code.  The point (@pxref{Point, Point,
Point, emacs, Point}, for an explanation of the Emacs point) must be on
the first line of the block.  For example, the following code is all
skewed.  It would be a pain to have to indent every line by itself
(especially if the routine had 90 lines instead of 9).  Fortunately, you
can preserve your @key{TAB} key by using @code{sather-indent-block}:

@example
cow:INT is
#OUT + "Count other windows\n";
  if doors > windows then
             #OUT + "You sure have a lot of doors.\n";
 return doors;
  else
   return windows;
end;
 end;
@end example

@noindent
Entering @kbd{M-C-q} with the point on the line that reads @code{cow:INT
is} would re-indent the code to look like this:

@example
cow:INT is
   #OUT + "Count other windows\n";
   if doors > windows then
      #OUT + "You sure have a lot of doors.\n";
      return doors;
   else
      return windows;
   end;
end;
@end example

This may be done with any Sather block (@pxref{Indentation Functions and
Keys}, for the list of keywords that open a block).

@node Indenting Regions, Indenting S-expressions, Indenting Blocks, Indenting
@section Indenting for Regions
@cindex Indenting, regions
@cindex Regions, indenting

@code{sather-mode} supports indentation for regions of code, created by
using the Emacs ``mark'' (@pxref{Mark, Mark, Mark, emacs, Emacs}).

@kindex M-C-\
@findex indent-region
Regions are indented using the Emacs function, @code{indent-region},
which is bound to @kbd{M-C-\} in most Emacs modes, including
@code{sather-mode}.  This function is enhanced in @code{sather-mode} so
that it provides configurability for comments in the region being
indented (@pxref{Indenting Comments}), and a ``% complete'' progress
indication in the status line for those long indentation tasks.

You can control how often progress updates are given using the variable,
@code{sather-progress-interval}.  If non-@code{nil}, the value must be
an integer indicating the number of seconds between updates.  If the
value is @code{nil}, updates are not given.  The default value is five
(5) seconds.

@node Indenting S-expressions, , Indenting Regions, Indenting
@section Indenting S-expressions
@cindex Indenting, s-expressions
@cindex S-expressions, indenting

@code{sather-mode} also does special indentation for certain types of
Sather expressions, known as s-expressions (from the Lisp world).
S-expressions are formed by matching pairs of things like parentheses.
The following is a list of the characters that open an s-expression, and
the characters that they match.

@table @code
@item (
@code{)}

@item @{
@code{@}}

@item [
@code{]}

@item |
@code{|}@footnote{Note that characters are not meant to match
themselves.  Because of this, @code{|} does not act as nicely as
@code{(} and @code{)} when traversing s-expressions using
@code{forward-sexp} and @code{backward-sexp}.}
@end table

S-expressions are indented so that all the text in them lines up
``under'' the opening of the expression.  Here is an example using
parentheses:

@example
if (a > b
    or (c > d
        and e < f)
    or (g = h))
then
   z := c + d;
end;
@end example

Notice that the first @code{or} lines up under, and one character to the
right of, the first open parenthesis.  Also, the @code{and} lines up
according to the second open parenthesis.  Once the second open
parenthesis is closed, the indentation is again at the level of the
first open parenthesis.  This is intended to clarify the level of
expressions by grouping them according to indentation.

A second example shows how long array declarations are grouped.
Consider the following initialization of the @code{bands} array object:

@example
attr bands:ARRAY@{STR@} := |"TKK", "KMFDM", "Front 242",
                          "Skinny Puppy", "Silkworm",
                          "Biohazard"|;
@end example

Because @code{|} opens an s-expression, the second line of entries for
the array line up just under and to the right of the first @code{|}.
This allows array elements to be more logically grouped (especially for
large arrays of formatted data).

This however, doesn't yet work as nicely for multi-dimensional arrays.
Maybe sometime soon.

@node Hiding and Showing Code, Minor Features, Indenting, Top
@chapter Hiding and Showing Code
@cindex hiding
@cindex showing
@cindex unhiding

Often when you're editing large classes, or just browsing classes to
find out how they work, all you're interested in is the names,
arguments, or return types of the routines in the class (known as the
class ``interface'').  Or maybe you just want to see a list of classes
in a given file.@footnote{If you're doing lots of code browsing, you may
wish to try the Sather Browser, which is designed to facilitate the
understanding of large systems.}

@code{sather-mode} provides a set of functions that can be used to
``hide'' routines and classes so that they are easier to browse or code
because of less clutter (yes, I just called your code ``cluttered'').
The effect of hiding a code segment is that only the first line (or
first few lines) of that segment is displayed.  The rest of the segment
is represented by ellipses (@dots{}).

The following lists the hiding functions, along with the keys to which
they are bound, followed by a description of the function.  The meaning
of these functions should be obvious from the names, so the following
list offers just brief comments.  The term, ``point'' used in the list
refers to the Emacs point, which is basically the location of the cursor
in the active buffer (@pxref{Point, Point, Point, emacs, Point}).

@table @kbd
@item  C-c C-h l
@itemx M-x sather-hide-classes
@kindex C-c C-h l
@findex sather-hide-classes
Hide all the classes in the current file.

@item  C-c C-h c
@itemx M-x sather-hide-current-class
@kindex C-c C-h c
@findex sather-hide-current-class
Hide the class in which the point resides.

@item  C-c C-h s
@itemx M-x sather-hide-current-class-routines
@kindex C-c C-h s
@findex sather-hide-current-class-routines
Hide all the routines of the class in which the point resides.

@item  C-c C-h r
@itemx M-x sather-hide-current-routine
@kindex C-c C-h r
@findex sather-hide-current-routine
Hide the routine in which the point resides.

@item  C-c C-h a
@itemx M-x sather-hide-routines
@kindex C-c C-h a
@findex sather-hide-routines
Hide all the routines in the current buffer.
@end table

The following is an example of hiding a routine in a Sather buffer.
This first code segment lists the routine before hiding:

@example
cow:INT is
   #OUT + "Count other windows\n";
   if doors > windows then
      #OUT + "You sure have a lot of doors.\n";
      return doors;
   else
      return windows;
   end;
end;
@end example

This second segment lists the routine after executing
@code{sather-hide-current-routine}:

@example
cow:INT is...
@end example

Each of the functions in the above list has an opposite ``show''
function, which (you guessed it) unhides things that are hidden.  Here's
the list:

@table @kbd
@item  C-c C-s l
@itemx sather-show-classes
@kindex C-c C-s l
@findex sather-show-classes
Show the full text of all the classes in the current buffer.

@item  C-c C-s c
@itemx M-x sather-show-current-class
@kindex C-c C-s c
@findex sather-show-current-class
Show the full text of the class in which the point resides.

@item  C-c C-s r
@itemx M-x sather-show-current-routine
@kindex C-c C-s r
@findex sather-show-current-routine
Show the full text of the routine in which the point resides.

@item  C-c C-s s
@itemx M-x sather-show-current-class-routines
@kindex C-c C-s s
@findex sather-show-current-class-routines
Show the full text of all the routines of the class in which the point
resides.

@item  C-c C-s a
@itemx M-x sather-show-routines
@kindex C-c C-s a
@findex sather-show-routines
Show the full text of all the routines in the current buffer.

@item  C-c C-s A
@itemx M-x sather-show-all
@kindex C-c C-s A
@findex sather-show-all
Show the full text of the current buffer, without context.  This is
useful for showing @emph{everything} in the current buffer.
@end table

@kindex S-mouse-2
You can also hide things using @kbd{S-mouse-2} (the @key{SFT} key held
down, and then pressing the middle mouse button).  To do this, place the
mouse cursor over the first line of a routine or class name, and press
@kbd{S-mouse-2}.  This should figure out if you are pointing at a class
or a routine, and hide or show it (depending on if it is already
hidden).  This is a much quicker method if you are hiding or showing
several routines our classes at once (or are very good with a mouse).

@node Minor Features, Inserting Code Stubs, Hiding and Showing Code, Top
@chapter Minor Features
@cindex Minor Features

@code{sather-mode} provides a set of capabilities, called ``minor
features'', that enable special ways of treating various keyboard input,
or buffer syntax elements.

Active features are listed on the Emacs mode-line, after the mode name,
by a single character that represents that feature.  When in
@code{sather-mode}, the mode name is ``Sather''.  Active features are
appended to the mode name, with a slash character separating the mode
name from the feature list.  For example, the ``Hungry Delete'' feature
is designated by an ``h''.  If this feature was active, the mode name
would appear as ``Sather/h''.

Here is a list of the minor features currently supported by
@code{sather-mode}.  The first entry is the name of the associated
toggle function.  Next the variable (where applicable) is listed.
Finally, the symbol that represents the feature in the Emacs mode line
is given.  The variables are available for backward compatibility.  It
is recommended that you use the toggle functions, even in
@code{sather-mode-hook}, as the internals of these features may change
in the future.

@table @asis
@item @kbd{M-x sather-toggle-hungry-state}
@itemx @code{sather-hungry-delete-key}
@itemx Symbol: @code{h}
@findex sather-toggle-hungry-state
@vindex sather-hungry-delete-key
If active, this feature causes backward-deleting to consume all
whitespace that precedes point@footnote{This feature (along with several
other parts of @code{sather-mode}) was stolen from @code{cc-mode}, by
Barry Warsaw.}.

This feature is inactive by default.

@item @kbd{M-x sather-toggle-indent-state}
@itemx @code{sather-auto-indent}
@itemx Symbol: @code{i}
@findex sather-toggle-indent-state
@vindex sather-auto-indent
@kindex RET
If active, @kbd{RET} will automatically indent the newly created line,
as long as it's empty and contains the cursor.  That may be tough to grasp without a couple of examples, so here they are:

In the following case, auto-indentation is performed when @kbd{RET} is
entered.  The location of point is indicated by @point{}.

@example
cow:INT is
   #OUT + "Count other windows\n";
   if doors > windows then
      #OUT + "You sure have a lot of doors.\n";@point{}
      return doors;
   else
      return windows;
   end;
end;
@end example

However, in the following case, auto-indentation is @emph{not}
performed when @key{RET} is pressed:

@example
cow:INT is
   #OUT + "Count other windows\n";
   if doors > windows then
      #OUT + "You sure have a lot of doors.\n";
@point{}     return doors;
   else
      return windows;
   end;
end;
@end example

@noindent
This is because point does not reside on the newly created line (or the
newly created line is not empty, depending on your perspective).  It is
still on the line with @code{return doors;}.

This feature is inactive by default.

@item @kbd{M-x sather-toggle-newline-state}
@itemx @code{sather-auto-newline}
@itemx Symbol: @code{n}
@findex sather-toggle-newline-state
@vindex sather-auto-newline
@kindex ;
If this feature is active, newline characters are automatically inserted
when a semi-colon (@kbd{;}) is entered.  Some people like this.

This feature is inactive by default.

@item @kbd{M-x sather-toggle-newline-state}
@itemx @code{sather-newline-prefix-indent}
@itemx Symbol: @code{p}
@findex sather-toggle-newline-state
@vindex sather-newline-prefix-indent
@kindex RET
If this feature is active, when @kbd{RET} is entered, the @emph{current}
line is indented @emph{before} a newline character is inserted and the
point is moved to the next line.

This feature is useful for properly indenting ambiguous (to Emacs)
Sather clauses, like @code{else} and @code{when}, which have no special
syntax to aid their indentation.

This feature is active by default.
@end table

These features may be enabled or disabled in two ways: by setting the
corresponding feature variable to @code{t} or @code{nil}, respectively,
or by using the corresponding ``toggle'' function (which is the
preferred way).

All of the toggle functions may take an argument.  If the argument is
@code{nil} or @code{0}, the feature is toggled.  If the argument is
negative, the feature is turned off (disabled).  If the argument is
positive, the feature is turned on (enabled).

In the following example, auto-indenting and auto-newlines are toggled,
newline prefix indenting is turned on, and the hungry delete key is
turned off.

@example
(sather-toggle-indent-state 0)
(sather-toggle-newline-state nil)
(sather-toggle-prefix-state t)          ;; `t' is Emacsian for `true'.
(sather-toggle-hungry-state -1)
@end example

@node Inserting Code Stubs, Compiling Sather Code, Minor Features, Top
@chapter Inserting Code Stubs
@cindex Stubs
@kindex C-c C-n c
@kindex C-c C-n a

Often when first implementing the classes from a design specification,
many class stubs are inserted.  It is convenient to be able to insert a
stub of these classes so that the real job of implementation may begin.

@code{sather-mode} provides a convenient command for quickly inserting
new class templates.  The command, @code{sather-new-class}, which is
bound to @kbd{C-c C-n c}, prompts for data concerning the class stub to
be inserted.  This data includes the name of the class, the kind of
class it is (i.e., abstract, external, partial, or value), and, if
external, the language interface of the class (e.g., ``C'').

The function converts the name given for the class to upper case, and
adds a @code{$} to the name if the class is declared to be abstract.

A sort-cut function is also provided for entering abstract classes.  The
command, @code{sather-new-abstract-class}, is bound to @kbd{C-c C-n a}.
Only the name of the class is required for this function.

When using either of these functions, the context of the file is
examined.  If the class being inserted is the first in the file, the
function, @code{sather-header}, is executed.  It depends on the values
of @code{sather-short-copyright} and @code{sather-long-copyright}.

@node Compiling Sather Code, Browsing Sather Code, Inserting Code Stubs, Top
@chapter Compiling Sather Code
@cindex Compiling
@kindex C-c C-c

You can compile Sather code in Emacs with @code{sather-mode}, using the
Sather Compiler.  @code{sather-mode} sets the Emacs variable,
@code{compile-command}, to the customizable variable,
@code{sather-compile-command}.  The default value for
@code{sather-compile-command} is @code{"sacomp .module"}.  The value may be
changed in your @code{sather-mode-hook}, or interactively, using the
@kbd{M-x set-variable} command.  @code{sather-mode} binds the Emacs
command, @code{compile}, to @kbd{C-c C-c}.  There are also two compile
menu entries, under the ``Sather'' menu: ``Compile Now!'' and
``Compile''.  The ``Compile'' entry executes the @code{compile} command,
which requires you to press @kbd{RET}, but lets you modify the command
line used to execute the compile.  The ``Compile Now!'' entry executes
the @code{recompile} command, which starts the compile without any
further interaction.

It is often convenient to set the value of @code{compile-command} as an
Emacs file variable (@pxref{Customizing Compilation}).

@node Browsing Sather Code, Commenting Code, Compiling Sather Code, Top
@chapter Browsing Sather Code
@cindex Browsing Sather Code

You can run the Sather Browser from within Emacs using the @kbd{M-x
sather-browse} command, or the @kbd{M-x sather-browse-now} command.
Both of these may be more easily executed using menu entries.

The command line used when executing the browser is controlled with
the @code{sather-browse-command} variable.

It is often convenient to control the value of
@code{sather-browse-command} by using Emacs file variables
(@pxref{Customizing Compilation}).

@node Commenting Code, Highlighting, Browsing Sather Code, Top
@chapter Commenting Code
@cindex Commenting Code

@code{sather-mode} provides several functions that help in providing
in-code documentation.  Mostly, this just means there are neat ways to
insert and adjust comments.  Additional documentation facilities exist
in the @code{sather-lib} lisp library (@pxref{Library Functions}).

@menu
* Inserting Comments::          Inserting new comments into code.
* Indenting Comments::          Indenting new and existing comments.
@end menu

@node Inserting Comments, Indenting Comments, Commenting Code, Commenting Code
@section Inserting Comments
@cindex Inserting Comments

The following is a list of the available comment functions and their key
bindings:

@table @kbd
@c @item M-x sather-header
@c @findex sather-header
@c @vindex sather-site
@c @vindex sather-short-copyright
@c @vindex sather-long-copyright
@c This function inserts a Sather source file header at the location of
@c point.  This function queries the system for the user's name and login
@c name, and uses the configurable variables @code{sather-site},
@c @code{sather-short-copyright}, and @code{sather-long-copyright}.  The
@c RCS targets, ``Id'' and ``Log'' (each surrounded by @code{$}s).
@c
@item M-q
@itemx M-x sather-fill-paragraph
@kindex M-q
@findex sather-fill-paragraph
This function ``fills'' Sather comments so that long lines are broken
up, and spacing is even and regular (similar to the
@code{fill-paragraph} command in Emacs text modes).  It is especially
useful when creating or changing very long comments.

Two variables are available to control filling of comments.

@defvar sather-comment-fill-across-blanks
@vindex sather-comment-fill-across-blanks
If non-@code{nil}, blank comments (comments that consist only of a
comment leader @code{--} followed by whitespace) are absorbed into the
comment.  This means that a comment that looks like this before filling:
@end defvar

@example
-- This is a comment that is
--
-- broken by a blank comment.
@end example

@noindent
would look like this after filling:

@example
-- This is a comment that is broken by a blank comment.
@end example

@noindent
The default value of this variable is @code{nil}.

@defvar sather-comment-fill-break-regexp
@vindex sather-comment-fill-break-regexp
If this variable is non-@code{nil}, it is a regular expression that
defines comment leaders that break comments across lines.
@end defvar

For example, setting the value of this variable to
@code{"^\\s-*--|?\\s-\\s-"} (which matches a comment leader followed by
at least two white-space characters; see @ref{Regexps, Regexps, Syntax
of Regular Expressions, emacs, Regexps}, in the Emacs manual) would
cause the comments in the following code not to be filled:

@example
get_time(zone:TIME_ZONE):TIME
   pre
      ~void(zone)
   -- Calculate the time in the given time zone.
   --  Arg zone is the desired time zone.
   --  Returns the local time specified by argument zone.
is
   ...
end;
@end example

The default value of this variable is @code{nil}.

@item M-;
@itemx M-x sather-comment
@kindex M-;
@findex sather-comment
@vindex sather-comment-col
This command adds a comment to the current line, indenting it according
to context, or indents an existing comment.  If point is within code on
a line, entering @kbd{M-;} inserts a comment leader (@code{-- }, which
includes one character of white-space) at the end of the line, and
places point immediately after it, according to the value of
@code{sather-comment-col} (@pxref{Indenting Comments}).

If the code on the line ends with a Sather @code{end} keyword, the
comment is placed immediately after the @code{end}, separated by a
single space.  This is to allow comments like:

@example
wombat is
   #OUT + "I'm the wombat!";
end; -- wombat
@end example
@end table

When writing long comments, it is often convenient to use a combination
of @code{sather-fill-paragraph} and @code{sather-comment}.  By first
entering @kbd{M-;} to start the comment, and then continuing to type on
the same line, occasionally entering @kbd{M-q}, a full block of
commented text may be easily inserted.

An alternative to this is to simply write the paragraph in a text
editing mode (or even straight into @code{sather-mode}).  You may then
copy the text into the desired Sather source buffer, mark the text as a
region (using Emacs' @code{set-mark-command}), and run @kbd{M-x
comment-region}, which will place the text within Sather comments
(you'll then probably need to enter @kbd{M-q} to fill the paragraph
correctly).

@node Indenting Comments, , Inserting Comments, Commenting Code
@section Indenting Comments
@cindex Indenting Comments

Comments are generally indented at the level of the current block (at
the same level of the code in the same context), like this:

@example
if a < b then
   -- This comment is at the level of the current block.
   #OUT + "`a' < `b'.\n";
end;
@end example

@vindex sather-comment-col
@kindex M-;
If you want to insert a comment at the end of a line of code (using
@kbd{M-;}), the comment is inserted according to the value of
@code{sather-comment-col}, which defaults to 32.  Here's an example:

@example
if a < b then
   #OUT + "`a' < `b'.\n";       -- At `sather-comment-col'.
end;
@end example

@noindent
If the code line contains more characters than the value of
@code{sather-comment-col}, the comment will come out like this:

@example
if a < b then
   #OUT + "`a' is less than `b'.\n"; -- At > `sather-comment-col'.
end;
@end example

@vindex sather-keep-left-comments
If a comment is in the first column, you can tell Sather mode that you
intend for it to stay there, no matter what the block context, by
setting the value of @code{sather-keep-left-comments} to @code{t} (the
default is @code{nil}).

@vindex sather-indent-design-comments-correctly
By convention, comments in a class or routine ``design region'' are
indented at the same level as comments inside the class or routine,
respectively, even though they are not actually in the body (which
begins with the keyword, @code{is}).  For example, the following shows a
class and routine with comments in the respective design regions:

@example
class WAR
   -- This is in the class's design region.
is
   hell:BOOL
      -- This is in the routine's design region.
   is
      return #FIRE.is_firing and #BRIMSTONE.is_brimming;
   end;
end;
@end example

@noindent
However, this functionality is turned off by default because it
significantly slows indentation@footnote{Indenting the Sather Compiler
module, @file{cgen.sa} was used to test the difference in indentation
times.  This file was around 3,400 lines at the time of the test.  With
design comment indentation turned off, this file indented in around
00:03:20.  With design comment indentation turned on, the indentation
took around 00:22:00.  If anyone would like to improve the method,
please do!}.  You can turn it on by setting the variable,
@code{sather-indent-design-comments-correctly} to @code{t}.

@findex indent-region
Another variable controls how comments are indented when indenting a
region of code using @kbd{M-x indent-region}, or @kbd{M-x
sather-indent-block}.  This variable is
@code{sather-indent-comments-with-region}.  If non-@code{nil} (the
default), comments are indented with the region being indented.  This is
sometimes not desirable when you intentionally have comments formatted
in an unconventional manner.  In these cases, set
@code{sather-indent-comments-with-region} to @code{nil}, and these
comments will be left alone by these functions.

@node Highlighting, Editing Module Files, Commenting Code, Top
@chapter Highlighting
@cindex Highlighting

@code{sather-mode} supports syntax highlighting using the three most
popular highlighting packages: @code{hilit19}, @code{hl319}, and
@code{font-lock}.

If you are using GNU Emacs 19.28 or earlier, it is recommended that you
use @code{hl319}.  If you are using GNU Emacs 19.29 or later, it is
recommended that you convert to @code{font-lock}, no matter what you are
currently using@footnote{@code{font-lock} appears to be the future of
syntax highlighting for both GNU Emacs and GNU XEmacs.  @code{font-lock}
is not as fast as hl319, but it has some built-in support, will have
more in the future, and has the advantage of being an Emacs Minor
Mode.}.  @code{hilit19} is not recommended because @code{hl319} is the
newer, faster, and more configurable version of that package.  It also
supports highlight on the fly (while you are typing), like
@code{font-lock}, and currently comes with @code{sather-mode}.

If you are using XEmacs, use @code{font-lock}, because it is the
de facto standard for that editor, and has a lot of built-in support.

But everyone has their preference, so @code{sather-mode} will support
all three until there is a clear standard (which will likely be
@code{font-lock}).

In order to determine what sort of highlighting package you prefer,
@code{sather-mode} examines the environment in which it is started, and
uses the package it finds first.  The order of the search is
@code{hl319}, @code{hilit19}, and then @code{font-lock}.  So if you have
@code{hilit19} loaded, @code{sather-mode} will use patterns for that
package.  This means that you must have your highlighting package loaded
before invoking @code{sather-mode}.  The easiest way to do this is to
@code{require} it in your initialization file.  For example:

@example
(require 'font-lock)
@end example

@node Editing Module Files, Library Functions, Highlighting, Top
@chapter Editing Module Files
@cindex Editing Module Files

@findex sather-module-mode
There is a special mode for editing Sather Module files.  These are
generally files that end in @file{.module}, or @file{.pmodule}.  This
mode is called @code{sather-module-mode}, and has special features for
coding and developing Sather Module files.

@code{sather-module-mode} supports standard Sather-ish comments
(@code{--}) for inserting or filling, using @kbd{M-q} or @kbd{M-;},
respectively.  Sather Module block comments (@code{(* ... *)}) can be
used, but they cannot be filled like @code{--} comments@footnote{This is
due to the fact that Emacs can't handle two different comment syntaxes
that start with different characters.  C++ can be handled because both
comment syntaxes begin with @code{/}.}

You can also compile and browse within @code{sather-module-mode} using
the same keys as in @code{sather-mode}.  Here's a list of all the key
mappings available in @code{sather-module-mode}:

@table @kbd
@item C-c C-b m
@itemx M-x sather-module-mode-submit-bug-report
Submit a bug report on, or make comments about,
@code{sather-module-mode}.
@findex sather-module-mode-submit-bug-report
@kindex C-c C-b m

@item C-c C-c
@itemx M-x compile
Launch the Sather compiler with the current module as default input, but
wait for confirmation.
@findex compile
@kindex C-c C-c

@item C-c C-r
@itemx M-x recompile
Launch the Sather compiler with the default arguments, not waiting for
confirmation.
@findex recompile
@kindex C-c C-r

@item C-c C-k
@itemx M-x kill-compilation
Kill the current compilation process.
@findex kill-compilation
@kindex C-c C-k

@item M-q
@itemx M-x sather-fill-paragraph
Fill the current @code{--}-commented paragraph.
@findex sather-fill-paragraph
@kindex M-q

@item M-;
@itemx M-x sather-comment
Enter a new @code{--}-comment, or reindent the existing comment.
@findex sather-comment
@kindex M-;
@end table

@node Library Functions, Customization, Editing Module Files, Top
@chapter Library Functions
@cindex Library Functions

The Sather Emacs Lisp Library, @code{sather-lib}, contains sundry useful
functions that help developers programming in Sather.  There is really
no logical grouping to these functions, so the following list documents
their uses:

@itemize @bullet
@item @code{doc-modification}
Insert a brief modification log at the beginning of the buffer.  It
looks for the RCS log header, ``$Log'', and inserts the entry there.

@item @code{uncomment-region}
Works like @code{comment-region}, but does the opposite.  It doesn't
work well for me in languages that don't use line-comments (like ``C''),
but it works great with Sather comments.

@item @code{sather-hide-active-region}
``Hide'' the active region.  This allows hiding on code segments that
cross class and routine boundaries, or are not defined by such boundaries.

@item @code{sather-show-active-region}
The same, but opposite.

@item @code{sather-create-stubs}
This function creates stub routines from an abstract type definition.

@item @code{sather-server-buffer-undone}
This is not a command, but a useful function for interacting with the
Sather Browser.  It can be used to tell Emacs to free clients waiting on
Sather files, so there are not dozens of @file{emacsclient}s hogging
your system.  An example of setting this up is in @file{sample.emacs},
which is part of the Emacs portion of the Sather
distribution.@footnote{Hopefully a future version of @file{emacsclient}
will be more flexible, like @file{gnuserv}.  @file{gnuserv} is available
from various ftp sites.  Try
@file{ftp://elisp-archive.ohio-state.edu:/pub/}.}
@end itemize

@node Customization, Bugs and Comments, Library Functions, Top
@chapter Customization
@cindex Customization

When @code{sather-mode} is run for a loaded file, the last thing it runs
is the function in @code{sather-mode-hook}.  This is intended for user
customizations (e.g. indenting, etc.), and goes into an initialization
file, just like the code for loading @code{sather-mode},
(@pxref{Getting Started}).  Here's an example of what might go into a
@code{sather-mode-hook}:

@example
(setq sather-mode-hook
      '(lambda ()
         (require 'sather-lib)
         (local-set-key [backspace] 'sather-electric-delete)
         (setq sather-delete-function 'backward-delete-char)
         (local-set-key [M-S-right] 'sather-forward-sexp)
         (sather-toggle-indent-state 1)
         (setq tab-width 8)
         (modify-syntax-entry ?_ "w")
         (modify-syntax-entry ?! "w")
         (modify-syntax-entry ?# "w")
         (modify-syntax-entry ?$ "w")
         ))
@end example

This example does the following things:

@enumerate
@item
Loads the @code{sather-lib} library package.

@item
@kindex BS
Binds the @key{BS} (often called ``Back Space'') key to
@code{sather-electric-delete}, the special deletion function.

@item
Sets @code{sather-delete-function} to @code{backward-delete-char}.  This
is the function @code{sather-electric-delete} calls to do the actual
deleting.  The default value of @code{sather-delete-function} is
@code{backward-delete-char-untabify}.

@item
@kindex M-S-right
Binds the @kbd{M-S-right} key to the command,
@code{sather-forward-sexp}, which moves the point from an opening clause
to its matching @code{end}.  This binding may not be available for some
systems.

@item
Turns on the auto-indentation feature for automatically indenting new,
blank lines.

@item
Sets the @code{tab-width} variable to 8, so that the tab character is
represented as eight spaces.

@item
Modifies the way Emacs thinks of the @code{_}, @code{!}, @code{#}, and
@code{$} characters.  Generally, Emacs considers these characters to be
punctuation.  However, in Sather it is convenient to think of them as
parts of words.  Also, @code{sather-mode} works better if you tell Emacs
to treat them as word constituents.
@end enumerate

How to customize specific areas is explained in the following sections.

@menu
* Customizing Indentation::
* Customizing Minor Features::
* Customizing Compilation::
* Customizing Highlighting::
@end menu

@node Customizing Indentation, Customizing Minor Features, Customization, Customization
@section Customizing Indentation
@cindex Indentation
@cindex Customizing Indentation

Indentation is easily customized by setting the @code{sather-mode}
indentation variables in @code{sather-mode-hook}, or interactively, via
the @kbd{M-x set-variable} Emacs command.

For example, placing the following lines in the body of your
@code{sather-mode-hook} sets the default indentation to 4 spaces, and
the continued line indentation to 1 space:

@example
(setq sather-indent 4)
(setq sather-continued-line-indent 1)
@end example

@node Customizing Minor Features, Customizing Compilation, Customizing Indentation, Customization
@section Customizing Minor Features
@cindex Minor Features, Customizing

Minor features are just as easy to customize.  You may turn minor
features on or off by placing a call to the appropriate toggle function
in your @code{sather-mode-hook}.  @xref{Minor Features} for the list of
toggle functions.

The following example shows how one would turn off the newline prefix
indent feature, and turn on the hungry delete feature.

@example
(sather-toggle-prefix-state -1)
(sather-toggle-hungry-state 1)
@end example

With the toggle functions, a value of 0 or @code{nil} toggles the state
of the function (if it is off, it is turned on, and vise versa).  Values
less than 0 turn the feature off; values greater than 0 turn the
feature on.

If you call the function interactively with no arguments, it is like
calling it with @code{nil}.  This is convenient if you are just trying
things out and what to toggle them while you are editing.  To do that,
you can just enter something like @kbd{M-x sather-toggle-hungry-state}.

@node Customizing Compilation, Customizing Highlighting, Customizing Minor Features, Customization
@section Customizing Compilation
@cindex Compilation, Customizing

There are several ways to customize the command @code{sather-mode} uses
to compile code when you execute one of the compilation functions.  The
simplest way is to set the @code{sather-compile-command} variable.  You
may do this in your @code{sather-mode-hook} as follows:

@example
(setq sather-compile-command "sacomp bovine.module")
@end example

This sets the default for @code{compile-command} for all Sather buffers.
This is convenient if you have a standard way of compiling Sather files
at your site.

However, it is often convenient to have a different compile command,
depending on the file you are editing.  In these cases, it is best to
use Emacs file variables.  Using file variables, you can set variables
for each file you visit, automatically.  Here is an example of a local
variable list which sets @code{compile-command} and
@code{sather-browse-command}:

@example
^L
-- Local Variables: 
-- compile-command: "sacomp bovine.module"
-- sather-browse-command "sabrowse bovine.module"
-- End:
@end example

(Note that we don't set @code{sather-compile-command}.  The
@code{sather-compile-command} variable is used to default
@code{compile-command} for Sather buffers---it is not actually used for
compiling code.)

@kindex C-q C-l
You should put these lines at the end of the file, with the form-feed
character right before the list.  You can enter a form-feed into your
buffer with @kbd{C-q C-l}.  @ref{File Variables, File Variables, File
Variables, emacs, Local Variables in Files}, for a discussion of local
variable lists.

You can set almost any variable you want in a local variables list, but
things like @code{sather-indent} should probably not be in the list, as
this would change that value for other buffers as well (which could be
most frustrating for other users editing the file).

@node Customizing Highlighting, , Customizing Compilation, Customization
@section Customizing Highlighting
@cindex Highlighting, customizing

Currently, @code{sather-mode} supports customization of only
@code{hl319} and @code{font-lock}.  Methods for customizing these two
packages are in the two following sections.

@menu
* Customizing hl319::           Customizing use of the hl319 package.
* Customizing font-lock::       Customizing use of the font-lock package.
@end menu

@node Customizing hl319, Customizing font-lock, Customizing Highlighting, Customizing Highlighting
@subsection Customizing @code{hl319}
@cindex @code{hl319}, customizing

The @code{hl319} package is customized by creating a ``user face
table'', and listing the names of the patterns you wish to customize,
then the value you wish to use for those patterns.

Here is an example of setting up @code{hl319} for use with
@code{sather-mode}:

@example
(cond (window-system
       (add-hook 'find-file-hooks 'hilit-install-line-hooks)
       (setq hilit-background-mode   'dark)
       (setq hilit-user-face-table
             ;; face         light           dark                 mono
             '((comment      nil             white-italic         nil)
               (defun        nil             cyan-bold            nil)
               (type         nil             yellow-bold          nil)
               (keyword      nil             white                nil)
               (string       nil             orange-medium        nil)
               ;; Extras for Sather.
               (constant     nil             cyan                 nil)
               (iterator     nil             green-bold           nil)
               (sugar        nil             nil                  nil)
               (builtin      nil             white-bold           nil)
               (exception    nil             Plum1                nil)
       (require 'hl319)
       (setq hilit-mode-enable-list '(not text-mode))
       ))
@end example

This example enables use for a ``dark'' (value, @code{'dark}) background
(use the value @code{'light}, if you use a light color on your
background, like white).  The values listed under the column labeled
``dark'' take effect if you set @code{hilit-background-mode 'dark}.  You
should read the header comments at the beginning of @file{hl319.el} for
details.

The above code also installs ``line hooks'' into @code{find-file-hooks}.
This enables highlight on the fly.  Some slower systems may not want to
use this hook.

Notice that the value of @code{sugar} is set to @code{nil}.  This means
that code that matches that pattern will not be highlighted.  This
speeds up highlighting some.

@node Customizing font-lock, , Customizing hl319, Customizing Highlighting
@subsection Customizing @code{font-lock}
@cindex font-lock, customizing

Highlighting with @code{font-lock} may be customized by associating
colors and face attributes with @code{font-lock} face variables (see the
@code{font-lock} documentation in the Emacs manual for a list of these
variables).

@code{sather-mode} adds some extra variables for a greater variety of
customization (but only for GNU Emacs 19.29 and later).  The following
shows how one might configure @code{font-lock} for Sather buffers:

@example
(cond (window-system

       ;; Add an automatic fontification for every buffer visited.
       (if (> emacs-minor-version 28)
           (add-hook 'find-file-hooks 'turn-on-font-lock))

       (setq font-lock-display-type 'color)
       (setq font-lock-background-mode 'dark)
       (setq font-lock-maximum-decoration t)
       (setq font-lock-face-attributes
             '((font-lock-comment-face "White" nil nil t nil)
               (font-lock-string-face "Orange" nil nil nil nil)
               (font-lock-keyword-face "White" nil nil nil nil)
               (font-lock-type-face nil nil t nil nil)
               (font-lock-function-name-face "Cyan" nil t nil nil)
               (font-lock-variable-name-face nil nil nil nil nil)
               (font-lock-reference-face "Plum1" nil nil nil nil)

               ;; Extras for Sather.
               (font-lock-builtin-face "White" nil t nil nil)
               (font-lock-constant-face "Cyan" nil nil nil nil)
               (font-lock-exception-face "Orange" nil nil nil nil)
               (font-lock-iterator-face "Green" nil t nil nil)
               (font-lock-sugar-face nil nil nil nil nil)
               ))
       (require 'font-lock)
       ))
@end example

By setting all the values of a face to @code{nil}, that face is
effectively ``turned off'', as for @code{font-lock-sugar-face} above.

The faces listed after the ``Extras for Sather'' comment will only take
effect for GNU Emacs 19.29 and later versions, and then only if the
value of @code{font-lock-maximum-decoration} is non-@code{nil}.

@node Bugs and Comments, Key Index, Customization, Top
@chapter Bugs and Comments
@cindex Bugs and Comments

@code{sather-mode} provides functions for automated bug reports.  You
can use the menu entries under the ``Send Bug Report'' under the
``Sather'' menu, or the following commands:

@table @kbd
@item  C-c C-b m
@itemx M-x sather-mode-submit-bug-report
@kindex C-c C-b m
@findex sather-mode-submit-bug-report
Submit a bug report or send comments for @code{sather-mode}.  Please
describe what you did to cause the problem, and what the problem is.  A
small amount of code that duplicates the problem is helpful.

@item  C-c C-b c
@itemx M-x sather-compiler-submit-bug-report
@kindex C-c C-b c
@findex sather-compiler-submit-bug-report
Submit a bug report or send comments for the Sather Compiler.  Please
include the version of the compiler you are using, and a description of
the problem.  Again, a small amount of code that duplicates the problem
is helpful.
@end table

Comments for either @code{sather-mode} or the Sather Compiler are
submitted in the same manner as bug reports.

If you make useful changes to @code{sather-mode}, please send a report
so that others may benefit from your ingenuity.

If you have ideas for improvement, please send a report.
@code{sather-mode} becomes more useful for everyone when good ideas are
contributed and incorporated into the distribution.

@node Key Index, Function Index, Bugs and Comments, Top
@chapter Key Index
@printindex ky

@node Function Index, Variable Index, Key Index, Top
@chapter Function Index
@printindex fn

@node Variable Index, Concept Index, Function Index, Top
@chapter Variable Index
@printindex vr

@node Concept Index, , Variable Index, Top
@chapter Concept Index
@printindex cp

@summarycontents

@contents
@bye
@c  LocalWords:  sather cindex RET emph defvar findex xref kbd
