1 files changed, 143 insertions, 0 deletions
diff --git a/bas2aplus.rst b/bas2aplus.rst
new file mode 100644
index 0000000..4ce3f50
--- /dev/null
+++ b/bas2aplus.rst
@@ -0,0 +1,143 @@
+=========
+bas2aplus
+=========
+
+---------------------------------------------------------------
+Convert Atari BASIC (and some BASIC XL/XE) programs to BASIC/A+
+---------------------------------------------------------------
+
+.. include:: manhdr.rst
+
+SYNOPSIS
+========
+
+bas2aplus *input-file* *output-file*
+
+DESCRIPTION
+===========
+
+**bas2aplus** reads an Atari BASIC or BASIC XL/XE tokenized (SAVEd)
+program and converts it to BASIC/A+. The conversion is a simple token
+replacement; no syntax or semantic analysis is done.
+
+*input-file* must be an Atari BASIC, BASIC XL, or BASIC XE program.
+Turbo BASIC is not supported. Trying to convert a program that is
+already BASIC/A+ will appear to succeed, but the resulting program
+will be gibberish and will likely crash BASIC/A+ when **RUN**.
+
+All Atari BASIC programs can be successfully converted. Some BASIC
+XL/XE tokens have no equivalent in BASIC/A+, so programs using these
+can't be converted (you will see messages on standard error, in that
+case).
+
+OPTIONS
+=======
+
+.. include:: genopts.rst
+
+BASIC
+=====
+
+BASIC/A+ is basically a later version of Atari BASIC, by the same team
+that developed Atari BASIC. As such, it's source-compatible with Atari
+BASIC, but *not* token-compatible.
+
+BASIC/A+ uses a different set of token numbers, but has all but two
+of the same tokens used by Atari BASIC. Conversion should always
+succeed, for an Atari BASIC program.
+
+The two missing tokens are the **COM** and **GO TO** commands, which
+are converted to **DIM** and **GOTO**, respectively.
+
+The resulting program should **LOAD** and **RUN** in BASIC/A+ and
+function identically to the BASIC version, unless it uses memory
+that's reserved in A+. **USR()** routines that are stored in the lower
+half of Page 6 will have to be relocated, since A+ uses this area
+itself. See the BASIC/A+ manual for full details.
+
+BASIC XL
+========
+
+BASIC XL is basically the next version of BASIC/A+, by the
+same developers. The token lists were rearranged so that it's
+token-compatible with Atari BASIC, and includes all the extra
+commands/functions/etc from BASIC/A+... with different token numbers.
+
+BASIC XL has keywords and operators that don't exist in BASIC/A+,
+which can't be translated by **bas2aplus**. These are:
+
+**NUM**
+  Rarely found in a program (usually only used in direct mode).
+
+**FAST**
+  Just doesn't exist in BASIC/A+.
+
+**LOCAL**, **EXIT**, **PROCEDURE**, **CALL**, **SORTUP**, **SORTDOWN**
+  These BASIC XL commands are provided by the disk-based Toolkit
+  extension, which doesn't exist for BASIC/A+.
+
+**String Arrays**
+  BASIC/A+ doesn't support these; if your BASIC XL program uses them,
+  it won't convert correctly.
+
+**BUMP** and **FIND**
+  While BASIC/A+ does support these functions, the token-level syntax
+  is different; it would be possible to translate them, but it would
+  require recalculating the line offset and statement offsets for
+  every line that uses them. For now, they're not supported.
+
+**%**
+  The exclusive OR operator in BASIC XL. No such animal, in A+.
+
+**HEX$**, **RANDOM**, **LEFT$**, **RIGHT$**, **MID$**
+  These functions don't exist in BASIC/A+.
+
+Also, BASIC XL supports hex constants, with a leading **$**. A+
+doesn't support these, so they get converted to the equivalent decimal
+constant. This is basically a cosmetic change; **A=$0600** assigns the
+same value as **A=1536**.
+
+BASIC XL also allows some syntax that's not valid in BASIC
+A+. For instance, **DIR** is allowed with no argument in XL.
+**bas2aplus** doesn't detect these constructs.
+
+BASIC XE
+========
+
+BASIC XE is the last in the series of OSS BASIC interpreters. It
+supports "EXTENDed" mode, which allows BASIC XE to use all the
+memory in a 130XE, but such programs are *not* supported by
+**bas2aplus**. Only non-EXTENDed BASIC XE programs can be converted.
+
+BASIC XE adds a few keywords to BASIC XL, which also don't exist in
+A+. These are:
+
+**EXTEND**
+  This command is direct-mode only, so it will never appear in a SAVEd
+  program anyway.
+
+**HITCLR**, **INVERSE**, **NORMAL**, **BLOAD**, **BSAVE**
+  Not supported in either A+ or XL.
+
+BASIC XE also allows some syntax that's not valid in either BASIC XL
+or A+. For instance, **IF <condition>**, without **THEN**, can appear
+as the last statement on a line, and **LVAR** no longer requires an
+argument. **bas2aplus** doesn't detect these constructs.
+
+Actually, BASIC/A+ will **LIST** and **RUN** programs with the **IF**
+issue, but such lines can't be edited in A+. Easy enough to add a
+**:REM** to the end of the line, though.
+
+TURBO BASIC
+===========
+
+Not supported. It's also an extended version of Atari BASIC (by
+a different developer), but extends the syntax in ways that just
+wouldn't convert directly to BASIC/A+.
+
+EXIT STATUS
+===========
+
+0 for success, non-zero for failure.
+
+.. include:: manftr.rst