documentation improvements

Author: robhagemans

docs/source/guide.html

@@ -1306,7 +1306,7 @@ <h3 id="stat-memory">Memory and machine ports</h3>
         low memory segment, including the keyboard buffer. Additionally, there is read
         support for font ROM, variable, array and string memory, <code><a href="#FIELD">FIELD</a></code>
         buffers as well as the program code itself. Writing into the program code is
-        disabled by default, but can be enabled with the <code><a href="--allow-code-poke">allow-code-poke</a></code>
+        disabled by default, but can be enabled with the <code><a href="#--allow-code-poke">allow-code-poke</a></code>
         option. A number of machine ports related to keyboard input and
         video modes are supported as well.
     </p>

docs/source/reference.html

@@ -3151,11 +3151,14 @@ <h5>Notes</h5>
                 <code>VARPTR</code> can be used with <code><a href="#PEEK">PEEK</a></code>
                 to read a variable's internal representation.
             </li>
+            <li>
+                If <code><var>name</var></code> is an undefined array element, it will be implicitly allocated in the same way as if it had been used in an expression.
+            </li>
         </ul>
         <h5>Errors</h5>
         <ul>
             <li>
-                <code><var>name</var></code> has not been previously defined: <samp>Illegal function call</samp>.
+                <code><var>name</var></code> is a scalar that has not been previously defined: <samp>Illegal function call</samp>.
             </li>
             <li>
                 <code><var>file_num</var></code> has a string value: <samp>Type mismatch</samp>.
@@ -3177,6 +3180,7 @@ <h4 id="VARPTR$"><code>VARPTR$</code></h4>
         </code>
         <p>
             Returns the memory address of variable <code><var>name</var></code> in the form of a 3-byte string.
+            <code><var>name</var></code> is a fully indexed array element (which may or may not have been defined) or a previously-defined scalar variable.
             The first byte is the length of the record the pointer points to:
         </p>
         <dl class="compact">
@@ -3196,10 +3200,16 @@ <h4 id="VARPTR$"><code>VARPTR$</code></h4>
             The last two bytes are the pointer address (as returned by
             <code><a href="#VARPTR">VARPTR</a></code>) in little-endian order.
         </p>
+        <h5>Notes</h5>
+        <ul>
+            <li>
+                If <code><var>name</var></code> is an undefined array element, it will be implicitly allocated in the same way as if it had been used in an expression.
+            </li>
+        </ul>
         <h5>Errors</h5>
         <ul>
             <li>
-                <code><var>name</var></code> has not been previously defined: <samp>Illegal function call</samp>.
+                <code><var>name</var></code> is a scalar that has not been previously defined: <samp>Illegal function call</samp>.
             </li>
         </ul>
     </section>
@@ -3234,8 +3244,8 @@ <h4 id="AUTO"><code>AUTO</code></h4>
             If a program line exists at a generated line number, a <code>*</code> is shown after the
             line number. To avoid overwriting this line, leave it empty and press <kbd>Enter</kbd>.
             To stop automatic line numbering, press <kbd>Ctrl</kbd>+<kbd>Break</kbd> or <kbd>Ctrl</kbd>+<kbd>C</kbd>. The line being edited at
-            that point is not saved. BASIC will return to command mode, even if <code>AUTO</code> was
-            run from a program line.
+            that point is not saved.
+            Also stops program execution and returns control to the user. Any further statements on the line will be ignored, also in direct mode.
         </p>
         <h5>Parameters</h5>
         <ul>
@@ -4262,6 +4272,7 @@ <h4 id="CONT"><code>CONT</code></h4>
             Resumes execution of a program that has been halted by
             <code><a href="#STOP">STOP</a></code>, <code><a href="#END">END</a></code>,
             <kbd>Ctrl</kbd>+<kbd>C</kbd>, or  <kbd>Ctrl</kbd>+<kbd>Break</kbd>.
+            If run from a program, stops program execution and returns control to the user. Any further statements on the line will be ignored, also in direct mode.
         </p>
         <h5>Notes</h5>
         <ul>
@@ -4580,7 +4591,7 @@ <h4 id="DELETE"><code>DELETE</code></h4>
         </code>
         <p>
             Deletes a range of lines from the program.
-            Also stops program execution and returns control to the user.
+            Also stops program execution and returns control to the user. Any further statements on the line will be ignored, also in direct mode.
         </p>
         <h5>Parameters</h5>
         <ul>
@@ -4880,6 +4891,7 @@ <h4 id="EDIT"><code>EDIT</code></h4>
             Displays the specified program line with the cursor positioned for editing.
             <code><var>line_number</var></code> must be a line that exists in the program, or a period (.) to
             indicate the last line stored.
+            Also stops program execution and returns control to the user. Any further statements on the line will be ignored, also in direct mode.
         </p>
         <h5>Errors</h5>
         <ul>
@@ -5012,6 +5024,7 @@ <h4 id="ERROR"><code>ERROR</code></h4>
         </code>
         <p>
             Raises the error with number <code><var>error_number</var></code>.
+            See the <a href="#errors">list of error numbers and messages</a>.
         </p>
         <h5>Parameters</h5>
         <ul>
@@ -6589,8 +6602,9 @@ <h4 id="LOAD"><code>LOAD</code></h4>
         </code>
         <p>
             Loads the program stored in a file into memory.
-            Existing variables will be cleared and any program in memory will be erased. <code>LOAD</code> implies a
+            Existing variables will be cleared and any program in memory will be erased. <code>LOAD</code> implies
             <code><a href="#CLEAR">CLEAR</a></code>.
+            Also stops program execution and returns control to the user. Any further statements on the line will be ignored, also in direct mode.
         </p>
         <p>
             If <code>,R</code> is specified, keeps all data files open and runs the specified file.
@@ -6818,6 +6832,9 @@ <h4 id="MERGE"><code>MERGE</code></h4>
             Overlays the lines of a program from a plain-text program file into the existing program. The loaded
             lines overwrite existing lines if they have the same line number.
         </p>
+        <p>
+            Also stops program execution and returns control to the user. Any further statements on the line will be ignored, also in direct mode.
+        </p>
         <h5>Parameters</h5>
         <ul>
             <li>
@@ -8877,6 +8894,9 @@ <h6>MML Parameters</h6>
             It is an error to write <code>PLAY "G=VAR;"</code> or <code>PLAY "G=" + VARPTR$(VAR)</code>.
             Use <code>PLAY "G4"</code> or <code>PLAY "L=VAR;G"</code> or <code>PLAY "L=" + VARPTR$(VAR) + "G"</code> instead.
         </p>
+        <p>
+            Commands may optionally be separated by one semicolon <code>;</code>, but not by more than one.
+        </p>
         <h5>Errors</h5>
         <ul>
             <li>
@@ -9313,7 +9333,10 @@ <h5>Format string syntax</h5>
                 </tr>
                 <tr>
                     <td><code>^^^^</code></td>
-                    <td>Specify that scientific notation <code>E+00</code> is to be used.</td>
+                    <td>
+                        Specify that scientific notation is to be used, with a mantissa and an exponent represented by <code>E+00</code>.
+                        In scientific notation, thousands separators will not be shown and any <code>,</code> character has the same effect as <code>#</code>.
+                    </td>
                 </tr>
             </table>
         </div>
@@ -9654,6 +9677,7 @@ <h4 id="RENUM"><code>RENUM</code></h4>
             less than <code><var>old</var></code> remain unchanged.
             <code><var>new</var></code>, <code><var>old</var></code> are line numbers; the dot <code>.</code> signifies the last line edited.
             <code><var>increment</var></code> is a line number but must not be a dot or zero.
+            Also stops program execution and returns control to the user. Any further statements on the line will be ignored, also in direct mode.
         </p>
         <h5>Notes</h5>
         <ul>
@@ -9893,8 +9917,8 @@ <h4 id="RUN"><code>RUN</code></h4>
         </code>
         <p>
             Executes a program.
-            Existing variables will be
-            cleared and any program in memory will be erased. <code>RUN</code> implies a <code><a href="#CLEAR">CLEAR</a></code>
+            Existing variables will be cleared. <code>RUN</code> implies <code><a href="#CLEAR">CLEAR</a></code>.
+            If <code><var>file_spec</var></code> is given, any program in memory will be erased.
             If <code>,R</code> is specified after <code><var>file_spec</var></code>, files are kept open; if not, all files are closed.
         </p>
         <h5>Parameters</h5>
@@ -9940,6 +9964,7 @@ <h4 id="SAVE"><code>SAVE</code></h4>
             <li>
                 If <code><b>,A</b></code> is specified, the program will be saved in plain text format.
                 In this case, program execution will stop and control will be returned to the user.
+                Any further statements on teh line will be ignored, also in direct mode.
             </li>
             <li>
                 If <code><b>,P</b></code> is specified, the program will be saved in <a href="#protected-file-format">protected format</a>.