diff options
Diffstat (limited to 'bas2aplus.1')
| -rw-r--r-- | bas2aplus.1 | 210 |
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. +. |