bas2aplus: added.

1 files changed, 166 insertions, 0 deletions

diff --git a/bas2aplus.1 b/bas2aplus.1
new file mode 100644
index 0000000..d263293
--- /dev/null
+++ b/bas2aplus.1
@@ -0,0 +1,166 @@
+.\" 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-21" "0.2.1" "Urchlay's Atari 8-bit Tools"
+.SH NAME
+bas2aplus \- Convert Atari BASIC (and some BASIC XL) 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 tokenized (SAVEd) program
+and converts it to BASIC/A+.
+.sp
+All Atari BASIC programs can be successfully converted. Some BASIC
+XL operators 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+. 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\&.
+.SH EXIT STATUS
+.sp
+0 for success, non\-zero for failuse.
+.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),
+\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).
+.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.
+.