1 05/15/80  Emacs PL/I Mode Changes
  2 
  3 The following changes have been made to Emacs pl1-mode and
  4 electric-pl1-mode.
  5 
  6 **This file is intended to be perused via dprint, print, or via an**
  7 **editor.  It is not intended to be perused with the help command **
  8 
  9 
 10 
 11 
 12 ^L
 13 1)  New pl1-line-length option.
 14 2)  Setting pl1-mode options.
 15 3)  Enhancements for pl1dcl (ESC-^D) request.
 16 4)  New pl1-skip-to-dcl-column (ESC-SPACE) request.
 17 5)  New pl1-backward-statement (ESC-^A) and pl1-forward-statement
 18     (ESC-^E) requests.
 19 6)  New pl1-comment-xxx requests.
 20 7)  Enhancements to pl1-comment-box (^XC) request.
 21 8)  New pl1-refill-comment-box-region (^ZC) request.
 22 9)  New pl1-line-between-procs (^ZD) request.
 23 10) New pl1-include-file-comment-start-end (^ZI) request.
 24 11) New pl1-compile-options option.
 25 
 26 
 27 pl1-line-length option:
 28 A new option called pl1-line-length controls the length of lines
 29 generated by pl1dcl (ESC-^D) and several other requests.  The line
 30 length is specified in terms of column positions, with a default
 31 length of 112 columns.
 32 
 33 
 34 Setting pl1-mode options:
 35 Several new options have been added.  pl1-line-length is desribed
 36 above, and others are described in the sections below.  Use ESC-X opt
 37 to list or set pl1-mode options.  When in a pl1-mode buffer, setting
 38 the value changes only the value for the current buffer.  When not in
 39 a pl1-mode buffer, setting the value changes the default value
 40 associated with all new pl1-mode buffers.  Setting these values in a
 41 start_up.emacs segment sets the defaults for all pl1-mode buffers.
 42 
 43 
 44 pl1dcl (ESC-^D):
 45 The pl1dcl request has several new features.  It uses the
 46 get_entry_point_dcl_$emacs subroutine to get the declaration.  This
 47 subroutine first looks in one or more declaration files for the name
 48 being declared.  These files are listed in the "declare" or "dcl"
 49 search paths, which can be set using add_search_paths, etc.  Thus, the
 50 user can define his own declaration files which override or add
 51 declarations in the standard file without duplicating other entries in
 52 the standard file.
 53 
 54 
 55 If the name is not found in one of these declaration files, then an
 56 attempt is made using object search rules to find the name.  If the
 57 name is a procedure entry point, its entry parameter descriptors
 58 (compiled into the object segment itself) are used to create a
 59 declaration.
 60 
 61 
 62 The declaration is then formatted according to a new pl1-mode option
 63 called pl1-dcl-style.  This option can have the following values.
 64 
 65 
 66 0  no formatting is performed.  The declaration appears on a single
 67    line with one space between tokens.
 68 
 69 1  formatting similar to that of the indent command.  It assumes that
 70    the word "dcl" is in column 1, followed by 2 spaces and the
 71    name.  Lines longer than pl1-line-length are folded, being
 72    continued from column 11.
 73 
 74 
 75 2  formatting similar to the experimental format_pl1 command with
 76    indattr mode.  It assumes that dcl is located somewhere between
 77    columns 1 and 10, and that the name is in column 11.  The
 78    declaration begins in pl1-dcl-column (a new options).  Lines longer
 79    than pl1-line-length are folded, being continued from
 80    pl1-dcl-column+5.
 81 
 82 The default value for pl1-dcl-style is 1.
 83 
 84 
 85 Entries in the declaration files have one of two forms.  Standard
 86 declarations begin with a name followed by the attributes to be
 87 associated with that name.  Folding can occur after any comma (or
 88 after whitespace if no commas are found).  No trailing punctuation
 89 should be given.  For example:
 90 
 91 ioa_        entry options(variable)
 92 cu_$arg_ptr entry (fixed bin, ptr, fixed bin(21), fixed bin(35))
 93 iox_$user_output ptr ext static
 94 code        fixed bin(35)
 95 
 96 
 97 A second form declares abbreviations to be used in typing PL/I
 98 programs.  They have the form
 99 
100 name  ==>  abbrev_value
101 
102 When ESC-^D is used with such a name, the name is REPLACED by the
103 abbrev_value.  No reformatting occurs.  Typical abbreviations might be:
104 
105 es        ==> ext static
106 esi       ==> ext static init(
107 fb        ==> fixed bin
108 is        ==> int static
109 isi       ==> int static init(
110 isoc      ==> int static options(constant)
111 isoci     ==> int static options(constant) init(
112 
113 
114 pl1-skip-to-dcl-column (ESC-SPACE):
115 This new request moves the cursor to the column specified by the
116 pl1-dcl-column option.  If the statement already extends beyond this
117 column, the cursor is moved to the pl1-dcl-column on a new line
118 following the current line.  This request is useful for indenting
119 attributes in declare statements when ESC-^D cannot be used and
120 pl1-dcl-style = 2.
121 
122 
123 pl1-backward-statement (ESC-^A), pl1-forward-statement (ESC-^E):
124 Two new requests move forward and backward in increments of PL/I
125 statements.  Both take a numeric argument to indicate how many
126 statements to move over.
127 
128 
129 pl1-comment-xxx requests:
130 A new option pl1-comment-style controls how comments are handled when
131 text extends into the pl1-comment-column (another new option).  The
132 pl1-comment-column defaults to column 61.  If text extends beyond the
133 comment column when one of the line comment requests is given, then
134 the placement of the comment depends upon the pl1-comment-style.
135 
136 
137 pl1-comment-style can have the following values.
138 
139 1  Comment is place on the current line following the text.
140 
141 2  If text extends beyond pl1-commnt-column + pl1-comment-column-delta
142    (a new option), then the comment is placed on a new line below the
143    current line.  Otherwise, it is placed on the current line.  The
144    default value of pl1-comment-column-delta is 10.
145 
146 3  Comment is placed on a new line following the current line.
147 
148 The default value for pl1-comment-style is 1.
149 
150 
151 The following comment requests observe pl1-comment-style.
152 
153 ESC-;     pl1-comment-current-line
154 ESC-N     pl1-comment-next-line
155 ESC-P     pl1-comment-prev-line
156 
157 ESC-N and ESC-P take a numeric argument to indicate how many lines
158 forward or backward the cursor should move before commenting the line.
159 
160 
161 A new pl1-comment-end (ESC-*) request moves the cursor to the end of
162 the line (according to the pl1-line-length option) and places a
163 comment suffix (*/) at the end of a comment line.
164 
165 
166 pl1-comment-box (^XC):
167 This request has been significantly enhanced.  When a new comment box
168 is created, fill-mode is entered to facilitate typing of prose text.
169 The pl1-line-length is used to control the filling of comment lines.
170 When a subsequent (^XC) is entered to exit comment minor-mode, the
171 comment box is completed by placing comment-suffix (*/) at the ends of
172 all box lines.
173 
174 
175 Fill-mode can be exited and re-entered during the creation of a
176 comment box using
177   ESC-X filloff
178   ESC-X fillon
179 
180 
181 If (^XC) is typed to enter comment minor-mode while the cursor is
182 positioned inside an existing comment box, then new comment lines are
183 inserted above the line on which the cursor is positioned.  Filling
184 occurs for only the new lines.  The old lines remain unchanged.
185 
186 
187 pl1-refill-comment-box-region (^ZC):
188 This new request complements the enhancements made to the
189 pl1-comment-box request.  It refills the comment box lines between
190 (and including) the lines containing the cursor and the-mark.
191 
192 
193 pl1-line-between-procs (^ZD):
194 This new request generates a dividing line between major blocks of
195 code in a PL/I program to provide visual separation of the code.  A
196 line of the form:
197 
198 /*  *  *  *  *  *  .... *  */
199 
200 which extends through the pl1-line-length column.  If the cursor is
201 positioned at the beginning of a dividing line, ^ZD causes a new
202 divider plus a newpage to be inserted.  Similarly, ^U^ZD causes a
203 divider, a new page and another divider to be inserted.
204 
205 
206 pl1-include-file-comment-start-end (^ZI):
207 This new request generates a starting and ending comment line for PL/I
208 include files.  The lines have the form:
209 
210 /* START OF:        xxx.incl.pl1        *  *  *  */
211 
212 /* END OF:          xxx.incl.pl1        *  *  *  */
213 
214 
215 New pl1-compile-options option:
216 The pl1-compile-options option can be set to specify the default
217 compilation options used by ESC-^C to compile the program.  The
218 default compiler option is "-table".