aboutsummaryrefslogtreecommitdiff
path: root/bas2aplus.1
diff options
context:
space:
mode:
Diffstat (limited to 'bas2aplus.1')
-rw-r--r--bas2aplus.1210
1 files changed, 210 insertions, 0 deletions
diff --git a/bas2aplus.1 b/bas2aplus.1
new file mode 100644
index 0000000..110fec4
--- /dev/null
+++ b/bas2aplus.1
@@ -0,0 +1,210 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "BAS2APLUS" 1 "2024-07-24" "0.2.1" "Urchlay's Atari 8-bit Tools"
+.SH NAME
+bas2aplus \- Convert Atari BASIC (and some BASIC XL/XE) programs to BASIC/A+
+.SH SYNOPSIS
+.sp
+bas2aplus \fIinput\-file\fP \fIoutput\-file\fP
+.SH DESCRIPTION
+.sp
+\fBbas2aplus\fP 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.
+.sp
+\fIinput\-file\fP 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 \fBRUN\fP\&.
+.sp
+All Atari BASIC programs can be successfully converted. Some BASIC
+XL/XE tokens have no equivalent in BASIC/A+, so programs using these
+can\(aqt be converted (you will see messages on standard error, in that
+case).
+.SH OPTIONS
+.SS General Options
+.INDENT 0.0
+.TP
+.B \fB\-\-help\fP
+Print usage message and exit.
+.TP
+.B \fB\-\-version\fP
+Print version number and exit.
+.TP
+.B \fB\-v\fP
+Verbose operation. When displaying a number in verbose mode, it will
+be prefixed with \fI$\fP if it\(aqs in hex, or no prefix for decimal.
+.UNINDENT
+.SH BASIC
+.sp
+BASIC/A+ is basically a later version of Atari BASIC, by the same team
+that developed Atari BASIC. As such, it\(aqs source\-compatible with Atari
+BASIC, but \fInot\fP token\-compatible.
+.sp
+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.
+.sp
+The two missing tokens are the \fBCOM\fP and \fBGO TO\fP commands, which
+are converted to \fBDIM\fP and \fBGOTO\fP, respectively.
+.sp
+The resulting program should \fBLOAD\fP and \fBRUN\fP in BASIC/A+ and
+function identically to the BASIC version, unless it uses memory
+that\(aqs reserved in A+. \fBUSR()\fP 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.
+.SH BASIC XL
+.sp
+BASIC XL is basically the next version of BASIC/A+, by the
+same developers. The token lists were rearranged so that it\(aqs
+token\-compatible with Atari BASIC, and includes all the extra
+commands/functions/etc from BASIC/A+... with different token numbers.
+.sp
+BASIC XL has keywords and operators that don\(aqt exist in BASIC/A+,
+which can\(aqt be translated by \fBbas2aplus\fP\&. These are:
+.INDENT 0.0
+.TP
+.B \fBNUM\fP
+Rarely found in a program (usually only used in direct mode).
+.TP
+.B \fBFAST\fP
+Just doesn\(aqt exist in BASIC/A+.
+.TP
+.B \fBLOCAL\fP, \fBEXIT\fP, \fBPROCEDURE\fP, \fBCALL\fP, \fBSORTUP\fP, \fBSORTDOWN\fP
+These BASIC XL commands are provided by the disk\-based Toolkit
+extension, which doesn\(aqt exist for BASIC/A+.
+.TP
+.B \fBString Arrays\fP
+BASIC/A+ doesn\(aqt support these; if your BASIC XL program uses them,
+it won\(aqt convert correctly.
+.TP
+.B \fBBUMP\fP and \fBFIND\fP
+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\(aqre not supported.
+.TP
+.B \fB%\fP
+The exclusive OR operator in BASIC XL. No such animal, in A+.
+.TP
+.B \fBHEX$\fP, \fBRANDOM\fP, \fBLEFT$\fP, \fBRIGHT$\fP, \fBMID$\fP
+These functions don\(aqt exist in BASIC/A+.
+.UNINDENT
+.sp
+Also, BASIC XL supports hex constants, with a leading \fB$\fP\&. A+
+doesn\(aqt support these, so they get converted to the equivalent decimal
+constant. This is basically a cosmetic change; \fBA=$0600\fP assigns the
+same value as \fBA=1536\fP\&.
+.sp
+BASIC XL also allows some syntax that\(aqs not valid in BASIC
+A+. For instance, \fBDIR\fP is allowed with no argument in XL.
+\fBbas2aplus\fP doesn\(aqt detect these constructs.
+.SH BASIC XE
+.sp
+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 \fInot\fP supported by
+\fBbas2aplus\fP\&. Only non\-EXTENDed BASIC XE programs can be converted.
+.sp
+BASIC XE adds a few keywords to BASIC XL, which also don\(aqt exist in
+A+. These are:
+.INDENT 0.0
+.TP
+.B \fBEXTEND\fP
+This command is direct\-mode only, so it will never appear in a SAVEd
+program anyway.
+.TP
+.B \fBHITCLR\fP, \fBINVERSE\fP, \fBNORMAL\fP, \fBBLOAD\fP, \fBBSAVE\fP
+Not supported in either A+ or XL.
+.UNINDENT
+.sp
+BASIC XE also allows some syntax that\(aqs not valid in either BASIC XL
+or A+. For instance, \fBIF <condition>\fP, without \fBTHEN\fP, can appear
+as the last statement on a line, and \fBLVAR\fP no longer requires an
+argument. \fBbas2aplus\fP doesn\(aqt detect these constructs.
+.sp
+Actually, BASIC/A+ will \fBLIST\fP and \fBRUN\fP programs with the \fBIF\fP
+issue, but such lines can\(aqt be edited in A+. Easy enough to add a
+\fB:REM\fP to the end of the line, though.
+.SH TURBO BASIC
+.sp
+Not supported. It\(aqs also an extended version of Atari BASIC (by
+a different developer), but extends the syntax in ways that just
+wouldn\(aqt convert directly to BASIC/A+.
+.SH EXIT STATUS
+.sp
+0 for success, non\-zero for failure.
+.SH COPYRIGHT
+.sp
+WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details.
+.SH AUTHOR
+.INDENT 0.0
+.IP B. 3
+Watson <\fI\%urchlay@slackware.uk\fP>; Urchlay on irc.libera.chat \fI##atari\fP\&.
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fBa8cat\fP(1),
+\fBa8eol\fP(1),
+\fBa8xd\fP(1),
+\fBatr2xfd\fP(1),
+\fBatrsize\fP(1),
+\fBaxe\fP(1),
+\fBbas2aplus\fP(1),
+\fBblob2c\fP(1),
+\fBblob2xex\fP(1),
+\fBcart2xex\fP(1),
+\fBcxrefbas\fP(1),
+\fBdasm2atasm\fP(1),
+\fBdiffbas\fP(1),
+\fBdumpbas\fP(1),
+\fBf2toxex\fP(1),
+\fBfenders\fP(1),
+\fBlistbas\fP(1),
+\fBprotbas\fP(1),
+\fBrenumbas\fP(1),
+\fBrom2cart\fP(1),
+\fBunmac65\fP(1),
+\fBunprotbas\fP(1),
+\fBvxrefbas\fP(1),
+\fBwhichbas\fP(1),
+\fBxex1to2\fP(1),
+\fBxexamine\fP(1),
+\fBxexcat\fP(1),
+\fBxexsplit\fP(1),
+\fBxfd2atr\fP(1),
+\fBxex\fP(5),
+\fBatascii\fP(7),
+\fBfauxtari\fP(7).
+.sp
+Any good Atari 8\-bit book: \fIDe Re Atari\fP, \fIThe Atari BASIC Reference
+Manual\fP, the \fIOS Users\(aq Guide\fP, \fIMapping the Atari\fP, etc.
+.\" Generated by docutils manpage writer.
+.