whichbas: added.

1 files changed, 75 insertions, 0 deletions

diff --git a/whichbas.rst b/whichbas.rst
new file mode 100644
index 0000000..5e7363c
--- /dev/null
+++ b/whichbas.rst
@@ -0,0 +1,75 @@
+========
+whichbas
+========
+
+----------------------------------------------------------
+Determine BASIC variant of a tokenized Atari 8-bit program
+----------------------------------------------------------
+
+.. include:: manhdr.rst
+
+SYNOPSIS
+========
+whichbas [-v] *input-file*
+
+DESCRIPTION
+===========
+**whichbas** reads a tokenized Atari 8-bit BASIC, Turbo BASIC,
+BASIC XL, BASIC XE, or Atari Microsoft BASIC program and attempts to
+discover which BASIC is required to run it.
+
+NOTES
+=====
+Turbo BASIC, BASIC XL, and BASIC XE are all supersets of Atari BASIC.
+If you wrote a program using one of them, but didn't use any of the
+extra commands or functions, the result is still an Atari BASIC program.
+
+There are two types of BASIC XE programs: regular and *EXTEND*\ed. The
+extended type is detected 100% reliably, because the first byte of the
+file changes from **$00** to **$DD**. Non-extended programs are only
+identified as BASIC XE if they use any of the extra commands BASIC XE
+adds to those found in BASIC XL.
+
+Atari BASIC programs can be detected 100% reliably.
+
+Detection of Turbo vs. BXL/BXE isn't 100% reliable, and probably
+never will be. There's too much overlap between the sets of extra
+tokens added by each. Programs that don't use very many of the extra
+functions provided by Turbo/BXL/BXE may show up as "Not Atari BASIC;
+probably either Turbo or BXL/BXE".
+
+Atari Microsoft BASIC is detected by checking that the first two
+bytes of the file are not zero, and that the last 3 are zero. This
+may result in false positives (files that aren't BASIC programs at
+all might show up as Microsoft). Also, no distinction is made between
+Atari MS BASIC 1.0 and 2.0.
+
+Various non-BASIC files are detected (including Mac/65 source,
+ELF binaries, etc) as a convenience, but I wouldn't rely on
+**whichbas**\'s non-BASIC file type detection if I were you.
+
+LIMITATIONS
+===========
+Currently, **whichbas** doesn't look at the variable name or type
+tables. One problem caused by this: If a program uses only Atari BASIC
+tokens, but uses variable(s) with _ in the name, it will be identified
+as Atari BASIC... even though _ in variable names is illegal in Atari
+BASIC and pretty much guarantees the program is Turbo/BXL/BXE.
+
+Looking at the variable types could also improve detection, since
+Turbo and BXL/BXE support extended variable types.
+
+**whichbas** knows nothing about other BASICs such as Frost BASIC,
+BASIC/A+, Altirra BASIC...
+
+OPTIONS
+=======
+
+.. include:: genopts.rst
+
+EXIT STATUS
+===========
+
+0 for success, 1 for failure.
+
+.. include:: manftr.rst