reduce-ide.texinfo

\input texinfo
@c %**start of header
@settitle GNU Emacs REDUCE Integrated Development Environment
@c Manual last updated:
@set UPDATED Time-stamp: <2024-12-16 15:18:12 franc>
@c Software version:
@set VERSION 1.13
@afourpaper
@c With different size paper the printed page breaks will need attention!
@c Look for @page and @need commands.
@setchapternewpage off
@paragraphindent 3
@c %**end of header

@dircategory GNU Emacs Lisp
@direntry
* REDUCE IDE: (reduce-ide).     REDUCE Integrated Development Environment.
@end direntry

@copying
This manual is for REDUCE IDE (version @value{VERSION}, updated
@value{UPDATED}), which provides GNU Emacs major modes for editing and
running REDUCE source code.

Copyright @copyright{} 1994, 1996, 1999, 2012, 2017-2018, 2022-2024 Francis J. Wright

@quotation
This manual and the software that it describes are subject to the GNU
General Public License that is distributed with GNU Emacs -- see the
file @file{COPYING}.

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 a 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 and 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 above conditions for modified
versions.
@end quotation
@end copying

@titlepage
@title GNU Emacs REDUCE IDE
@subtitle An Integrated Development Environment for REDUCE:
@subtitle Major modes for editing and running REDUCE source code
@subtitle Software version @value{VERSION}
@author @uref{https://sites.google.com/site/fjwcentaur, Francis J. Wright}
Manual last updated @value{UPDATED}

@c The following two commands start the copyright page.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@c Output the table of contents at the beginning.
@contents

@c ===================================================================

@ifnottex
@node Top, Introduction, (dir), (dir)
@top REDUCE Integrated Development Environment

@display
This manual is for REDUCE IDE, version @value{VERSION}.
GNU Emacs major modes for editing and running REDUCE source code
@uref{https://sites.google.com/site/fjwcentaur, Francis J. Wright}
Manual last updated @value{UPDATED}
@end display
@end ifnottex

@menu
* Introduction::                What is REDUCE IDE?
* Installation::                How to install REDUCE IDE
* General::                     General features of REDUCE mode
* Statements::                  Commands that operate on statements
* Procedures::                  Commands that operate on procedures
* Comments::                    Support for REDUCE comments
* Indentation::                 Commands for automatic indentation
* Structures::                  Structure templates
* Completion::                  Completion and expansion of REDUCE keywords
* Font-Lock::                   Font selection for syntactic highlighting
* Information::                 Procedure, operator and variable information
* Running::                     Running REDUCE in an Emacs window
* Miscellaneous::               Miscellaneous features
* Customization::               Options that control REDUCE IDE
* Feedback::                    Bug reports, suggestions, comments, @dots{}
* Command Index::               Index of REDUCE IDE commands
* Variable Index::              Index of REDUCE IDE configuration variables
* Keystroke Index::             Index of REDUCE IDE keystrokes
* Concept Index::               Index of general REDUCE IDE concepts
@end menu

@c ===================================================================

@node Introduction, Installation, Top, Top
@chapter Introduction to REDUCE IDE
@cindex Introduction to REDUCE IDE

This manual documents the GNU Emacs Integrated Development Environment
(IDE) for REDUCE, which comprises a primary major mode for
syntax-directed editing of REDUCE source code (REDUCE mode) and a
subsidiary major mode for running REDUCE as an inferior process with
input and output via a buffer (REDUCE Run mode).  REDUCE is a system
and language for algebraic computing developed originally by Anthony
C. Hearn, which is now Open Source and available from
@uref{https://sourceforge.net/projects/reduce-algebra/, SourceForge}.
It therefore shares the GNU spirit of collaborative software
development, which provided part of my motivation to begin this
project.  Also, REDUCE is written in Lisp, as is (most of) Emacs.
However, the REDUCE user language is similar to
@uref{https://en.wikipedia.org/wiki/ALGOL_60, Algol 60}, an ancestor
of most current programming languages.

I began development of REDUCE mode tentatively in late 1992 and
seriously in early 1994, and I began adding REDUCE Run mode in late
1998.  I have continued development sporadically.  Comments,
suggestions, bug reports, etc.@: are welcome; @ref{Feedback}.

REDUCE IDE is released as an Emacs package; @ref{Installation,,
Installation of REDUCE IDE}.  The latest development source code
(which may not work!)@: is available from
@uref{https://github.com/fjwright/REDUCE-IDE, GitHub}, where package
release versions are tagged (e.g.@: @code{v1.7}) and are available as
releases (e.g.@: @code{reduce-ide-1.7.tar}).  The source code (only)
for the latest package release is also available from
@uref{https://sourceforge.net/p/reduce-algebra/code/HEAD/tree/trunk/generic/emacs/,
SourceForge}.

The current version of REDUCE IDE is intended for use with GNU Emacs
version 29 or later, which I will endeavour to support under recent
versions of Microsoft Windows and Linux.  It should also run on other
platforms, but I may not be able to provide support.

This manual assumes that you are familiar in general with both Emacs
and REDUCE.

The purpose of REDUCE mode is to provide editing commands that are
aware of the syntax of the REDUCE language, and therefore allow
operations to be performed on the major syntactic elements, namely
statements, procedures and comments.  To the reader who has never used
a syntax-directed editor, I can only say that it is surprisingly
useful!  In particular, the automatic indentation code provides
valuable clues to potential REDUCE programming errors by showing how
the REDUCE parser is likely to interpret the code; @ref{Indentation,,
Indenting REDUCE code automatically}.

The purpose of REDUCE Run mode is to provide a friendly interface to a
@strong{command-line version} of REDUCE running as an inferior process
in an Emacs buffer.  REDUCE Run mode inherits much of its
functionality from REDUCE mode and cannot be run alone.  The
assumption is that normal use will involve editing one or more REDUCE
source files and running REDUCE simultaneously, and this is what
REDUCE Run mode aims to support.  REDUCE Run mode is described in its
own chapter; @ref{Running, Running REDUCE in a buffer}.

@kindex C-h m
@findex describe-mode
All REDUCE IDE commands are self-documenting as usual in Emacs,
including in particular the modes themselves.  Hence, for an overview
of REDUCE mode, select it in some buffer and then give the command
@kbd{C-h m} (@code{describe-mode}) or use the @kbd{Help} menu option
@kbd{Describe}.

@c ===================================================================

@node Installation, General, Introduction, Top
@chapter Installation of REDUCE IDE
@cindex Installation of REDUCE IDE

I recommend that you use the GNU Emacs package manager to install the
latest REDUCE IDE package as described in the
@uref{https://reduce-algebra.sourceforge.io/reduce-ide/#installation,
installation section of the main REDUCE IDE web page}.  Alternatively,
releases as Emacs package (@code{.tar}) files are available from
@uref{https://github.com/fjwright/REDUCE-IDE/releases, GitHub} and via
the @uref{https://reduce-algebra.sourceforge.io/reduce-ide/, REDUCE
IDE home page}.  You can download a package file to any convenient
directory and run the Emacs command @kbd{M-x package-install-file} on
it.  For further details, @ref{Packages,,, emacs}.  None of the manual
installation described below is then required.

The rest of this chapter, and the related section of the chapter on
REDUCE Run mode, are for users who want to install and configure
REDUCE IDE ``by hand'', or who want to understand the installation
process.

REDUCE mode is provided by files called @file{reduce-mode.el},
@file{reduce-delim.el} and @file{reduce-font-lock.el}, which are files
of Emacs Lisp source code.  These files should be byte-compiled, and
the compiled (@file{.elc}) files installed in a directory from which
Emacs loads its Lisp code.  If necessary, you can customize your Emacs
@code{load-path} so that Emacs can find the @file{.elc} files;
@ref{Customization,,,emacs, The Emacs Editor}.

Emacs initialization and customization is stored in a file that is
normally called @file{.emacs} and lives in your home directory.  The
precise meaning of ``home directory'' depends on both your operating
system and Emacs version; the easiest way to find it in Emacs is to
visit the directory @file{~}, or just visit the file @file{~/.emacs}
directly.  Your @file{.emacs} file is updated automatically by the
Emacs customization facility and you can also edit it by hand to add
other configuration.  @xref{Init File,,,emacs,The Emacs Editor}.

@findex load-library
Before REDUCE mode can be used, the file @file{reduce-mode.elc} must
be loaded.  (It will then normally load @file{reduce-delim.elc} and
@file{reduce-font-lock.elc} automatically.)  This is necessary only
once per Emacs session.  It can be loaded explicitly, most easily by
giving the command @kbd{M-x load-library reduce-mode}.  However, you
will probably want @file{reduce-mode.elc} to be loaded automatically
the first time you (explicitly or implicitly) turn on REDUCE mode.
The way to do this is to put the following statement into your
@file{.emacs} file:

@findex autoload
@lisp
(autoload 'reduce-mode "reduce-mode"
          "Major mode for REDUCE code editing" t)
@end lisp

This statement is completely innocuous and will have no effect unless
you select REDUCE mode.  It could therefore quite safely be put in a
system-wide configuration file (e.g.@: @file{default.el} or
@file{site-start.el}).  @xref{Init File,,,emacs,The Emacs Editor}.

It is also very convenient to have REDUCE mode turned on automatically
when editing a REDUCE source code file.  This can be done based on the
``extension'' of the filename.  Provided you end all REDUCE source code
file names with the standard extension @file{.red}, the following
statement in your @file{.emacs} file will have the desired effect:

@vindex auto-mode-alist
@lisp
(add-to-list 'auto-mode-alist '("\\.red\\'" . reduce-mode))
@end lisp

You can use other extensions as well or instead; if you use a different
file naming convention then make the appropriate change(s) to the above
statement.  Emacs also provides other facilities that can be used for
controlling major modes.

Installation of REDUCE Run mode is documented separately; @ref{Running,,
Running REDUCE in a buffer}.

@c ===================================================================

@node General, Statements, Installation, Top
@chapter General features of REDUCE mode
@cindex General features
@cindex Features

@findex reduce-mode
REDUCE mode can be selected by giving the command @kbd{M-x
reduce-mode}, although normally it will be selected automatically,
probably via the filename extension; @ref{Installation,, Installation
of the REDUCE IDE}.  REDUCE mode inherits from @code{prog-mode} and so
shares some basic functionality common to all Emacs programming modes.

The commands provided by REDUCE mode are aware of REDUCE syntax and
ignore the contents of strings and the case of characters.  Except for
the special comment commands, they also ignore comments;
@ref{Comments,, Support for REDUCE comments}.  The standard GNU Emacs
indentation (@pxref{Indentation,, Indenting REDUCE code
automatically}) and comment commands are supported, either via the
general Emacs mechanisms or by re-binding the standard keys to REDUCE
mode versions of standard commands.  The design of this mode is
modelled primarily on Lisp mode and the %-comment conventions
basically follow those of Lisp mode.  I have also taken some ideas
from FORTRAN mode.

The standard Emacs syntax tables are modified to reflect REDUCE syntax
so that, for example, Emacs knows that the REDUCE escape character is
@code{!}.

Blank lines separate ``paragraphs''.

Loading the REDUCE mode library runs any functions on
@code{reduce-mode-load-hook}, which can be used to customize global
features of REDUCE mode such as its key map.  Entry to REDUCE mode
runs any functions on @code{prog-mode-hook} and then any functions on
@code{reduce-mode-hook}, which can be used to customize buffer-local
features of REDUCE mode, e.g.@: to turn on font-lock mode.
@xref{Installation,, Installation of the REDUCE IDE}.
@xref{Customization,, Options that control REDUCE IDE}.

REDUCE mode is intended to support both the algebraic and symbolic modes
of REDUCE@.  It provides very limited support for Lisp syntax to the
extent that it is likely to be used in symbolic-mode code, and hence it
understands the significance of the quote symbol (@code{'}) to some
extent.  Syntax-directed editing naturally works correctly only if the
syntax of the source code being edited is correct.  If it is not then
strange things can happen, and the services of the Emacs undo facilities
may be required!

@c @table @kbd
@c @item  <backspace>
@c @kindex <backspace>
@c @itemx M-x backward-delete-char-untabify
@c @findex backward-delete-char-untabify
@c Delete one character backwards, converting tabs to spaces if necessary.
@c @end table

A major mode menu provides convenient access to most of the major
facilities of REDUCE mode.

@c ===================================================================

@node Statements, Procedures, General, Top
@chapter Statement-oriented commands
@cindex Statements
@cindex Operations on Statements

The most basic facility provided by REDUCE mode is the ability to move
forwards and backwards by statements or expressions through a file of
REDUCE source code.  Moving by one statement means moving to the
beginning or end of the @emph{logical} statement currently containing
(or respectively preceding or following) point, which may involve
skipping many actual statements that are contained within the current
statement.  In particular, as REDUCE mode looks for the beginning or
end of a statement it will skip complete compound or block statements
(@code{begin @dots{}  end}), group statements (@code{<< @dots{} >>}),
and bracketed expressions (@code{(@dots{})}, @code{@{@dots{}@}} and
@code{[@dots{}]}, although square brackets are not normally used in
REDUCE)@.  Bracket skipping is controlled entirely by the Emacs syntax
table.

Hence, ``statement'' in this manual will normally mean a complete
@emph{logical statement}.  A syntax-directed editor clearly must perform
a limited amount of parsing, but it must be remembered that a
syntax-directed editor has the following important differences from a
normal parser, because their basic purposes are different:

@itemize @bullet
@item
A syntax-directed editor must be able to parse both forwards @emph{and
backwards}.

@item
It will typically parse only locally for speed and must therefore parse
based on incomplete information.

@item
It is provided for the convenience of the user and therefore need not
obey precisely the full syntax of the language, provided it is
consistent and reliable.
@end itemize

In particular, the REDUCE-mode movement commands may fail if point is
within a comment or string, although they should skip complete
comments and strings.

REDUCE mode considers REDUCE statements to be terminated by either of
the characters @code{;} or @code{$}.  It also considers statements
contained within any kind of brackets to be delimited by those
brackets, statements within compound or block statements (@code{begin
@dots{} end}) to be delimited by the @code{begin} and @code{end}
keywords, and statements within group statements (@code{<< @dots{}
>>}) to be delimited by the @code{<<} and @code{>>} tokens.  Commas
are not considered to delimited statements.

More precisely, a statement is considered to begin at the first
non-white-space character following the previous statement terminator,
opening bracket, @code{begin} or @code{<<}.  It is considered to end
immediately after the first statement terminator or immediately after
the last non-white-space character preceding a closing bracket,
@code{end} or @code{>>}.  Comments are treated as white space by all
REDUCE-mode commands other than those specifically related to
comments; @ref{Comments,, Support for REDUCE comments}.

The current philosophy of REDUCE mode is that the statements within a
compound or group statement form an essentially isolated system, and
that the basic statement-oriented commands should not move point
either into or out of this system, for which separate commands are
provided.  However, if you try hard enough, REDUCE mode will let a
simple statement-oriented command move out of (but never into) a
compound or group statement.  Trying hard enough means repeating the
same command enough times, which is determined by the value of the
option @code{reduce-max-escape-tries}, which currently has the default
value 2; @ref{Customization,, Options that control REDUCE IDE}.  The
overall effect of this is to enforce a brief pause (one ineffective
command execution) that serves to prevent you from skipping out of a
compound or group statement accidentally, but without causing any
serious inconvenience.

The following commands all accept a numerical argument, which defaults
to 1.  The commands to move forwards or backwards by statements do not
move in the opposite direction if given a negative argument, in which
case they do not move at all.  They contain special code to handle the
keyword @code{end} followed by a terminator when used as the
end-of-file marker, provided it appears at the start of a line
(optionally preceded by a terminator but no space), and they do not
regard comment statements as statements, i.e.@: they treat them as
white space.  They report a user error if they fail.

@table @kbd
@item C-c C-n
@kindex C-c C-n
@itemx M-x reduce-forward-statement
@findex reduce-forward-statement
Move forwards to the end of the current statement if within a
statement or to the end of the following statement otherwise.  With an
argument, do it that many times.  If looking at the end of a block or
group, or the end-of-file marker, move over it after
@code{reduce-max-escape-tries} consecutive interactive tries.

@item C-c C-p
@kindex C-c C-p
@itemx M-x reduce-backward-statement
@findex reduce-backward-statement
Move backwards to the start of the current statement if within a
statement or to the start of the previous statement otherwise.  With
an argument, do it that many times.  If looking at the beginning of a
block or group move over it after @code{reduce-max-escape-tries}
consecutive interactive tries.  The end-of-file marker is treated as a
statement.

@item C-c C-k
@kindex C-c C-k
@itemx M-x reduce-kill-statement
@findex reduce-kill-statement
Kill the rest of the current statement from point.  With a prefix
argument, kill that many statements from point.  Negative arguments
kill statements backwards, where the prefix argument minus (-) is
equivalent to -1.

@item C-c C-u
@kindex C-c C-u
@itemx M-x reduce-up-block-or-group
@findex reduce-up-block-or-group
Move backwards up one level of block or group, i.e.@: to the beginning
of the @code{begin} or @code{<<} at the start of the block or group
containing point.  A universal argument means move forwards, i.e.@: to
the end of the @code{end} or @code{>>} at the end of the block or
group containing point.  Report a user error if the move fails.  With
a numeric argument, do it that many times, where a negative argument
means move forwards instead of backwards.

@item C-c C-d
@kindex C-c C-d
@itemx M-x reduce-down-block-or-group
@findex reduce-down-block-or-group
Move forwards down one level of block or group, i.e.@: to the end of
the nearest @code{begin} or @code{<<} within the current block or
group, if any.  A universal argument means move backwards to the
beginning of the nearest @code{end} or @code{>>} within the current
block or group, if any.  Report a user error if the move fails.  With
a numeric argument, do it that many times, where a negative argument
means move backwards instead of forwards.
@end table

The following two commands move by ``balanced expression'', which
means a symbol, string, bracketed expression, block or group.  A
symbol or bracketed expression may be quoted.  The commands skip any
preceding or intervening white space or terminator characters, but
assume point is not in a string or comment.

@table @kbd
@item C-M-f
@kindex C-M-f
@itemx M-x reduce-forward-sexp
@findex reduce-forward-sexp
Move forwards across one ``balanced expression''.  With a numeric
argument, move that many times, where a negative argument means move
backwards instead of forwards.  This command is modelled on
@code{forward-sexp}.

@item C-M-b
@kindex C-M-b
@itemx M-x reduce-backward-sexp
@findex reduce-backward-sexp
Move backwards across one ``balanced expression''.  With a numeric
argument, move that many times, where a negative argument means move
forwards instead of backwards.  This command is modelled on
@code{backward-sexp}.
@end table

@c ===================================================================

@node Procedures, Comments, Statements, Top
@chapter Procedure-oriented commands
@cindex Procedures
@cindex Operations on Procedures

Files of REDUCE source code frequently consist mainly of procedure
definitions.  This is certainly true of symbolic-mode code, and hence
it is true of most of the source code of the REDUCE system itself.
REDUCE mode provides the following operations on procedures.  They
work on all kinds of REDUCE procedures provided they contain one of
the procedural keywords @code{procedure}, @code{listproc} or
@code{matrixproc} within their header.  Procedure type declarations
(@code{symbolic}, @code{inline}, @code{real}, etc.@:) preceding the
procedural keyword are also supported.

A procedure is considered to begin at the first non-white-space
character of the definition, and to end after the statement defining
the procedure body.  White space and the first newline after the
procedure body are always considered to be part of the procedure.  The
commands to mark and kill a procedure also include @emph{all} blank
lines before the procedure definition.  Many procedure-oriented
commands support a prefix argument.

The two commands for moving over procedures accept a positive integer
argument that indicates by how many procedures to move -- the default
is 1.  These commands do not move in the opposite direction if given a
negative argument, in which case they do not move at all.

@table @kbd
@item C-M-e
@kindex C-M-e
@itemx M-x reduce-forward-procedure
@findex reduce-forward-procedure
Move forwards to the end of the procedure ending after point.  With a
positive argument, do it that many times.  If this fails, move
forwards by as many complete procedures as possible and report a user
error.  Skip to the first following non-blank character or the next
line.

@item C-M-a
@kindex C-M-a
@itemx M-x reduce-backward-procedure
@findex reduce-backward-procedure
Move backwards to the start of the procedure starting before point.
With a positive argument, do it that many times.  If this fails, move
backwards by as many complete procedures as possible and report a user
error.  Skip to the start of any procedural types.
@end table

Regardless of whether point is within a procedure or not, these two
commands move respectively to the first following end of a procedure,
or the first preceding start of a procedure.  One way to move to the
start of the next procedure is to move forwards to its end and then
move backwards to its start.

Marking is the basis for many operations on procedures.

@table @kbd
@item C-M-h
@kindex C-M-h
@itemx M-x reduce-mark-procedure
@findex reduce-mark-procedure
Mark the procedure ending after point.  With a positive argument, mark
that many procedures ending after point.  Put mark at the first
non-blank character or next line after the appropriate end of
procedure.  If this fails, do not mark anything and report a user
error.  Leave point at the start of the first procedure before any
preceding blank lines.

@item C-c k
@kindex C-c k
@itemx M-x reduce-kill-procedure
@findex reduce-kill-procedure
Kill the procedure ending after point.  With a positive argument,
kill that many procedures ending after point, including any preceding
blank lines.  If this fails, do not kill anything and report a user
error.

@item C-M-q
@kindex C-M-q
@itemx M-x reduce-indent-procedure
@findex reduce-indent-procedure
Indent the procedure (and trailing white space) ending after point.
@xref{Indentation,, Indenting REDUCE code automatically}.
@end table

It is often desirable to be able to see as much as possible of a
procedure definition within the current window.  The standard Emacs
command @code{reposition-window} (@pxref{Scrolling,,, emacs, The Emacs
Editor}) attempts to do this for Lisp functions, and the command
@code{reduce-reposition-window} provides a harness to apply this
function to REDUCE procedures, to which the standard key @kbd{C-M-l} is
rebound.

@table @kbd
@item C-M-l
@kindex C-M-l
@itemx M-x reduce-reposition-window
@findex reduce-reposition-window
Reposition the procedure containing point to maximize its visibility
within the window.  @xref{Scrolling,,, emacs, The Emacs Editor}, and see
the documentation for the function @code{reposition-window} for details.
@end table

To restrict all editing to a single REDUCE procedure, the standard Emacs
key @kbd{C-x n d} that runs the command @code{narrow-to-defun} is
rebound to a function to narrow to the current procedure.

@table @kbd
@item C-x n d
@kindex C-x n d
@itemx M-x reduce-narrow-to-procedure
@findex reduce-narrow-to-procedure
Narrow to the procedure ending after point.  In other words, make all
text outside this procedure invisible.  With a positive argument,
include that many procedures ending after point.  Also include any
preceding blank lines.  If narrowing fails, report a user error.
@xref{Narrowing,,, emacs, The Emacs Editor}.
@end table

@c ===================================================================

@node Comments, Indentation, Procedures, Top
@chapter Support for REDUCE comments
@cindex Comment support

There are three comment conventions used in REDUCE@.  One is the
comment statement, which is a statement that begins with the keyword
@code{comment} and ends with a statement terminator.  This is not used
much in modern REDUCE code.  The most commonly used form of comment
begins with a @code{%} character and ends at the end of the line.
Hence, it can appear either on its own on a line or at the end of a
line after other code.  C-style comments, which begin with @code{/*}
and end with @code{*/}, are also accepted although not (yet) widely
used.  REDUCE mode highlights them all as comments.

Comments are ignored (skipped) by all syntax-directed commands.  (This
is not trivial to achieve, since comments can contain essentially
arbitrary text including keywords, and @code{%} and @code{/**/}
comments can contain statement terminators that do not have any
syntactic significance.)  There is currently no way to use any of the
REDUCE syntax-directed commands on comment statements.

The REDUCE mode indentation and fill commands support all three
comment types, but there is no other support for comment statements or
@code{/**/} comments.  There is considerably more support for
%-comments, much of which is already built into Emacs because
%-comments are very similar to the comments used in Emacs Lisp.
Indeed, the comment conventions supported by REDUCE mode are modelled
primarily on those used in Emacs Lisp mode.

The comment commands are intimately related to the automatic comment
indentation conventions.  (These are the indentation conventions
enforced by the Emacs comment and indentation commands, although the
user is not otherwise forced to follow them.)  @xref{Indentation,,
Indenting REDUCE code automatically}.

The indentation of a @code{%}-comment that begins with no more than 2
@code{%} characters together and appears alone on a line is determined
by the previous non-blank line.  If this is a procedure (header)
statement then the comment line is indented relative to it, otherwise
it has no indent relative to the previous line, and at the beginning
of a file it is not indented at all.  A @code{%}-comment at the end of
a line of code is indented to the column specified by the value of the
standard Emacs buffer-local variable @code{comment-column}, which by
default is 40 (half way across a ``standard'' 80 column page), unless
the code extends beyond this column.  In that case, the comment begins
one space later.

This convention can be over-ridden as follows.  If the comment begins
with 3 or more @code{%} characters then the comment indentation is not
changed.  This allows a comment to be placed anywhere on an empty line
without any risk of it being automatically re-indented.

A new single-@code{%}-comment can be introduced and/or automatically
indented by the standard Emacs command @code{comment-dwim}, normally
bound to the key @kbd{M-;}.  An existing @code{%}-comment can be
automatically continued on the next line by the standard Emacs command
@code{default-indent-new-line}, normally bound to the keys @kbd{M-j}
and @kbd{C-M-j}.  This will copy the structure of the @code{%}-comment
to be continued, including the number of @code{%} characters and the
indentation.  All other indentation commands will also indent
@code{%}-comments, in particular those bound to the @kbd{@key{TAB}}
and @kbd{@key{BACKTAB}} (i.e.@: @kbd{S-@key{TAB}}) keys.
@xref{Indentation,, Indenting REDUCE code automatically}.

@table @kbd
@item  M-;
@kindex M-;
@itemx M-x comment-dwim
@findex comment-dwim
Indent this line's comment appropriately, or insert an empty comment.

@item  C-M-j
@kindex C-M-j
@item  M-j
@kindex M-j
@itemx M-x default-indent-new-line
@findex default-indent-new-line
Break the line at point and indent, continuing a comment if presently
within one.  The body of the continued comment is indented under the
previous comment line.
@end table

The only program text that it normally makes sense to fill or justify
is comment text.  Hence, REDUCE mode rebinds the key @kbd{M-q} that
normally fills or justifies a paragraph to the command
@code{reduce-fill-comment}.  This should be completely safe to use in
REDUCE code (unlike @code{fill-paragraph} etc., which would be a
potential disaster were there no undo facility!), and makes it easy to
keep comments formatted tidily.

@table @kbd
@item  M-q
@kindex M-q
@itemx M-x reduce-fill-comment
@findex reduce-fill-comment
Fill a comment statement, successive @code{%}-comment lines or a
@code{/**/} comment around or immediately following point.  A prefix
argument means justify as well.
@end table

REDUCE mode also provides commands for turning sections of text into
@code{%}-comments by adding @code{%} characters at the start of each
line, which will be referred to as ``start-comments''.  These commands
are intended primarily for temporarily preventing REDUCE from
executing sections of code without actually removing them.  Such a
section can be either the current region or the procedure ending after
point.  By default, these commands automatically toggle the comment
status.  When given an interactive argument, they remove any
start-commenting of the specified section of text if the argument is
negative (or null) and insert start-commenting if the argument is
positive.  The precise text that is added to or removed from each line
is the value of the variable @code{reduce-comment-region-string},
which defaults to @samp{%% }.

@table @kbd
@item  C-c ;
@kindex C-c ;
@itemx M-x reduce-comment-region
@findex reduce-comment-region
Comment/uncomment every line in the region.  By default, it toggles
the commenting, i.e.@: it comments the region if it is uncommented and
uncomments if it is commented.  With an interactive argument, comment
if non-negative, uncomment if null or negative (cf.@: toggling minor
modes).  When commenting, it puts the value of the variable
@code{reduce-comment-region-string} at the beginning of every line in
the region.

@item  C-c :
@kindex C-c :
@itemx M-x reduce-comment-procedure
@findex reduce-comment-procedure
As for @code{reduce-comment-region}, but applies to the procedure ending
after point.
@end table

@c ===================================================================

@node Indentation, Structures, Comments, Top
@chapter Indenting REDUCE code automatically
@cindex Indentation

Indentation refers to the white space at the left of a line, which
therefore determines the column in which the actual text of the line
begins.  Indentation is used in normal English text to indicate the
beginning of paragraphs, quotations, lists, etc.@: and hence to indicate
the logical structure of a document.

It is very important to use systematic indentation to indicate the
logical structure of the source code of a computer program.  Whilst the
general principles of indentation are largely agreed, precise
indentation conventions vary from author to author.  The automatic
indentation currently provided by REDUCE mode is very inflexible and
reflects very much my own style of indentation.  Future versions may
provide more flexible and customizable indentation.

Currently all indentation is done in steps consisting of a fixed
number of spaces determined by the value of the variable
@code{reduce-indentation}, the default value of which is 3;
@ref{Customization,, Options that control REDUCE IDE}.  This is the
indentation recommended by A.@ C.@ Hearn (the principal author of
REDUCE) for the indentation of the first line after a procedure
(header) statement.

REDUCE mode provides fairly intelligent automatic indentation.  The
style used is as follows, where the indentation of a child statement is
expressed relative to the parent statement.  Each top-level statement is
indented to the left margin.  Procedure bodies are indented by one step.
Bodies of multi-line compound and group statements are indented by one
step and labels are exdented to match the beginning of the enclosing
block.  Lines that begin with @code{end} or @code{>>} are exdented to
match the line containing the matching @code{begin} or @code{<<}.
Bodies of control structures and lines that continue a previous
statement are indented by one step.  As parts of larger statements,
compound and group statements themselves are generally not indented if
they occupy multiple lines (because their bodies are indented) but they
are indented if they occupy only a single line.

When a new line that is inserted is being indented, the indentation
can be based only on the preceding code, and not on the code that will
appear in the line.  Therefore, it is often necessary to re-indent a
line in order to get consistent indentation.  This may seem a little
strange, but it is unavoidable given the syntax of REDUCE and the
indentation style that I have chosen.  It is for this reason that the
key @kbd{C-j} runs the command
@code{reindent-then-newline-and-indent} rather than just
@code{newline-and-indent}.

The command to indent, or re-indent, a line of text is
@code{reduce-indent-line}, normally bound (indirectly) to the key
@kbd{@key{TAB}}.  The execution of @code{reduce-indent-line} is
independent of the position of point within the line.  It does not
move point relative to the text around it unless point was within the
indentation, in which case it is left before the first non-blank
character (i.e.@: at the end of the indentation), or at the end of the
line if it contains only white space.  Normally, however, the most
convenient way to use automatic indentation is to terminate each line
of code with @kbd{C-j} rather than @kbd{@key{RET}}.
@xref{Miscellaneous,, Miscellaneous features}.

When called with any argument, which is possible only via the direct
key binding @kbd{M-i}, @code{reduce-indent-line} will indent the
current line correctly and then re-indent the rest of the logical
statement containing point by the same amount that the current line
was re-indented.  This is @emph{not} the same as correctly
re-indenting the subsequent lines -- it re-indents them rigidly,
without changing their relative indentations at all, and is much
faster.

@table @kbd
@item TAB
@kindex TAB
@item M-i
@kindex M-i
@itemx M-x reduce-indent-line
@findex reduce-indent-line
Indent or re-indent the current line as REDUCE code.  Indents to a
fixed style determined by the current and previous non-blank lines.
With an interactive argument, indent any additional lines of the same
statement rigidly together with this one.

@item C-j
@kindex C-j
@itemx M-x reindent-then-newline-and-indent
@findex reindent-then-newline-and-indent
Re-indent the current line, insert a newline, then indent the new line.
Indentation of both lines is done using @code{reduce-indent-line}, which
is bound by default to @kbd{TAB}.
@end table

With the current indentation style, it is not possible in all cases to
determine the correct indentation until after some text has been
entered on a line.  This applies to the terminal delimiter of a block
(@code{end}) or group (@code{>>}) and to an @code{else} clause.
Therefore, REDUCE mode can automatically re-indent the current line
once there is enough text to recognise that this is necessary.  It
does this only when it is otherwise idle and only when the relevant
text has just been typed.  It is not done if the cursor is later moved
onto such a line since it is assumed that the desired indentation has
been set by then.  (The indentation of any text can, of course, be
changed at any time, but it will never be automatically changed
retrospectively!)

This facility can be turned on and off by the command
@code{reduce-auto-indent-mode}, and it is turned on automatically if
the value of the option @code{reduce-auto-indent-mode-on} is non-nil,
which it is by default.  The length of idle time required before the
facility will operate is controlled by the option
@code{reduce-auto-indent-delay}, and whether the current line is
re-indented by this facility is controlled by the regular expression
that is the value of the option @code{reduce-auto-indent-regexp}.
Auto-indentation is on by default.  @xref{Customization,,
Customization of the REDUCE IDE}.

@table @kbd
@item M-x reduce-auto-indent-mode
@findex reduce-auto-indent-mode
Toggle REDUCE Auto Indent mode.  With a prefix argument, turn the mode
on if and only if the argument is positive.  When REDUCE Auto Indent
mode is enabled, after @code{reduce-auto-indent-delay} seconds of Emacs
idle time re-indent the current line if the text just typed matches
@code{reduce-auto-indent-regexp}.
@end table

A section of code can be re-indented using one command if it is first
marked as the current region, or the whole buffer or a complete
procedure definition can be re-indented by a single command.  The
latter command works by marking the procedure and then re-indenting
the region.  Region (and hence procedure) indenting is currently
implemented inefficiently by applying the single-line indentation
algorithm line-by-line, and hence is very slow for a large region or
procedure.  In some future version it may be re-implemented more
efficiently.

@table @kbd
@item  C-M-\
@kindex C-M-\
@itemx M-x reduce-indent-region
@findex reduce-indent-region
Indent or re-indent the region as REDUCE source code by applying
@code{reduce-indent-line} to each line.  With a prefix argument it
indents the whole buffer.

@item  C-M-q
@kindex C-M-q
@itemx M-x reduce-indent-procedure
@findex reduce-indent-procedure
Indent or re-indent the procedure (and trailing white space) ending
after point by applying @code{reduce-indent-line} to each line.
@end table

The command @code{reduce-indent-line-always}, bound to
@kbd{C-@key{TAB}}, is analogous to @code{reduce-indent-line} but
always indents by precisely one additional step consisting of
@code{reduce-indentation} spaces.  With an argument, it rigidly
indents by one step the current line and the rest of the logical
statement.

The command @code{reduce-unindent-line}, bound to @kbd{S-@key{TAB}}
(i.e.@: @kbd{@key{BACKTAB}}), is an inverse of
@code{reduce-indent-line-always} and decreases the indentation by one
step.  With an argument, it rigidly unindents by one step the current
line and the rest of the logical statement.

@table @kbd
@item C-TAB
@kindex C-TAB
@itemx M-x reduce-indent-line-always
@findex reduce-indent-line-always
Indent the current line as REDUCE code by adding
@code{reduce-indentation} spaces at the beginning of the line.  With
an interactive argument, indent any additional lines of the same
statement rigidly along with this one.

@item BACKTAB
@kindex BACKTAB
@item S-TAB
@kindex S-TAB
@itemx M-x reduce-unindent-line
@findex reduce-unindent-line
Unindent the current line as REDUCE code by deleting
@code{reduce-indentation} spaces (or as many as possible) from the
beginning of the line.  With an interactive argument, unindent any
additional lines of the same statement rigidly along with this one.
@end table

@c ===================================================================

@node Structures, Completion, Indentation, Top
@chapter Templates for REDUCE structures
@cindex Templates for structures
@cindex Structure templates

Commands are provided to insert and format the major REDUCE language
structures; currently block or compound (@code{begin @dots{} end}),
group (@code{<< @dots{} >>}) and conditional (@code{if @dots{} then
@dots{} else @dots{}}) statements are supported.  By default they are
formatted to be multi-line.  If given a prefix argument, the commands to
insert block and group statements (composites) format them on a single
line (appropriate in some very simple cases).

If there is text on the line after where a composite is inserted then it
is moved into the body of the composite; if transient mark mode is on
and the mark is active then the whole region is moved into the
composite; the composite is then re-indented.

The cursor is left in place to enter the body statements of a group,
whereas a block is inserted complete with an empty @code{scalar}
declaration and the cursor is left in place to enter the names of the
scalar variables.

@table @kbd
@item  C-c b
@kindex C-c b
@itemx M-x reduce-insert-block
@findex reduce-insert-block
Insert and indent a @code{begin scalar ; @dots{} end} block and position
point inside.  With an argument put @code{begin} and @code{end} on the
same line.

@item  C-c <
@kindex C-c <
@itemx M-x reduce-insert-group
@findex reduce-insert-group
Insert and indent a @code{<< @dots{} >>} group and position point
inside.  With an argument put @code{<<} and @code{>>} on the same line.

@item  C-c i
@kindex C-c i
@itemx M-x reduce-insert-if-then
@findex reduce-insert-if-then
Insert @code{if @dots{} then} and position point inside.  With argument
include a correctly indented @code{else} on a second line.
@end table

Probably the easiest way to access these templates from the keyboard is
not directly as described above but via the generalized completion
facilities described in the next chapter.  @xref{Completion,,Keyword
completion and abbreviation expansion,,}.

@c ===================================================================

@node Completion, Font-Lock, Structures, Top
@chapter Keyword completion and abbreviation expansion
@cindex Completion
@cindex Keyword completion
@cindex Expansion
@cindex Abbreviations
@cindex Structures

Emacs provides various standard facilities for semi-automatic
completion of key words and phrases.  @xref{Symbol Completion,,
Completion for Symbol Names, emacs, The Emacs Editor}.  @xref{Dynamic
Abbrevs,, Dynamic Abbrev Expansion, emacs, The Emacs Editor}.  REDUCE
mode provides completion of common REDUCE key words and phrases, such
as @samp{procedure}, by typing the first few letters of a key word or
phrase and then pressing @kbd{Meta-@key{TAB}}.  (For use under
Microsoft Window @ref{Miscellaneous,,Miscellaneous features,,}.)  This
works in a similar way to completion in other major modes; @ref{Symbol
Completion,, Completion for Symbol Names, emacs, The Emacs Editor}.

REDUCE mode also provides @emph{abbreviations} that are expanded like
completions, except that they are @emph{replaced} by their expansions
rather than completed.  Examples of the abbreviations currently defined
are:

@lisp
    ("ap" . "algebraic procedure ")
    ("st" . "such that ")
    ("sop" . "symbolic operator ")
    ("sp" . "symbolic procedure ")
@end lisp

The following symbols currently trigger @emph{structure completion}:

@lisp
    ("begin" . reduce-insert-block)
    ("ift" . reduce-expand-if-then)
    ("ife" . reduce-expand-if-then-else)
    ("<<" . reduce-insert-group)
@end lisp

They operate in exactly the same way as if the appropriate structure
insertion command had been executed directly, and they receive any
prefix argument entered before the completion key.

For the full set of completions and abbreviations see the customizable
option @code{reduce-completion-alist}.

@table @kbd
@item  M-TAB
@kindex M-TAB
@itemx M-x reduce-complete-symbol
@findex reduce-complete-symbol
Perform completion on the REDUCE symbol preceding point (or preceding
the region if it is active).  Compare that symbol against the elements
of @code{reduce-completion-alist}.  If a perfect match (only) has a
@code{cdr} then delete the match and insert the @code{cdr} if it is a
string or call it if it is a (nullary) function, passing on any prefix
argument (in raw form).
@end table

@c ===================================================================

@node Font-Lock, Information, Completion, Top
@chapter Font-lock support for automatic font selection
@cindex Font-lock support
@cindex Font selection
@cindex Highlighting of keywords
@cindex Keyword highlighting

Font-lock mode causes Emacs to select automatically the font in which
text is displayed (``fontify'' it) so as to indicate its logical
status.  @xref{Font Lock,, Font Lock mode, emacs, The Emacs Editor}.
The first version of font-lock support for REDUCE mode was contributed
by Rainer Schöpf.  The current version applies to both REDUCE mode and
REDUCE Run mode (@ref{Running}) and provides 4 strictly inclusive level:
``Symbolic'' includes ``Algebraic'', which includes ``Basic'', which
includes ``Minimal''.  The level can be selected using the standard
font-lock facilities, or interactively most easily via the REDUCE
major mode @emph{Syntax Highlighting} sub-menu.  The levels and
corresponding highlighting are as follows:

@enumerate 0
@item
Minimal: strings are displayed using @code{font-lock-string-face} and
``syntactic'' comments (namely comments from @code{%} to the end of
the line, and C-style comments between @code{/*} and @code{*/}
delimiters) are displayed using @code{font-lock-comment-face}.

In REDUCE Run mode (@ref{Running}) REDUCE warning and error messages, and
REDUCE (@code{rtrace}) and Lisp trace output, are displayed using
@code{font-lock-warning-face}.

@item
Basic: as minimal level and additionally comment statements are
displayed using @code{font-lock-comment-face}; the main keywords
including block delimiters and group delimiters are displayed using
@code{font-lock-keyword-face}.

@item
Algebraic: as basic level and additionally procedure names are
displayed using @code{font-lock-function-name-face} and procedure
parameters are displayed using @code{font-lock-variable-face}; general
types such as ``algebraic'' are displayed using
@code{font-lock-type-face}; local variable types such as ``scalar''
are displayed using @code{font-lock-type-face} and variable names
declared local are displayed using
@code{font-lock-variable-name-face}; goto and label names and named
constants such as ``pi'' and ``Catalan'' are displayed using
@code{font-lock-constant-face}; declared operator, operator type such
as ``linear'', vector, array and matrix declarations are displayed
using @code{font-lock-type-face}; operator, vector, and array and
matrix identifiers (with or without bounds) are displayed using
@code{font-lock-function-face}.

@item
Symbolic: as algebraic level and additionally preprocessor
#-directives are displayed using @code{font-lock-preprocessor-face};
the key symbolic-mode ``types'' @code{fluid} and @code{global} are
displayed using @code{font-lock-type-face} and the variable names
declared fluid or global are displayed using
@code{font-lock-variable-name-face}; all other quoted objects are
displayed using @code{font-lock-constant-face}; asserted types are
displayed using @code{font-lock-type-face}; ``declare'' and ``struct''
statements, as used in ``redlog'', are displayed using
@code{font-lock-keyword-face}, @code{font-lock-function-name-face} and
@code{font-lock-type-face}; module, endmodule and other symbolic-mode
keywords are displayed using @code{font-lock-keyword-face}; module
names are displayed using @code{font-lock-constant-face}; key
symbolic-mode functions such as ``flag'' and ``get'' are displayed
using @code{font-lock-builtin-face}; other symbolic-mode ``types''
such as ``switch'' and ``share'' are displayed using
@code{font-lock-type-face}; declared lambda parameters are displayed
using @code{font-lock-variable-face}.
@end enumerate

Using Emacs' default settings gives symbolic-level highlighting, but
if you find this too gaudy or too slow then you might prefer to select
a lower level.  Font-lock mode can be turned on interactively in the
normal way that any minor mode is turned on, e.g.@: it can be toggled
on and off by the command @code{font-lock-mode}.  It can also be
turned on and off via the REDUCE mode @emph{Syntax Highlighting}
sub-menu.  To turn on font-lock mode automatically with REDUCE mode,
put this in your @file{.emacs} file:

@lisp
(add-hook 'reduce-mode-hook 'turn-on-font-lock)
@end lisp

To control the operation of font-lock mode, customize the appropriate
options in the @code{Font Lock} group.  The default level of
fontification used by any mode can be specified by customizing the
option @code{font-lock-maximum-decoration}, which REDUCE mode
respects.

Emacs provides standard facilities to control the use of different
display faces.  @xref{Faces,, Using Multiple Typefaces, emacs, The Emacs
Editor}.  @xref{Faces,,, elisp, The GNU Emacs Lisp Reference Manual},
for further technical detail.  To alter the appearance of a Font Lock
face, use the customization buffer for the @code{Font Lock Highlighting
Faces} group.  @xref{Face Customization,, Customizing Faces, emacs, The
Emacs Editor}.

REDUCE mode passes information to font-lock mode via the value of the
buffer-local variable @code{font-lock-defaults}, which could be re-set
or modified via the REDUCE mode hook, although this is not recommended.

For more information see the description of the command
@code{font-lock-mode} and related commands and variables, and/or the
ELisp source code file @file{font-lock.el}.

Font-locking of major syntactic elements, such as comments and
strings, is normally controlled by the syntax table for the text being
edited.  This leads to a problem with a language such as REDUCE,
because the character @code{!} represents an escape character within
an identifier but not within a string.  This is different from the
convention in the languages (C and Emacs Lisp) that Emacs was
primarily designed to support, in which the significance of the escape
character does not depend on the context.  The solution I adopt in
REDUCE mode is to reset the syntax of @code{!} from escape to
punctuation when it occurs immediately followed by a double quote,
i.e.@: as @code{!"}, but only within a string.

@c ===================================================================

@node Information, Running, Font-Lock, Top
@chapter Procedure, operator and variable information
@cindex Procedure, operator and variable information
@cindex Information on procedures, operators and variables
@cindex Procedure information
@cindex Operator information
@cindex Variable information

REDUCE mode can provide information about the procedure that point is
currently in, and easy access via the @code{Imenu} facility to all the
procedure definitions and the operator and variable declarations
within the current file.  Whilst @code{Imenu} provides a convenient
way to find a procedure or operator definition rapidly in the current
file, the standard Emacs ``tag'' facility is the best way to find a
procedure or operator definition rapidly in another file.

@menu
* Show Proc::                   Showing the current procedure
* Imenu::                       Menu access to procedures, etc.
* Tags::                        Tag access to procedures and operators
@end menu

@node Show Proc, Imenu, Information, Information
@section Show proc mode
@cindex Show proc mode
@cindex Procedure display
@cindex Displaying current procedure
@cindex Showing current procedure
@cindex Which procedure

When editing or viewing long procedure definitions it is easy to
forget which procedure you are looking at when the procedure statement
itself is off the top of the screen.  REDUCE mode can show in the mode
line the name of the procedure (if any) that point is in.  This
facility is turned on and off by the command @kbd{M-x
reduce-show-proc-mode} or via the REDUCE mode menu; it is on by
default.  (It is analogous to the standard Emacs ``Which Function''
mode -- @pxref{Which Function,,,emacs, The Emacs Editor} -- but it is
implemented independently.)

The procedure name is shown in the mode line near the end surrounded
by square brackets.  It provides a mouse menu as do most mode-line
items; hover over it to see the options.  Clicking mouse button 1
(usually the left button) on the procedure name jumps to the beginning
of the procedure; clicking mouse button 2 (usually the right button)
jumps to the end of the procedure; clicking mouse button 3 (usually
the middle button) toggles hiding the buffer contents other than the
procedure, i.e.@: it narrows to the procedure or widens the buffer if
it is currently narrowed.

@table @kbd
@item M-x reduce-show-proc-mode
@findex reduce-show-proc-mode
Toggle REDUCE Show Proc mode.  REDUCE Show Proc mode displays the
current procedure name in the mode line and updates it after
@code{idle-update-delay} seconds of Emacs idle time.

This is a minor mode.  If called interactively, toggle REDUCE Show
Proc mode.  If the prefix argument is positive, enable the mode, and
if it is zero or negative, disable the mode.
@end table

@c -------------------------------------------------------------------

@node Imenu, Tags, Show Proc, Information
@section Imenu support
@cindex Imenu support
@cindex Support for imenu
@cindex Menu of procedures, operators and variables
@cindex Procedures menu
@cindex Operators menu
@cindex Variables menu

REDUCE mode supports the standard Emacs @code{Imenu} facilities
(@pxref{Imenu,,,emacs, The Emacs Editor}).  REDUCE mode can add an
``Index'' menu to the menubar to the left of the REDUCE menu, which
lists all the procedures found in the current buffer.  If the current
buffer defines any operators then they are listed in an
``*Operators*'' submenu, and if the current buffer defines any
symbolic-mode global or fluid variables then they are listed in a
``*Variables*'' submenu.  Selecting an entry in this menu moves point
to the start of the line in which the specified procedure is defined
or the specified operator or variable is declared.

If the customizable option @code{reduce-imenu-add} is non-nil, which
it is by default, then REDUCE mode adds an ``Index'' menu
automatically (@ref{Customization,, Options that control REDUCE IDE}).
Otherwise, selecting the appropriate item in the REDUCE menu adds an
``Index'' menu.

Another way to use @code{Imenu} is by entering the extended command
@kbd{M-x imenu} and then using the standard Emacs completion
facilities to select a procedure name, but note that this works only
for procedures.

@c -------------------------------------------------------------------

@node Tags,  , Imenu, Information
@section Support for tag files
@cindex Support for tag files
@cindex Tags
@cindex Tag files

A REDUCE mode submenu provides rapid access to some of the main
facilities for finding a procedure definition via a tag file.  Two
commands (and submenu options) facilitate tagging the REDUCE files in
one directory or in a directory and its sub-directories.  The former
is useful for tagging all the files associated with a single project
or package; the latter for tagging all REDUCE packages in a single tag
file.

Once a TAGS file has been generated, the standard Emacs @code{xref}
interface is available to find identifier references, in particular
the command @command{xref-find-definitions}, which is also available
via the REDUCE mode submenu.  @xref{Xref,, Find Identifier References,
emacs, GNU Emacs Manual}.

The tagging commands use the standard Emacs @code{etags} program,
which should be available in the Emacs @code{bin} directory.  REDUCE
mode uses the value of the option @option{reduce-etags-directory},
which should be appropriate by default, but if not can be customized.
(It is not required that the Emacs @code{bin} directory be in your
execution path, but if it is you can optionally set
@option{reduce-etags-directory} to nil.)

@table @kbd
@item M-.
@item M-x xref-find-definitions
Show the definitions of the identifier at point.  With a prefix
argument, or if there’s no identifier at point, prompt for the
identifier.

@item M-x reduce-tagify-dir
@findex reduce-tagify-dir
Generate a REDUCE TAGS file for (all @file{.red} files in) the
specified directory, by default the current directory.  The TAGS file
goes in the specified directory.

@item M-x reduce-tagify-dir-recursively
@findex reduce-tagify-dir-recursively
Generate a REDUCE TAGS file for (all @code{.red} files in) the
specified directory, by default the current directory, and its
sub-directories to the specified depth.  The depth defaults to 2,
which means the specified directory and each of its immediate
sub-directories, but no deeper sub-directories.  Specifying a depth
less than or equal to 0 means all sub-directories with no limit.  This
may fail on the REDUCE packages directory because it attempts to tag
too many files.  The single TAGS file goes in the specified directory.
@end table

@c ===================================================================

@node Running, Miscellaneous, Information, Top
@chapter Running REDUCE in an Emacs window
@cindex Running REDUCE
@cindex Run mode

REDUCE Run mode is a subsidiary of REDUCE mode, in the sense that it
requires REDUCE mode to be loaded before it is loaded (which it tries
to ensure automatically).  It provides an interface that allows you to
run a command-line (as opposed to a GUI) version of REDUCE
interactively in an Emacs window, with input from and output to that
window.

In fact, it allows you to run multiple versions of REDUCE
simultaneously and independently in multiple windows.  By default, it
runs the distributed pre-built versions of CSL and PSL REDUCE, but it
can easily be configured to run other versions of REDUCE, such as ones
you have built yourself from the development sources, including REDUCE
on Common Lisp.

You can also run a REDUCE source code file or an Emacs buffer
containing REDUCE source code (in REDUCE mode) as a complete REDUCE
program in an independent window automatically named from the source
code file or buffer.

REDUCE statements, procedures or general regions of code in a REDUCE
mode buffer can be sent to REDUCE running in another buffer.  If
REDUCE is running in multiple buffers then you select which buffer to
use.  If you try to send REDUCE code to REDUCE but REDUCE is not
running, then REDUCE Run mode will (optionally) start REDUCE
automatically.

@menu
* Run Introduction::            Introduction to REDUCE Run mode
* Run Installation::            Installation of REDUCE Run mode
* REDUCE on Windows::           Running REDUCE on Microsoft Windows
* REDUCE on Unix::              Running REDUCE on Unix-like platforms
* Running REDUCE::              Running, rerunning and switching to REDUCE
* Running Programs::            Running complete REDUCE programs
* Evaluating Code::             Inputting code fragments to REDUCE
* Processing Files::            Inputting, loading and compiling REDUCE files
@end menu

@c -------------------------------------------------------------------

@node Run Introduction, Run Installation, Running, Running
@section Introduction to REDUCE Run mode
@cindex Introduction to REDUCE Run mode

REDUCE Run mode provides the following facilities for running REDUCE:

@itemize @bullet
@item
input editing and flexible re-execution of previous input;
@item
flexible browsing of all input and output;
@item
syntax highlighting of prompts, input, warning and error messages, and
trace output;
@item
bracket and delimiter highlighting or matching as in REDUCE mode;
@item
easy REDUCE package loading, source file input and module compilation;
@item
seamless integration with source files being edited using REDUCE edit
mode, including easy input of statements, procedure definitions,
arbitrary regions or the whole file to REDUCE;
@item
optional automatic starting of REDUCE;
@item
menu access to many facilities;
@item
all other standard Emacs facilities, such as printing part or all of the
interaction buffer.
@end itemize

These facilities include many of those offered by other REDUCE
interfaces, but REDUCE IDE does not currently provide typeset quality
display of mathematical output.

REDUCE Run mode is a subsidiary library to REDUCE mode and when loaded
it hooks itself into and cooperates closely with REDUCE mode.

REDUCE Run mode is built on top of the general
command-interpreter-in-a-buffer (comint) mode and so shares a common
base functionality and a common set of key bindings with all modes
derived from comint mode.  This makes these modes easier to use.
(Among these, shell mode is likely to be the most familiar.
@xref{Interactive Shell,, Interactive Inferior Shell, emacs, The
Emacs Editor}.  In fact, REDUCE Run mode is based on the standard
library @file{inf-lisp} by @email{shivers@@cs.cmu.edu, Olin Shivers}.
@xref{External Lisp,, Running an External Lisp, emacs, The Emacs
Editor}.)

For further documentation on the functionality provided by comint mode
and the hooks available for customizing it, see the @code{comint}
customization group and the file @file{comint.el}.

Note that, by default, in comint mode the whole interaction buffer is
editable, which applies also to REDUCE Run mode, unlike most other
REDUCE interfaces, in which previous input and output cannot be
changed.  This can be particularly disconcerting when deleting
erroneous input ``back to the prompt'' because, by default, the prompt
itself can also be deleted.  This can be prevented by customizing the
option @code{comint-prompt-read-only}.  The @code{comint}
customization group can be accessed via a link in the REDUCE Run
customization group.

@subheading Implementation Note

REDUCE is eventually run by the Emacs function @code{make-process}
(see @pxref{Asynchronous Processes,,, elisp}), which is implemented in
C code.  It runs programs directly if possible, but uses the default
shell to run shell scripts or batch files.  It looks up relative
program file names in @code{exec-path} (see @pxref{Subprocess
Creation,,, elisp}).  By default, it directs @code{stdout} and
@code{stderr} to the process buffer.  It uses pipes for communication
on Microsoft Windows, but pseudo-terminals (ptys) on other platforms.

@c -------------------------------------------------------------------

@node Run Installation, REDUCE on Windows, Run Introduction, Running
@section Installation of REDUCE Run mode
@cindex Installation of REDUCE Run mode

It is probably best to use the GNU Emacs package manager to install
the latest REDUCE IDE package; @ref{Installation,, Installation of
REDUCE IDE}.  None of the manual installation described below is then
required.  But if you want to install by hand, or understand the
details of the installation process, then read on.

REDUCE Run mode requires the library @file{reduce-mode} both when it is
compiled and when it is loaded.  It tries quite hard to locate this
library, but normally it should be in the same directory as
@file{reduce-run}.

Byte-compile the file @file{reduce-run.el}, put the result somewhere in
your @code{load-path}, and put the following in your @file{.emacs} file:

@lisp
(autoload 'run-reduce "reduce-run" "Run a REDUCE process" t)
@end lisp

To control access to the features of REDUCE Run mode from REDUCE mode
you can customize the option @code{reduce-run-autoload}.  @xref{Run
Customization}.

You can customize the values of the options
@code{reduce-root-dir-file-name} and @code{reduce-run-commands}
(@pxref{Running REDUCE,, Running@comma{} rerunning and switching to
REDUCE}) if the default values are not correct, and/or to add commands
to run additional versions of REDUCE, such as those built directly
from the Subversion repository or REDUCE on Common Lisp.

@subheading Incompatible Changes in Versions 1.12 and 1.13

The option @code{reduce-run-commands} has been changed so that a
REDUCE command is a list of strings rather than a single string, which
allows spaces in both the command and its arguments.  Run mode
automatically updates a saved value to the new structure and offers to
edit and/or save it.

The option @code{reduce-run-installation-directory} has been renamed
to @code{reduce-root-dir-file-name} and become a directory file name
rather than a directory name, i.e.@: the final directory separator has
been removed.  This makes it suitable as the default value of the
environment variable @code{reduce}.

The option @code{reduce-run-MSWin-drives} has been removed and its use
incorporated into the definition of @code{reduce-root-dir-file-name},
without using any external programs.

There is now a facility to set the root directory separately for each
command in @code{reduce-run-commands}; if unset then it defaults to
the value of @code{reduce-root-dir-file-name}.  The environment
variable @code{reduce} is now always set to the local root directory,
which is also used to find REDUCE packages.  Hence, the option
@code{reduce-packages-directory} is no longer used.

The shorthand @code{$reduce} is replaced at the start of strings
(other than Name) in @code{reduce-run-commands} with the local root
directory.

The special support for PSL REDUCE has been removed since it is not
needed when REDUCE is run directly and is no longer needed from REDUCE
revision 6726 when REDUCE is run using a batch file.  If you had
customized @code{reduce-run-commands} then you @emph{may} need to
erase the customization (at least for PSL REDUCE) and then
re-customize it.

@c -------------------------------------------------------------------

@node REDUCE on Windows, REDUCE on Unix, Run Installation, Running
@section Running REDUCE on Microsoft Windows
@cindex Microsoft Windows
@cindex Windows
@cindex Running REDUCE on Microsoft Windows

The REDUCE installer does not add the REDUCE executable folder to your
path, so by default you can run REDUCE only via absolute pathnames,
which is what the shortcuts added to the @emph{Start} menu do.
Therefore, REDUCE Run mode also uses absolute pathnames if it can find
them, which it does by looking for the installation directory
@file{\Program Files\Reduce\} in all local drives (drive letters
@code{C:} to @code{Z:}).

The default configuration runs REDUCE directly rather than via the
@code{.bat} files, which avoids the query @emph{Terminate batch job
(Y/N)?} when REDUCE is killed (such as by attempting to interrupt it).
Temporarily, the @code{.bat} commands remain available for comparison.

Note that it is necessary to use the argument @code{-nocd} with the
CSL REDUCE command @code{redcsl.bat} to preserve the current working
directory.

@c -------------------------------------------------------------------

@node REDUCE on Unix, Running REDUCE, REDUCE on Windows, Running
@section Running REDUCE on Unix-like platforms
@cindex Unix-like platforms
@cindex Linux, macOS, etc.
@cindex Running REDUCE on Unix-like platforms

On Unix-like platforms (Linux, macOS, etc.), the behaviour of CSL
REDUCE depends on the terminal type as specified by the value of the
environment variable @env{TERM}.  In order to be able to interrupt CSL
REDUCE without causing it to terminate, @env{TERM} needs to be set to
something appropriate rather than the default value of @code{dumb}.
This is controlled by the value of @code{reduce-run-terminal}, which
defaults to @code{"Eterm"} except on Microsoft Windows, where it
defaults to @code{nil} to disable this facility.

@c -------------------------------------------------------------------

@node Running REDUCE, Running Programs, REDUCE on Unix, Running
@section Running, rerunning and switching to REDUCE
@cindex Multiple Process Support
@cindex Process Support, Multiple
@cindex Support for Multiple Process

The main command to start REDUCE is @command{run-reduce}, which is
bound to the key @kbd{M-R} (that's a capital @code{R}, so use
@kbd{@key{META}-@key{SHIFT}-r}) in REDUCE mode.  It is also available
in the REDUCE mode @emph{Run REDUCE} menu.

If the option @code{reduce-run-multiple} is non-nil (which by default
it is) then @command{run-reduce} starts a new REDUCE process every
time it is executed; successive REDUCE process buffers have
successively higher numbers at the end of their names, e.g.@:
@code{*CSL REDUCE*}, @code{*CSL REDUCE 1*}, @code{*CSL REDUCE 2*},
@enddots{}  Otherwise it only starts a new REDUCE process if necessary
-- if an appropriate REDUCE process is already running then it simply
switches to it.  Finally, these commands run the hooks from
@code{reduce-run-mode-hook} (after the @code{comint-mode-hook} is
run).

If the option @code{reduce-run-autostart} is non-nil (which by default
it is) then all commands that require a REDUCE process automatically
start one if necessary.  @xref{Run Customization,, Customization of
REDUCE Run mode}.  Where appropriate, input commands have their own
history lists, and if run in REDUCE mode then any input file defaults
to the file being edited.

@table @kbd
@item M-R
@kindex M-R
@itemx M-x run-reduce
@findex run-reduce
This command prompts for the name of a REDUCE command in the
minibuffer, using completion and ignoring case.  The REDUCE command
names are as specified by the option @code{reduce-run-commands} and
the default command name is as specified by the option
@code{reduce-run-command-name-default}, if non-nil.  If you don’t
provide a command name, i.e.@: you just hit @key{RET}, then the
command aborts.  The REDUCE process buffer is named using the name of
the REDUCE command that it runs, e.g.@: @code{*CSL REDUCE*} or
@code{*PSL REDUCE*}.

If this command is executed with a prefix argument then it reads an
actual command to run REDUCE from the minibuffer and runs that
command.  In this case, the REDUCE process buffer is named without any
reference to the REDUCE command, e.g.@: @code{*REDUCE*}.
@end table

A couple of convenience commands allow you to re-start a running
REDUCE process in the same buffer and switch from any REDUCE-mode
buffer to a running REDUCE process buffer.

@table @kbd
@item M-x rerun-reduce
@findex rerun-reduce
This command is defined only in REDUCE Run mode, i.e.@: in a REDUCE
process buffer.  If REDUCE is running in the current buffer then it is
terminated.  The command then reruns the REDUCE command whose name is
shown in the buffer name.  If no command name is shown then it uses
the previous explicit command.  @strong{Beware that this command
previously had the now-obsolete name @code{re-run-reduce}.}

@item C-c C-z
@kindex C-c C-z
@itemx M-x switch-to-reduce
@findex switch-to-reduce
This command is defined only in REDUCE mode.  It is primarily intended
for internal use by other commands but it can be used interactively to
switch to a running REDUCE process buffer.  If the current buffer is
an active REDUCE process buffer then the command does nothing; if
there is only one active REDUCE process buffer then the command
switches to it; otherwise, the command reads the name of an active
REDUCE process buffer from the minibuffer with completion.  This means
that pressing the @key{TAB} key will give a list of active REDUCE
process buffers from which to select one.  It remembers the last
buffer used and offers that as the default, making it easy to switch
repeatedly to the same REDUCE process buffer.  This function is used
by all commands described below that send REDUCE code fragments to a
running REDUCE process.  With an interactive argument, position the
cursor at the end of the REDUCE process buffer.

If REDUCE is not running then this command will start REDUCE
automatically by calling @command{run-reduce} if the option
@code{reduce-run-autostart} is non-nil (which by default it is).
@end table

Within a running REDUCE process buffer, pressing @key{RET} at the end
of a line of input sends it to REDUCE, as with the standard REDUCE
interfaces.  However, if there is no terminator at the end of the line
then a @code{;} is automatically appended, unless there is a @code{?}
in the input line (implying that the input is the response to a user
query, which must not be followed by a terminator).  You can avoid
this automatic behaviour completely by holding down the @key{SHIFT}
key, i.e.@: by pressing @key{SHIFT}-@key{RET}.  Also, if there is no
input then a newline (with no terminator) is sent to REDUCE to support
use of @code{on demo}.


@table @kbd
@item RET
@kindex RET
@itemx reduce-run-send-input
@findex reduce-run-send-input
Send the preceding input to REDUCE after appending a @code{;} if
appropriate; holding down the @key{SHIFT} key avoids this.  If there
is no input then send a newline with no terminator.
@end table

The following REDUCE mode key binding is also available in REDUCE Run
mode.

@table @kbd
@item M-TAB
@kindex M-TAB
@itemx C-c TAB
@kindex C-c TAB
@itemx reduce-complete-symbol
@findex reduce-complete-symbol
Perform completion on the REDUCE symbol preceding point (or preceding
the region if it is active).  Compare that symbol against the elements
of @code{reduce-completion-alist}.  If a perfect match (only) has a
@code{cdr} then delete the match and insert the @code{cdr} if it is a
string or call it if it is a (nullary) function, passing on any prefix
argument (in raw form).
@end table

Note that most of the default key bindings provided by comint mode are
also available in REDUCE Run mode.

The REDUCE Run library provides a REDUCE Run major mode menu and also
adds a slightly modified version of this menu to the menu bar in
REDUCE mode.  These two menus provide appropriate access to all the
REDUCE Run mode commands.

@c -------------------------------------------------------------------

@node Running Programs, Evaluating Code, Running REDUCE, Running
@section Running complete REDUCE programs

The commands @command{reduce-run-file} and @command{reduce-run-buffer}
run REDUCE code as an independent REDUCE program by starting the
specified version of REDUCE in a new process buffer named uniquely by
the file or buffer containing the REDUCE code.  This allows several
REDUCE programs to be conveniently run simultaneously and
independently.  Both commands prompt for the REDUCE command to run
(via @code{run-reduce}).

@table @kbd
@item C-c C-M-f
@kindex C-c C-M-f
@itemx M-x reduce-run-file
@findex reduce-run-file
This command reads a file name from the minibuffer, starts REDUCE in a
new process buffer named uniquely by the file (unless it already
exists) and inputs the file into REDUCE.  It asks whether you want the
input echoed.  The key binding is provided in both REDUCE Edit and Run
modes.

@item C-c C-M-b
@kindex C-c C-M-b
@itemx M-x reduce-run-buffer
@findex reduce-run-buffer
This command starts REDUCE in a new process buffer named uniquely by
the current buffer (unless it already exists) and inputs the current
buffer into REDUCE.  The key binding is provided in REDUCE mode only.
@end table

@c -------------------------------------------------------------------

@node Evaluating Code, Processing Files, Running Programs, Running
@section Inputting code fragments to REDUCE
@cindex Key bindings
@cindex Menu

When developing REDUCE code, it may be convenient to be able to test
fragments by inputting them into REDUCE@.  The following commands are
intended to be used in a REDUCE mode buffer to send code to a REDUCE
process buffer.  They all use @command{switch-to-reduce} to decide
where to send the code.  With a prefix argument, the commands also
explicitly switch to the REDUCE process window.

The following key bindings are added to REDUCE mode:

@table @kbd
@item C-x C-e
@kindex C-x C-e
@itemx M-x reduce-eval-last-statement
@findex reduce-eval-last-statement
This command sends the code between the beginning of the statement
before point and point to REDUCE.  The assumption is that point is at
the end of a REDUCE statement, but this is not checked so it is
possible to send an incomplete statement.  (This key binding follows the
Emacs convention and is available in both REDUCE Edit and Run modes.)

@item C-x C-M-e
@kindex C-x C-M-e
@itemx M-x reduce-eval-line
@findex reduce-eval-line
This command sends the current line of code to REDUCE.  A prefix
argument means also switch to the REDUCE window.  (This key binding is
available in both REDUCE Edit and Run modes.)

@item C-M-x
@kindex C-M-x
@itemx C-c C-e
@kindex C-c C-e
@itemx M-x reduce-eval-proc
@findex reduce-eval-proc
This command sends the procedure definition ending after point to
REDUCE@.  (The @kbd{C-M-x} key binding follows the Emacs convention.)

@item C-c C-r
@kindex C-c C-r
@itemx M-x reduce-eval-region
@findex reduce-eval-region
This command sends the code in the selected region to REDUCE.
@end table

@c -------------------------------------------------------------------

@node Processing Files,  , Evaluating Code, Running
@section Inputting, loading and compiling REDUCE files
@cindex Key bindings
@cindex Menu

The following commands deal with complete REDUCE files that do not
necessarily constitute complete programs.  The key bindings are
provided in both REDUCE Edit and Run modes:

@table @kbd
@item C-c C-f
@kindex C-c C-f
@itemx M-x reduce-input-file
@findex reduce-input-file
Read a file name from the minibuffer and input the file into a REDUCE
process.  It asks whether you want the input echoed.

@item C-c C-M-l
@kindex C-c C-M-l
@itemx M-x reduce-load-package
@findex reduce-load-package
Read a REDUCE package name from the minibuffer and load it into a
REDUCE process.  The read process uses completion based on the file
@code{package.map} in the REDUCE source code package directory
specified by the option @code{reduce-packages-directory}, which
should automatically be set correctly when REDUCE Run mode loads.
Pressing the @key{TAB} key should list the packages available, from
which you can select in the usual way, such as by clicking on a
package name with the mouse.

@item C-c C-M-c
@kindex C-c C-M-c
@itemx M-x reduce-compile-file
@findex reduce-compile-file
Read a file name from the minibuffer and compile it into a
fast-loading (``fasl'') file, for which it prompts for the name with a
name based on the source file name as default.  It asks whether you
want the input echoed.
@end table

@c ===================================================================

@node Miscellaneous, Customization, Running, Top
@chapter Miscellaneous features
@cindex Miscellaneous
@cindex Features

REDUCE mode extends some of the standard Emacs handling of
parenthesised ``lists'' to include REDUCE group and block constructs.
It provides a major mode menu and easy access to its version
information.  This chapter also describes how to access some special
function keys that are useful in Emacs in general and in REDUCE mode
in particular.

@menu
* Groups and blocks highlighting::  Delimiter highlighting
* Major mode menu::             Major mode menu
* Version::                     REDUCE IDE version information
* Special function keys::       Linefeed, Meta-TAB, etc.
@end menu

@c -------------------------------------------------------------------

@node Groups and blocks highlighting, Major mode menu, Miscellaneous, Miscellaneous
@section Groups and blocks: delimiter highlighting
@cindex Groups
@cindex Blocks
@cindex Delimiters
@cindex Highlighting

Delimiters for groups (@code{<<} and @code{>>}) and blocks
(@code{begin} and @code{end}) are treated like brackets.  Either
highlighting of matching group and block delimiters or (group only)
blink matching is toggled by the command
@code{reduce-show-delim-mode}.

REDUCE Show Delim mode is based closely on Show Paren mode;
@ref{Matching,, Automatic Display Of Matching Parentheses, emacs, The
Emacs Editor}.  It is completely independent except that all settings
default to the corresponding values for Show Paren mode.  Show Delim
mode applies to both REDUCE mode and REDUCE Run mode (@ref{Running})
and is turned on automatically when a REDUCE mode is selected if
@code{reduce-show-delim-mode-on} is non-nil, which it is by default if
Show Paren mode is on.

Note that highlighting of matching group and block delimiters does not
work when point is @emph{within} a delimiter.  (This cannot happen
with brackets, which are single characters).  This may be changed in
future.

@table @kbd
@item M-x reduce-show-delim-mode
@findex reduce-show-delim-mode
Toggle REDUCE Show Delim mode.  With a prefix argument, turn the mode
on if and only if the argument is positive.  REDUCE Show Delim mode
highlights matching group or block delimiters after
@code{show-paren-delay} seconds of Emacs idle time.
@end table

Show Delim mode is a buffer-local minor mode.  Whenever point is
before an opening delimiter or after a closing delimiter, the
delimiter, its matching delimiter, and optionally the text between
them are highlighted.  To customize REDUCE Show Delim mode, type
@kbd{M-x customize-group @key{RET} reduce-delim-showing}.  The
customizable options which control the operation of this mode include
the following:

@itemize
@item
@code{reduce-show-delim-highlight-opendelim} controls whether to
highlight an opening delimiter when point stands just before it, and
hence its position is marked by the cursor anyway.  The default is the
value of @code{show-paren-highlight-openparen}.
@item
@code{reduce-show-delim-style} controls whether just the two
delimiters, or also the space between them get highlighted.  The valid
options here are @code{delimiter} (show the matching delimiter),
@code{expression} (highlight the entire expression enclosed by the
delimiters), and @code{mixed} (highlight the matching delimiter if it
is visible, the expression otherwise).  The default is determined by
the value of @code{show-paren-style}.
@item
@code{reduce-show-delim-when-point-inside-delim}, when non-@code{nil},
causes highlighting also when point is immediately inside a delimiter.
The default is the value of @code{show-paren-when-point-inside-paren}.
@item
@code{reduce-show-delim-when-point-in-periphery}, when non-@code{nil},
causes highlighting also when point is in whitespace at the beginning
or end of a line, and there is respectively an opening or closing
delimiter as the first or last non-whitespace characters on the line.
The default is the value of @code{show-paren-when-point-in-periphery}.
@end itemize

@c -------------------------------------------------------------------

@node Major mode menu, Version, Groups and blocks highlighting, Miscellaneous
@section Major mode menu
@cindex Major mode menu
@cindex Menu, Major mode

@kindex C-down-mouse-3
@findex mouse-major-mode-menu
REDUCE mode adds a major-mode menu called ``REDUCE'' to the menu bar,
which is also available as a pop-up menu activated by the command
@code{mouse-major-mode-menu} on the standard key @kbd{C-down-mouse-3}.

REDUCE Run mode adds a second major-mode menu called ``Run REDUCE'',
which appears immediately to the right of the ``REDUCE'' menu on the
menu bar and immediately below the ``REDUCE'' menu on the pop-up menu.
It is possible to have the ``Run REDUCE'' menu displayed even when
REDUCE Run mode is not loaded, which is controlled by the option
@code{reduce-run-autoload}.  @xref{Run Customization}.

@c -------------------------------------------------------------------

@node Version, Special function keys, Major mode menu, Miscellaneous
@section REDUCE IDE version information
@cindex REDUCE IDE version information
@cindex Version information
@cindex Information about version

The version of REDUCE IDE that is running is available as the value of
the variable @code{reduce-ide-version}, which is a string that can be
displayed in the echo area by selecting the @code{Show Version} menu
option from the REDUCE Edit or Run mode menu, or by running the
command @kbd{M-x reduce-ide-version} (both of which also record it in
the @code{*Messages*} buffer).  If no REDUCE mode is running then an
easy way to start REDUCE mode is to switch to a temporary buffer
(e.g.@: by using @kbd{C-x b tmp}) and then switch it to REDUCE mode
(by using @kbd{M-x reduce-mode}).

@c -------------------------------------------------------------------

@node Special function keys,  , Version, Miscellaneous
@section Special function keys
@cindex Special function keys
@cindex Function keys
@cindex Keys, special function
@cindex TAB
@kindex TAB
@cindex Meta-TAB
@kindex Meta-TAB

The standard key to complete a symbol is @kbd{Meta-@key{TAB}}, but
Microsoft Windows uses this key combination (referred to as @code{Alt
+ Tab}) to switch between open apps.  However, @kbd{@key{TAB}} can
always be accessed via its ASCII code as @kbd{C-i}, so
@kbd{Meta-@key{TAB}} can always be accessed as @kbd{C-M-i}.

@c ===================================================================

@node Customization, Feedback, Miscellaneous, Top
@chapter Options that control REDUCE IDE
@cindex Customization
@cindex Options
@cindex Variables

REDUCE IDE supports a small amount of customization and the following
options can be changed using the standard Emacs customization
facilities.  The main REDUCE IDE customization group is called
``REDUCE'', under which are the four sub-groups ``REDUCE Display'',
``REDUCE Format'', ``REDUCE Interface'' and ``REDUCE Run''.  Every
customizable option includes a link to the appropriate section of this
manual.

REDUCE mode inherits from @code{prog-mode}, so some of its options
also affects this mode.  The @code{prog-mode} customization group can
be accessed via a link in the REDUCE customization group.

REDUCE IDE font-lock support can be customized by resetting standard
font-lock variables (@pxref{Font-Lock,, Font-lock support for automatic
font selection}).

@menu
* Hooks::                       REDUCE IDE hooks
* Display Customization::       REDUCE mode display customization
* Format Customization::        REDUCE mode format customization
* Interface Customization::     REDUCE mode interface customization
* Run Customization::           REDUCE Run mode customization
@end menu

@node Hooks, Display Customization, Customization, Customization
@section REDUCE IDE hooks
@cindex Hooks

Hooks allow arbitrary customization that is not supported by the
standard customization facilities.  When REDUCE mode or REDUCE Run
mode is loaded into Emacs, the last step of the loading process is to
execute the function(s) assigned to the load hook.  This hook would be
appropriate for modifying global properties of the mode such as its
key map.

When REDUCE mode or REDUCE Run mode is activated in a buffer the last
step of its initialization process is to execute the function(s)
assigned to the mode hook.  This hook would be appropriate for
modifying properties local to the buffer.

@xref{Installation,, Installation of the REDUCE IDE}, for further
details.

@vtable @code
@item prog-mode-hook
Default value @code{nil}.  Normal hook run when entering programming
modes.  Functions added to this hook apply to all programming modes.
They are run @emph{before} any functions on @code{reduce-mode-hook}.

@item reduce-mode-load-hook
Default value @code{nil}.  List of functions to be called when REDUCE
mode is loaded.  It can be used to customize global features of REDUCE
mode such as its key map, i.e.@: it is a good place to put key
bindings.

However, adding the function @code{require-reduce-run} to this hook to
automatically load @code{reduce-run} is no longer supported and the
function has been removed; instead, please customize the option
@code{reduce-run-autoload}.  @xref{Run Customization}.

@item reduce-mode-hook
Default value @code{nil}.  List of functions to be called when REDUCE
mode is entered.  It can be used to customize buffer-local features of
REDUCE mode, e.g.@: use @code{turn-on-font-lock} to turn on font-lock
mode locally.

@item reduce-run-load-hook
Default value @code{nil}.  The hook run when REDUCE Run mode is
loaded.  It is a good place to put key bindings.

@item reduce-run-mode-hook
Default value @code{nil}.  The main hook for customizing REDUCE Run
mode.
@end vtable

@c -------------------------------------------------------------------

@node Display Customization, Format Customization, Hooks, Customization
@section REDUCE mode display customization
@cindex Display customization

Options that control how REDUCE source code is displayed in REDUCE
mode but have no effect on the code itself.

@vtable @code
@item reduce-font-lock-mode-on
Default value @code{t}.  If non-nil then turn on REDUCE Font Lock mode
automatically.  REDUCE Font Lock mode automatically selects the font
in which text is displayed (“fontifies” it) so as to indicate its
logical status.

Once REDUCE Font Lock mode has been turned on, it can be
controlled by the standard Emacs Font Lock facilities.

@item reduce-show-delim-mode-on
Default value the value of @code{show-paren-mode}.  If non-nil then
turn on REDUCE Show Delim mode automatically.  REDUCE Show Delim mode
displays highlighting on whatever group or block delimiter matches the
one before or after point.

This is a buffer-local minor mode so it can also be turned on and off
in each buffer independently using the command
@code{reduce-show-delim-mode}.

@item reduce-show-proc-delay
Obsolete; replaced by @code{idle-update-delay}.

@item reduce-show-proc-mode
Obsolete; effectively replaced by @code{reduce-show-proc-mode-on}.

@item reduce-show-proc-mode-on
Default value @code{t}.  If non-nil then turn on REDUCE Show Proc mode
automatically.  REDUCE Show Proc mode displays the current procedure
name in the mode line and updates it after @code{idle-update-delay}
seconds of Emacs idle time.

This is a buffer-local minor mode so it can also be turned on and
off in each buffer independently using the command
@code{reduce-show-proc-mode}.
@end vtable

@subsection Subgroup: Reduce Delim Showing

Further details of showing (un)matching of group/block delimiters and
enclosed expressions.

@c -------------------------------------------------------------------

@node Format Customization, Interface Customization, Display Customization, Customization
@section REDUCE mode format customization
@cindex Format customization

Options that control the automatic formatting of REDUCE source code by
REDUCE mode editing commands.

@vtable @code
@item reduce-auto-indent-delay
Default value 0.125.  Time in seconds to delay before maybe re-indenting
current line.

@item reduce-auto-indent-mode-on
Default value @code{t}.  If non-nil then turn on REDUCE Auto Indent
mode automatically.  REDUCE Auto Indent mode re-indents the current
line after @code{reduce-auto-indent-delay} seconds of Emacs idle time
if the text just typed matches @code{reduce-auto-indent-regexp}.

@item reduce-auto-indent-regexp
Default value @code{\_<\(?:else\|end\|>>\)\_>.*\=}.  Auto
indent the current line if the text just typed matches this regexp.
It should end with @code{\=}.

@item reduce-comment-region-string
Default value @samp{%% }.  String inserted by
@code{reduce-comment-region} or @code{reduce-comment-procedure} at the
start of each line.

@item reduce-indentation
Default value 3.  Depth of successive indentation in REDUCE code.
@end vtable

@c -------------------------------------------------------------------

@node Interface Customization, Run Customization, Format Customization, Customization
@section REDUCE mode interface customization
@cindex Interface customization

Options that control the REDUCE mode user interface.

@vtable @code
@item reduce-completion-alist
Association list of REDUCE-mode completions searched by
@code{reduce-complete-symbol}.  Each key word or phrase to be simply
completed should be a list containing a single string.  If a perfectly
matched string (only) is a non-trivial pair then the match is deleted
and the @code{cdr} inserted if it is a string or called if it is a
(nullary) function, passing on any prefix argument (in raw form).

@item reduce-etags-directory
Directory containing the @code{etags} program, or @code{nil} if it is
in path.  If non-nil the string must end with @code{/}.

@item reduce-imenu
Obsolete; renamed to @code{reduce-imenu-add}.

@item reduce-imenu-add
Default value @code{t}.  If non-nil REDUCE mode automatically calls
@code{imenu-add-menubar-index}, which adds an ``Index'' menu to the
menubar.

@item reduce-imenu-generic-expression
Obsolete.

@item reduce-imenu-title
Obsolete.

@item reduce-max-escape-tries
Default value 2.  Number of repeats of @code{reduce-forward-statement}
or @code{reduce-backward-statement} required to escape out of a block
or group.  (This option was previously called
@code{reduce-max-up-tries}.)
@end vtable

@c -------------------------------------------------------------------

@node Run Customization,  , Interface Customization, Customization
@section REDUCE Run mode customization
@cindex Run customization

@strong{The option @code{reduce-run-commands} must be set correctly
otherwise REDUCE will not run correctly.  The settings of other
options are less critical.}

REDUCE Run inherits from comint, so comint options also affects this
mode.  The @code{comint} customization group can be accessed via a
link in the REDUCE Run customization group.

@vtable @code
@item reduce-input-filter
Default value @code{"\\`\\([ \t;$]*\\|[ \t]*.[ \t]*\\)\\'"}.  What not
to save on REDUCE Run mode's input history.  The value is a regular
expression (regexp).  The default matches any combination of zero or
more whitespace characters and/or statement terminators, or any single
character (e.g.@: @kbd{y} or @kbd{n}) possibly surrounded by
whitespace.

@item reduce-packages-directory
This option is obsolete since version 1.13.  The packages directory is
assumed to be a sub-directory of the root directory.

@item reduce-root-dir-file-name
Default value @file{?:/Program Files/Reduce} on Microsoft Windows,
where @code{?} is a letter @code{C}--@code{Z}, and
@file{/usr/share/reduce} on other platforms.  Absolute root directory
file name of the REDUCE installation, or nil if not set.  It is the
directory containing the @file{packages} directory and, on Microsoft
Windows, the @file{bin} directory containing the user-executable batch
files.  On Microsoft Windows, REDUCE Run mode attempts to determine
the correct drive letter automatically.  Note that you can complete
the directory name using @kbd{M-@key{TAB}}.

@item reduce-run-autoload
Whether, and if so how, to autoload REDUCE Run mode.  Loading it is
necessary only if you plan to run REDUCE within REDUCE IDE@.  If the
value is @code{t} then load REDUCE Run mode after @code{reduce-mode}
has loaded; if it is @code{menu} (the default) then display the Run
REDUCE menu in REDUCE mode; if it is @code{nil} then do nothing.

@item reduce-run-autostart
Default value @code{t}.  If non-nil then all commands that require a
REDUCE process will automatically start a new one if none is already
running.

@item reduce-run-commands
The definition of this option changed in version 1.12 and again
slightly in version 1.13.

An association list with an element for each version of REDUCE, which
is a list.  The first element of each list is the command name as a
string, by default either "CSL" or "PSL"; the second element is either
@code{nil} or the root directory for this REDUCE command, which is
also used to set the environment variable @code{reduce}; the third
element is the program to run as a string, which must be either an
absolute pathname or a command name to be looked up on the execution
path; subsequent elements are optional command arguments as strings.
The root directory defaults to the value of the option
@code{reduce-root-dir-file-name}.  Strings may contain spaces and may
begin with the shortcut @code{$reduce}, which is replaced with the
root directory.  Each command must run REDUCE using a command-line
interface.

By default, REDUCE Run mode on Microsoft Windows uses absolute
pathnames and runs REDUCE directly rather than via batch files,
whereas on other platforms it uses the shell scripts that should be
found on the execution path.

@item reduce-run-command-name-default
Default value the first command name in @code{reduce-run-commands}.
If non-nil then the value specifies the default REDUCE command name.

@item reduce-run-installation-directory
Renamed to @code{reduce-root-dir-file-name} with a slightly different
definition in version 1.12.

@item reduce-run-mswin-drives
Subsumed into @code{reduce-root-dir-file-name} and removed in version
1.12.

@item reduce-run-multiple
Default value @code{t}.  If non-nil then commands that explicitly
start REDUCE will always start a new REDUCE process in a new distinct
buffer, even if REDUCE is already running.  Otherwise, they will
re-use any appropriate running REDUCE process.

@item reduce-run-prompt
Default value @code{"^\\(?:[0-9]+[:*] \\)+"}.  The regexp to recognise
prompts in REDUCE Run mode.  This variable is used to initialize
@code{comint-prompt-regexp} in the REDUCE run buffer.

@item reduce-run-terminal
Default value @code{nil} on Microsoft Windows and @code{"Eterm"} on
all other platforms.  If non-@code{nil}, this specifies the value of
@code{TERM} to use, which is intended only for Unix-like platforms.
This sets @code{comint-terminfo-terminal} to the value of
@code{reduce-run-terminal} and @code{system-uses-terminfo} to @code{t}
locally within @code{run-reduce} so that CSL REDUCE responds
appropriately to interrupts, which with a dumb terminal it does not.
A @code{nil} value means use the Emacs defaults.  Possible values to
try are @code{"Eterm"}, @code{"emacs"}, @code{"xterm"}.

@item reduce-source-modes
Default value @code{(reduce-mode)}.  Used to determine if a buffer
contains REDUCE source code.  If a file is loaded into a buffer that is
in one of these major modes then it is considered to be a REDUCE source
file by @code{reduce-input-file} and @code{reduce-fasl-file}.  Used by
these commands to determine defaults.
@end vtable

@c ===================================================================

@node Feedback, Command Index, Customization, Top
@chapter Feedback: bug reports, suggestions, comments, @dots{}
@cindex Feedback
@cindex Bug reports
@cindex Suggestions
@cindex Comments
@cindex Contact

Feedback is welcome, including reports of errors or features that do
not work well and suggestions for improvements or additional features.
You can provide feedback in several ways:

@itemize
@item
informally using email (or a web form) via
@uref{https://sites.google.com/site/fjwcentaur/feedback, my website};

@item
via my @uref{https://github.com/fjwright/REDUCE-IDE/issues, GitHub
issue tracker}, for which you must be logged in to GitHub;

@item
via the main @uref{https://sourceforge.net/p/reduce-algebra/bugs/,
REDUCE bug tracker}, for which you must be logged in to SourceForge.
@end itemize

If possible, please include details of the version of Emacs that you
are using, the platform on which you are using it, and the version of
REDUCE IDE that you are using.  (This information is essential if you
are reporting a bug.)  An easy way to do this is to send me the Emacs
and REDUCE IDE version strings.  You can access the former from the
standard Emacs @code{Help} menu and the latter from the REDUCE major
mode menus, in all cases by selecting the @code{Show Version} menu
option.  The version strings can also be accessed by running the
commands @kbd{M-x emacs-version} and @kbd{M-x reduce-ide-version}.
These menu options and commands will display the version string in the
echo area at the bottom of the frame; it will also be recorded in the
@code{*Messages*} buffer, from where it can easily be copied.

@c ===================================================================

@comment END OF MANUAL TEXT
@page

@node Command Index, Variable Index, Feedback, Top
@unnumbered Command Index

@printindex fn

@node Variable Index, Keystroke Index, Command Index, Top
@unnumbered Variable Index

@printindex vr

@node Keystroke Index, Concept Index, Variable Index, Top
@unnumbered Keystroke Index

@printindex ky

@c Without a page throw here, the page length seems to get reset to the
@c depth of the index that fits on the page after the previous index.
@c This must be a bug!

@c @page

@node Concept Index,  , Keystroke Index, Top
@unnumbered Concept Index

@printindex cp

@bye


Formatting this file on Windows
===============================

This only seems to work using Cygwin.  Install the texinfo and
texinfo-tex packages (which also installs a lot of dependent packages,
including texlive).  Then run the following commands from the Cygwin
bash shell.  (They don't run in Emacs or from other shells.)

To format as info: makeinfo reduce-ide.texinfo

To format as HTML: makeinfo --html reduce-ide.texinfo

To format as PDF: texi2pdf --build=tidy reduce-ide.texinfo