minor doc updates

Author: maurymarkowitz

README.md

@@ -99,7 +99,7 @@ RetroBASIC CLI
 > RUN
 ```
 
-As part of this addition, support for a "break" key was added. This is wired to the `Esc` key on Unix and macOS machines. On Windows machines, you can use both `Esc` as well as the `Pause`/`Break` key above the cursor controls. Break also works in non-interactive mode, but in that case it will exit directly to the shell. In interactive mode, it return sto the line editor, where you can modify the program and then `CONT`inue. If you wish to exit to the shell from interactive mode, use `BYE` or Control-C.
+As part of this work, support for a "break" key was added. This is wired to the `Esc` key on Unix and macOS machines. On Windows machines, you can use both `Esc` as well as the `Pause`/`Break` key above the cursor controls. Break also works in non-interactive mode, but in that case it will exit directly to the shell. This is still useful when you find the program is stuck in a loop. In interactive mode, it returns to the line editor, where you can modify the program and then `CONT`inue. If you wish to exit to the shell from interactive mode, use `BYE` or Control-C.
 
 ## Missing features and Errata
 

docs/RetroBASIC design.md

@@ -13,7 +13,7 @@ This document explains some of the design goals, coding decisions and style sele
 
 RetroBASIC started in 2020 as a project to collect statistics from classic BASIC programs in an effort to find ways to improve the notoriously slow Atari BASIC. The goal was to find changes that would offer the most significant improvements for the least amount of changes to the original code. For this I needed useful statistics on what sorts of things programs of the era actually did.
 
-Initially this led to some regex-like work in Python, but it quickly became clear that the complexity of the code was daunting. For instance, one of the statistics that I wanted to collect was the number and distribution of numeric constants in a typical program. These took up lots of memory in Atari BASIC and I felt that there were possible savings here. But it was also important to know the difference between constants and line numbers, like in GOTOs, and the distribution of each. When one considers all of the places constants appear - in formulas, array indexes, line numbers, etc. - separating out the cases became annoying.
+Initially this led to some regex-like work in Python, but it quickly became clear that the complexity of the code was daunting. For instance, one of the statistics that I wanted to collect was the number and distribution of numeric constants in a typical program. These took up lots of memory in Atari BASIC and I felt that there were possible improvements here. But it was also important to know the difference between constants and line numbers, like in GOTOs, and the distribution of each. When one considers all of the places constants appear - in formulas, array indexes, line numbers, etc. - separating out the cases became annoying.
 
 So I decided the best solution was to use an actual BASIC interpreter and collect statistics from the tokenized code. Desiring a solution that would run on practically any system with a minimum of external software, I went with lex/yacc, as it has existed for decades and is available everywhere. While it is no longer as widely used as it once was, there's lots of example code out there and still a lot of experience available to help on the 'net.
 
@@ -37,29 +37,29 @@ Dartmouth was developed on a mainframe and they chose to implement the language
 
 ### HP
 
-At almost the same time that Dartmouth v4 appeared, Hewlett-Packard introduced the HP2000, a minicomputer whose primary language was BASIC. Their variation had string support using the FORTRAN-like concept of "array slicing". For instance, to extract the first five characters of a string, one would `A$ = B$(1,5)`, or to concatenate two strings, `A$(10) = B$`, which means that everything from character 10 on should be replaced by the contents of B$. This provided almost all of the needed functionality using a single syntax, which also has performance advantages (more on this below).
+At almost the same time that Dartmouth v4 appeared, Hewlett-Packard introduced the HP2000, a minicomputer whose primary language was BASIC. Their variation had string support using the FORTRAN-like concept of "array slicing". For instance, to extract the first five characters of a string, one would `A$ = B$(1,5)`, or to concatenate two strings, `A$(10) = B$`, which means that everything from character 10 on should be replaced by the contents of B$. This provided almost all of the needed functionality using a single, clean, syntax, which also has performance advantages (more on this below).
 
 But you can also see a problem: they used the same syntax as an array access, so there was no way to define arrays of strings. What's particularity odd about this is that HP offered an alternative syntax using square brackets, `A$[10] = B$`. Had they simply specified brackets for string slicing and parens for array access, then something like `A$(1)[1,5]` would be possible. But... they didn't.
 
-Largely lost to history today, the HP2000s were *extremely* influential. That's because for the low-low price of about $50,000 (a little under half a million in 2022), one could build out a system that would run up to 16 users on a single rack-mount machine. For a time, until the first all-in-one microcomputers appeared in the later 1970s, the HP dialect was by far the most popular and there and books filled with HP code. When other companies entered the mini space, like Data General, they were most familiar with the HP version and generally copied it. For a time, HP BASIC *was* BASIC, and BASIC was *the* language of the future.
+Largely lost to history today, the HP2000s were *extremely* influential. That's because for the low-low price of about $50,000 (a little under half a million in 2022 dollars), one could build out a system that would run up to 16 users on a single rack-mount machine. For a time, until the first all-in-one microcomputers appeared in the later 1970s, the HP dialect was by far the most popular and there were libraries worth of books filled with HP code. When other companies entered the mini space, like Data General, they were most familiar with the HP version and generally copied it. For a time, HP BASIC *was* BASIC, and BASIC was *the* language of the future.
 
 ### DEC
 
 And then there's Digital. DEC was slow to the BASIC game because they were pushing their own language, FOCAL.
 
 At the same time that Dartmouth was creating BASIC, a team at SRI was creating JOSS. BASIC and JOSS are very similar in concept and implementation. FOCAL is a very cut-down version of JOSS that was small enough to run on the PDP-8. The result is almost identical to early versions of BASIC, lacking string variables and other features introduced in later versions, but otherwise differing mostly in the names of the keywords.
 
-At DEC, David Ahl was tired of seeing people ignore their PDP-8 in favor of the HP2000 because DEC had FOCAL and HP had BASIC. Management was locked deep in  not-invented-here syndrome, and wouldn't consider BASIC. So Ahl went out and hired someone to write BASIC for the PDP-8. All interest in FOCAL immediately evaporated. He helped this process along by personally porting over many of the popular FOCAL programs to BASIC, like Lunar Lander and Hamurabi. The PDP-8 had only 4k of memory, so it was a simple dialect, but still useable for most early programs.
+At DEC, David Ahl was tired of seeing people ignore their PDP-8 in favor of the HP2000 because DEC had FOCAL and HP had BASIC. Management was locked deep in not-invented-here syndrome, and wouldn't consider BASIC. So Ahl went out and hired someone to write BASIC for the PDP-8. All interest in FOCAL immediately evaporated. He helped this process along by personally porting over many of the popular FOCAL programs to BASIC, like Lunar Lander and Hamurabi. The PDP-8 had only 4k of memory, so it had to be a simple dialect, but it was still useable for most early programs.
 
 But then DEC released the PDP-10, and shortly after, the PDP-11. DEC had been working with Tymshare on operating systems for the PDP-10, and Tymshare had their own SUPER BASIC which set the pattern for DEC's own BASIC-PLUS. The most notable difference in Tymshare's implementation was their set of string functions, `MID`, `LEFT`, `RIGHT` and so forth. I have no idea why they went this route when the HP pattern was already widespread, and I suspect the people that know are no longer around. But here we are, only a couple of years into the history of BASIC, and there is yet another solution to the same string problem.
 
 There is a real drawback to DEC's solution. Consider the code `A$="HELLO WORLD":PRINT LEFT$(A$,5);:PRINT " ";:PRINT RIGHT$(A$,5)`. This code produces three separate strings on the heap because the string functions return new strings. In contrast, A$="HELLO WORLD":PRINT A$(1,5);:PRINT " ";:PRINT A$(6) in the HP dialect results in only one string on the heap because slices are simply pointers into the existing string. The HP concept is generally more memory efficient and faster because it's not always creating new objects.
 
-### What does all this have to do with anything?
+### What does all of this have to do with anything?
 
 So along comes 1975 and the Altair 8800. Within a year there are dozens of microcomputer kits on the market, and every single one uses BASIC as a primary language. Dartmouth was a compiler that ran on mainframes, so that was going nowhere. Most of the people that got a micro had worked with a BASIC interpreter on a DEC or HP machine. When they created their versions of BASIC, they did so based on whatever version they knew.
 
-When Gates, Allen and Davidoff began writing their BASIC for the Altair, they did so on the PDP-10, and naturally the result looks a lot like DEC's BASIC-PLUS. In contrast, when Woz wrote Apple BASIC while working a day job at HP, it naturally ended up looking like HP BASIC. For a time, 1975 through about late 1978, the two dialects were equally common and there are dozens of examples of both being used on various platforms.
+When Gates, Allen and Davidoff began writing their BASIC for the Altair, they did so on the PDP-10, and naturally the result looks a lot like DEC's BASIC-PLUS. In contrast, when Woz wrote Apple BASIC while working a day job at HP, it naturally ended up looking like HP BASIC. For a time, 1975 through about late 1978, the two dialects were equally common and there are dozens of examples of both being used on various platforms, but the HP style was definitely more common.
 
 Things started changing in late 1977; over a period of about six months, the Apple II, TRS-80 and Commodore PET were released. Commodore licensed MS's new 6502 version as its dialect, and Apple shipped their Applesoft version as an loadable program before including it in the ROM as the standard BASIC in the II+. From that point on, the HP dialect starts to disappear. It was used as the basis for Atari BASIC in 1979, and Sinclair and other UK-based systems shortly after that, but even as early as 1980 anything that didn't use MS-style strings was considered non-standard.
 

docs/RetroBASIC reference manual.md

@@ -497,7 +497,7 @@ In contrast to most dialects, RetroBASIC will allow you to `CONT`inue in most si
 <!-- TOC --><a name="end"></a>
 ### `END`
 
-`END` stops the execution of the program and exits RetroBASIC, returning you to the console shell. `END` is optional in most dialects, but adding an `END` was considered good form. `END` does not have to be at the end of the source code, it was often found higher in the code with subroutines below it, preventing them from running unless explicitly called. It can also be called anywhere in the code to exit the program based on user input.
+`END` stops the execution of the program and exits RetroBASIC, returning you to the console shell or interactive prompt. `END` is optional in most dialects, but adding an `END` was considered good form. `END` does not have to be at the end of the source code, it was often found higher in the code with subroutines below it, preventing them from running unless explicitly called. It can also be called anywhere in the code to exit the program based on user input.
 
 #### See also:
 
@@ -565,15 +565,15 @@ RetroBASIC also supports the variation seen in many later versions of BASIC, whi
 <!-- TOC --><a name="stop-sexp"></a>
 ### `STOP` [*sexp*]
 
-`STOP` is similar to `END` in that the program stops executing and the user is returned to the shell. It is intended to stop execution in the middle of the program and keep the data intact so the user can `CONT`inue running after it stops. It is mostly used for debugging purposes.
+`STOP` is similar to `END` in that the program stops executing and the user is returned to the shell or interactive prompt. It is intended to stop execution in the middle of the program and keep the data intact so the user can `CONT`inue running after it stops. It is mostly used for debugging purposes.
 
 RetroBASIC adds a feature from Wang and IBM 5100 BASIC, which outputs an optional string. This is useful for saying things like "Stopping for debugging, you should PRINT A". If no expression is included, RetroBASIC instead prints the default message "STOPped at line:" along with the line number.
 
 Lien notes that some varieties of BASIC will branch to the `END` statement when they reach a `STOP`, which means on these dialects the two commands are identical and there is no way to `CONT`inue after a `STOP`. However, which dialects these might be is not noted.
 
 #### Variations:
 
-PDP-8 BASIC and the Tektronics 4051 used `STO` instead.
+PDP-8 BASIC and the Tektronics 4051 used `STO` instead, although whether this was simply an abbreviated input and `STOP` would work as well is not clear in the documentation.
 
 Harris BASIC-V added the `BREAK` statement, which allowed one to place multiple `STOP` markers in the code in a single statement. For instance, `BREAK 10-50,100` would perform a stop (break) at any line from 10 to 50, or line 100. This is useful as it allows you to easily control debugging without having to edit the entire program, a single statement at the top has the same effect as multiple `STOP` statements spread all over the code. RetroBASIC does not currently support `BREAK`.