1 files changed, 99 insertions, 0 deletions
diff --git a/bas2aplus.rst b/bas2aplus.rst
new file mode 100644
index 0000000..0eb44d6
--- /dev/null
+++ b/bas2aplus.rst
@@ -0,0 +1,99 @@
+=========
+bas2aplus
+=========
+
+------------------------------------------------------------
+Convert Atari BASIC (and some BASIC XL) programs to BASIC/A+
+------------------------------------------------------------
+
+.. include:: manhdr.rst
+
+SYNOPSIS
+========
+
+bas2aplus *input-file* *output-file*
+
+DESCRIPTION
+===========
+
+**bas2aplus** reads an Atari BASIC or BASIC XL tokenized (SAVEd) program
+and converts it to BASIC/A+.
+
+All Atari BASIC programs can be successfully converted. Some BASIC
+XL operators 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+. 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**.
+
+EXIT STATUS
+===========
+
+0 for success, non-zero for failuse.
+
+.. include:: manftr.rst