documentation.html

<!--
    PC-BASIC documentation
    Copyright (c) 2014-2022 Rob Hagemans
    This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
    http://creativecommons.org/licenses/by-sa/4.0/legalcode
-->

<article>
    <h2 id="using">User's guide</h2>

    <section>
        <h3 id="workenv">The working environment</h3>
        <p>
            The first thing you'll see when starting PC-BASIC is the working environment.
            Like GW-BASIC, but unlike practically all modern compilers and interpreters,
            PC-BASIC's working environment serves both as a development environment and as a
            canvas on which to execute BASIC commands directly. With a few exceptions,
            practically all commands that can be run in the working environment can be used
            in a program, and vice versa.
        </p>
        <p>
            The default PC-BASIC screen has 25 rows and 80 columns. The 25th row is used
            by PC-BASIC to show keyboard shortcuts,
            which means you can't use it to type on. In some video modes, there are only 40
            or 20 columns.
        </p>
        <p>
            <em>Logical lines</em> exceed the width of the physical row: if you keep
            typing beyond the screen width, the text will
            wrap to the next line but PC-BASIC will still consider it part of the same line.
            A logical line can be at most 255 characters long; if you type more than 255
            characters, it will ignore the remainder. A line can also be wrapped by a
            line-feed, entered with <kbd>Ctrl</kbd>+<kbd>Enter</kbd>.
        </p>
        <p>
            If you press <kbd>Enter</kbd>, PC-BASIC will attempt to execute the
            logical line on which the cursor is placed as a command. When the command is executed correctly,
            PC-BASIC will display the prompt <samp>Ok</samp>. If there is an error, it will
            display an error message followed by <samp>Ok</samp>.
            If the line starts with a number, it will be stored as a program line. No prompt is displayed.
        </p>

        <section>
            <h4 id="special-keys">Special keys</h4>
            <p>The following keys have a special effect in the working environment:</p>
            <div class="scrollable">
                <table>
                    <tr>
                        <td><kbd>&#8593;<!--up--></kbd> or <kbd>Ctrl</kbd>+<kbd>6</kbd></td>
                        <td>Move the cursor up, except at the top row.</td>
                    </tr>
                    <tr>
                        <td><kbd>&#8595;<!--down--></kbd> or <kbd>Ctrl</kbd>+<kbd>-</kbd></td>
                        <td>Move the cursor down, except at row 24.</td>
                    </tr>
                    <tr>
                        <td><kbd>&#8592;<!--left--></kbd> or <kbd>Ctrl</kbd>+<kbd>]</kbd></td>
                        <td>Move the cursor left. The left edge of the screen wraps around, except at the top row.</td>
                    </tr>
                    <tr>
                        <td><kbd>&#8594;<!--right--></kbd> or <kbd>Ctrl</kbd>+<kbd>/</kbd></td>
                        <td>Move the cursor right. The right edge of the screen wraps around, except at row 24.</td>
                    </tr>
                    <tr>
                        <td><kbd>Ctrl</kbd>+<kbd>&#8592;<!--left--></kbd> or <kbd>Ctrl</kbd>+<kbd>B</kbd></td>
                        <td>
                            Move to the first letter of the previous word. Words consist of
                            letters <code>A&#8212;Z</code> and figures <code>0&#8212;9</code>.
                        </td>
                    </tr>
                    <tr>
                        <td><kbd>Ctrl</kbd>+<kbd>&#8594;<!--right--></kbd> or <kbd>Ctrl</kbd>+<kbd>F</kbd></td>
                        <td>Move to the first letter of the next word.</td>
                    </tr>
                    <tr>
                        <td><kbd>Tab</kbd> or <kbd>Ctrl</kbd>+<kbd>I</kbd></td>
                        <td>Move the cursor to the next tab stop. Tab stops are 8 columns wide.</td>
                    </tr>
                    <tr>
                        <td><kbd>Backspace</kbd> or <kbd>Ctrl</kbd>+<kbd>H</kbd></td>
                        <td>
                            Delete the character left of the cursor, shift all further characters on the logical line one
                            position to the left and change the attributes of those characters to the current attribute. At the
                            left edge of the screen, this does the same as <kbd>Del</kbd>.
                        </td>
                    </tr>
                    <tr>
                        <td>
                            <kbd>Del</kbd> or <kbd>Ctrl</kbd>+<kbd>Backspace</kbd>
                        </td>
                        <td>
                            Delete the character at the cursor and shift all
                            further characters one position to the left,
                            changing attributes to current.
                        </td>
                    </tr>
                    <tr>
                        <td><kbd>Esc</kbd> or <kbd>Ctrl</kbd>+<kbd>[</kbd></td>
                        <td>Delete the current logical line.</td>
                    </tr>
                    <tr>
                        <td><kbd>Ctrl</kbd>+<kbd>End</kbd> or <kbd>Ctrl</kbd>+<kbd>E</kbd></td>
                        <td>
                            Delete all characters from the cursor to the end
                            of the logical line.
                        </td>
                    </tr>
                    <tr>
                        <td><kbd>Ctrl</kbd>+<kbd>Break</kbd> or <kbd>Ctrl</kbd>+<kbd>C</kbd> or <kbd>Ctrl</kbd>+<kbd>Scroll Lock</kbd></td>
                        <td>Jump to the first column of the next line, without executing or storing the line under the cursor.</td>
                    </tr>
                    <tr>
                        <td><kbd>Enter</kbd> or <kbd>Ctrl</kbd>+<kbd>M</kbd></td>
                        <td>
                            Execute or store the current logical line. The
                            complete line on the screen is considered part of
                            the command, even if you did not type it.
                            A line starting with a number is stored as a
                            program line.
                        </td>
                    </tr>
                    <tr>
                        <td><kbd>End</kbd> or <kbd>Ctrl</kbd>+<kbd>N</kbd></td>
                        <td>
                            Move the cursor to the first position after the
                            end of the logical line.
                        </td>
                    </tr>
                    <tr>
                        <td><kbd>Home</kbd> or <kbd>Ctrl</kbd>+<kbd>K</kbd></td>
                        <td>Move the cursor to the top left of the screen.</td>
                    </tr>
                    <tr>
                        <td><kbd>Ctrl</kbd>+<kbd>Home</kbd> or <kbd>Ctrl</kbd>+<kbd>L</kbd></td>
                        <td>
                            Clear the screen and move the cursor to the top
                            left of the screen.
                        </td>
                    </tr>
                    <tr>
                        <td><kbd>Ctrl</kbd>+<kbd>Enter</kbd> or <kbd>Ctrl</kbd>+<kbd>J</kbd></td>
                        <td>
                            Move to the first column of the next line,
                            connecting the two lines into one logical line.
                        </td>
                    </tr>
                    <tr>
                        <td><kbd>Ctrl</kbd>+<kbd>G</kbd></td>
                        <td>Beep the speaker.</td>
                    </tr>
                    <tr>
                        <td><kbd>Pause</kbd> or <kbd>Ctrl</kbd>+<kbd>Num Lock</kbd></td>
                        <td>Pause. Press another key to resume. The latter key press will not be detected by BASIC.</td>
                    </tr>
                    <tr>
                        <td><kbd>Ctrl</kbd>+<kbd>Print Screen</kbd></td>
                        <td>Toggle echoing screen output to the printer (or other device attached to <code>LPT1:</code>).</td>
                    </tr>
                    <tr>
                        <td><kbd>Shift</kbd>+<kbd>Print Screen</kbd></td>
                        <td>Print the screen.</td>
                    </tr>
                    <tr>
                        <td><kbd>Ins</kbd> or <kbd>Ctrl</kbd>+<kbd>R</kbd></td>
                        <td>
                            Toggle <em>insert mode</em>. In insert mode, characters
                            are inserted rather than overwritten at the
                            current location. If insertion causes the line to
                            extend the physical screen width, the logical
                            line extends onto the next line. Arrow keys exit
                            insert mode.
                        </td>
                    </tr>
                </table>
            </div>

            <p>
                When a program is started, the commands in the program are followed until the
                program quits and returns to direct mode or until user input is required.
                When a program is running, a few keys have immediate effect:
            </p>
            <div class="scrollable">
                <table>
                    <tr>
                        <td>
                            <kbd>Pause</kbd> or <kbd>Ctrl</kbd>+<kbd>Num Lock</kbd>
                        </td>
                        <td>
                            Pause execution. Press another key to resume.
                        </td>
                    </tr>
                    <tr>
                        <td>
                            <kbd>Ctrl</kbd>+<kbd>Break</kbd>
                            or <kbd>Ctrl</kbd>+<kbd>Scroll Lock</kbd>
                        </td>
                        <td>
                            Stop execution and return to direct mode. A <samp>Break</samp> message is printed.
                        </td>
                    </tr>
                    <tr>
                        <td>
                            <kbd>Ctrl</kbd>+<kbd>C</kbd>
                        </td>
                        <td>
                            If <code><a href="#--ctrl-c-break">ctrl-c-break</a>=True</code>: stop execution and return to direct mode.
                            A <samp>Break</samp> message is printed.
                        </td>
                    </tr>
                </table>
            </div>

            <p>
                If user input is required by the statements <code>INPUT</code>, <code>LINE INPUT</code>, or <code>RANDOMIZE</code>,
                most keys have the same effect as in direct mode. The following keys have a different effect:
            </p>
            <div class="scrollable">
                <table>
                    <tr>
                        <td>
                            <kbd>Ctrl</kbd>+<kbd>Break</kbd> or <kbd>Ctrl</kbd>+<kbd>C</kbd>
                            or <kbd>Ctrl</kbd>+<kbd>Scroll Lock</kbd>
                        </td>
                        <td>
                            Stop execution and return to direct mode.
                            A <samp>Break</samp> message is printed.
                        </td>
                    </tr>
                    <tr>
                        <td><kbd>Enter</kbd></td>
                        <td>
                            Finish input and return to the previous mode.
                        </td>
                    </tr>
                </table>
            </div>
        </section>
        <hr />

        <section>
            <h4 id="shortcuts">Keyboard shortcuts</h4>
            <p>
                The function keys and the alt key can be used as keyboard shortcuts for some
                keywords.
                The default values for the function keys are:
            </p>
            <div class="scrollable">
                <table>
                    <tr>
                        <td><kbd>F1</kbd></td>
                        <td><code><a href="#LIST">LIST</a></code></td>
                    </tr>
                    <tr>
                        <td><kbd>F2</kbd></td>
                        <td><code><a href="#RUN">RUN</a></code><kbd>Enter</kbd></td>
                    </tr>
                    <tr>
                        <td><kbd>F3</kbd></td>
                        <td><code><a href="#LOAD">LOAD</a>"</code></td>
                    </tr>
                    <tr>
                        <td><kbd>F4</kbd></td>
                        <td><code><a href="#SAVE">SAVE</a>"</code></td>
                    </tr>
                    <tr>
                        <td><kbd>F5</kbd></td>
                        <td><code><a href="#CONT">CONT</a></code><kbd>Enter</kbd></td>
                    </tr>
                    <tr>
                        <td><kbd>F6</kbd></td>
                        <td><code>,"LPT1:"</code><kbd>Enter</kbd></td>
                    </tr>
                    <tr>
                        <td><kbd>F7</kbd></td>
                        <td><code><a href="#TRON">TRON</a></code><kbd>Enter</kbd></td>
                    </tr>
                    <tr>
                        <td><kbd>F8</kbd></td>
                        <td><code><a href="#TRON">TROFF</a></code><kbd>Enter</kbd></td>
                    </tr>
                    <tr>
                        <td><kbd>F9</kbd></td>
                        <td><code><a href="#KEY-list">KEY</a></code><kbd>Space</kbd></td>
                    </tr>
                    <tr>
                        <td><kbd>F10</kbd></td>
                        <td><code><a href="SCREEN-statement">SCREEN</a> 0,0,0</code><kbd>Enter</kbd></td>
                    </tr>
                </table>
            </div>
            <p>
                The function key shortcuts can be redefined with the <code>KEY</code> statement.
                The shortcuts are displayed at the bottom of the screen.
            </p>
            <p>
                The following keywords can be entered
                with <kbd>Alt</kbd>+first letter. The <kbd>Alt</kbd> shortcuts cannot be redefined.
            </p>
            <ul class="compact">
                <li><code><a href="#AUTO">AUTO</a></code></li>
                <li><code><a href="#BSAVE">BSAVE</a></code></li>
                <li><code><a href="#COLOR">COLOR</a></code></li>
                <li><code><a href="#DELETE">DELETE</a></code></li>

                <li><code><a href="#ELSE">ELSE</a></code></li>
                <li><code><a href="#FOR">FOR</a></code></li>
                <li><code><a href="#GOTO">GOTO</a></code></li>
                <li><code><a href="#HEX$">HEX$</a></code></li>

                <li><code><a href="#INPUT">INPUT</a></code></li>
                <li><code><a href="#KEY-list">KEY</a></code></li>
                <li><code><a href="#LOCATE">LOCATE</a></code></li>
                <li><code><a href="#MOTOR">MOTOR</a></code></li>

                <li><code><a href="#NEXT">NEXT</a></code></li>
                <li><code><a href="#OPEN">OPEN</a></code></li>
                <li><code><a href="#PRINT">PRINT</a></code></li>
                <li><code><a href="#RUN">RUN</a></code></li>

                <li><code><a href="#SCREEN">SCREEN</a></code></li>
                <li><code><a href="#THEN">THEN</a></code></li>
                <li><code><a href="#PRINT">USING</a></code></li>
                <li><code><a href="#VAL">VAL</a></code></li>

                <li><code><a href="#WIDTH">WIDTH</a></code></li>
                <li><code><a href="#XOR">XOR</a></code></li>
            </ul>
        </section>
        <hr />

        <section>
            <h4 id="alternative-keys">Alternative keys</h4>
            <p>
                In PC-BASIC, the <kbd>F12</kbd> key can be used to enter special keys that are not
                present on some keyboards.
            </p>
            <table>
                <tr>
                    <td><kbd>F12</kbd>+<kbd>B</kbd></td>
                    <td><kbd>Ctrl</kbd>+<kbd>Break</kbd></td>
                </tr>
                <tr>
                    <td><kbd>F12</kbd>+<kbd>P</kbd></td>
                    <td><kbd>Pause</kbd></td>
                </tr>
                <tr>
                    <td><kbd>F12</kbd>+<kbd>C</kbd></td>
                    <td><kbd>Caps Lock</kbd></td>
                </tr>
                <tr>
                    <td><kbd>F12</kbd>+<kbd>N</kbd></td>
                    <td><kbd>Num Lock</kbd></td>
                </tr>
                <tr>
                    <td><kbd>F12</kbd>+<kbd>S</kbd></td>
                    <td><kbd>Scroll Lock</kbd></td>
                </tr>
                <tr>
                    <td><kbd>F12</kbd>+<kbd>H</kbd></td>
                    <td><kbd>Print Screen</kbd></td>
                </tr>
            </table>
            <p>
                The <kbd>F12</kbd> key can also be used in combination with the regular number
                keys and arrow keys to enter numbers from the numeric keypad.
                The <kbd>F12</kbd> combinations are not present in GW-BASIC.
            </p>
            <p>
                Furthermore, as in GW-BASIC, the <kbd>Alt</kbd> key can be used to enter characters by their <a href="#cp437">code points</a> (ASCII values).
                This is done by pressing the <kbd>Alt</kbd> key and typing the code point as a decimal value
                on the numeric keypad, then releasing the <kbd>Alt</kbd> key.
            </p>
        </section>
        <hr />

        <section>
            <h4 id="clipboard-operations">Clipboard operations</h4>
            <p>
                Unlike in GW-BASIC, you can copy and paste text to the clipboard.
                This can be done with the mouse or with the <kbd>F11</kbd> key.
            </p>
            <p>
                Operating the clipboard with the mouse works in the style of X11:
                Left button is select and copy; middle button
                is paste.
            </p>
            <p>
                The following keyboard combinations also operate the clipboard:
            </p>
            <div class="scrollable">
                <table>
                    <tr>
                        <td>
                            <kbd>F11</kbd>+<kbd>&#8593;<!--up--></kbd><kbd>&#8595;<!--down--></kbd><kbd>&#8592;<!--left--></kbd><kbd>&#8594;<!--right--></kbd>
                        </td>
                        <td>Select a screen region.</td>
                    </tr>
                    <tr>
                        <td><kbd>F11</kbd>+<kbd>A</kbd></td>
                        <td>Select all.</td>
                    </tr>
                    <tr>
                        <td><kbd>F11</kbd>+<kbd>C</kbd></td>
                        <td>Copy to clipboard.</td>
                    </tr>
                    <tr>
                        <td><kbd>F11</kbd>+<kbd>V</kbd></td>
                        <td>Paste from clipboard.</td>
                    </tr>
                </table>
            </div>
        </section>
        <hr />

        <section>
            <h4 id="emulator-keys">Emulator control keys</h4>
            <p>
                In PC-BASIC, <kbd>F11</kbd>+<kbd>F</kbd> toggles fullscreen mode.
            </p>
        </section>
        <section>
            <h4 id="system-keys">Compatibility</h4>
            <p>
                Some key combinations may have a different effect than described above,
                depending on the operating system and the choice of interface to use with PC-BASIC.
            </p>
            <ul>
                <li>
                    Certain key combinations will be interpreted by the operating system or
                    window manager and cause special actions. For example, on most systems,
                    <kbd>Alt</kbd>+<kbd>F4</kbd> will terminate PC-BASIC unless
                    the <a href="#--prevent-close"><code>prevent-close</code></a> option is set; <kbd>F1</kbd>
                    may open your operating system's help system. It may be possible to avoid
                    some of these effects by using the graphical interface in full-screen mode.
                </li>
                <li>
                    In the command-line interface on Windows, <kbd>Ctrl</kbd>+<kbd>C</kbd>
                    terminates PC-BASIC.
                </li>
                <li>
                    In the command-line interface on Linux and Mac, <kbd>Ctrl</kbd>+<kbd>D</kbd>
                    terminates PC-BASIC.
                </li>
            </ul>
        </section>
        <hr />
    </section>

    <section>
        <h3 id="programs">Programs and files</h3>
        <p>
            PC-BASIC can hold one BASIC program at a time in memory. To enter a program
            line, start with a <em>line number</em> and enter BASIC commands after that.
            The maximum length of a program line is 255 characters, including the line
            number and any spaces. The program line will not be immediately executed, but
            stored in the program. Program lines are sorted by line number, so that line
            <code>10</code> is executed before line <code>20</code>. All program
            lines must have a line number. Line numbers range from <code>0</code> to <code>65535</code> inclusive.
            It is not possible to enter a line number higher than <code>65529</code>, but these can
            exist in loaded programs.
            Within one program line, statements are separated by colons <code>:</code>.
        </p>
         <p>
             To run the program, type the command <code>RUN</code>. PC-BASIC will now
            execute all program lines in order inside the working environment. You cannot
            move the cursor around or enter commands while the program is running. If and
            when the program finishes, it will return control of the working environment to
            you. You can interrupt a program at any time by using one of the key
            combinations <kbd>Ctrl</kbd>+<kbd>Break</kbd> or <kbd>Ctrl</kbd>+<kbd>Scroll
            Lock</kbd>. The program will stop immediately, print a <samp>Break</samp>
            message and return control to you.
        </p>
        <p>
            In GW-BASIC, you can <em>not</em> use  <kbd>Ctrl</kbd>+<kbd>C</kbd> to interrupt a running program.
            However, many modern keyboards do not have a <kbd>Break</kbd> or
            <kbd>Scroll Lock</kbd> key, which would make it impossible to interrupt
            a program that does not exit. Therefore, by default, PC-BASIC treats <kbd>Ctrl</kbd>+<kbd>C</kbd>
            as if it were <kbd>Ctrl</kbd>+<kbd>Break</kbd>. Set the <a href="#settings">option</a> <code><a href="#--ctrl-c-break">ctrl-c-break</a>=False</code>
            if you prefer the GW-BASIC style behaviour. When using the text-based or command-line interface,
            this option is ignored.
        </p>
        <p>
            A program can be stored on a drive by using the <code><a href="#SAVE">SAVE</a></code> command, in one of three ways:
        </p>
        <ol>
            <li>Plain text, readable by any text editor: <code>SAVE "MYPROG",A</code></li>
            <li>Tokenised, taking up less storage space: <code>SAVE "MYPROG"</code></li>
            <li>Protected, which is an encrypted format:  <code>SAVE "MYPROG",P</code></li>
        </ol>
        <p>
            In all three cases, the program will be written to the current working
            directory with the name <code>MYPROG.BAS</code>.
        </p>
        <p>
            PC-BASIC can read and write Protected files created by GW-BASIC. Unlike
            GW-BASIC, however, it does not disable accessing the unencrypted contents of the
            file. The encryption used by GW-BASIC has been broken many decades ago, so
            Protected mode offered little protection anyway; disallowing access is a small
            security hazard as it would allow someone to send you a program that you cannot
            inspect before running it. However, it is possible to disable access of
            protected files by enabling the option <code><a href="#--hide-protects">hide-protected</a></code>. </p> <p>You
            can read a program file into memory with <code><a href="#LOAD">LOAD</a> "MYPROG"</code>. This will
            erase the program currently in memory and replace it with the one read from the
            current working directory. To access files in a different directory, specify a path from the current
            directory. The path specification follows DOS conventions. The only valid path
            separator is the backslash <code>\</code>. For example, <code>LOAD "PROGRAMS\MYPROG"</code>.
        </p>
        <p>
            You can load or run a program immediately on starting PC-BASIC by using the
            <code><a href="#--load">load</a></code> or <code><a href="#--run">run</a></code> options.
            For example,
        </p>
        <code class="block">
            <b>pcbasic --run=MYPROG.BAS</b>
        </code>
        <p>
            The arguments to these options can be provided
            as PC-BASIC paths or as paths in the standard form for your operating
            system.
        </p>
        <p>
            PC-BASIC can be used to convert between the three program formats: either by loading the program and saving
            in your desired format, or from the command line using the <code><a href="#--convert">convert</a></code> option. To convert a
            tokenised or protected file to plain text you could use, for example:
        </p>
        <code class="block">
            <b>pcbasic --convert=A PROGRAMP.BAS PROGRAMA.BAS</b>
        </code>

        <section>
            <h4 id="mounting">Accessing your drives</h4>
            <p>
                PC-BASIC emulates DOS disk devices, which are referred to by drive letters such as <code>Z:</code>.
                One of the drive letters is the <em>current device</em>.
            </p>
            <p>
                On <strong>Windows</strong>:
            </p>
            <ul>
                <li>
                    By default, PC-BASIC disk devices will agree with Windows drive letters at the
                    start of the PC-BASIC session.
                </li>
                <li>
                    If PC-BASIC is started from the start menu shortcut, the current device will be
                    your <i>Documents</i> folder (or <i>My Documents</i> on some versions of Windows).
                    You can change this location by setting the shortcut's <i>Start In</i> folder.
                </li>
                <li>
                    If PC-BASIC is started from the command prompt, the current device will be set to
                    the current working directory of the command prompt.
                </li>
                <li>
                    If PC-BASIC's current device or <i>Start In</i> folder is changed to a system folder such as <code>C:\Program Files\PC-BASIC</code>,
                    Windows will move files written there to <code>%LocalAppData%\VirtualStore</code> instead.
                    This is best avoided.
                </li>
                <li>
                    Note that <em>PC-BASIC's DOS disk devices are not the same thing as Windows drive letters</em>.
                    The device <code>C:</code> on PC-BASIC is <em>not</em> always your Windows <code>C:</code> drive.
                    By default, Windows drive letters are mapped to PC-BASIC devices at the start
                    of the PC-BASIC session. However, if you use the <code><a href="#--mount">mount</a></code> option;
                    or if Windows drive letters change while PC-BASIC is running (through e.g. <code>net use</code> or
                    <i>Map Network Drive</i> operations), they will no longer agree.
                </li>
            </ul>
            <p>
                On <strong>other systems</strong>:
            </p>
            <ul>
                <li>
                    By default, <code>Z:</code> will point to the current working directory from where PC-BASIC was started.
                    It will be the current device.
                </li>
                <li>
                    If started from a menu or app package, this will usually be your home directory <code>&tilde;</code>.
                </li>
            </ul>
            <p>
                This current device is where files will be saved to and loaded from in BASIC if you do not specify another device.
                You can change the current device using the <code><a href="#--current-device">current-device</a></code>
                option in the <a href="#settings">configuration file or on the command prompt</a>.
            </p>
            <p>
                You can map drives and other file system locations as PC-BASIC devices by
                using the <code><a href="#--mount">mount</a></code> option. For example,
                on Windows, the option
                <code class="block">
                    <b>mount=A:C:\Users\Me\BasicFloppy</b>
                </code>
                will make the folder <code>C:\Users\Me\BasicFloppy</code> available as PC-BASIC's <code>A:</code> device.
                On other platforms, an example mount option could look like
                <code class="block">
                    <b>mount=A:/home/me/BasicFloppy</b>
                </code>
                which would make the directory <code>/home/me/BasicFloppy</code> available as PC-BASIC's <code>A:</code> device.
            </p>
            <p>
                PC-BASIC uses <a href="#eightpointthree">DOS conventions</a> for filenames and paths.
                These are subtly different from Windows short filename
                conventions and not-so-subtly different from Unix conventions. This may lead
                to surprising effects in the presence of several files that match
                the same DOS name. To avoid such surprises, it's best to run PC-BASIC in a working
                directory of its own and use all-caps 8.3 format for all files.
            </p>
        </section>
        <hr />

        <section>
            <h4 id="program-files">Compatible BASIC files</h4>
            <p>
                Many BASIC dialects use the same extension <code>.BAS</code>, but their files are not compatible.
                PC-BASIC runs GW-BASIC program files only. Some tips to recognise GW-BASIC programs:
            </p>
            <ul>
                <li>GW-BASIC files stored as text are plain text files with line numbers.</li>
                <li>Tokenised files are binary files that start with magic byte <code>&amp;hFF</code>.</li>
                <li>Protected files are binary files that start with magic byte <code>&amp;hFE</code>.</li>
            </ul>
            <p>
                In particular, QBASIC files (which have no line numbers) and QuickBASIC files
                (magic byte <code>&amp;hFC</code>) will not run.
            </p>
            <p>
                PC-BASIC will accept both DOS and Unix newline conventions for programs
                stored as plain text.
                This behaviour is different from GW-BASIC, which only
                accepts text files with <code><i>CR LF</i></code> line endings.
                As a consequence, in exceptional cases where a program line is continued through <code><i>LF</i></code>
                correct GW-BASIC text files may not be loaded correctly.
                If you encounter such a case, use
                the <code><a href="#--soft-linefeed">soft-linefeed</a></code> option to enable GW-BASIC behaviour. If
                <code>soft-linefeed</code> is enabled, text files in standard Unix format
                (<code><i>LF</i></code> line endings, no end-of-file character) will fail to load, as they do in GW-BASIC.
                On Linux or Mac, use a utility such as
                <a href="http://waterlan.home.xs4all.nl/dos2unix.html"><code>unix2dos</code></a>
                to convert programs saved as text files before loading them. When saving as text,
                PC-BASIC always uses <code><i>CR LF</i></code> line endings and <code>&amp;h1A</code> at end-of-file.
            </p>
        </section>
        <hr />

        <section>
            <h4 id="packages">Packages</h4>
            <p>
                PC-BASIC can run packaged programs. A package is simply a directory or zip archive.
                The directory or zipfile contents will be loaded as the current working
                directory. If a configuration file named <code>PCBASIC.INI</code> is present
                inside this directory, its settings are loaded; usually, one of those settings will be a
                <code><a href="#--run">run</a></code> argument linking to a BASIC program enclosed in the archive or directory.
                PC-BASIC will recognise zipfiles regardless of their extension.
                A suggested extension for PC-BASIC packages is <code>.BAZ</code>.
                Packages are a convenient choice if a program needs to change many PC-BASIC options
                to function as desired, or if it needs a particular working directory setup.
            </p>
            <p>
                Zipfile packages are unpacked to a temporary directory each time they are loaded.
                The temporary directory is removed when PC-BASIC closes. With zipfile packages, it is therefore
                not possible to save files and re-open them on the next run of the package.
            </p>
        </section>
        <hr />

        <section>
            <h4 id="cassette">Cassette tapes</h4>
            <p>
                The <code>CAS1</code> device interfaces with the cassette tape emulator.
                Tapes were never very popular on the IBM PC, and indeed only available with the
                original PC and the PCjr. There are not many IBM PC cassettes in the wild.
                However, should you come across one, all you have to do to read it with PC-BASIC
                is record it into a <code>.WAV</code> (RIFF WAVE) file and attach it to the <code>CAS1:</code>
                device with the <code><b><a href="#--cas1">cas1</a>=WAV:</b><var>filename</var></code> option.
                You can also generate your own tape images and store your programs on it. <code>WAV</code>
                files generated by PC-BASIC are large but very easily compressed in a <code>ZIP</code>
                archive; this works better and leads to smaller files than transcoding to a lossy
                audio format like <code>MP3</code>.
            </p>
            <p>
                As an alternative to <code>.WAV</code>, you can store tapes in <code>CAS</code>
                format. This is simply a bit-dump of the tape and is interchangeable
                with tape images for the <a href="http://www.hampa.ch/pce/">PCE</a> IBM PC emulator.
            </p>
            <p>
                Previous versions of PC-BASIC included support for BASICODE cassettes; this has
                been discontinued in favour of a separate
                <a href="https://github.com/robhagemans/basicode">BASICODE decoder</a>.
                Use this decoder to convert the BASICODE program to PC-BASIC format
                before loading it into PC-BASIC.
            </p>
        </section>
        <hr />

        <section>
            <h4 id="security">Security</h4>
            <p>PC-BASIC makes some default choices with basic security in mind, but does not
                sandbox its programs in any meaningful way. BASIC programs have more or less
                full access to your computer. You should treat them with the same caution as
                you would shell scripts or binaries. Therefore, do not run a program from the
                internet that you have not inspected first using <code><a href="#LIST">LIST</a></code> or
                <code class="block"><b>pcbasic <a href="#--convert">--convert</a>=A</b> <var>filename</var></code> on the <a href="#settings">command line</a>. You wouldn't just download
                an executable from the internet and run it either, right?</p>
        </section>
        <hr />
    </section>

    <section>
        <h3 id="peripherals">Connecting to peripherals</h3>
        <section>
        <h4 id="printing">Printing</h4>
            <p>
                You can print from PC-BASIC programs
                by accessing the <code>LPT1:</code> device. PC-BASIC will send the output to
                your operating system's default printer, unless you change the <code>lpt1=</code>
                option. To print through a printer named <code>MyPrinter</code>, set
                <code><b><a href="#--lpt1">lpt1</a>=PRINTER:MyPrinter</b></code>. You can also attach printers to the
                <code>LPT2:</code> and <code>LPT3:</code> devices.
            </p>

            <p>
                The output will be sent to the printer when one of the following happens:
                a file open to <code>LPT1:</code> is closed, a program terminates, or PC-BASIC is closed.
                If you prefer, you can instead send every page separately to the printer by setting
                <code>lpt1=PRINTER:MyPrinter:page</code>. You can even send every line separately, but
                this only makes sense on a tractor-fed printer (as was common in GW-BASIC's heyday).
            </p>

            <p>
                It's easy to print to a file instead of a printer:
                set <code><b><a href="#--lpt1">lpt1</a>=FILE:output.txt</b></code>
                to send all <code>LPT1:</code> printer output to the text file <code>output.txt</code>.
            </p>
            <p>
                The printing statements <code><a href="#LPRINT">LPRINT</a></code> and <code><a href="#LLIST">LLIST</a></code> always send
                their output to PC-BASIC's <code>LPT1:</code> device.
            </p>

            <p>
                The presentation of printed documents is left to your operating system: it
                will be the default presentation of text files. If you wist to change the way
                documents are printed, please refer to your OS's settings.
            </p>
            <ul>
                <li>
                    On Windows, text files are printed the same way as would happen when you drag
                    a text file and drop it on the printer's icon.
                    That means the formatting is handled by the application associated to
                    <code>.txt</code> files; usually this is <code>notepad.exe</code>. To change
                    the way PC-BASIC documents are printed, change the page setup
                    in that application. You will need to set a
                    printer font that includes the characters you need to print.
                </li>
                <li>
                    On Unix systems,
                    PC-BASIC will use the <code>paps</code> utility if it is available; this will
                    automatically select fonts that support the characters you need.
                </li>
            </ul>
        </section>
        <hr />

        <section>
            <h4 id="ports">Serial and parallel ports</h4>
            <p>
                PC-BASIC provides the serial devices <code>COM1:</code> and <code>COM2:</code>.
                To make use of these, you need to attach them to a communications port on your
                computer with the <code><a href="#--com1">com1</a>=</code> or <code><a href="#--com2">com2</a>=</code> option. To attach to
                the first physical serial port, set <code><b><a href="#--com1">com1</a>=PORT:0</b></code> (or, alternatively,
                <code><b><a href="#--com1">com1</a>=PORT:COM1</b></code> on Windows or
                <code><b><a href="#--com1">com1</a>=PORT:/dev/ttyS0</b></code> on
                Linux). If you do not have a serial port, you can emulate one by sending the
                communications over a network socket: set <code><b><a href="#--com1">com1</a>=SOCKET:localhost:7000</b></code>
                and all <code>COM1:</code> traffic will be sent through socket <code>7000</code>.
            </p>

            <p>
                To access a parallel port, attach it to one of <code>LPT1:</code>, <code>LPT2:</code> or <code>LPT3:</code>.
                For example, set <code><b><a href="#--lpt2">lpt2</a>=PARPORT:0</b></code> to attach your computer's first
                parallel port to <code>LPT2:</code>.
            </p>
        </section>
        <hr />

    </section>

    <section>
        <h3 id="interface">Changing the interface</h3>
        <section>
            <h4 id="presets">Emulation targets</h4>
            <p>
                By default, PC-BASIC emulates GW-BASIC on a system with VGA video capabilities.
                However, it can emulate several other setups, which differ from each other in
                terms of video and audio capacity, fonts, memory size, as well as available BASIC syntax.
                The easiest way to set the emulation target is by using a <code><a href="#--preset">preset</a></code> option.
                For example, run <code><b>pcbasic --preset=pcjr</b></code>.
                Other available emulation target presets are:
            </p>
            <div class="scrollable">
                <table>
                    <tr>
                        <th>Preset</th><th>Emulation target</th>
                    </tr>
                    <tr>
                        <td><code>gwbasic</code></td>
                        <td>Microsoft GW-BASIC 3.23</td>
                    </tr>
                    <tr>
                        <td><code>basica</code></td>
                        <td>IBM BASICA.</td>
                    </tr>
                    <tr>
                        <td><code>pcjr</code></td>
                        <td>IBM PCjr with Cartridge BASIC, including PCjr video and 3-voice sound capabilities and extended BASIC syntax.</td>
                    </tr>
                    <tr>
                        <td><code>tandy</code></td>
                        <td>Tandy 1000 with GW-BASIC, including Tandy video and 3-voice sound capabilities and extended BASIC syntax.</td>
                    </tr>
                    <tr>
                        <td><code>olivetti</code></td>
                        <td>Olivetti M24 or AT&amp;T PC 6300.</td>
                    </tr>
                    <tr>
                        <td><code>cga</code></td>
                        <td>IBM or compatible with Color/Graphics Adapter and a composite monitor. This enables composite colorburst emulation.</td>
                    </tr>
                    <tr>
                        <td><code>ega</code></td>
                        <td>IBM or compatible with Extended Graphics Adapter.</td>
                    </tr>
                    <tr>
                        <td><code>vga</code></td>
                        <td>IBM or compatible with Video Graphics Array.</td>
                    </tr>
                    <tr>
                        <td><code>mda</code></td>
                        <td>
                            IBM or compatible with Monochrome Display Adapter and
                            green-tinted monochrome monitor.
                        </td>
                    </tr>
                    <tr>
                        <td><code>hercules</code></td>
                        <td>
                            IBM compatible with Hercules Graphics Adapter and green-tinted
                            monochrome monitor.
                        </td>
                    </tr>
                    <tr>
                        <td><code>strict</code></td>
                        <td>Choose strict compatibility with GW-BASIC over convenience,
                        security, rhyme or reason.</td>
                    </tr>
                </table>
            </div>
            <p>
                <em>Presets</em> are groups of options that are defined in the default configuration
                file. You can create your own presets by creating a header in your private configuration
                file with the name of the new preset, followed by the options you want to apply. For example,
                if you define:
                <code class="block">
                    [my_preset]<br />
                    video=vga<br/>
                    syntax=pcjr<br>
                </code>
                you can now run <code><b>pcbasic --preset=my_preset</b></code> to start an emulation of
                a hypothetical machine with a VGA video card running PCjr Cartridge BASIC.
            </p>
            <h5 id="gwbasic">GW-BASIC compatibility features</h5>
            <p>
                PC-BASIC aims for a very high level of compatibility with GW-BASIC. However,
                some compatibility features are disabled by default for convenience or security reasons.
                These features can be switched on using individual <a href="#options">command-line options</a>. The highest level of
                compatibility with GW-BASIC can be attained by setting
                <code><a href="#--preset">preset</a>=strict</code>,
                which switches off all convenience and security features that cause differences with
                GW-BASIC.
            </p>

        </section>
        <hr />

        <section>
            <h4 id="codepages">Codepages</h4>
            <p>
                PC-BASIC supports a large number of legacy codepages that were common at the
                time GW-BASIC was popular, including double-byte character set codepages used
                for Chinese, Japanese and Korean. You can select your codepage by using the
                <code><a href="#--codepage">codepage</a>=</code> option. For example, <code>codepage=936</code> selects
                the GBK codepage commonly used on the Chinese mainland. PC-BASIC will load and
                save all program files as if encoded in the codepage you select.
            </p>
            <p>
                It is also possible to load and save programs in a standard encoding
                by enabling the <code><a href="#--text-encoding">text-encoding</a></code> option.
                For example, if <code>--text-encoding=utf-8</code> is set, plain-text program source
                will be saved and loaded in standard UTF-8 encoding. Please note that you will still
                need to select a codepage that provides all the Unicode characters that your program
                needs.
            </p>
            <p>
                Note that PC-BASIC does not implement the following features relevant to some of these codepages:
            </p>
            <dl>
                <dt id="bidi">
                    Bidirectional text
                </dt>
                <dd>
                    All text is printed
                    left-to-right independent of the codepage selected. To write strings in a language that
                    is written right-to-left, the logical character sequence must be inverted so that
                    the order appears correct visually. While this is inconvenient, it is in line with the behaviour of GW-BASIC.
                    This affects code pages marked with <i>B</i> in the table.
                </dd>

                <dt id="combi">
                    Combining characters
                </dt>
                <dd>
                    PC-BASIC recognises single-byte code points (where each glyph shows on a single cell on the screen) and
                    double-byte code points (where a single glyph takes up two cells on the screen). Combining characters
                    (such as the combining diacritics of codepages <code>874</code> and <code>1258</code>) are therefore not
                    shown correctly: instead of being combined with their preceding base character as a single combined glyph,
                    such combinations will be shown as separate glyphs. Where available, alternative codepages with precomposed
                    characters will give better results. This affects code pages marked with <i>C</i> in the table.
                </dd>
            </dl>
            <p>
                The following codepages are available. PC-BASIC uses the Microsoft OEM codepage number where
                this is unambiguous. The code pages are expected to agree with Microsoft sources for the ranges
                <code>&amp;h80</code>&ndash;<code>&amp;hFF</code>. Ranges <code>&amp;h00</code>&ndash;<code>&amp;h1F</code>
                and <code>&amp;h7F</code> are implemented as the IBM Special Graphic Characters where some
                code page sources will list these as the corresponding control characters.
                For unofficial codepages and those with conflicting numbering, codepage
                names are used instead of numbers.
            </p>
            <div class="scrollable"><table>
                <tr>
                    <th><code><var>codepage_id</var></code></th>
                    <th>Codepage</th>
                    <th>Languages</th>
                    <th>Notes</th>
                </tr>
                <tr>
                    <td><code>437</code></td>
                    <td>DOS Latin USA</td>
                    <td>English</td>
                    <td></td>
                </tr>
                <tr>
                    <td><code>720</code></td>
                    <td>Transparent ASMO</td>
                    <td>Arabic</td>
                    <td><a href="#bidi"><i>B</i></a></td>
                </tr>
                <tr>
                    <td><code>737</code></td>
                    <td>DOS Greek</td>
                    <td>Greek</td>
                    <td></td>
                </tr>
                <tr>
                    <td><code>775</code></td>
                    <td>DOS Baltic Rim</td>
                    <td>Estonian, Latvian and Lithuanian</td>
                    <td></td>
                </tr>
                <tr>
                    <td><code>850</code></td>
                    <td>DOS Latin 1</td>
                    <td>Western European languages</td>
                    <td></td>
                </tr>
                <tr>
                    <td><code>851</code></td>
                    <td>DOS Greek 1</td>
                    <td>Greek</td>
                    <td></td>
                </tr>
                <tr>
                    <td><code>852</code></td>
                    <td>DOS Latin 2</td>
                    <td>Central European languages</td>
                    <td></td>
                </tr>
                <tr>
                    <td><code>853</code></td>
                    <td>DOS Latin 3</td>
                    <td>Southern European languages</td>
                    <td></td>
                </tr>
                <tr>
                    <td><code>855</code></td>
                    <td>DOS Cyrillic 1</td>
                    <td>Serbian, Macedonian and Bulgarian</td>
                    <td></td>
                </tr>
                <tr>
                    <td><code>856</code></td>
                    <td>DOS Hebrew</td>
                    <td>Hebrew</td>