1\input texinfo 2@c %**start of header 3@settitle GNU Emacs REDUCE Integrated Development Environment 4@c Version: $Id: reduce-ide.texinfo 4710 2018-08-04 16:45:18Z fjwright $ 5@c Manual last updated: 6@set UPDATED Time-stamp: <2018-08-04 17:42:09 fjw> 7@c Software version: 8@set VERSION 1.54 9@afourpaper 10@c With different size paper the printed page breaks will need attention! 11@c Look for @page and @need commands. 12@setchapternewpage off 13@paragraphindent 3 14@c %**end of header 15 16@dircategory GNU Emacs Lisp 17@direntry 18* REDUCE IDE: (reduce-ide). REDUCE Integrated Development Environment. 19@end direntry 20 21@copying 22This manual is for REDUCE IDE (version @value{VERSION}, updated 23@value{UPDATED}), which provides GNU Emacs major modes for editing and 24running REDUCE source code. 25 26Copyright @copyright{} 1994, 1996, 1999, 2012, 2017-2018 Francis J. Wright 27 28@quotation 29This manual and the software that it describes are subject to the GNU 30General Public License that is distributed with GNU Emacs -- see the 31file @file{COPYING}. 32 33Permission is granted to make and distribute verbatim copies of this 34manual provided the copyright notice and this permission notice are 35preserved on all copies. 36 37@ignore 38Permission is granted to process this file through TeX and print the 39results, provided the printed document carries a copying permission 40notice identical to this one except for the removal of this paragraph 41(this paragraph not being relevant to the printed manual). 42 43@end ignore 44Permission is granted to copy and distribute modified versions of this 45manual under the conditions for verbatim copying and provided that the 46entire resulting derived work is distributed under the terms of a 47permission notice identical to this one. 48 49Permission is granted to copy and distribute translations of this manual 50into another language, under the above conditions for modified 51versions. 52@end quotation 53@end copying 54 55@titlepage 56@title GNU Emacs REDUCE IDE 57@subtitle An Integrated Development Environment for REDUCE: 58@subtitle Major modes for editing and running REDUCE source code 59@subtitle Software version @value{VERSION} 60@author @uref{https://sourceforge.net/u/fjwright, Francis J. Wright} 61Manual last updated @value{UPDATED} 62 63@c The following two commands start the copyright page. 64@page 65@vskip 0pt plus 1filll 66@insertcopying 67@end titlepage 68 69@c Output the table of contents at the beginning. 70@contents 71 72@c =================================================================== 73 74@ifnottex 75@node Top, Introduction 76@top REDUCE Integrated Development Environment 77 78@display 79This manual is for REDUCE IDE, version @value{VERSION}. 80GNU Emacs major modes for editing and running REDUCE source code 81@uref{https://sourceforge.net/u/fjwright, Francis J. Wright} 82Manual last updated @value{UPDATED} 83@end display 84@end ifnottex 85 86@menu 87* Introduction:: What is REDUCE IDE? 88* Installation:: How to install REDUCE IDE 89* General:: General features of REDUCE edit mode 90* Statements:: Commands that operate on statements 91* Procedures:: Commands that operate on procedures 92* Comments:: Support for REDUCE comments 93* Indentation:: Commands for automatic indentation 94* Structures:: Structure templates 95* Completion:: Completion and expansion of REDUCE keywords 96* Font-Lock:: Font selection for syntactic highlighting 97* Access:: Access to procedure and operator definitions 98* Miscellaneous:: Miscellaneous minor features and bugs 99* Customization:: User options that control REDUCE IDE 100* Run:: Running REDUCE in a window 101* Feedback:: Bug reports, suggestions, comments, @dots{} 102* Command Index:: Index of REDUCE IDE commands 103* Variable Index:: Index of REDUCE IDE configuration variables 104* Keystroke Index:: Index of REDUCE IDE keystrokes 105* Concept Index:: Index of general REDUCE IDE concepts 106@end menu 107 108@c =================================================================== 109 110@node Introduction 111@chapter Introduction to REDUCE IDE 112@cindex Introduction to REDUCE IDE 113 114This manual documents the GNU Emacs Integrated Development Environment 115(IDE) for REDUCE, which comprises a primary major mode for 116syntax-directed editing of REDUCE source code (edit mode) and a 117subsidiary major mode for running REDUCE as an inferior process with 118input and output via a buffer (run mode). REDUCE is a system and 119language for algebraic computing developed originally by Anthony C. 120Hearn, which is now Open Source and available from 121@uref{https://sourceforge.net/projects/reduce-algebra/, SourceForge}. 122It therefore shares the GNU spirit of collaborative software 123development, which provided part of my motivation to begin this 124project. REDUCE is also written in Lisp, as is (most of) Emacs. 125However, the REDUCE user language is similar to Algol-60 (which looks 126a bit like a cross between Pascal and FORTRAN-77). 127 128I began development of REDUCE edit mode tentatively in late 1992 and 129seriously in early 1994, and continued sporadically until 2001. I 130began development of REDUCE run mode in late 1998. The latest 131versions of the software and documentation source code are available 132from 133@uref{https://sourceforge.net/p/reduce-algebra/code/HEAD/tree/trunk/generic/emacs/, 134SourceForge}. Comments, suggestions, bug reports, etc.@: are welcome. 135 136The current version of the REDUCE IDE is intended for use with GNU 137Emacs version 25 or later, which I will endeavour to support under 138recent versions of Microsoft Windows and Ubuntu Linux. It might run 139under closely related versions of GNU Emacs but I cannot explicitly 140support either XEmacs or other platforms. 141 142REDUCE IDE version 1.5 provides two major updates. One is a 143substantial rewrite of REDUCE run mode to provide explicit support for 144both CSL and PSL REDUCE, and for easily running multiple REDUCE 145processes simultaneously. The other is distribution as a multi-file 146package via @uref{http://reduce-algebra.sourceforge.net/reduce-ide/, 147the REDUCE IDE web page}, which makes installation and updating very 148easy via the GNU Emacs package manager (@pxref{Packages,, Emacs Lisp 149Packages, emacs, GNU Emacs Manual}). 150 151@strong{However, beware that in native Microsoft Windows GNU Emacs 152(only) PSL REDUCE currently does not run correctly without some 153additional support. The problem appears to be that PSL REDUCE needs 154to be explicitly run from a shell, which is arranged automatically if 155you use the GNU Emacs package manager. @xref{PSL on Windows} for 156further details.} 157 158This manual assumes that you are familiar in general with both Emacs 159and REDUCE. 160 161The purpose of REDUCE edit mode is to provide editing commands that are 162aware of the syntax of the REDUCE language, and therefore allow 163operations to be performed on the major syntactic elements, namely 164statements, procedures and comments. To the reader who has never used a 165syntax-directed editor, I can only say that it is surprisingly useful! 166In particular, the automatic indentation code provides valuable clues to 167potential REDUCE programming errors by showing how the REDUCE parser is 168likely to interpret the code (@pxref{Indentation,, Indenting REDUCE code 169automatically}). 170 171The purpose of REDUCE run mode is to provide a friendly interface to a 172@strong{command-line version} of REDUCE running as an inferior process 173in an Emacs buffer. REDUCE run mode inherits much of its 174functionality from REDUCE edit mode and cannot be run alone. The 175assumption is that normal use will involve editing one or more REDUCE 176source files and running REDUCE simultaneously, and this is what 177REDUCE run mode aims to support. REDUCE run mode is described in its 178own sub-manual: @pxref{Run, Running REDUCE in a buffer}. 179 180@kindex C-h m 181@findex describe-mode 182All REDUCE IDE commands are self-documenting as usual in Emacs, 183including in particular the modes themselves. Hence, for an overview of 184the version of a REDUCE mode that is actually installed in your Emacs, 185select it in some buffer and then give the command @kbd{C-h m} 186(@code{describe-mode}) or use the @kbd{Help} menu option @kbd{Describe}. 187 188@c =================================================================== 189 190@node Installation 191@chapter Installation of REDUCE IDE 192@cindex Installation of REDUCE IDE 193 194It is probably best to use the GNU Emacs package manager to install 195the latest complete REDUCE IDE package as described in the 196@uref{http://reduce-algebra.sourceforge.net/reduce-ide/#installation, 197installation section of the main REDUCE IDE web page}. None of the 198manual installation described below is then required. 199 200The rest of this chapter, and the related section of the chapter on 201REDUCE run mode, are for users who want to install and configure 202REDUCE IDE ``by hand'', or who want to understand the installation 203process. 204 205REDUCE edit mode is provided by a file called @file{reduce-mode.el}, 206which is a file of Emacs Lisp source code. This file should be 207byte-compiled, and the compiled file @file{reduce-mode.elc} should be 208installed in the normal directory from which Emacs loads its Lisp code 209(if you have suitable permission). Otherwise, customize your Emacs 210@code{load-path} so that Emacs can find @file{reduce-mode.elc}. 211@xref{Customization,,,emacs, The Emacs Editor}. 212 213Emacs initialization and customization is stored in a file that is 214normally called @file{.emacs} and lives in your home directory. The 215precise meaning of ``home directory'' depends on both your OS and 216Emacs version; the easiest way to find it in Emacs is to visit the 217directory @file{~}, or just visit the file @file{~/.emacs} directly. 218Your @file{.emacs} file is updated automatically by the Emacs 219customization facility and you can also edit it by hand to add other 220configuration. @xref{Init File,,,emacs,The Emacs Editor}. 221 222@findex load-library 223Before REDUCE mode can be used, the file @file{reduce-mode.elc} must be 224loaded. This is necessary only once per Emacs session. It can be 225loaded explicitly, most easily by giving the command @kbd{M-x 226load-library reduce-mode}. However, you will probably want 227@file{reduce-mode.elc} to be loaded automatically the first time you 228(explicitly or implicitly) turn on REDUCE mode. The way to do this, on 229a per-user basis, is to put the following statement into your 230@file{.emacs} file: 231 232@findex autoload 233@lisp 234(autoload 'reduce-mode "reduce-mode" 235 "Major mode for REDUCE code editing" t) 236@end lisp 237 238This statement is completely innocuous and will have no effect unless 239you select REDUCE mode. It could therefore quite safely be put in a 240system-wide configuration file (e.g.@: @file{default.el} or 241@file{site-start.el}). @xref{Init File,,,emacs,The Emacs Editor}. 242 243It is also very convenient to have REDUCE mode turned on automatically 244when editing a REDUCE source code file. This can be done based on the 245``extension'' of the filename. Provided you end all REDUCE source code 246file names with the standard extension @file{.red}, the following 247statement in your @file{.emacs} file will have the desired effect: 248 249@vindex auto-mode-alist 250@lisp 251(add-to-list 'auto-mode-alist '("\\.red\\'" . reduce-mode)) 252@end lisp 253 254You can use other extensions as well or instead; if you use a different 255file naming convention then make the appropriate change(s) to the above 256statement. Emacs also provides other facilities that can be used for 257controlling major modes. 258 259Installation of REDUCE run mode is documented separately. @xref{Run, , 260Running REDUCE in a buffer}. 261 262@c =================================================================== 263 264@node General 265@chapter General features of REDUCE edit mode 266@cindex General features 267@cindex Features 268 269@findex reduce-mode 270REDUCE edit mode can be selected by giving the command @kbd{M-x 271reduce-mode}, although normally it will be selected automatically, 272probably via the filename extension (@pxref{Installation,, Installation 273of the REDUCE IDE}). 274 275The commands provided by REDUCE mode are aware of REDUCE syntax and 276ignore the contents of strings and the case of characters. Except for 277the special comment commands (@pxref{Comments,, Support for REDUCE 278comments}), they also ignore comments. The standard GNU Emacs 279indentation (@pxref{Indentation,, Indenting REDUCE code automatically}) 280and comment commands are supported, either via the general Emacs 281mechanisms or by re-binding the standard keys to REDUCE-mode versions of 282standard commands. The design of this mode is modelled primarily on 283Lisp mode and at present the comment conventions basically follow those 284of Lisp mode, except that comments are started by percent (@code{%}) 285signs or the keyword @code{comment}. It has also taken some ideas from 286FORTRAN mode. 287 288The standard Emacs syntax tables have been modified to reflect REDUCE 289syntax, so that for example Emacs knows that the REDUCE escape character 290is @code{!}. However, there remain some unresolved problems concerning 291the REDUCE escape character. @xref{Font-Lock,,Font-lock support for 292automatic font selection,,}. @xref{Miscellaneous,,Miscellaneous minor 293features and bugs,,}. 294 295Blank lines separate ``paragraphs''. 296 297Loading the REDUCE mode library runs any functions on 298@code{reduce-mode-load-hook}, which can be used to customize global 299features of REDUCE mode such as its key map. Entry to REDUCE mode runs 300any functions on @code{reduce-mode-hook}, which can be used to customize 301buffer-local features of REDUCE mode, e.g.@: to turn on font-lock mode. 302@xref{Installation,, Installation of the REDUCE IDE}. 303@xref{Customization,, Customization of the REDUCE IDE}. 304 305REDUCE mode is intended to support both the algebraic and symbolic modes 306of REDUCE@. It provides very limited support for Lisp syntax to the 307extent that it is likely to be used in symbolic-mode code, and hence it 308understands the significance of the quote symbol (@code{'}) to some 309extent. Syntax-directed editing naturally works correctly only if the 310syntax of the source code being edited is correct. If it is not then 311strange things can happen, and the services of the Emacs undo facilities 312may be required! 313 314@table @kbd 315@item DEL 316@kindex DEL 317@itemx M-x backward-delete-char-untabify 318@findex backward-delete-char-untabify 319Delete one character backwards, converting tabs to spaces if necessary. 320@end table 321 322A major mode menu provides convenient access to most of the major 323facilities of REDUCE mode. 324 325@c =================================================================== 326 327@node Statements 328@chapter Statement-oriented commands 329@cindex Statements 330@cindex Operations on Statements 331 332The most basic facility provided by REDUCE mode is the ability to move 333forward and backward by statement through a file of REDUCE source code. 334Moving by one statement means moving to the beginning or end of the 335@emph{logical} statement currently containing (or respectively preceding 336or following) point, which may involve skipping many actual statements 337that are contained within the current statement. In particular, as 338Emacs looks for the beginning or end of a statement it will skip 339complete compound statements (@code{begin @dots{} end}), group 340statements (@code{<< @dots{} >>}), and bracketed expressions 341(@code{(@dots{})}, @code{@{@dots{}@}} and @code{[@dots{}]}, even though 342square brackets are not normally used in REDUCE). Bracket skipping is 343controlled entirely by the Emacs syntax table. 344 345Hence, ``statement'' in this manual will normally mean a complete 346@emph{logical statement}. A syntax-directed editor clearly must perform 347a limited amount of parsing, but it must be remembered that a 348syntax-directed editor has the following important differences from a 349normal parser, because their basic purposes are different: 350 351@itemize @bullet 352@item 353A syntax-directed editor must be able to parse both forwards @emph{and 354backwards}. 355 356@item 357It will typically parse only locally for speed and must therefore parse 358based on incomplete information. 359 360@item 361It is provided for the convenience of the user and therefore need not 362obey precisely the full syntax of the language, provided it is 363consistent and reliable. 364@end itemize 365 366Emacs considers REDUCE statements to be terminated by the statement 367separator characters @code{;} and @code{$}. It also considers 368statements contained within any kind of brackets to be terminated by 369those brackets, statements within compound statements (@code{begin 370@dots{} end}) to be terminated by the @code{begin} and @code{end} 371keywords, and statements within group statements (@code{<< @dots{} >>}) 372to be terminated by the @code{<<} and @code{>>} tokens. Commas are not 373considered to separate statements. 374 375More precisely, a statement is considered to begin at the first 376non-white-space character following the previous statement separator, 377opening bracket, @code{begin} or @code{<<}. It is considered to end 378immediately after the first statement separator or immediately after the 379last non-white-space character preceding a closing bracket, @code{end} 380or @code{>>}. 381 382The current philosophy of REDUCE mode is that the statements within 383compound or group statements form essentially isolated systems, and that 384the basic statement-oriented commands should not move point either into 385or out of this system. Separate commands are provided to move into and 386out of compound and group statements. However, if you try hard enough, 387REDUCE mode will let a simple statement-oriented command move out of 388(but never into) a compound or group statement. Trying hard enough 389means repeating the same command enough times, which is determined by 390the value of the user option @code{reduce-max-up-tries} 391(@pxref{Customization,, Customization of the REDUCE IDE}), which 392currently has the default value 2. The overall effect of this is to 393enforce a brief pause (one ineffective command execution) that serves to 394prevent you from skipping out of a compound or group statement 395accidentally, but without causing any serious inconvenience. 396 397There is special code to handle the keyword @code{end} when it is used 398as the end-of-file marker. The following commands all accept a 399numerical argument, which defaults to 1. The commands to move forward 400or backward by statements do not move in the opposite direction if given 401a negative argument, in which case they do not move at all. 402 403@table @kbd 404@item C-c C-n 405@kindex C-c C-n 406@itemx M-x reduce-forward-statement 407@findex reduce-forward-statement 408Move forward to the end of the statement. With an argument, do it that 409many times. If looking at the end of a block or group, or the 410end-of-file marker, move over it after @code{reduce-max-up-tries} 411consecutive interactive tries. 412 413@item C-c C-p 414@kindex C-c C-p 415@itemx M-x reduce-backward-statement 416@findex reduce-backward-statement 417Move backward to the start of the statement. With an argument, do it 418that many times. If looking at the beginning of a block or group move 419over it after @code{reduce-max-up-tries} consecutive interactive tries. 420The end-of-file marker is treated as a statement. 421 422@item C-c C-k 423@kindex C-c C-k 424@itemx M-x reduce-kill-statement 425@findex reduce-kill-statement 426Kill the rest of the current statement; if there are no non-blank 427characters kill through the newline. With an argument, kill that many 428statements from point. Negative arguments kill complete statements 429backwards, cf.@: @code{kill-line}. 430 431@item C-c C-u 432@kindex C-c C-u 433@itemx M-x reduce-up-block-or-group 434@findex reduce-up-block-or-group 435Move backward up one level of block or group, i.e.@: to the beginning of 436the nearest unpaired @code{begin} or @code{<<}. A universal argument 437means move forward, i.e.@: to the end of the nearest unpaired @code{end} 438or @code{>>}. With a numeric argument, do it that many times, where a 439negative argument means move forward instead of backward. 440 441@item C-c C-d 442@kindex C-c C-d 443@itemx M-x reduce-down-block-or-group 444@findex reduce-down-block-or-group 445Move forward down one level of block or group, i.e.@: to the end of the 446nearest unpaired @code{begin} or @code{<<}. A universal argument means 447move backward to the beginning of the nearest unpaired @code{end} or 448@code{>>}. With a numeric argument, do it that many times, where a 449negative argument means move backward instead of forward. 450@end table 451 452@c =================================================================== 453 454@node Procedures 455@chapter Procedure-oriented commands 456@cindex Procedures 457@cindex Operations on Procedures 458 459Files of REDUCE source code frequently consist mainly of procedure 460definitions. This is certainly true of symbolic-mode code, and hence it 461is true of most of the source code of the REDUCE system itself. REDUCE 462mode provides the following operations on procedures. They work on all 463kinds of REDUCE procedures provided they contain the keyword 464@code{procedure} somewhere within the first statement of their 465definition. 466 467A procedure is considered to begin at the first non-white-space 468character of the definition, and to end after the statement defining the 469procedure body. White space and the first newline after the procedure 470body are always considered to be part of the procedure. The commands to 471mark, kill and reformat a procedure also include @emph{all} blank lines 472after the procedure definition, because this seems most convenient in 473practice. Some procedure-oriented commands support a prefix argument. 474 475The two commands for moving over procedures accept a positive integer 476argument that indicates by how many procedures to move -- the default is 4771. These commands do not move in the opposite direction if given a 478negative argument, in which case they do not move at all. 479 480@table @kbd 481@item C-M-e 482@kindex C-M-e 483@itemx M-x reduce-forward-procedure 484@findex reduce-forward-procedure 485Move forward to the next end of a procedure. With a numeric argument, 486do it that many times. 487 488@item C-M-a 489@kindex C-M-a 490@itemx M-x reduce-backward-procedure 491@findex reduce-backward-procedure 492Move backward to the next start of a procedure. With a numeric 493argument, do it that many times. 494@end table 495 496Regardless of whether point is within a procedure or not, these two 497commands move respectively to the first following end of a procedure, or 498the first preceding start of a procedure. To move to the start of the 499next procedure, move forward to its end and then move backward to its 500start. 501 502The remaining commands do not accept an argument because (even without 503an argument) they can change large portions of text. Marking a 504procedure is the basis of the other operations on procedures. 505 506@table @kbd 507@item C-M-h 508@kindex C-M-h 509@itemx M-x reduce-mark-procedure 510@findex reduce-mark-procedure 511Put the mark after the next end of a procedure and point at the start of 512that procedure. A procedure ends @emph{after} any trailing white space. 513With a numeric argument, mark that many following procedures including 514this one. 515 516@item C-c k 517@kindex C-c k 518@itemx M-x reduce-kill-procedure 519@findex reduce-kill-procedure 520Kill the procedure (and trailing white space) ending after point. 521 522@item C-M-q 523@kindex C-M-q 524@itemx M-x reduce-indent-procedure 525@findex reduce-indent-procedure 526Indent the procedure (and trailing white space) ending after point. 527@xref{Indentation,, Indenting REDUCE code automatically}. 528@end table 529 530It is often desirable to be able to see as much as possible of a 531procedure definition within the current window. The standard Emacs 532command @code{reposition-window} (@pxref{Scrolling,,, emacs, The Emacs 533Editor}) attempts to do this for Lisp functions, and the command 534@code{reduce-reposition-window} provides a harness to apply this 535function to REDUCE procedures, to which the standard key @kbd{C-M-l} is 536rebound. 537 538@table @kbd 539@item C-M-l 540@kindex C-M-l 541@itemx M-x reduce-reposition-window 542@findex reduce-reposition-window 543Reposition the procedure containing point to maximize its visibility 544within the window. @xref{Scrolling,,, emacs, The Emacs Editor}, and see 545the documentation for the function @code{reposition-window} for details. 546@end table 547 548To restrict all editing to a single REDUCE procedure, the standard Emacs 549key @kbd{C-x n d} that runs the command @code{narrow-to-defun} is 550rebound to a function to narrow to the current procedure. 551 552@table @kbd 553@item C-x n d 554@kindex C-x n d 555@itemx M-x reduce-narrow-to-procedure 556@findex reduce-narrow-to-procedure 557Make text outside the current procedure invisible. The procedure 558visible is the one that contains point or follows point. With a prefix 559argument, narrow to the following arg procedures including this one. 560@xref{Narrowing, , , emacs, The Emacs Editor}. 561@end table 562 563@c =================================================================== 564 565@node Comments 566@chapter Support for REDUCE comments 567@cindex Comment support 568 569There are two comment conventions used in REDUCE@. One is the comment 570statement, which is a statement that begins with the keyword 571@code{comment} and ends with a statement separator. This is not used 572much in modern REDUCE code. The most commonly used form of comment 573begins with a @code{%} character and ends at the end of the line. 574Hence, it can appear either on its own on a line or at the end of a line 575after other code. 576 577Comments are ignored (skipped) by all syntax-directed commands. (This 578is not trivial to achieve, since comments can contain essentially 579arbitrary text including keywords, and %-comments can contain statement 580separators, which do not have any syntactic significance.) There is 581currently no way to use any of the REDUCE syntax-directed commands on 582comment statements. 583 584There is no special support for comment statements other than that they 585are currently @emph{completely} ignored. There is considerably more 586support for %-comments, much of which is already built into Emacs 587because %-comments are very similar to the comments used in Emacs Lisp. 588Indeed, the comment conventions supported by REDUCE mode are modelled 589primarily on those used in Emacs Lisp mode. 590 591The comment commands are intimately related to the automatic comment 592indentation conventions. (These are the indentation conventions 593enforced by the Emacs comment and indentation commands, although the 594user is not otherwise forced to follow them.) @xref{Indentation,, 595Indenting REDUCE code automatically}. 596 597The indentation of a %-comment that begins with no more than 2 @code{%} 598characters together and appears alone on a line is determined by the 599previous non-blank line. If this is a procedure (header) statement then 600the comment line is indented relative to it, otherwise it has no indent 601relative to the previous line, and at the beginning of a file it is not 602indented at all. A %-comment at the end of a line of code is indented 603to the column specified by the value of the standard Emacs buffer-local 604variable @code{comment-column}, which by default is 40 (half way across 605a ``standard'' 80 column page), unless the code extends beyond this 606column. In that case, the comment begins one space later. 607 608This convention can be over-ridden as follows. If the comment begins 609with 3 or more @code{%} characters then the comment indentation is not 610changed. This allows a comment to be placed anywhere on an empty line 611without any risk of it being automatically re-indented. 612 613A new single-%-comment can be introduced and/or automatically indented 614by the standard Emacs command @code{indent-for-comment}, normally bound 615to the key @kbd{Meta-;}. An existing %-comment can be automatically 616continued on the next line by the standard Emacs command 617@code{indent-new-comment-line}, normally bound to the key 618@kbd{Meta-@key{LFD}}. This will copy the structure of the %-comment to 619be continued, including the number of @code{%} characters and the 620indentation. All other indentation commands will also indent 621%-comments, in particular those bound to the @kbd{@key{TAB}} and 622@kbd{@key{BACKTAB}} (i.e.@: @kbd{Shift-@key{TAB}}) keys. 623@xref{Indentation,, Indenting REDUCE code automatically}. 624 625@table @kbd 626@item M-; 627@kindex M-; 628@itemx M-x indent-for-comment 629@findex indent-for-comment 630Indent this line's comment appropriately, or insert an empty comment. 631 632@item M-LFD 633@kindex M-LFD 634@itemx M-x indent-new-comment-line 635@findex indent-new-comment-line 636Break the line at point and indent, continuing a comment if presently 637within one. The body of the continued comment is indented under the 638previous comment line. 639@end table 640 641The only program text that it normally makes sense to fill or justify is 642comment text. Hence, REDUCE mode rebinds the key @kbd{M-q} that 643normally fills or justifies a paragraph to the command 644@code{reduce-fill-comment}. This should be completely safe to use in 645REDUCE code (unlike @code{fill-paragraph} etc., which would be a 646potential disaster were there no undo facility!), and makes it easy to 647keep comments formatted tidily. Currently this command fills or 648justifies only %-comments and not comment statements. 649 650@table @kbd 651@item M-q 652@kindex M-q 653@itemx M-x reduce-fill-comment 654@findex reduce-fill-comment 655Fill successive %-comment lines around or immediately following point. 656A prefix argument means justify as well. 657@end table 658 659REDUCE mode also provides commands for turning sections of text into 660%-comments by adding @code{%} characters at the start of each line, 661which will be referred to as ``start-comments''. These commands are 662intended primarily for temporarily preventing REDUCE from executing 663sections of code without actually removing them. Such a section can be 664either the current region or the procedure ending after point. By 665default, these commands automatically toggle the comment status. When 666given an interactive argument, they remove any start-commenting of the 667specified section of text if the argument is negative (or null) and 668insert start-commenting if the argument is positive. The precise text 669that is added to or removed from each line is the value of the variable 670@code{reduce-comment-region-string}, which defaults to @samp{%% }. 671 672@table @kbd 673@item C-c ; 674@kindex C-c ; 675@itemx M-x reduce-comment-region 676@findex reduce-comment-region 677Comment/uncomment every line in the region. By default, it toggles the 678commenting, i.e.@: it comments the region if it is uncommented and 679uncomments if it is commented. With an interactive argument, comment if 680non-negative, uncomment if null or negative (cf.@: minor modes). When 681commenting, it puts the value of the variable 682@code{reduce-comment-region-string} at the beginning of every line in the 683region. 684 685@item C-c : 686@kindex C-c : 687@itemx M-x reduce-comment-procedure 688@findex reduce-comment-procedure 689As for @code{reduce-comment-region}, but applies to the procedure ending 690after point. 691@end table 692 693@c =================================================================== 694 695@node Indentation 696@chapter Indenting REDUCE code automatically 697@cindex Indentation 698 699Indentation refers to the white space at the left of a line, which 700therefore determines the column in which the actual text of the line 701begins. Indentation is used in normal English text to indicate the 702beginning of paragraphs, quotations, lists, etc.@: and hence to indicate 703the logical structure of a document. 704 705It is very important to use systematic indentation to indicate the 706logical structure of the source code of a computer program. Whilst the 707general principles of indentation are largely agreed, precise 708indentation conventions vary from author to author. The automatic 709indentation currently provided by REDUCE mode is very inflexible and 710reflects very much my own style of indentation. Future versions may 711provide more flexible and customizable indentation. 712 713Currently all indentation is done in steps consisting of a fixed number 714of columns determined by the value of the variable 715@code{reduce-indentation} (@pxref{Customization,, Customization of the 716REDUCE IDE}), the default value of which is 3. This is the indentation 717recommended by A. C. Hearn (the principal author of REDUCE) for the 718indentation of the first line after a procedure (header) statement. 719 720REDUCE mode provides fairly intelligent automatic indentation. The 721style used is as follows, where the indentation of a child statement is 722expressed relative to the parent statement. Each top-level statement is 723indented to the left margin. Procedure bodies are indented by one step. 724Bodies of multi-line compound and group statements are indented by one 725step and labels are exdented to match the beginning of the enclosing 726block. Lines that begin with @code{end} or @code{>>} are exdented to 727match the line containing the matching @code{begin} or @code{<<}. 728Bodies of control structures and lines that continue a previous 729statement are indented by one step. As parts of larger statements, 730compound and group statements themselves are generally not indented if 731they occupy multiple lines (because their bodies are indented) but they 732are indented if they occupy only a single line. 733 734When a new line that is empty is being indented, the indentation can be 735based only on the preceding code, and not on the code that will appear 736in the line. Therefore, it is often necessary to re-indent a line in 737order to get consistent indentation. This seems a little strange, but 738it is unavoidable (given the syntax of REDUCE and the indentation style 739that I have chosen). It is for this reason that the key @kbd{@key{LFD}} 740runs the command @code{reindent-then-newline-and-indent} rather than 741just @code{newline-and-indent}. But see also below. 742 743The command to indent, or re-indent, a line of text is 744@code{reduce-indent-line}, normally bound to the key @kbd{@key{TAB}}. 745If re-run immediately after itself (or run immediately after 746@code{reindent-then-newline-and-indent} (@kbd{@key{LFD}}) or 747@code{newline-and-indent} (@kbd{M-x newline-and-indent})) then it 748indents by one further step. This is non-standard additional 749flexibility provided by REDUCE mode. To force a line back to its 750standard indentation after multiple use of the @kbd{@key{TAB}} key, 751simply execute any other command(s) and then press @kbd{@key{TAB}} 752@emph{once}. The execution of @code{reduce-indent-line} is independent 753of the position of point within the line. It does not move point 754relative to the text around it unless point was within the indentation, 755in which case it is left before the first non-blank character (i.e.@: at 756the end of the indentation), or at the end of the line if it is empty. 757Normally, however, the most convenient way to use automatic indentation 758is to terminate each line of code with @kbd{@key{LFD}} rather than 759@kbd{@key{RET}}. @xref{Miscellaneous,, Miscellaneous minor features and 760bugs}. 761 762When called with any argument, @code{reduce-indent-line} will indent the 763current line correctly and then re-indent the rest of the logical 764statement containing point by the same amount that the current line was 765re-indented. This is @emph{not} the same as correctly re-indenting the 766subsequent lines -- it re-indents them rigidly, without changing their 767relative indentations at all, and is much faster. 768 769@table @kbd 770@item TAB 771@kindex TAB 772@itemx M-x reduce-indent-line 773@findex reduce-indent-line 774Indent or re-indent the current line as REDUCE code. Indents to a fixed 775style determined by the current and previous non-blank lines. 776Subsequent consecutive calls indent additionally by 777@code{reduce-indentation}. With an interactive argument, indent any 778additional lines of the same statement rigidly together with this one. 779 780@item LFD 781@kindex LFD 782@itemx M-x reindent-then-newline-and-indent 783@findex reindent-then-newline-and-indent 784Re-indent the current line, insert a newline, then indent the new line. 785Indentation of both lines is done using @code{reduce-indent-line}, which 786is bound by default to @kbd{TAB}. 787@end table 788 789With the current indentation style, it is not possible in all cases to 790determine the correct indentation until after some text has been entered 791on a line. This applies to the terminal delimiter of a block @code{end} 792or group @code{>>} when it appears alone on a line and to an @code{else} 793clause. Therefore, REDUCE mode can automatically re-indent the current 794line once there is enough text to recognise that this is necessary. It 795does this only when it is otherwise idle and only when the relevant text 796has just been typed. It is not done if the cursor is later moved onto 797such a line since it is assumed that the desired indentation has been 798set by then. (The indentation of any text can, of course, be changed at 799any time, but it will never be automatically changed retrospectively!) 800This facility is turned on and off by the command 801@code{reduce-auto-indent-mode}, the length of idle time required before 802the facility will operate is controlled by the user option 803@code{reduce-auto-indent-delay}, and whether the current line is 804auto-indented by this facility is controlled by the regular expression 805that is the value of the user option @code{reduce-auto-indent-regexp}. 806Auto-indentation is on by default. @xref{Customization,, Customization 807of the REDUCE IDE}. 808 809@table @kbd 810@item M-x reduce-auto-indent-mode 811@findex reduce-auto-indent-mode 812Toggle REDUCE Auto Indent mode. With a prefix argument, turn the mode 813on if and only if the argument is positive. When REDUCE Auto Indent 814mode is enabled, after @code{reduce-auto-indent-delay} seconds of Emacs 815idle time re-indent the current line if the text just typed matches 816@code{reduce-auto-indent-regexp}. 817@end table 818 819A section of code can be re-indented using one command if it is first 820marked as the current region, or the whole buffer or a complete 821procedure definition can be re-indented by a single command. The latter 822command works by marking the procedure and then re-indenting the region; 823it currently leaves the procedure marked. Region (and hence procedure) 824indenting is currently implemented inefficiently by applying the 825single-line indentation algorithm line-by-line, and hence is very slow 826for a large region or procedure. In some future version it may be 827re-implemented more efficiently. 828 829@table @kbd 830@item C-M-\ 831@kindex C-M-\ 832@itemx M-x reduce-indent-region 833@findex reduce-indent-region 834Indent or re-indent the region as REDUCE source code by applying 835@code{reduce-indent-line} to each line. With a prefix argument it 836indents the whole buffer. 837 838@item C-M-q 839@kindex C-M-q 840@itemx M-x reduce-indent-procedure 841@findex reduce-indent-procedure 842Indent or re-indent the procedure (and trailing white space) ending 843after point by applying @code{reduce-indent-line} to each line. 844@end table 845 846An inverse of the extra-indentation facility is provided to decrease the 847indentation by one step. This command is bound to @kbd{Shift-@key{TAB}} 848(i.e.@: @kbd{@key{BACKTAB}}) if possible, but not all platforms support 849this (because it has no ASCII representation). It may be no different 850from @kbd{@key{TAB}} alone, or it may generate an obscure ASCII 851sequence, so just try @kbd{Shift-@key{TAB}}, or ask Emacs what function 852is bound to @kbd{Shift-@key{TAB}} (by using @kbd{C-h k}). A default key 853binding, which should work on all platforms, is provided as @kbd{C-c 854@key{TAB}}. (However, currently this is rebound by REDUCE run mode. 855@xref{Run Keys, , Run mode key bindings and menu}.) 856 857With an argument, @code{reduce-unindent-line} rigidly unindents by one 858step the current line and the rest of the logical statement as an 859inverse of extra applications of @code{reduce-indent-line} with an 860argument. 861 862@table @kbd 863@item BACKTAB 864@kindex BACKTAB 865@itemx Shift-TAB 866@kindex Shift-TAB 867@kindex TAB 868@itemx C-c TAB 869@kindex C-c TAB 870@itemx M-x reduce-unindent-line 871@findex reduce-unindent-line 872Unindent the current line as REDUCE code by deleting 873@code{reduce-indentation} spaces from the beginning of the line. With 874an interactive argument, unindent any additional lines of the same 875statement rigidly along with this one. 876@end table 877 878@c =================================================================== 879 880@node Structures 881@chapter Templates for REDUCE structures 882@cindex Templates for structures 883@cindex Structure templates 884 885Commands are provided to insert and format the major REDUCE language 886structures; currently block or compound (@code{begin @dots{} end}), 887group (@code{<< @dots{} >>}) and conditional (@code{if @dots{} then 888@dots{} else @dots{}}) statements are supported. By default they are 889formatted to be multi-line. If given a prefix argument, the commands to 890insert block and group statements (composites) format them on a single 891line (appropriate in some very simple cases). 892 893If there is text on the line after where a composite is inserted then it 894is moved into the body of the composite; if transient mark mode is on 895and the mark is active then the whole region is moved into the 896composite; the composite is then re-indented. 897 898The cursor is left in place to enter the body statements of a group, 899whereas a block is inserted complete with an empty @code{scalar} 900declaration and the cursor is left in place to enter the names of the 901scalar variables. 902 903@table @kbd 904@item C-c b 905@kindex C-c b 906@itemx M-x reduce-insert-block 907@findex reduce-insert-block 908Insert and indent a @code{begin scalar ; @dots{} end} block and position 909point inside. With an argument put @code{begin} and @code{end} on the 910same line. 911 912@item C-c < 913@kindex C-c < 914@itemx M-x reduce-insert-group 915@findex reduce-insert-group 916Insert and indent a @code{<< @dots{} >>} group and position point 917inside. With an argument put @code{<<} and @code{>>} on the same line. 918 919@item C-c i 920@kindex C-c i 921@itemx M-x reduce-insert-if-then 922@findex reduce-insert-if-then 923Insert @code{if @dots{} then} and position point inside. With argument 924include a correctly indented @code{else} on a second line. 925@end table 926 927Probably the easiest way to access these templates from the keyboard is 928not directly as described above but via the generalized completion 929facilities described in the next chapter. @xref{Completion,,Keyword 930completion and abbreviation expansion,,}. 931 932@c =================================================================== 933 934@node Completion 935@chapter Keyword completion and abbreviation expansion 936@cindex Completion 937@cindex Keyword completion 938@cindex Expansion 939@cindex Abbreviations 940@cindex Structures 941 942Emacs provides various standard facilities for semi-automatic completion 943of key words and phrases (@pxref{Symbol Completion,, Completion for 944Symbol Names, emacs, The Emacs Editor}, @pxref{Dynamic Abbrevs,, Dynamic 945Abbrev Expansion, emacs, The Emacs Editor}). REDUCE mode provides 946completion of common REDUCE key words and phrases, such as 947@samp{procedure}, by typing the first few letters of a key word or 948phrase and then pressing @kbd{Meta-@key{TAB}}. (For use under Microsoft 949Window @pxref{Miscellaneous,,Miscellaneous minor features and bugs,,}) 950This works in a similar way to completion in other major modes 951(@pxref{Symbol Completion,, Completion for Symbol Names, emacs, The 952Emacs Editor}). 953 954REDUCE mode also provides @emph{abbreviations} that are expanded like 955completions, except that they are @emph{replaced} by their expansions 956rather than completed. Examples of the abbreviations currently defined 957are: 958 959@lisp 960 ("ap" . "algebraic procedure ") 961 ("st" . "such that ") 962 ("sop" . "symbolic operator ") 963 ("sp" . "symbolic procedure ") 964@end lisp 965 966The following symbols currently trigger @emph{structure completion}: 967 968@lisp 969 ("begin" . reduce-insert-block) 970 ("ift" . reduce-expand-if-then) 971 ("ife" . reduce-expand-if-then-else) 972 ("<<" . reduce-insert-group) 973@end lisp 974 975They operate in exactly the same way as if the appropriate structure 976insertion command had been executed directly, and they receive any 977prefix argument entered before the completion key. 978 979For the full set of completions and abbreviations see the customizable 980user option @code{reduce-completion-alist}. 981 982@table @kbd 983@item M-TAB 984@kindex M-TAB 985@itemx M-x reduce-complete-symbol 986@findex reduce-complete-symbol 987Perform completion on the REDUCE symbol preceding point (or preceding 988the region if it is active). Compare that symbol against the elements 989of @code{reduce-completion-alist}. If a perfect match (only) has a 990@code{cdr} then delete the match and insert the @code{cdr} if it is a 991string or call it if it is a (nullary) function, passing on any prefix 992argument (in raw form). 993@end table 994 995@c =================================================================== 996 997@node Font-Lock 998@chapter Font-lock support for automatic font selection 999@cindex Font-lock support 1000@cindex Font selection 1001@cindex Highlighting of keywords 1002@cindex Keyword highlighting 1003 1004Font-lock mode causes Emacs to select automatically the font in which 1005text is displayed (``fontify'' it) so as to indicate its logical 1006status. @xref{Font Lock,, Font Lock mode, emacs, The Emacs Editor}. 1007The first version of font-lock support for REDUCE mode was contributed 1008by Rainer Schoepf. The current version provides 4 levels of 1009decoration, which can be selected using the standard font-lock 1010facilities, or interactively most easily via the REDUCE mode font-lock 1011sub-menu. The levels and corresponding highlighting are as follows. 1012 1013@enumerate 1014@item 1015Minimum: main keywords and group delimiters, procedure and other main 1016type declarations, strings, %-comments 1017@item 1018Algebraic: minimum plus labels, algebraic-mode declarations and 1019variables 1020@item 1021Symbolic: minimum plus labels, symbolic-mode declarations and variables 1022@item 1023Maximum: all the above plus function calls and all uses of variables 1024@end enumerate 1025 1026@noindent 1027Minimum highlighting is probably a good general-purpose level for normal 1028use, but if you program almost exclusively in either the algebraic or 1029symbolic mode of REDUCE then you might prefer the highlighting tailored 1030to that mode. Maximum highlighting is probably too gaudy and too slow 1031for general use; also the code is complicated and not well tested, so 1032maximum highlighting is likely to be the least reliable. 1033 1034REDUCE mode does not make any (user configurable) face definitions of 1035its own and only standard font-lock faces are used. The faces used to 1036highlight particular syntactic elements are as follows: 1037 1038@vtable @code 1039@item font-lock-builtin-face 1040not currently used 1041@item font-lock-comment-face 1042%-comments (only) 1043@item font-lock-constant-face 1044labels 1045@item font-lock-function-name-face 1046procedure, operator and module names @emph{in their definition 1047statements only} (which may change in a later version) 1048@item font-lock-keyword-face 1049main REDUCE keywords 1050@item font-lock-string-face 1051strings 1052@item font-lock-type-face 1053type declaration keywords 1054@item font-lock-variable-name-face 1055variables 1056@item font-lock-warning-face 1057currently used only by REDUCE run mode 1058@item font-lock-reference-face 1059obsolete and replaced by @code{font-lock-constant-face} 1060@end vtable 1061 1062Font-lock mode can be turned on interactively in the normal way that any 1063minor mode is turned on, e.g.@: it can be toggled on and off by the 1064command @code{font-lock-mode}. It can also be turned on and off via the 1065REDUCE mode font-lock sub-menu. To turn on font-lock mode automatically 1066with REDUCE mode, put this in your @file{.emacs} file: 1067 1068@lisp 1069(add-hook 'reduce-mode-hook 'turn-on-font-lock) 1070@end lisp 1071 1072To control the operation of font-lock mode use the customization buffer 1073for the @code{Font Lock} group. The default level of fontification used 1074by any mode can be specified by customizing the user option 1075@code{font-lock-maximum-decoration}, which REDUCE mode respects. 1076 1077Emacs provides standard facilities to control the use of different 1078display faces. @xref{Faces,, Using Multiple Typefaces, emacs, The Emacs 1079Editor}. @xref{Faces,,, elisp, The GNU Emacs Lisp Reference Manual}, 1080for further technical detail. To alter the appearance of a Font Lock 1081face, use the customization buffer for the @code{Font Lock Highlighting 1082Faces} group. @xref{Face Customization,, Customizing Faces, emacs, The 1083Emacs Editor}. 1084 1085REDUCE mode passes information to font-lock mode via the value of the 1086buffer-local variable @code{font-lock-defaults}, which could be re-set 1087or modified via the REDUCE mode hook, although this is not recommended. 1088 1089For more information see the description of the command 1090@code{font-lock-mode} and related commands and variables, and/or the 1091ELisp source code file @file{font-lock.el}. 1092 1093Standard font-lock fontification can be slow. An elegant solution is 1094provided by the @code{lazy-lock} package, which immediately fontifies 1095only the visible part of the buffer and fontifies the remainder 1096``stealthily'' in the background when Emacs is not otherwise busy. This 1097makes font-lock mode eminently usable even on a relatively low-powered 1098computer (provided it has a suitable display) and I recommend it! 1099 1100Font-locking of major syntactic elements, such as comments and strings, 1101is normally controlled by the syntax table for the text being edited. 1102This leads to a problem with a language such as REDUCE, because the 1103character @code{!} represents an escape character within an identifier 1104but not within a string. This is different from the convention in the 1105languages (C and Emacs Lisp) that Emacs was primarily designed to 1106support, in which the significance of the escape character does not 1107depend on the context. I have not found a completely satisfactory way 1108to deal with this problem. The solution currently adopted in REDUCE 1109mode is to use a recently added font-lock facility that allows the 1110syntax of @code{!} to be reset from escape to punctuation when it occurs 1111immediately followed by a double quote, i.e.@: as @code{!"}. This 1112avoids most of the difficulties, but it fails in the (fairly rare) case 1113that @code{!"} appears in an identifier (which it does in one or two of 1114the core REDUCE system files). 1115 1116@c =================================================================== 1117 1118@node Access 1119@chapter Access to procedure and operator definitions 1120@cindex Access to procedure and operator definitions 1121@cindex Information, procedures and operators 1122@cindex Procedure access 1123@cindex Operator access 1124 1125REDUCE mode can provide information about the procedure that point is 1126currently in, and easy access via the @code{Imenu} facility to all the 1127procedure and operator definitions within the current file. Whilst 1128@code{Imenu} provides a convenient way to find a procedure or operator 1129definition rapidly in the current file, the standard Emacs ``tag'' 1130facility is the best way to find a procedure or operator definition 1131rapidly in another file. 1132 1133@menu 1134* Show Proc:: Showing the current procedure 1135* Imenu:: Menu access to procedures and operators 1136* Tags:: Tag access to procedures and operators 1137@end menu 1138 1139@node Show Proc 1140@section Show procedure mode 1141@cindex Show procedure mode 1142@cindex Procedure display 1143@cindex Displaying current procedure 1144@cindex Showing current procedure 1145@cindex Which procedure 1146 1147When editing or viewing long procedure definitions it is easy to forget 1148which procedure you are looking at when the procedure statement itself 1149is off the top of the screen. REDUCE mode can show in the mode line the 1150name of the procedure (if any) that point is in. This facility is 1151turned on and off by the command @kbd{M-x reduce-show-proc-mode} or via 1152the REDUCE mode menu; it is off by default. (It is analogous to the 1153standard Emacs ``Which Function'' mode, but it is implemented 1154differently and largely independently.) 1155 1156@table @kbd 1157@item M-x reduce-show-proc-mode 1158@findex reduce-show-proc-mode 1159Toggle REDUCE Show Proc mode. With a prefix argument, turn REDUCE Show 1160Proc mode on if and only if the argument is positive. When REDUCE Show 1161Proc mode is enabled, display the current procedure name in the mode 1162line after @code{reduce-show-proc-delay} seconds of Emacs idle time. 1163@end table 1164 1165@c ------------------------------------------------------------------- 1166 1167@node Imenu 1168@section Imenu support 1169@cindex Imenu support 1170@cindex Support for imenu 1171@cindex Menu of procedures and operators 1172@cindex Procedure menu 1173@cindex Operator menu 1174 1175REDUCE mode supports the standard Emacs @code{Imenu} facilities 1176(@pxref{Imenu,,,elisp, The GNU Emacs Lisp Reference Manual}). The 1177easiest way to use them is via the REDUCE menu entry that builds a new 1178(nested) menu of REDUCE procedure and operator names. Selecting an 1179entry in this menu moves point to the start of the definition of the 1180specified procedure or operator. Another way to use @code{Imenu} is by 1181entering the extended command @kbd{M-x imenu} and then using the 1182standard Emacs completion facilities to select a procedure or operator 1183name. The REDUCE mode @code{Imenu} menu-bar menu name and the regular 1184expression used to build menu entries can be customized 1185(@pxref{Customization,, Customization of the REDUCE IDE}). 1186 1187@c ------------------------------------------------------------------- 1188 1189@node Tags 1190@section Support for tag files 1191@cindex Support for tag files 1192@cindex Tags 1193@cindex Tag files 1194 1195A REDUCE mode submenu provides rapid access to some of the main 1196facilities for finding a procedure definition via a tag file. Two 1197commands (and submenu options) facilitate tagging the REDUCE files in 1198one directory or in a directory and all its sub-directories. The 1199former is useful for tagging all the files associated with a single 1200project or package; the latter for tagging all REDUCE packages in a 1201single tag file. 1202 1203Once a TAGS file has been generated, the standard Emacs @code{xref} 1204interface is available to find identifier references, in particular 1205the command @command{xref-find-definitions}, which is also available 1206via the REDUCE mode submenu. @xref{Xref,, Find Identifier References, 1207emacs, GNU Emacs Manual}. 1208 1209The tagging commands use the standard Emacs @code{etags} program, 1210which should be available in the Emacs @code{bin} directory. REDUCE 1211mode uses the value of the option @option{reduce-etags-directory}, 1212which should be appropriate by default, but if not can be customized. 1213(It is not required that the Emacs @code{bin} directory be in your 1214execution path, but if it is you can optionally set 1215@option{reduce-etags-directory} to nil.) 1216 1217@table @kbd 1218@item M-. 1219@item M-x xref-find-definitions 1220Show the definitions of the identifier at point. With a prefix 1221argument, or if there’s no identifier at point, prompt for the 1222identifier. 1223 1224@item M-x reduce-tagify-dir 1225@findex reduce-tagify-dir 1226Generate a REDUCE TAGS file for (all @file{.red} files in) the 1227specified directory, by default the current directory. The TAGS file 1228goes in the specified directory. 1229 1230@item M-x reduce-tagify-dir-recursively 1231@findex reduce-tagify-dir-recursively 1232Generate a REDUCE TAGS file for (all @code{.red} files in) the 1233specified directory, by default the current directory, and all its 1234subdirectories. The single TAGS file goes in the specified directory. 1235@end table 1236 1237@c =================================================================== 1238 1239@node Miscellaneous 1240@chapter Miscellaneous minor features and bugs 1241@cindex Miscellaneous 1242@cindex Features 1243@cindex Bugs 1244@cindex Minor modes 1245 1246REDUCE mode extends some of the standard Emacs handling of parenthesised 1247``lists'' to include REDUCE group and block constructs. It provides a 1248major mode menu and easy access to its version information. This 1249chapter also discusses known and potential problems using REDUCE mode, 1250and describes how to access some special function keys that are useful 1251in Emacs in general and in REDUCE mode in particular. 1252 1253@menu 1254* Groups and blocks moving:: Moving over 1255* Groups and blocks highlighting:: Delimiter highlighting 1256* Major mode menu:: Major mode menu 1257* Version:: REDUCE mode version information 1258* Problems:: Known and potential problems 1259* Special function keys:: Linefeed, Meta-TAB, etc. 1260@end menu 1261 1262@node Groups and blocks moving 1263@section Groups and blocks: moving over 1264@cindex Groups 1265@cindex Blocks 1266@cindex Moving over 1267 1268A group or block is regarded as a ``symbolic expression'' (sexp) by 1269the commands @code{reduce-backward-sexp} and 1270@code{reduce-forward-sexp}. 1271 1272@table @kbd 1273@item C-M-f 1274@kindex C-M-f 1275@itemx M-x reduce-forward-sexp 1276@findex reduce-forward-sexp 1277Move forward across one balanced expression. With a numeric argument, 1278do it that many times. 1279 1280@item C-M-b 1281@kindex C-M-b 1282@itemx M-x reduce-backward-sexp 1283@findex reduce-backward-sexp 1284Move backward across one balanced expression. With a numeric argument, 1285do it that many times. 1286@end table 1287 1288@c ------------------------------------------------------------------- 1289 1290@node Groups and blocks highlighting 1291@section Groups and blocks: delimiter highlighting 1292@cindex Groups 1293@cindex Blocks 1294@cindex Delimiters 1295@cindex Highlighting 1296 1297Delimiters for groups (@code{<<} and @code{>>}) and blocks 1298(@code{begin} and @code{end}) are treated like brackets. Either 1299highlighting of matching group and block delimiters or (group only) 1300blink matching is toggled by the command 1301@code{reduce-show-delim-mode}. 1302 1303Beware: Currently the blink matching facility for groups is probably 1304broken! 1305 1306REDUCE Show Delim mode is based closely on Show Paren mode 1307(@pxref{Matching,, Automatic Display Of Matching Parentheses, emacs, 1308The Emacs Editor}). It is completely independent except that all 1309settings default to the corresponding values for Show Paren mode. 1310Show Delim mode is turned on automatically when REDUCE mode is 1311selected if @code{reduce-show-delim-mode-on} is non-nil, which it is 1312by default if Show Paren mode is on. 1313 1314Note that highlighting of matching group and block delimiters does not 1315work when point is @emph{within} a delimiter. (This cannot happen 1316with brackets, which are single characters). This may be changed in 1317future. 1318 1319@table @kbd 1320@item M-x reduce-show-delim-mode 1321@findex reduce-show-delim-mode 1322Toggle REDUCE Show Delim mode. With a prefix argument, turn REDUCE 1323Show Delim mode on if and only if the argument is positive. When 1324REDUCE Show Delim mode is enabled, any matching delimiter is 1325highlighted after @code{reduce-show-delim-delay} seconds of Emacs idle 1326time. @xref{Customization,, Customization of the REDUCE IDE}. 1327@end table 1328 1329Show Delim mode is a buffer-local minor mode. Whenever point is 1330before an opening delimiter or after a closing delimiter, the 1331delimiter, its matching delimiter, and optionally the text between 1332them are highlighted. To customize REDUCE Show Delim mode, type 1333@kbd{M-x customize-group @key{RET} reduce-delim-showing}. The 1334customizable options which control the operation of this mode include 1335the following: 1336 1337@itemize 1338@item 1339@code{reduce-show-delim-highlight-opendelim} controls whether to 1340highlight an opening delimiter when point stands just before it, and 1341hence its position is marked by the cursor anyway. The default is the 1342value of @code{show-paren-highlight-openparen}. 1343@item 1344@code{reduce-show-delim-style} controls whether just the two 1345delimiters, or also the space between them get highlighted. The valid 1346options here are @code{delimiter} (show the matching delimiter), 1347@code{expression} (highlight the entire expression enclosed by the 1348delimiters), and @code{mixed} (highlight the matching delimiter if it 1349is visible, the expression otherwise). The default is determined by 1350the value of @code{show-paren-style}. 1351@item 1352@code{reduce-show-delim-when-point-inside-delim}, when non-@code{nil}, 1353causes highlighting also when point is immediately inside a delimiter. 1354The default is the value of @code{show-paren-when-point-inside-paren}. 1355@item 1356@code{reduce-show-delim-when-point-in-periphery}, when non-@code{nil}, 1357causes highlighting also when point is in whitespace at the beginning 1358or end of a line, and there is respectively an opening or closing 1359delimiter as the first or last non-whitespace characters on the line. 1360The default is the value of @code{show-paren-when-point-in-periphery}. 1361@end itemize 1362 1363@c ------------------------------------------------------------------- 1364 1365@node Major mode menu 1366@section Major mode menu 1367@cindex Major mode menu 1368@cindex Menu, Major mode 1369 1370@kindex C-down-mouse-3 1371@findex mouse-major-mode-menu 1372REDUCE mode adds a major-mode menu called ``REDUCE'' to the menu bar, 1373which is also available as a pop-up menu activated by the command 1374@code{mouse-major-mode-menu} on the standard key @kbd{C-down-mouse-3}. 1375 1376@c ------------------------------------------------------------------- 1377 1378@node Version 1379@section REDUCE mode version information 1380@cindex REDUCE mode version information 1381@cindex Version information 1382@cindex Information about version 1383 1384The version of REDUCE mode that is running is available as the value of 1385the variable @code{reduce-mode-version}, which is a string that can be 1386displayed in the echo area either by selecting the @code{Show Version} 1387menu option from the REDUCE major mode menu or by running the command 1388@kbd{M-x reduce-mode-version} (both of which also record it in the 1389@code{*Messages*} buffer). If REDUCE mode is not running then an easy 1390way to start it is to switch to a temporary buffer (e.g.@: by using 1391@kbd{C-x b tmp}) and then switch it to REDUCE mode (by using @kbd{M-x 1392reduce-mode}). 1393 1394@c ------------------------------------------------------------------- 1395 1396@node Problems 1397@section Known and potential problems 1398@cindex Problems 1399@cindex Bugs 1400@cindex Compatibility 1401 1402There is a problem with the way that REDUCE mode handles an exclamation 1403mark (@samp{!}) followed immediately by a double quote @samp{"}. 1404@xref{Font-Lock,, Font-lock support for automatic font selection}. This 1405should not be a problem in ``normal'' code, but it may upset the parsing 1406of code that uses this character sequence within an identifier. It is 1407caused by a limitation in the way that Emacs currently handles the 1408syntax of the text being edited and is not easy to avoid completely! I 1409am looking for a better resolution of this problem. 1410 1411There is no guarantee that an arbitrary minor mode or other extension 1412will be compatible with REDUCE mode, although I am not aware of any 1413conflicts. Two minor modes that are known to be compatible with REDUCE 1414mode are transient-mark-mode and delete-selection-mode (because I always 1415use them and I recommend them!). 1416 1417@c ------------------------------------------------------------------- 1418 1419@node Special function keys 1420@section Special function keys 1421@cindex Special function keys 1422@cindex Function keys 1423@cindex Keys, special function 1424@cindex Linefeed 1425@cindex LFD 1426@kindex LFD 1427@cindex Meta-LFD 1428@kindex Meta-LFD 1429@cindex TAB 1430@kindex TAB 1431@cindex Meta-TAB 1432@kindex Meta-TAB 1433 1434A number of ``special function'' keys are useful in Emacs in general and 1435in REDUCE mode in particular, which are not directly accessible on all 1436platforms. The following comments apply particularly to Microsoft 1437Windows. 1438 1439The standard key to terminate lines of indented code is @kbd{@key{LFD}} 1440and the standard key to continue a comment is @kbd{Meta-@key{LFD}}, but 1441@kbd{@key{LFD}} does not exist on a standard PC keyboard. Note that 1442@kbd{@key{LFD}} can always be accessed via its ASCII code as @kbd{C-j}, 1443or on some keyboards @kbd{Control-@key{RET}} generates @kbd{@key{LFD}}. 1444In some situations, the keyboard can be re-programmed to provide this 1445very convenient synonym, which is true of the better terminal emulators. 1446 1447The standard key to complete a symbol is @kbd{Meta-@key{TAB}}, but 1448Microsoft Windows uses this key combination for fast task switching. 1449 1450When Emacs is able to read the keyboard directly, as when it is run 1451under X or Microsoft Windows, @kbd{@key{LFD}} can be conveniently 1452emulated as @kbd{Control-@key{RET}} and @kbd{Meta-@key{TAB}} as 1453@kbd{Control-@key{TAB}}. A good way to generate these and similar 1454emulations is to put the following code in your @file{.emacs} file: 1455 1456@lisp 1457(define-key function-key-map [(control return)] [?\C-J]) 1458(define-key function-key-map [(control meta return)] [?\C-\M-J]) 1459(define-key function-key-map [(control tab)] [?\M-\t]) 1460@end lisp 1461 1462@c =================================================================== 1463 1464@node Customization 1465@chapter Customization of REDUCE IDE 1466@cindex Customization 1467@cindex Options 1468@cindex User options 1469@cindex Variables 1470 1471REDUCE IDE supports a small amount of customization. The following 1472edit-mode user options can be changed using the standard Emacs 1473customization facilities. The main REDUCE customization group is called 1474``REDUCE'', under which are the two sub-groups ``REDUCE Interface'' and 1475``REDUCE Format & Display'' and two hooks. 1476 1477REDUCE IDE font-lock support can be customized by resetting standard 1478font-lock variables (@pxref{Font-Lock,, Font-lock support for automatic 1479font selection}). 1480 1481Customization of REDUCE run mode is documented separately. @xref{Run 1482Customization, , Customization of REDUCE run mode}. 1483 1484@menu 1485* Interface:: Interface customization 1486* Format & Display:: Format and display customization 1487* Hooks:: REDUCE mode hooks 1488@end menu 1489 1490@node Interface 1491@section REDUCE mode interface customization 1492@cindex Interface customization 1493 1494@vtable @code 1495@item reduce-imenu-generic-expression 1496Imenu support for procedure definitions and operator declarations. An 1497alist with elements of the form @code{(MENU-TITLE REGEXP INDEX)} -- see 1498the documentation for @code{imenu-generic-expression}. 1499 1500@item reduce-imenu 1501Default value @code{nil}. If non-nil then REDUCE mode automatically 1502calls @code{imenu-add-to-menubar} to add a Contents menu to the menubar. 1503 1504@item reduce-imenu-title 1505Default value "Procs/Ops". The title to use if REDUCE mode adds a 1506procedure/operator menu to the menubar. 1507 1508@item reduce-max-up-tries 1509Default value 2. Number of repeats of @code{reduce-forward} or 1510@code{backward-statement} required to move up out of a block or group. 1511 1512@item reduce-completion-alist 1513Association list of REDUCE-mode completions searched by 1514@code{reduce-complete-symbol}. Each key word or phrase to be simply 1515completed should be a list containing a single string. If a perfectly 1516matched string (only) is a non-trivial pair then the match is deleted 1517and the @code{cdr} inserted if it is a string or called if it is a 1518(nullary) function, passing on any prefix argument (in raw form). 1519@end vtable 1520 1521@c ------------------------------------------------------------------- 1522 1523@node Format & Display 1524@section REDUCE mode format & display customization 1525@cindex Format & display customization 1526@cindex Format customization 1527@cindex Display customization 1528 1529@subheading Format 1530 1531@vtable @code 1532@item reduce-indentation 1533Default value 3. Depth of successive indentation in REDUCE code. 1534 1535@item reduce-comment-region-string 1536Default value @samp{%% }. String inserted by 1537@code{reduce-comment-region} or @code{reduce-comment-procedure} at the 1538start of each line. Was named @code{reduce-comment-region} up to version 1555! 1539 1540@item reduce-auto-indent-mode 1541Default value @code{t}. If non-nil then conditionally re-indent the 1542current line after @code{reduce-auto-indent-delay} seconds of Emacs idle 1543time if the text just typed matches @code{reduce-auto-indent-regex}. 1544 1545@item reduce-auto-indent-delay 1546Default value 0.125. Time in seconds to delay before maybe re-indenting 1547current line. 1548 1549@item reduce-auto-indent-regexp 1550Default value @code{"\\(else\\|end\\|>>\\)\\="}. Auto indent the 1551current line if the text just typed matches this regexp. It should end 1552with @code{\=}. 1553@end vtable 1554 1555@subheading Display 1556 1557@vtable @code 1558@item reduce-show-delim-mode 1559Default value is ``on'' if this makes sense. If non-nil then highlight 1560matching group and block delimiters. Otherwise blink the open-group 1561matching an inserted close-group. 1562 1563@item reduce-show-delim-match-face 1564Default value as for standard paren match highlighting (Show Paren 1565mode). Face used for a matching REDUCE delimiter. 1566 1567@item reduce-show-delim-mismatch-face 1568Default value as for standard paren match highlighting (Show Paren 1569mode). Face used for a mismatching REDUCE delimiter. 1570 1571@item reduce-show-proc-mode 1572Default value @code{nil}. If non-nil then display the current procedure 1573name in the mode line after @code{reduce-show-proc-delay} seconds of 1574Emacs idle time. 1575 1576@item reduce-show-proc-delay 1577Default value 0.125. Time in seconds to delay before showing the 1578current procedure name. 1579@end vtable 1580 1581@c ------------------------------------------------------------------- 1582 1583@node Hooks 1584@section REDUCE mode hooks 1585@cindex Hooks 1586 1587Hooks allow arbitrary customization that is not supported by the 1588standard customization facilities. When the REDUCE mode library is 1589loaded into Emacs, the last step of the loading process is to execute 1590the function(s) assigned to the variable @code{reduce-mode-load-hook}. 1591This hook would be appropriate for modifying global properties of REDUCE 1592mode such as its key map. 1593 1594When REDUCE mode is activated in a buffer the last step of its 1595initialization process is to execute the function(s) assigned to the 1596variable @code{reduce-mode-hook}. This hook would be appropriate for 1597modifying properties local to the buffer. 1598 1599@xref{Installation,, Installation of the REDUCE IDE}, for further 1600details. 1601 1602@vtable @code 1603@item reduce-mode-load-hook 1604Default value @code{nil}. List of functions to be called when REDUCE 1605mode is loaded, e.g.@: @code{require-reduce-run} to automatically load 1606@code{reduce-run}. It can be used to customize global features of 1607REDUCE mode such as its key map, i.e.@: it is a good place to put 1608key bindings. 1609 1610@item reduce-mode-hook 1611Default value @code{nil}. List of functions to be called when REDUCE 1612mode is entered. It can be used to customize buffer-local features of 1613REDUCE mode, e.g.@: use @code{turn-on-font-lock} to turn on font-lock 1614mode locally. 1615@end vtable 1616 1617@c =================================================================== 1618 1619@node Run 1620@chapter Running REDUCE in an Emacs window 1621@cindex Running REDUCE 1622@cindex Run mode 1623 1624REDUCE run mode is a subsidiary of REDUCE edit mode, in the sense that 1625it requires REDUCE edit mode to be loaded before it is loaded (which 1626it tries to ensure automatically). It provides an interface that 1627allows you to run a command-line (as opposed to a GUI) version of 1628REDUCE interactively in an Emacs window, with input from and output to 1629that window. 1630 1631In fact, it allows you to run CSL and/or PSL REDUCE simultaneously and 1632independently in multiple windows. You specify your preferred REDUCE 1633version, which is then used by default, but there are also commands to 1634start CSL or PSL REDUCE specifically. (The default preference is CSL 1635REDUCE, mainly because it seems to be slightly more robust.) 1636 1637You can also run a REDUCE source code file or an Emacs buffer 1638containing REDUCE source code (in REDUCE mode) as a completed REDUCE 1639program in an independent window automatically named from the source 1640code file or buffer. 1641 1642REDUCE statements, procedures or general regions of code in a REDUCE 1643mode buffer can be sent to REDUCE running in another buffer. If 1644REDUCE is running in multiple buffers then you select which buffer to 1645use. If you try to send REDUCE code to REDUCE but REDUCE is not 1646running, then REDUCE run mode will (optionally) start REDUCE 1647automatically. 1648 1649@menu 1650* Run Introduction:: Introduction to REDUCE run mode 1651* Run Installation:: Installation of REDUCE run mode 1652* PSL on Windows:: Running PSL REDUCE on Microsoft Windows 1653* Run Customization:: Customization of REDUCE run mode 1654* Run REDUCE:: Running, re-running and switching to REDUCE 1655* Run REDUCE Program:: Running complete REDUCE programs 1656* Evaluating Code:: Inputting code fragments to REDUCE 1657* Processing REDUCE Files:: Inputting, compiling and loading REDUCE files 1658* Run Keys:: Run mode key bindings and menu 1659@end menu 1660 1661@c ------------------------------------------------------------------- 1662 1663@node Run Introduction 1664@section Introduction to REDUCE run mode 1665@cindex Introduction to REDUCE run mode 1666 1667REDUCE run mode provides the following facilities for running REDUCE: 1668 1669@itemize @bullet 1670@item 1671input editing and flexible re-execution of previous input; 1672@item 1673flexible browsing of all input and output; 1674@item 1675syntax highlighting of prompts, input and error messages; 1676@item 1677bracket and delimiter highlighting or matching as in REDUCE edit mode; 1678@item 1679easy REDUCE package loading, source file input and module compilation; 1680@item 1681seamless integration with source files being edited using REDUCE edit 1682mode, including easy input of statements, procedure definitions, 1683arbitrary regions or the whole file to REDUCE; 1684@item 1685optional automatic starting of REDUCE; 1686@item 1687menu access to many facilities; 1688@item 1689all other standard Emacs facilities, such as printing part or all of the 1690interaction buffer; 1691@item 1692the full source code is free, and the package is documented and user 1693customizable. 1694@end itemize 1695 1696These facilities include most, if not all, of the facilities offered by 1697any other REDUCE interface, with the notable exception of typeset 1698quality display of mathematical output. It may be possible to support 1699this in some future version. 1700 1701REDUCE run mode is provided as a separate library so that if you 1702prefers another REDUCE interface you do not need to install it. It is 1703a subsidiary library to REDUCE edit mode and when loaded it hooks 1704itself into and cooperates closely with REDUCE edit mode. 1705 1706REDUCE run mode is based closely on the standard library @file{inf-lisp} 1707by @email{shivers@@cs.cmu.edu, Olin Shivers}. @xref{External Lisp, , 1708Running an External Lisp, emacs, The Emacs Editor}. Since this mode is 1709built on top of the general command-interpreter-in-a-buffer (comint) 1710mode, it shares a common base functionality and a common set of key 1711bindings with all modes derived from comint mode. (Among these, shell 1712mode is likely to be the most familiar. @xref{Interactive Shell, , 1713Interactive Inferior Shell, emacs, The Emacs Editor}.) This makes these 1714modes easier to use. 1715 1716For further documentation on the functionality provided by comint mode 1717and the hooks available for customising it, see the file 1718@file{comint.el}. 1719 1720@c ------------------------------------------------------------------- 1721 1722@node Run Installation 1723@section Installation of REDUCE run mode 1724@cindex Installation of REDUCE run mode 1725 1726It is probably best to use the GNU Emacs package manager to install 1727the latest complete REDUCE IDE package as described in the 1728@uref{http://reduce-algebra.sourceforge.net/reduce-ide/#installation, 1729installation section of the main REDUCE IDE web page}. None of the 1730manual installation described below is then required. 1731 1732But if you want to install by hand, or understand the details of the 1733installation process, then read on. (Please also @pxref{Installation, 1734, Installation of REDUCE IDE}.) 1735 1736REDUCE run mode requires the library @file{reduce-mode} both when it is 1737compiled and when it is loaded. It tries quite hard to locate this 1738library, but normally it should be in the same directory as 1739@file{reduce-run}. 1740 1741Byte-compile the file @file{reduce-run.el}, put the result somewhere in 1742your @code{load-path}, and put the following in your @file{.emacs} file: 1743 1744@lisp 1745(autoload 'run-reduce "reduce-run" "Run a REDUCE process" t) 1746@end lisp 1747 1748If you would like to have automatic full access to the features of 1749REDUCE run mode from REDUCE edit mode then also put the following in 1750your @file{.emacs} file: 1751 1752@lisp 1753(add-hook 'reduce-mode-load-hook 'require-reduce-run) 1754@end lisp 1755 1756@c ------------------------------------------------------------------- 1757 1758@node PSL on Windows 1759@section Running PSL REDUCE on Microsoft Windows 1760@cindex PSL on Windows 1761@cindex Running PSL REDUCE on Windows 1762 1763It seems that PSL REDUCE on Windows currently needs to be run 1764explicitly from the Windows shell, which is arranged automatically if 1765you use the GNU Emacs package manager. In that case, you can ignore 1766the rest of this section, unless something foes wrong! 1767 1768The package manager installs a file called 1769@file{reduce-run-redpsl.bat} in the same folder as REDUCE IDE and 1770REDUCE run mode automatically executes this file in order to run PSL 1771REDUCE. The file just contains the following two lines (apart from an 1772inessential comment line): 1773 1774@verbatim 1775@echo off 1776"C:\Program Files\Reduce\bin\redpsl.bat" 1777@end verbatim 1778 1779It is important that the second line is the full path of the file 1780@file{redpsl.bat} on your computer. (If you include the REDUCE 1781@file{bin} folder in your search path---which is not done 1782automatically by the REDUCE installer---then you can optionally just 1783use @file{"redpsl.bat"}, where the extension and the double quotes are 1784also now optional.) 1785 1786The user option @var{reduce-run-commands} (see the next section) 1787should automatically show the full pathname of 1788@file{reduce-run-redpsl.bat} as the command to start PSL REDUCE. If 1789not, you can customize it to the correct value. 1790 1791@c ------------------------------------------------------------------- 1792 1793@node Run Customization 1794@section Customization of REDUCE run mode 1795@cindex Customization 1796@cindex Options 1797@cindex User options 1798@cindex Variables 1799 1800REDUCE run mode provides a small amount of customization and the 1801following user options can be changed using the standard Emacs 1802customization facilities. The main REDUCE customization group is 1803called ``REDUCE'', under which REDUCE run mode provides a sub-group 1804``REDUCE Run'' that allows the following options to be customized. 1805 1806@strong{It is essential to check that @var{reduce-run-commands} is set 1807correctly otherwise REDUCE will not run correctly. The settings of 1808other user options are not critical.} 1809 1810@defopt reduce-run-program 1811This variable is obsolete and has been replaced by 1812`reduce-run-commands' with different value syntax, as described below. 1813@end defopt 1814 1815@defopt reduce-run-commands 1816Default value @code{(("CSL" . "redcsl --nogui") ("PSL" . "redpsl"))} 1817except on Microsoft Windows. 1818 1819The value of this variable is an association list of two elements, one 1820for each of the main Lisp versions on which REDUCE is distributed, 1821namely CSL and PSL. The order of these elements determines the order 1822in which commands that do not specify the REDUCE version try to run 1823REDUCE versions; see below. Each element is a ``dotted pair'' of 1824strings, of which the first is either "CSL" or "PSL" and the second is 1825the command to run that version of REDUCE using a command-line 1826interface. This can include any required options, as illustrated 1827above by the default value for CSL REDUCE. 1828 1829The command can be either the command name, as illustrated above, or 1830it can be a full path name, which can contain spaces. (But spaces are 1831not allowed in the command options.) If command names are used then 1832those commands must be on your search path and on platforms other than 1833Microsoft Windows this should be the case automatically. 1834 1835On Microsoft Windows REDUCE run mode uses full pathnames by default 1836and moreover it uses a separate batch file to run PSL REDUCE, as 1837described above (@pxref{PSL on Windows, Running PSL REDUCE on 1838Microsoft Windows}). 1839@end defopt 1840 1841@defopt reduce-run-prompt 1842Default value @code{"^\\([0-9]+[:*] \\)+"}. The regexp to recognise 1843prompts in REDUCE run mode. The default works well for CSL REDUCE. 1844This variable is used to initialize @code{comint-prompt-regexp} in the 1845REDUCE run buffer. 1846@end defopt 1847 1848@c @item reduce-run-echo 1849@c Default value @code{t}. If non-nil then echo ``automatic'' input to 1850@c REDUCE processes, i.e.@: input generated by REDUCE run mode rather than 1851@c typed directly by the user. 1852 1853@defopt reduce-run-autostart 1854Default value @code{t}. If non-nil then all commands that require a 1855REDUCE process will automatically start a new one if none is already 1856running. 1857@end defopt 1858 1859@defopt reduce-run-multiple 1860Default value @code{t}. If non-nil then commands that explicitly 1861start REDUCE will always start a new REDUCE process in a new distinct 1862buffer, even if REDUCE is already running. Otherwise, they will 1863re-use any appropriate running REDUCE process. 1864@end defopt 1865 1866@defopt reduce-run-mode-hook 1867Default value @code{nil}. The main hook for customising REDUCE run 1868mode. 1869@end defopt 1870 1871@defopt reduce-run-load-hook 1872Default value @code{nil}. The hook run when REDUCE run mode is 1873loaded. It is a good place to put key bindings. 1874@end defopt 1875 1876@defopt reduce-input-filter 1877Default value @code{"\\`\\([ \t;$]*\\|[ \t]*.[ \t]*\\)\\'"}. What not 1878to save on REDUCE run mode's input history. The value is a regular 1879expression (regexp). The default matches any combination of zero or 1880more whitespace characters and/or statement terminators, or any single 1881character (e.g.@: @kbd{y} or @kbd{n}) possibly surrounded by 1882whitespace. 1883@end defopt 1884 1885@defopt reduce-source-modes 1886Default value @code{(reduce-mode)}. Used to determine if a buffer 1887contains REDUCE source code. If a file is loaded into a buffer that is 1888in one of these major modes then it is considered to be a REDUCE source 1889file by @code{reduce-input-file} and @code{reduce-fasl-file}. Used by 1890these commands to determine defaults. 1891@end defopt 1892 1893@defopt reduce-packages-directory 1894Absolute pathname of the directory containing REDUCE packages, or nil. 1895This variable should be set automatically when REDUCE run mode loads. 1896It looks for the packages directory based on the location of default 1897command used to run REDUCE. If the directory cannot be found then 1898this variable will be set to nil. You can customize this variable to 1899override the default setting. 1900@end defopt 1901 1902@c ------------------------------------------------------------------- 1903 1904@node Run REDUCE 1905@section Running, re-running and switching to REDUCE 1906@cindex Multiple Process Support 1907@cindex Process Support, Multiple 1908@cindex Support for Multiple Process 1909 1910The main commands for starting REDUCE are @command{run-reduce}, 1911@command{run-csl-reduce} and @command{run-psl-reduce}. If the user 1912option @var{reduce-run-multiple} is non-nil then they all start a new 1913REDUCE process every time they are executed; successive REDUCE process 1914buffers have successively higher numbers at the end of their names, 1915e.g.@: @code{*CSL REDUCE*}, @code{*CSL REDUCE 1*}, @code{*CSL REDUCE 19162*}, @enddots{} Otherwise they only start a new REDUCE process if 1917necessary---if an appropriate REDUCE process is already running then 1918they simply switch to it. Finally, these commands run the hooks from 1919@var{reduce-run-mode-hook} (after the @var{comint-mode-hook} is run). 1920 1921@deffn Command run-reduce 1922By default, this command starts the default REDUCE version. More 1923precisely, it attempts to start the REDUCE version that appears first 1924in @var{reduce-run-commands}, and if that fails then it attempts to 1925start the REDUCE version that appears second in 1926@var{reduce-run-commands}. It names the REDUCE process buffer with 1927the REDUCE version that it runs, e.g.@: @code{*CSL REDUCE*} or 1928@code{*PSL REDUCE*}. 1929 1930If this command is executed with a prefix argument then it reads a 1931command to run REDUCE from the minibuffer and runs that command. In 1932this case, it names the REDUCE process buffer without any REDUCE 1933version, e.g.@: @code{*REDUCE*}. 1934@end deffn 1935 1936@deffn Command run-csl-reduce 1937This command starts CSL REDUCE and names the REDUCE process buffers 1938that it creates @code{*CSL REDUCE*}, @code{*CSL REDUCE 1*}, etc. 1939@end deffn 1940 1941@deffn Command run-psl-reduce 1942This command starts PSL REDUCE and names the REDUCE process buffers 1943that it creates @code{*PSL REDUCE*}, @code{*PSL REDUCE 1*}, etc. 1944@end deffn 1945 1946A couple of convenience commands allow a running REDUCE process to be 1947re-started in the same buffer and switching from any buffer to a 1948running REDUCE process buffer. 1949 1950@deffn Command re-run-reduce 1951This command is only allowed in a REDUCE process buffer. If REDUCE is 1952running in the current buffer then it is terminated. The command then 1953reruns the version of REDUCE shown in the buffer name. (This will not 1954work if you entered the command to run REDUCE interactively.) 1955@end deffn 1956 1957@deffn Command switch-to-reduce 1958This command is primarily intended for internal use by other commands 1959but it can be run interactively to switch to a running REDUCE process 1960buffer. If the current buffer is an active REDUCE process buffer then 1961the command does nothing; if there is only one active REDUCE process 1962buffer then the command switches to it; otherwise, the command reads 1963the name of an active REDUCE process buffer from the minibuffer with 1964completion. This means that pressing the @kbd{tab} key will give a 1965list of active REDUCE process buffers from which to select one. It 1966remembers the last buffer used and offers that as the default, making 1967it easy to switch repeatedly to the same REDUCE process buffer. This 1968function is used by all commands described below that send REDUCE code 1969fragments to a running REDUCE process. 1970 1971If REDUCE is not running then this command will start REDUCE 1972automatically by calling @command{run-reduce} if the user option 1973@var{reduce-run-autostart} is non-nil (which by default it is). 1974@end deffn 1975 1976@c ------------------------------------------------------------------- 1977 1978@node Run REDUCE Program 1979@section Running complete REDUCE programs 1980 1981The commands @command{reduce-run-file} and @command{reduce-run-buffer} 1982run REDUCE code as an independent REDUCE program by starting the 1983default version of REDUCE in a new process buffer named uniquely by 1984the file or buffer containing the REDUCE code. This allows several 1985REDUCE programs to be conveniently run simultaneously and 1986independently. 1987 1988@deffn Command reduce-run-file 1989This command reads a file name from the minibuffer, starts REDUCE in a 1990new process buffer named uniquely by the file (unless it already 1991exists) and inputs the file into REDUCE. 1992@end deffn 1993 1994@deffn Command reduce-run-buffer 1995This command starts REDUCE in a new process buffer named uniquely by 1996the current buffer (unless it already exists) and inputs the current 1997buffer into REDUCE. 1998@end deffn 1999 2000@c ------------------------------------------------------------------- 2001 2002@node Evaluating Code 2003@section Inputting code fragments to REDUCE 2004@cindex Key bindings 2005@cindex Menu 2006 2007When developing REDUCE code, it may be convenient to be able to test 2008fragments by inputting them into REDUCE. The following commands are 2009intended to be used in a REDUCE edit mode buffer to send code to a 2010REDUCE process buffer. They all use @command{switch-to-reduce} to 2011decide where to send the code. With a prefix argument, the commands 2012also explicitly switch to the REDUCE process window. 2013 2014@deffn Command reduce-eval-last-statement 2015This command sends the code between the beginning of the statement 2016before point and point to REDUCE. The assumption is that point is at 2017the end of a REDUCE statement, but this is not checked so it is 2018possible to send an incomplete statement. 2019@end deffn 2020 2021@deffn Command reduce-eval-region 2022This command sends the code in the selected region to REDUCE. 2023@end deffn 2024 2025@deffn Command reduce-eval-proc 2026This command sends the procedure definition before or containing point 2027to REDUCE. 2028@end deffn 2029 2030@c ------------------------------------------------------------------- 2031 2032@node Processing REDUCE Files 2033@section Inputting, compiling and loading REDUCE files 2034@cindex Key bindings 2035@cindex Menu 2036 2037The following commands deal with complete REDUCE files that do not 2038necessarily constitute complete programs. 2039 2040@deffn Command reduce-input-file 2041Read a file name from the minibuffer and input the file into a REDUCE 2042process. It asks you whether you want the input echoed. 2043@end deffn 2044 2045@deffn Command reduce-fasl-file 2046Read a file name from the minibuffer and compile it into a 2047fast-loading (``fasl'') file, for which it prompts for the name with 2048the source file name as default. It asks you whether you want the 2049input echoed. 2050@end deffn 2051 2052@deffn Command reduce-load-package 2053Read a REDUCE package name from the minibuffer and load it into a 2054REDUCE process. The read process uses completion based on the files 2055in the REDUCE package directory specified by the variable 2056@var{reduce-packages-directory}, which should automatically be set 2057correctly when REDUCE run mode loads. Pressing the @kbd{tab} key 2058should list the packages available, from which you can select in the 2059usual way, such as by clicking on a package name with the mouse. 2060@end deffn 2061 2062@c ------------------------------------------------------------------- 2063 2064@node Run Keys 2065@section Run mode key bindings and menu 2066@cindex Key bindings 2067@cindex Menu 2068 2069If the user option @code{reduce-run-autostart} is non-nil (which it is 2070by default) then all commands that require a REDUCE process 2071automatically start one if necessary. @xref{Run Customization, , 2072Customization of REDUCE run mode}. Where appropriate, input commands 2073have their own history lists, and if run in REDUCE edit mode then any 2074input file defaults to the file being edited. 2075 2076The following key bindings are provided in both REDUCE edit and run 2077modes: 2078 2079@table @kbd 2080@item C-c C-i 2081@kindex C-c C-i 2082@kindex C-c TAB 2083@itemx reduce-input-file 2084@findex reduce-input-file 2085Input a REDUCE source file into the REDUCE process. Echo it if 2086@code{reduce-run-echo} is non-nil. (This key binding redefines its 2087default meaning in REDUCE mode.) 2088 2089@item C-c C-l 2090@kindex C-c C-l 2091@itemx reduce-load-package 2092@findex reduce-load-package 2093Load a REDUCE package into the REDUCE process. 2094 2095@item C-c C-f 2096@kindex C-c C-f 2097@itemx reduce-fasl-file 2098@findex reduce-fasl-file 2099Compile a REDUCE source file to a FASL image in the REDUCE process. 2100Echo the file if @code{reduce-run-echo} is non-nil. 2101@end table 2102 2103The following key bindings are added to REDUCE edit mode: 2104 2105@table @kbd 2106@item C-x C-e 2107@kindex C-x C-e 2108@itemx reduce-eval-last-statement-and-go 2109@findex reduce-eval-last-statement-and-go 2110Send the previous statement to the REDUCE process, and switch to its 2111buffer. (This key binding follows Emacs convention.) 2112 2113@item M-C-x 2114@kindex M-C-x 2115@itemx C-c C-e 2116@kindex C-c C-e 2117@itemx reduce-eval-proc-and-go 2118@findex reduce-eval-proc-and-go 2119Send the current procedure definition to the REDUCE process, and switch 2120to its buffer. (The @kbd{M-C-x} key binding follows Emacs convention.) 2121 2122@item C-c C-r 2123@kindex C-c C-r 2124@itemx reduce-eval-region-and-go 2125@findex reduce-eval-region-and-go 2126Send the current region to the REDUCE process, and switch to its buffer. 2127 2128@item C-c C-z 2129@kindex C-c C-z 2130@itemx switch-to-reduce 2131@findex switch-to-reduce 2132Switch to the REDUCE process buffer. With an argument, position the 2133cursor at the end of the buffer. 2134@end table 2135 2136Versions of the above ``and-go'' commands are also defined with names 2137that omit the ``-and-go'' prefix, which do not switch to the REDUCE 2138process buffer. These seem to be less useful and so are not currently 2139bound to any keys. 2140 2141The following key bindings, in addition to the defaults provided by 2142comint mode, are provided in REDUCE run mode: 2143 2144@table @kbd 2145@c DOES NOT WORK RELIABLY IN EDIT MODE! 2146@c @item C-x C-e 2147@c @kindex C-x C-e 2148@c @itemx reduce-eval-last-statement 2149@c @findex reduce-eval-last-statement 2150@c Send the previous statement to the REDUCE process. 2151@c Prefix argument means switch to the REDUCE buffer afterwards. 2152@c 2153@item M-TAB 2154@kindex M-TAB 2155@itemx reduce-complete-symbol 2156@findex reduce-complete-symbol 2157Perform completion on the REDUCE symbol preceding point (or preceding 2158the region if it is active). Compare that symbol against the elements 2159of @code{reduce-completion-alist}. If a perfect match (only) has a 2160@code{cdr} then delete the match and insert the @code{cdr} if it is a 2161string or call it if it is a (nullary) function, passing on any prefix 2162argument (in raw form). (This key binding is exactly as in REDUCE mode. 2163It is included explicitly here because it is one of the edit mode key 2164bindings that is also particularly useful in run mode.) 2165@end table 2166 2167The REDUCE run library provides a REDUCE run major mode menu and also 2168adds a slightly modified version of this menu to the menu bar in REDUCE 2169edit mode. These two menus provide appropriate access to all the above 2170commands, and to echoing and highlighting control for REDUCE run mode. 2171 2172@c =================================================================== 2173 2174@node Feedback 2175@chapter Feedback: bug reports, suggestions, comments, @dots{} 2176@cindex Feedback 2177@cindex Bug reports 2178@cindex Suggestions 2179@cindex Comments 2180@cindex Contact 2181 2182Feedback to the author via SourceForge is welcome, including reports 2183of errors or features that do not work well and suggestions for 2184improvements or additional features. 2185 2186If possible, please include details of the version of Emacs that you 2187are using, the platform on which you are using it, and the version of 2188REDUCE edit (and if relevant run) mode that you are using. (This 2189information is essential if you are reporting a bug.) An easy way to 2190do this is to send me the Emacs and REDUCE IDE version strings. You 2191can access the former from the standard Emacs @code{Help} menu and the 2192latter from the REDUCE major mode menus, in all cases by selecting the 2193@code{Show Version} menu option. The version strings can also be 2194accessed by running the commands @kbd{M-x emacs-version}, @kbd{M-x 2195reduce-mode-version} and @kbd{M-x reduce-run-version}. These menu 2196options and commands will display the version string in the echo area 2197at the bottom of the frame; it will also be recorded in the 2198@code{*Messages*} buffer, from where it can easily be copied. 2199 2200@c =================================================================== 2201 2202@comment END OF MANUAL TEXT 2203@page 2204 2205@node Command Index 2206@unnumbered Command Index 2207 2208@printindex fn 2209 2210@node Variable Index 2211@unnumbered Variable Index 2212 2213@printindex vr 2214 2215@node Keystroke Index 2216@unnumbered Keystroke Index 2217 2218@printindex ky 2219 2220@c Without a page throw here, the page length seems to get reset to the 2221@c depth of the index that fits on the page after the previous index. 2222@c This must be a bug! 2223 2224@page 2225 2226@node Concept Index 2227@unnumbered Concept Index 2228 2229@printindex cp 2230 2231@bye 2232 2233 2234Formatting this file on Windows 2235=============================== 2236 2237This only seems to work using Cygwin. Install the texinfo and 2238texinfo-tex packages (which also installs a lot of dependent packages, 2239including texlive). Then run the following commands from the Cygwin 2240bash shell. (They don't run in Emacs or from other shells.) 2241 2242To format as info: makeinfo reduce-ide.texinfo 2243 2244To format as HTML: makeinfo --html reduce-ide.texinfo 2245 2246To format as PDF: texi2pdf --build=tidy reduce-ide.texinfo 2247