6 Support for REDUCE comments

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

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

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

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

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

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

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

M-;
M-x comment-dwim

Indent this line’s comment appropriately, or insert an empty comment.

C-M-j
M-j
M-x default-indent-new-line

Break the line at point and indent, continuing a comment if presently within one. The body of the continued comment is indented under the previous comment line.

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

M-q
M-x reduce-fill-comment

Fill a comment statement, successive %-comment lines or a /**/ comment around or immediately following point. A prefix argument means justify as well.

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

C-c ;
M-x reduce-comment-region

Comment/uncomment every line in the region. By default, it toggles the commenting, i.e. it comments the region if it is uncommented and uncomments if it is commented. With an interactive argument, comment if non-negative, uncomment if null or negative (cf. toggling minor modes). When commenting, it puts the value of the variable reduce-comment-region-string at the beginning of every line in the region.

C-c :
M-x reduce-comment-procedure

As for reduce-comment-region, but applies to the procedure ending after point.