From 782ecb6302fd7bd5d5721e654b6513807d97d12c Mon Sep 17 00:00:00 2001 From: Lars Brinkhoff Date: Tue, 28 Sep 2021 14:42:54 +0200 Subject: [PATCH] Docmentation for EMACS CLU mode; autoload. Source: http://pdp10.nocrew.org/its/dl/info/eclu.info.Z It's identical to ECLU.INFO.24 on ToTS tape 9003789. --- build/timestamps.txt | 1 + doc/info/eclu.info | 411 ++++++++++++++++++++++++++ src/emacs1/{usrcom.514 => usrcom.515} | 6 + 3 files changed, 418 insertions(+) create mode 100644 doc/info/eclu.info rename src/emacs1/{usrcom.514 => usrcom.515} (99%) diff --git a/build/timestamps.txt b/build/timestamps.txt index 66e21970..42f35f96 100644 --- a/build/timestamps.txt +++ b/build/timestamps.txt @@ -778,6 +778,7 @@ info/dskuse.10 198108121657.45 _info_/dskuse.info 197605101405.04 _info_/dskuse.recent 197605111409.58 _info_/dump.info 198610240403.57 +info/eclu.info 198012121026.27 info/emacs.147 198107122137.10 info/epasc.32 198209152107.32 _info_/fasbin.format 197610190941.23 diff --git a/doc/info/eclu.info b/doc/info/eclu.info new file mode 100644 index 00000000..b226acc3 --- /dev/null +++ b/doc/info/eclu.info @@ -0,0 +1,411 @@ +-*-Text-*- +This is the file eclu.info, which documents the CLU Mode +EMACS package. + +File: ECLU Node: Top Up: (EMACS) Next: Commands + + ---> report bugs and misfeatures to WBA@XX <--- + + EMACS CLU mode is an editing package to facilitate editing of +CLU programs. It is most briefly described as being LISP mode which +knows about the CLU statement nesting keywords. That is, it replaces +the "S-expression" with a "CLUexp" -- a properly nested CLU expression +or statement. + + CLU mode is entered with the command M-X CLU Mode. This mode +is also entered by the usual mechanism when visiting a file with the +extension "CLU", "SPECS", or "EQUATE", or with the incantation +"-*-CLU-*-" on the first nonempty line. + + A CLUexp is a properly nested piece of text in which the +nesting depth is increased by these "beginning" tokens: + + ( [ { begin proc iter cluster if for while tagcase except + +and is decreased by these "ending" tokens: + + ) ] } end + +Furthermore, these "intermediate" tokens: + + then elseif else do tag others when + +are treated like an invisible "end begin" pair. This assists the +indenter. The types of the beginning and ending tokens are not +checked against each other. For example, "begin )" is a legal CLUexp +(though it will confuse the "display matching paren" feature, since +the latter does not know about keywords.) + + In CLU mode, letters, digits and underscore are alphabetic; +all others are break characters. But see the special treatment of +dollarsign and period by C-M-F and C-M-B. All of the usual word +commands (M-F, M-B, M-D, M-rubout, M-T, etc.) are available. + +* Menu: + +* Commands:: List of available commands. +* Indent:: The indentation format. +* Comments:: Comment conventions. +* Variables:: Synopsis of all variables used. +* Restrictions:: Things that might confuse it. + +ECLU Node: Commands Previous: Restrictions Up: Top Next: Indent + +The commands of CLU mode are listed below. These generally try to be +as similar as possible to the corresponding commands of Lisp or +Fundamental mode. + +C-M-F ^R Forward CLUexp +----------------------------------- +Move forward one complete CLUexp, or as many as the argument. If the +argument is negative, move backward. + +C-M-B ^R Backward CLUexp +------------------------------------ +Move backward one complete CLUexp, or as many as the argument. If the +argument is negative, move forward. + + It is an error to go forward by a CLUexp if just before an + "ending" or "intermediate" token, or to go backward if just + after a "beginning" or "intermediate" token. A CLUexp is a + properly nested piece of text, or a sequence of alphabetic + characters, or a character or string constant. These commands + will go past any other text that they encounter on the way to + the CLUexp: operators, whitespace, comments, etc. + + If, after going past an alphabetic CLUexp in either direction, + the very next character is a dollarsign or period and the next + is alphabetic, it passes an extra CLUexp. So, for example, + "foo.bar" and "int$add" are considered single CLUexp's, but + "(foo).bar" and "[int]$add" are each two CLUexp's. To get EMACS + to stop on the period or dollarsign between two symbols, use the + word commands M-F or M-B instead of C-M-F or C-M-B. + +C-M-K ^R Kill CLUexp +C-M-rubout ^R Backward Kill CLUexp +----------------------------------------- +These kill the text between the current location and where C-M-F or +C-M-B would go. They can take positive or negative arguments like +C-M-F and C-M-B. The killed text is placed on the Kill Ring. + + Note - to move blocks of text around, these commands do not kill + the carriage return at the end of the last line. A better way is + to use M-H to mark the entire block and then C-W or M-W or whatever. + +C-M-@ ^R Mark CLUexp +------------------------------- +This places a mark one (or several) CLUexp's from the cursor, in the +appropriate direction. The cursor does not move. + +M-H ^R Mark Lines Of CLUexp +----------------------------------------- +This BACKS UP TO THE BEGINNING OF THE LINE, counts the appropriate +number of CLUexp's forward or backward, and places the region around +them, including extra text so that the region contains only complete +lines. The mark is left at the beginning and the cursor at the end. + +C-M-T ^R Transpose CLUexps +-------------------------------------- +This performs the standard EMACS transposition operation, transposing +the CLUexps before and after the cursor. With a positive argument it +transposes the CLUexps before and after the cursor, moves right, and +repeats the specified number of times, dragging the CLUexp to the left +of the cursor right. With a negative argument, it transposes the two +CLUexps to the left of the cursor, moves between them, and repeats the +specified number of times, exactly undoing the positive argument form. +With a zero argument, it transposes the CLUexps after point and mark. + +C-M-D ^R Down CLUexp +-------------------------------- +This goes forward into ("down") 1 level of CLU structure, or as many +as the argument. Given a negative argument, it goes forward out that +many levels. C-M-D and C-M-U are easier to remember if one thinks of +them as traversing a series of left parentheses, that is, a "downward +slope". That way, down means forward and up means backward. + +C-M-U, C-M-( ^R Backward Up CLUexp +--------------------------------------- +This goes backward out ("up") 1 level of CLU structure, or as many as +the argument. Given a negative argument, it goes backward into that +many levels. Note that the sign of the argument never changes the +direction. + +C-M-) ^R Forward Up CLUexp +-------------------------------------- +This goes forward out 1 level of CLU structure, or as many as the +argument. Given a negative argument, it goes forward into that many +levels. The mnemonic significance of C-M-( and C-M-) is that they go +out of CLU structure as if searching for the appropriate type of +parenthesis. + +C-M-A ^R Beginning of Module +---------------------------------------- +This moves to the beginning of this or the previous module definition. +Given an argument, it does it that many times. It leaves a mark in +case it is typed by accident. It acts by searching back for the last +module header, which is a line whose first three tokens are a symbol, +equals sign, and "proc" or "iter", with optional whitespace around +them. + +C-M-E ^R End of Module +---------------------------------- +This moves to the end of this or the next module definition. Given an +argument, it does it that many times. It leaves a mark in case it is +typed by accident. Since module ends are hard to identify, it acts by +looking for the next module header and backing up to just after the +"end" that ends the previous module. This means that if it is in the +last module of a cluster, it will go to the end of the entire cluster. + +M-( ^R Make CLU () +M-[ ^R Make CLU [] +M-{ ^R Make CLU {} +------------------------------- +These insert a pair of parens, brackets, or braces, leaving the cursor +between them. If given an explicit positive argument, they push the +closing paren, bracket, or brace forward past the specified number of +already existing CLUexps. M-( is similar to its behavior in LISP +mode. M-[ and M-{ are new. Note that the definition of M-[ destroys +the function ^R Backward Paragraph, which is not useful in CLU mode. + +tab ^R Indent for CLU +---------------------------------- +If there is anything other than whitespace to the left on this line, a +tab character is inserted. + +Otherwise, if the line is not empty, the indentation is set to be +correct relative to to the last nonempty line preceding, excluding +lines with only single or triple percent comments. Any comment has +its indentation set according to the algorithm described elsewhere. +The cursor is left at the beginning of the line in this case. + +If the line is empty, indentation is created to align what will be +typed next, assuming it will not start with "ending" tokens. (It +can't really set the indentation right for a line it hasn't seen yet, +but the use of the linefeed command can correct this.) The cursor is +left at the end of the indentation. + +linefeed ^R Indent new CLU Line +---------------------------------------- +This deletes whitespace to the left of the cursor, inserts a CRLF, and +behaves, roughly, as though tab were typed. That is, it sets up the +indentation correctly for the next line. It does one other thing: if +typed at the end of a line, it corrects the indentation of that line +before going to the next, on the assumption that that line's +indentation was calculated before it was actually typed. Thus the +behavior of linefeed is such that, if fresh text is typed in using +linefeed to start new lines, the text will indent itself correctly. +Lines beginning with tokens such as "end" or "else" will be too far to +the right while they are being typed, but they will correct themselves +when they are ended with linefeeds. + +If not typed at the end of a line, it breaks the text at that point +and sets the indentation of the next line, but does not attempt to +correct the indentation of the original line. This may be used for +"manual grinding". For example, if we have + + OBJ := thing$make_const(block${val: foo$make_x(V), typ: Y}) + | | + +and we type linefeeds at the points shown, we get + + OBJ := thing$make_const(block${ + val: foo$make_x(V), + typ: Y}) + +C-;, M-; ^R Indent for CLUcomment +----------------------------------------- +This aligns an existing comment on the current line, depending on +whether it begins with one, two, or more percents, according to the +algorithm described elsewhere. If there is no comment, it creates a +single percent comment ready to be typed into. The cursor is always +left after the comment starter. + +Given a numeric argument N, it aligns existing comments (not creating +new ones) in the next N lines, and leaves the cursor after those +lines. + +M-linefeed, M-J ^R Indent New CLUcomment Line +---------------------------------------------- +This deletes whitespace to the left of the cursor, inserts a CRLF, +and, if the old line contained a comment, creates indentation and +percents for a continuation of that comment on the next line. The +number of percents and starting column are copied from the previous +line. If it was typed at the end of a line, the new line will be +empty except for the indentation and percents, ready for a comment to +be typed in. In this case it also corrects the indentation of the +preceding line, just as simple linefeed does. Hence, fresh text typed +in with linefeeds and meta-linefeeds will indent itself. If it was +not typed at the end of a line, that line will not be corrected, and +the text after the point where it is typed will become the comment on +the new line. + +If this is typed when not in a comment, the behavior is the same as +simple linefeed. + +M-G ^R Indent CLU Region +------------------------------------- +The lines between the cursor and the mark (that is, the lines whose +first characters are between the cursor and the mark) are indented +according to the algorithm described elsewhere. The indentation of +the first such line is set to be correct relative to the last nonempty +line preceding, excluding lines with only single or triple percent +comments. All comments are appropriately indented according to the +algorithm described elsewhere. Mark is left at the beginning of the +newly indented text and the cursor at the end, unless an argument (for +example, just C-U) is given, in which case they are the other way +around. Nothing is moved from one line to another. There is no +"grind" operation. + +M-Q ^R Indent Lines Of CLUexp +------------------------------------------- +This BACKS UP TO THE BEGINNING OF THE LINE, counts the appropriate +number of CLUexp's forward or backward, and indents the resulting +region just as M-G does. Mark is left at the beginning and the cursor +at the end. This is just M-H followed by M-G. + +M-& ^R CLU Compile +-------------------------------- +This runs a CLU compiler in an inferior fork, creating one if +necessary. The compiler is kept from one run to another until killed +by C-U 0 M-&. It first offers to write out each file, unless there is +a numeric arg other than 0. It then reads a command line to pass to +CLU: in this line, any occurrence of "&" is translated into the full +name of the visited file. If the line is empty, "compile &" is used, +that is, the visited file is compiled. The command line may have +several commands separated by "#", for example: + "optimize time # compile &" +The "stay" command is always implicitly added. + +When the compiler finishes, the file "clu.junk" on the connected +directory is then displayed as if with the "M-X View File" command. +Type a space to go to the next screenful, or backspace to back up. +Space after the end will terminate viewing and go back to the visited +file. + +If M-& is called with an argument of zero, the compiler is simply +killed, so that a fresh one will be created next time. No other +action is taken. + +When a fresh compiler is created, its name is taken from the variable +"CLU Compiler", which see. + +******************** RECOVERING FROM MISTAKES ******************** + +The text killed or indented by C-M-K, C-M-rubout, M-G, or M-Q can be +restored with the "M-X Undo" command. Killed text can also be brought +back with the C-Y command. + +ECLU Node: Indent Previous: Commands Up: Top Next: Comments + + The indentation format is quite simple. (Of course, you don't +need to format your program this way; this is simply the format that +results from using the automatic indentation commands such as M-G or +M-Q.) + + Lines of code are indented relative to each other according to +the lowest nesting level that they attain after the initial run of +ending tokens. A sample is + +if X then % minimum level=0, set to 1 by "if" + foo % 1 +elseif Y then % 0, since "elseif" goes down to 0, + % then back to 1 + if P then Q else R end % 1 (oscillates between 1 and 2) + for + J : int in T$indexes(Q) % 2 + do % down to 1, then back to 2 + F := S${ % min is 2, then up to 3 + a: 1, % 3 + b: 2, + c: 3} % down to 2, but not in initial run of + % ending tokens, so it counts as 3 + end % down to 1 +end % down to 0 + + The indentation per nesting level is the value of the variable +CLU Indent Offset. It is normally 3. + +ECLU Node: Comments Previous: Indent Up: Top Next: Variables + + The comment character is of course percent, and all of the +usual comment operations are available. The standard EMACS +conventions apply: + + A comment beginning with a single "%" will be indented by indenting + commands (M-; for example) to column 32, or some multiple of 8 + beyond that if necessary. The variables Comment Column and Comment + Rounding may be used to alter these numbers. + + A comment beginning with "%%" and with only whitespace before it is + indented as though it were code. That is, it is aligned relative to + the CLU code preceding it. + + A comment beginning with "%%%" is never moved by the indenting + commands, unless they push the preceding text into it. Double + and triple percent comments should be on lines by themselves. + +ECLU Node: Variables Previous: Comments Up: Top Next: Restrictions + +The CLU library has a few switches you can set to customize its +behavior. For info on how to set the variables: +*Note Vars: (EMACS)Variables. + +Comment Column and Comment Rounding determine the normal starting +column for single percent comments and the action to take when that is +not suitable. The normal values are 32 and the next acceptable +multiple of 8. Comment Column may be set to the current horizontal +position (or a numerical argument) by C-X ;. It may also be changed +on a per-buffer basis by a Local Modes specification at the end of the +text file, or by running M-X Edit Options. It may also be set for all +CLU buffers by defining the variable CLUcomment Column in an INIT or +EVARS file. + +Comment Begin contains the string used to start newly created +comments. It is normally "% ", so one blank is created after the +percent. It may be changed to get a different number of leading +blanks. It may be changed on a per-buffer basis by a Local Modes +specification at the end of the text file, or by running M-X Edit +Options. It may also be set for all CLU buffers by defining the +variable CLUcomment Begin in an INIT or EVARS file. + +CLU Indent Offset gives the amount of indentation per nesting level. +The normal value is 3. It may be changed by an INIT or EVARS file or +by running M-X Edit Options, or, on a per-buffer basis, by a Local +Modes specification at the end of the text file. + +CLU Compiler contains the name of the compiler to be used by M-&. Its +normal value is "ps:tcmp.exe.0", for the "new" CLU. It may be +changed (to "ps:clu.exe.0", for example) by an INIT or EVARS +file, or by M-X Edit Options. However, it is only examined when a new +compiler is loaded, so, when M-X Edit Options is used, you must kill +the present compiler with C-U 0 M-& to force it to load a new one. + +Do not change Comment Start or Comment End. The syntax of comments is +built in to the functions of CLU Mode. + +ECLU Node: Restrictions Previous: Variables Up: Top Next: Commands + + The CLUexp parsing routines may behave strangely if started +from within a comment or a character or string constant, or if a +character or string constant extends past a line boundary (not legal +in CLU). + + The "display matching paren" feature uses a TECO mechanism +that does not know the full syntax of CLU, so it may be fooled by +parens, brackets, or braces inside character or string constants or +comments. The CLUexp parsing routines have no such problems. + + A few of the standard EMACS routines for dealing with comments +can be confused by percent in a string. These include possibly C-U +C-X ;, ^R Indent Comment Relative, ^R Indent Nested, and ^R Auto Fill +Space. + +Tag Table: +File: ECLU Node: Top115 +ECLU Node: Commands1896 +ECLU Node: Indent13797 +ECLU Node: Comments14833 +ECLU Node: Variables15687 +ECLU Node: Restrictions17736 + +End Tag Table diff --git a/src/emacs1/usrcom.514 b/src/emacs1/usrcom.515 similarity index 99% rename from src/emacs1/usrcom.514 rename to src/emacs1/usrcom.515 index 0eb009a4..a7d19cf8 100755 --- a/src/emacs1/usrcom.514 +++ b/src/emacs1/usrcom.515 @@ -185,6 +185,12 @@ Arg is line number to split screen at.! M(M.M Load_Library) DSK:EMACS;TDEBUG' F:M(M.M Debug_Mode) +!CLU Mode:! !C Set up to edit CLU code. +g(m.aC~DOC~ CLU Mode)jk! + + M(M.M Load_Library)CLU + :M(M.M CLU_Mode) + !Auto Fill Mode:! !C Break lines between words at the right margin. A positive argument turns Auto Fill mode on; zero or negative, turns it off. With no argument, the mode is toggled.