\documentclass{article}
\title{BASLOAD-ROM user manual}
\date{\today}

\setlength{\parindent}{0pt}
\setlength{\parskip}{1.2ex}

\usepackage{hyperref}
\renewcommand{\familydefault}{\sfdefault}
\usepackage{graphicx}
\usepackage{wrapfig}
\usepackage{float}
\usepackage{wrapfig}
\usepackage{longtable}

\begin{document}

\begin{huge}
    BASLOAD-ROM User Manual
\end{huge}

\vspace{1em}
\today

\vspace{4em}
\tableofcontents
\vspace{4em}

\section{Introduction}

    BASLOAD runs natively on the Commander X16 retro computer. It loads BASIC 
    source code in plain text format from the SD card and converts it to 
    runnable BASIC programs.

    The goal of BASLOAD is to make BASIC programming for the Commander X16 more convenient.

    The main benefits of BASLOAD are:

    \begin{itemize}
        \item Source code may be edited in any text editor
        \item Line numbers are not used in the source code; named labels are 
              decleared as targets for GOTOs and GOSUBs
        \item Long variable names are supported, while only the first two 
              characters of a variable name are significant in the built-in 
              BASIC
    \end{itemize}
    
    This manual only describes the ROM based version of BASLOAD.

    The Commander X16 was devised by David Murray a.k.a. the 
    8-Bit Guy. For more information on the platform, go to 
    \href{http://www.commanderx16.com}{www.commanderx16.com}.

\section{Hello World Example}

    Lets begin with a simple Hello world example in BASLOAD formatted
    source code. Open your text editor, type in the code below, and save it to
    the file "HELLO.BAS" on the SD card.

    \begin{verbatim}
    LOOP:
        PRINT "HELLO, WORLD!"
        GOTO LOOP
    \end{verbatim}

    Convert the file to a runnable program with the following
    command:

    \begin{verbatim}
    BASLOAD "HELLO.BAS"
    \end{verbatim}

    The program is now loaded into memory. You can type LIST to
    show it and RUN to execute it.

    If you get a ?Syntax Error, it means that BASLOAD is not
    present in your ROM.

\section{Source Code Files}

    BASLOAD expects source code files to be stored on the 
    Commander X16's SD card.

    Source code files may be created with any text editor as
    long as the following requirements are met:

    \begin{itemize}
        \item The source code must be plain ASCII or PETSCII encoded text
        \item Line breaks may be encoded with CR, LF or CRLF
        \item A line may not be more than 250 characters long
    \end{itemize}

\section{BASIC Syntax}

    \subsection{General}

        Source code written for BASLOAD is meant to be as close as
        possible to BASIC typed in at the on-screen editor
        (the "built-in BASIC").

        The source code follows the same syntax and supports the
        same commands and operators as the built-in
        BASIC. For further information on this topic, see
        \href{https://github.com/X16Community/x16-docs/blob/master/X16%20Reference%20-%2003%20-%20BASIC.md}
        {x16-docs/Basic Programming}.

        There are, however, four important differences between
        BASLOAD source code and the built-in BASIC:

        \begin{itemize}
            \item Line numbers are not used in BASLOAD source code
            \item Labels are decleared as targets for GOTOs, GOSUBs and
                  other commands that normally take a line number
            \item Variable names have up to 64 significant characters, compared to two
                  in the built-in BASIC
            \item Some whitespace is required to separate identifiers, 
                  \textit{i.e.} commands, labels, and variables, from each other
                  
        \end{itemize}
    
    \subsection{Identifiers}

        BASIC commands, labels and variables are commonly referred to as "identifiers" in this
        manual.

        Identifiers start with a letter, any of A--Z.

        Subsequent characters may be any of:

        \begin{itemize}
            \item A letter A--Z
            \item A digit 0--9 
            \item A decimal point (.)
        \end{itemize}

        Identifiers are not case-sensitive, and may be at most 64 characters long.

        An identifier may not be exactly the same as an already existing identifier.

    \subsection{Labels}

        Labels are used as targets for commands that take a line number in
        the built-in BASIC, such as GOTO, GOSUB and RESTORE.

        A label is decleared at the beginnig of a line. There may, however,
        be whitespace before the start of the declaration.

        A label must be a valid identifier, as described above. The end of
        a label declaration is marked with a colon.

        Examples:

        \begin{itemize}
            \item LOOP: is a valid label declaration
            \item PRINT: is not a valid label declaration as PRINT is a reserved word
            \item PRINTME: is valid
        \end{itemize}

        When you want to refer to a label later on in the source code, for
        instance after a GOTO command, you just type the label name without
        colon.

        Example:

        \begin{verbatim}
        LOOP:
            ...
            GOTO LOOP
        \end{verbatim}

    \subsection{Variables}

        Variables are automatically decleared when they are first used in
        code.

        A variable must be a valid identifier as described above.

        As in the built-in BASIC, you add a dollar sign (\$) to the end
        of the variable name to make it a string or a percentage sign (\%)
        to make it an integer.

        Examples:

        \begin{verbatim}
    INPUT "WHAT IS YOUR NAME"; NAME$
    PRINT "HELLO, "; NAME$
        \end{verbatim}

    \subsection{Whitespace to Separate Identifiers}

        BASLOAD requires some whitespace to separate identifiers. 
        Specifically, two identifiers next to each other must
        be separated by whitespace if not otherwise separated by
        a character outside the group of characters allowed in
        identifier names.

        The following characters are recognized as whitespace:

        \begin{itemize}
            \item Blank space (PETSCII/ASCII 32)
            \item Horizontal tab (PETSCII/ASCII 9)
            \item Shift + Blank space (PETSCII/ASCII 160)
        \end{itemize}

        Examples:

        \begin{itemize}
            \item PRINTME needs to be separated if you want to PRINT the value of ME
            \item PRINT"ME" does not need to be separated as double quote cannot be part of an identifier name
        \end{itemize}

\section{BASLOAD Options}

    \subsection{General}

        BASLOAD lets you put options in the source code that affect the output. In some
        programming languages they are called directives.

        An option must be placed at the beginning of a line, but there may be
        whitespace before it.

        Options have the following syntax:

        \begin{verbatim}
    #<NAME> <ARGUMENT>
        \end{verbatim}

        The following options are supported:

        \begin{itemize}
            \item \#\#
            \item \#REM
            \item \#INCLUDE
            \item \#AUTONUM
            \item \#CONTROLCODES
            \item \#SYMFILE
        \end{itemize}

        The argument is separated from the option name by one or more whitespace characters. It
        may be either an integer number or a string. A string may optionally be enclosed in
        duoble quotes, which makes it possible for it to contain whitespace characters.

    \subsection{Option: \#\# Comment}

        This option is an alternative comment that is never outputted to runnable
        code.

        Example:

        \begin{verbatim}
    ## A comment
        \end{verbatim}

    \subsection{Option: \#REM 0 $|$ 1}

        This option lets you select whether REM statements are included in
        the resulting code or not. \#REM 0 turns off the output and \#REM 1
        turns it on again.

        It is possible to change the option value multiple times in the
        source code. The option takes effect from the line where it is 
        encountered and remains in force until changed.

        The default value is 0 (off).

        Example that turns on output of REM statements:
        \begin{verbatim}
    #REM 1
        \end{verbatim}

    \subsection{Option: \#INCLUDE "filename"}

        This option includes the content of another BASIC source
        file where it is encountered.

        An included source file can in its turn include another
        source file. The maximum depth of includes is limited
        by the fact that the Commander X16 can have at most
        ten files open at the same time.

        Example that includes the file FUNC.BAS:
        \begin{verbatim}
    #INCLUDE "FUNC.BAS"
        \end{verbatim}    

    \subsection{Option: \#AUTONUM 0 $|$ 1}

        The autonum option makes it possible to set how many
        steps the line number of the resulting code is
        advanced for each outputted line.

        The option takes effect from the line where it is
        found and remains in force until changed. It is
        possible to change the value multiple times in a
        source file.

        The default step value is 1.

        This option may come in handy if you want to make
        room to insert code directly into the runnable code,
        for instance for debugging.
        
        Example that advances the output line counter 10 steps per line
        \begin{verbatim}
    #AUTONUM 10
        \end{verbatim}

    \subsection{Option: \#CONTROLCODES 0 $|$ 1}
        The controlcodes option makes it possible to type
        named PETSCII control characters, such as arrow up or
        down.

        The available named control characters are listed in
        Appendix A.

        The controlcodes option takes effect from the line
        where it is encountered and remains in force until
        changed. It is possible to set and change the
        option multiple times in the source code.

        The default value is 0 (off).

        The named control characters are only available
        within a string.

        If you want to put a left curly bracket or a 
        backslash in a string, you need to escape each of them with 
        a backslash while this option is active.

        Examples:

    \begin{verbatim}
    #CONTROLCODES 1
    PRINT "{CLEAR}Hello, world": REM {CLEAR}->PETSCII $93
    PRINT "\{CLEAR} clears the screen": REM {CLEAR} unconverted
    \end{verbatim}

    \subsection{Option: \#SYMFILE "@:filename"}

        This option writes symbols (labels and variables) found during the
        translation of the source code to the specified
        symbol file.

        Symbol files are inteded to help while debugging BASLOAD code.
    
        The symfile option may only be placed at the top of
        the source code before any runnable code has
        been outputted.

        The option may not be used more than once in the source code.

        It is recommended that you add @: before the filename. That will cause
        an existing symbol file to be overwritten, which generally is what you
        want. Otherwise it is not possible to run BASLOAD multiple times
        without file exists error.

        Example that writes the symbol file "MYPRG.SYM", overwriting the
        file if it exists:
        \begin{verbatim}
    #SYMFILE "@:MYPRG.SYM"
        \end{verbatim}

\section{Running BASLOAD}

    \subsection{Planned Interface}

        There are two ways planned to start BASLOAD, neither of which is yet
        part of the official ROM.

        The first method is to use a dedicated BASIC command, like BASLOAD "filename".

        The second method is a keyboard shortcut in X16 Edit, the text editor.

    \subsection{API}

        BASLOAD can be integrated into other programs, and started through its
        API as set out below.

        \vspace{1em}
        \textbf{Call address:} \$C000

        \textbf{Input parameters:} 

        \begin{longtable}[l]{l l p{6cm}}
            \textbf{Register} & \textbf{Address} & \textbf{Description} \\
	        \hline \\
            R0L & \$02            & File name length \\
            R0H & \$03            & Device number \\
            ---  & \$00:BF00--BFFF & File name buffer \\
        \end{longtable}
        \vspace{-1.5em}
        \textbf{Returns:} 

        \begin{longtable}[l]{l l p{6cm}}
            \textbf{Register} & \textbf{Address} & \textbf{Description} \\
	        \hline \\
            R1L      & \$04       & Return code \\
            R1H..R2H & \$05--07   & Source line number where error occured \\
            R3       & \$08--09   & Pointer to source file name where error occured (always bank 1) \\
            ---      & \$00:BF00--BFFF & Plain text return message \\
        \end{longtable}

        The possible return codes are:

        \begin{itemize}
            \item 0 = OK
            \item 1 = Line too long
            \item 2 = Symbol too long
            \item 3 = Duplicate sybols
            \item 4 = Symbol table full
            \item 5 = Out of variable names
            \item 6 = Label expected
            \item 7 = Label not expected
            \item 8 = Line number overflow
            \item 9 = Option unknown
            \item 10 = File error
            \item 11 = Invalid param
            \item 12 = Invalid control code
            \item 13 = Invalid symbol file
            \item 14 = Symbol file I/O error
        \end{itemize}

\appendix
\newpage
\section{Named PETSCII Control Characters}
    
    In order to use named control characters you must first
    put this line in the source code:

    \begin{verbatim}
    #CONTROLCODES 1
    \end{verbatim}

    \begin{longtable}[l]{l l l}
        \textbf{PETSCII} & \textbf{Name} & \textbf{Description} \\
        \hline \\
        \$01 & \{SWAP COLORS\} & SWAP COLORS\\
        \$02 & \{PAGE DOWN\} & PAGE DOWN\\
        \$03 & \{STOP\} & STOP\\
        \$04 & \{END\} & END\\
        \$05 & \{WHITE\} & COLOR: WHITE\\
        \$05 & \{WHT\} & COLOR: WHITE\\
        \$06 & \{MENU\} & MENU\\
        \$07 & \{BELL\} & BELL\\
        \$08 & \{CHARSET SWITCH OFF\} & DISALLOW CHARSET SW (SHIFT+ALT)\\
        \$09 & \{TAB\} & TAB / ALLOW CHARSET SW\\
        \$09 & \{CHARSET SWITCH ON\} & TAB / ALLOW CHARSET SW\\
        \$0A & \{LF\} & LF\\
        \$0D & \{CR\} & RETURN\\
        \$0E & \{LOWER\} & CHARSET: LOWER/UPPER\\
        \$0F & \{ISO ON\} & CHARSET: ISO ON\\
        \$10 & \{F9\} & F9\\
        \$11 & \{DOWN\} & CURSOR: DOWN\\
        \$12 & \{RVS ON\} & REVERSE ON\\
        \$13 & \{HOME\} & HOME\\
        \$14 & \{BACKSPACE\} & DEL (PS/2 BACKSPACE)\\
        \$15 & \{F10\} & F10\\
        \$16 & \{F11\} & F11\\
        \$17 & \{F12\} & F12\\
        \$18 & \{SHIFT TAB\} & SHIFT+TAB\\
        \$19 & \{DEL\} & FWD DEL (PS/2 DEL)\\
        \$1B & \{ESC\} & ESC\\
        \$1C & \{RED\} & COLOR: RED\\
        \$1D & \{RIGHT\} & CURSOR: RIGHT\\
        \$1E & \{GREEN\} & COLOR: GREEN\\
        \$1E & \{GRN\} & COLOR: GREEN\\
        \$1F & \{BLUE\} & COLOR: BLUE\\
        \$1F & \{BLU\} & COLOR: BLUE\\
        \$80 & \{VERBATIM\} & VERBATIM MODE\\
        \$81 & \{ORANGE\} & COLOR: ORANGE\\
        \$81 & \{ORG\} & COLOR: ORANGE\\
        \$82 & \{PAGE UP\} & PAGE UP\\
        \$85 & \{F1\} & F1\\
        \$86 & \{F3\} & F3\\
        \$87 & \{F5\} & F5\\
        \$88 & \{F7\} & F7\\
        \$89 & \{F2\} & F2\\
        \$8A & \{F4\} & F4\\
        \$8B & \{F6\} & F6\\
        \$8C & \{F8\} & F8\\
        \$8D & \{SHIFT CR\} & SHIFTED RETURN\\
        \$8E & \{UPPER\} & CHARSET: UPPER/PETSCII\\
        \$8F & \{ISO OFF\} & CHARSET: ISO OFF\\
        \$90 & \{BLACK\} & COLOR: BLACK\\
        \$90 & \{BLK\} & COLOR: BLACK\\
        \$91 & \{UP\} & CURSOR: UP\\
        \$92 & \{RVS OFF\} & REVERSE OFF\\
        \$93 & \{CLEAR\} & CLEAR\\
        \$93 & \{CLR\} & CLEAR\\
        \$94 & \{INSERT\} & INSERT\\
        \$95 & \{BROWN\} & COLOR: BROWN\\
        \$96 & \{LIGHT RED\} & COLOR: LIGHT RED\\
        \$97 & \{GREY 3\} & COLOR: DARK GRAY\\
        \$98 & \{GREY 2\} & COLOR: MIDDLE GRAY\\
        \$99 & \{LIGHT GREEN\} & COLOR: LIGHT GREEN\\
        \$9A & \{LIGHT BLUE\} & COLOR: LIGHT BLUE\\
        \$9B & \{GREY 1\} & COLOR: LIGHT GRAY\\
        \$9C & \{PURPLE\} & COLOR: PURPLE\\
        \$9C & \{PUR\} & COLOR: PURPLE\\
        \$9D & \{LEFT\} & CURSOR: LEFT\\
        \$9E & \{YELLOW\} & COLOR: YELLOW\\
        \$9E & \{YEL\} & COLOR: YELLOW\\
        \$9F & \{CYAN\} & COLOR: CYAN\\
        \$9F & \{CYN\} & COLOR: CYAN\\
    \end{longtable}

\end{document}

Pihjalalinna
Terveystalo
Mehiläinen
Lääkärikeskus Aava
Pohjola Vakuutus 49-10622-6