From 2f18176c58d05305ef5c94c26914f4a2e51077ba Mon Sep 17 00:00:00 2001 From: Lars Brinkhoff Date: Tue, 28 Sep 2021 14:55:21 +0200 Subject: [PATCH] Documentation for EMACS PL1 mode; fix version number. Backups show that EMACS1; PL1 251 is identical to version 250 except the timestamp. --- build/timestamps.txt | 3 +- doc/info/pl1lib.102 | 283 ++++++++++++++++++++++++++++++++ src/emacs1/{pl1.251 => pl1.250} | Bin 3 files changed, 285 insertions(+), 1 deletion(-) create mode 100644 doc/info/pl1lib.102 rename src/emacs1/{pl1.251 => pl1.250} (100%) diff --git a/build/timestamps.txt b/build/timestamps.txt index 90f08bc7..3e7bf73e 100644 --- a/build/timestamps.txt +++ b/build/timestamps.txt @@ -385,7 +385,7 @@ emacs1/muddle.14 198904011826.00 emacs1/page.42 198904011826.17 emacs1/pascal.51 198209152103.32 emacs1/pictur.16 198904011826.28 -emacs1/pl1.251 198904011826.29 +emacs1/pl1.250 198104041055.27 emacs1/purify.127 198904011826.37 emacs1/^rbase.374 198709111507.21 emacs1/renum.454 198904011826.39 @@ -852,6 +852,7 @@ _info_/palx.order 198210041150.54 _info_/pcode.info 197710311017.34 _info_/pdp11.order 197708042053.56 info/photo.6 198906221349.13 +info/pl11lib.102 197804071146.27 info/pr.5 198201071721.21 _info_/qioord.2122 198203101438.35 _info_/qmail.info 197507031634.21 diff --git a/doc/info/pl1lib.102 b/doc/info/pl1lib.102 new file mode 100644 index 00000000..21633896 --- /dev/null +++ b/doc/info/pl1lib.102 @@ -0,0 +1,283 @@ + +File: PL1LIB Node: TOP Next: USER Up: (DIR) + + The EMACS library PL1LIB contains macros to help edit PL1 +code. Since PL1 indentation styles vary a lot, the PL1LIB macros are +structured into an extensible scheme that allows the user control +over the kinds of indenting done. + + Load these macros into an EMACS, by MM Load Library$PL1LIB$$. +Then MM PL1 Mode$$ will set things up for editing PL1 code, such as +setting comment delimiters, and putting the statement indenter into +TAB. If you want to set things up differently, you can provide a +macro named Init PL1 Mode. + + The main macro is ^R Indent PL1 Statement. This macro is the +"driver" which implements the indentation scheme, calling special +indentation subroutines to do the actual work of indenting, based on +the kind of previous statement, if the macro is called to indent a +new statement. If called to indent a new line of an unfinished +statement the indentation subroutine is chosen based on the current +kind of statement. There are indentation subrs provided for different +kinds of PL1 statement types, and you can provide your own to taylor +indenting style. + + BEWARE! Pl1 mode is not as smart as you or I. (Well... half right +at least...) Avoid using statment keywords that drive indenting as +variables at the beginning of a statement, e.g. don't do: + + DO = ...; + +Don't even do: + + DO = END; + + Everyone should acquaint themselves with ^R Indent PL1 Statement +(do "M User Calls" or just "N" to read about it). After that, you can +read about various indentation subrs to handle common PL1 statements +that are provided in the basic PL1LIB library (by doing "M Finished" +or "M Unfinished" from here, or just "N" from Indent Stmt). Those +interested in writing their own indentation subrs can read through +other parts of this info file. + + To insert a full description of the PL1 commands, ^R macros, and +subrs you can do: + MM Load Library$ABSTR$ + MM Abstract File$ $ $PL1LIB$ +Also, to keep up with changes or make suggestions, you can put +yourself on the INFO-PL1-MODE mailing list on MC. + +* Menu: Read at least User Calls, Related. + +* User Calls: USER Commands and ^R macros. + +* Related: USEFUL Useful, related macros in EMACS. + +* Finished: FIN Indentation subrs called when previous stmt was + finished. + +* Unfinished: UNFIN Indentation subrs called when previous stmt was + unfinished, i.e. really beginning of this one. + +* Subroutines: SUBRS PL1LIB provides several subroutines for moving + around PL1 code, for use by indentation subrs. + +File: PL1LIB Node: USER Next: USEFUL Up: TOP + +^R Indent PL1 Stmt: + + The statement indenter is the main macro in the PL1LIB library. +It indents a statement by an amount that depends on the previous +statement's type, and whether it was finished (i.e. had a semi-colon +at its end -- you can call ^R Indent PL1 Stmt to indent a part of a +statement that was started on a previous line). Any existing +indentation is removed before indenting. + After determining the previous statement's type (e.g. DO or IF, +based on the first non-label, non-comment token found in the +statement), ^R Indent PL1 Stmt will make up a name of an indentation +subr to handle indenting statements that follow that type: & PL1 +Indent After . If the previous statement was unfinished, the +indentation subr name is of the form & PL1 Indent Unfin . If +there is no such subr, a default is called: & PL1 Indent After Stmt, +or & Indent Unfin PL1 Stmt. These subrs indent based on the type and +indentation of the previous statement. + If an ARG is specified (e.g. ^U TAB), if there are tokens to the +left in the line, or if indentation is beyond the desired column +(e.g. TAB TAB), then ^R PL1 Indent Relative is called. + +^R PL1 Indent Relative: + + Successive calls indent under successive words of last line. + +^R Global Comment, and ^R End Global Comment: + + Call ^R for a large comment. Comment column is set to 10 and +auto fill is turned on. End comment returns from this ^R. This +macro may someday put the resulting text in a comment-box. + +^R Slurp PL1 to Char: + + A fix for auto-fill indenting over too far, this macro pulls +non-comment text from previous line (back to CHAR typed) and inserts +it at point, calling the statement indenter again so you can see if +things look better now. + +^R Print Last PL1 Indenter: + + Prints name of indentation subroutine that was called by the +statement indenter -- i.e. this will tell you what kind of previous +statement the indenter thought it was working with. (IF, DO, ...) +This macro is useful if you're not sure just what happened w + +Indent PL1 Region: + + Calls the statement indenter for each line from here to MARK. I +suggest that you use this carefully, e.g. indenting small, +screen-sized regions. To protect against horrible mistakes, the old +text is put on the kill stack, and point and MARK surround the new. + +File: PL1LIB Node: USEFUL Next: FIN Previous: USER Up: TOP + +Some related EMACS ^R macros that you may find useful, ordered by how +useful I find them, are: + + ^R Indent for Comment + ^R End Comment + ^R Indent New Comment Line (both comments and non-comments) + ^R Delete Horizontal Space + ^R Indent Nested + ^R Indent Under (TMACS library version combines this and nested) + + ^R Back to Indentation + ^R Delete Indentation + + ^R Indent Rigidly + + ^R Up Indented Line + ^R Down Indent Line + +If you want more you can always MM Apropos$Indent$, or +MM Apropos$Comment$... + +File: PL1LIB Node: FIN Next: UNFIN Previous: USEFUL Up: Top + + This section documents the indentation subroutines called to +handle new statements, i.e. there is nothing between here and the +previous statement end (;) except labels and comments. Such +indentation subrs have names of the form & PL1 Indent After . +The PL1LIB library provides indentation subrs for finished previous +statements of type: + IF, ON, ELSE, (the compound statement types) + DO, BEGIN, (block beginners) + PROC, ENTRY + END, (block ender) + and the default (previous statement had no specific + subr for it) + The default for random previous statements, & PL1 Indent After +Stmt, just indents the same amount as the previous statement. (If +this is the first pl1 statement in the buffer, indentation is given +by the variable $1st Stmt Indentation$, which has default 10.) + +* Menu: More details on PL1LIB's indentation subrs. + +* Compound: COMP Compound statements, IF, ELSE and ON, look at + the last sub-statement, e.g. IF ... THEN DO; vs + IF ... THEN CALL FOO;. + +* Block: BLOCK Statements that start blocks, DO and BEGIN. + +* Procedure: PROC Proc and entry. + +* End: END The END statement looks back for matching DO etc. + +File: PL1LIB Node: COMP Next: BLOCK Up: FIN + + The compound statements IF, ELSE, and ON contain sub-statements, and +indenting after these depends on the last sub-statement: if this last +sub-statement is a DO or BEGIN, the next statement is indented past +the DO/BEGIN by a user-specified amount, in variable $COMP BLOCK +INDENTATION$. I.e., & PL1 Indent After Compound will indent the next line +to align with the DO or BEGIN, and then indent $COMP...$ more. The +default for $...$ is 0, in which case some examples are: + + IF ... THEN IF ... THEN DO WHILE I>0; + here +or + IF ... + THEN BEGIN; + here + + If there is no DO or BEGIN, indentation is kept the same: + + IF ... THEN CALL FOO; + here +or + IF ... + THEN IF ... THEN CALL FOO; + here + + For $COMP BLOCK Indentation$ = 5: + + IF ... THEN BEGIN; + here + +File: PL1LIB Node: BLOCK Next: PROC Previous: COMP Up: FIN + + DO and BEGIN statements start blocks which are indented to align +with the first non-whitespace following the DO or BEGIN, e.g. + + DO WHILE I > 0; + here + or + BEGIN; + here +or + DO I = 1 TO 50; + here + +File: PL1LIB Node: PROC Next: END Previous: BLOCK Up: FIN + + Indent a constant amount, specified by $1st Proc Stmt Indentation$. +If not exist, defaults to 10. + +File: PL1LIB Node: END Previous: PROC Up: FIN + + END statements are the trickiest: they search back over +preceeding statements until a matching DO, BEGIN, or PROC is found. +The indentation for the statement following the END is the same as +that of the statement containing the matching DO/BEGIN/PROC. + + For example: + + DO WHILE TRUE; + A = B; + IF THIS THEN THAT; + END; + here + +or + IF THIS THEN DO; + A = B; + DO WHILE FOO; + B = C; + END; + CALL GAGGLE(GEESE); + END; + here + +File: PL1LIB Node: UNFIN Next: SUBRS Previous: FIN Up: TOP + + The unfinished-IF indents the same amount as the IF, if the THEN +hasn't occurred yet. If it has, calls the default unfin-indenter. + + The unfinished compound for ON and ELSE indents the same amount +as the last sub-statement so far. + + The default is fairly hairy and has several mutually exclusive cases: + +Case 1: If there is an open paren, align with next non-whitespace. +Case 2: If $Unfin Stmt Indentation$ exists, indent that more than + start of statement. +Case 3: If prev line contains start of stmt, aligns with 1st word + after beginning of stmt token (note: tokens may be several + words, e.g. var_name is one token, two words). +Case 4: Calls ^R PL1 Indent Relative if the above cases don't hold. + +File: PL1LIB Node: SUBRS Previous: UNFIN Up: TOP + + There are several subroutines available for use by indentation +subroutines, to help move to tokens past labels and comments, move to +previous statement ends, find the last sub-statement in a +compound (IF or ON) statement, etc. + + These subroutines generally take arguments telling where to start +their searches from, and/or an iteration count. Subroutines that +find tokens return two values, surrounding the token. Subroutines +finding ends of statements return a pointer to the semi-colon. + + For failed searches, generally either b or z is returned for values. + + For more info on these subrs, you can abstract PL1LIB as +mentioned earlier, or while it is loaded, you can MM List +Subroutines$$ and MM Describe$$ whatever looks interesting. + diff --git a/src/emacs1/pl1.251 b/src/emacs1/pl1.250 similarity index 100% rename from src/emacs1/pl1.251 rename to src/emacs1/pl1.250