ossintbas: added man page.

4 files changed, 642 insertions, 1 deletions

diff --git a/Makefile b/Makefile
index 95d3b77..ba9e830 100644
--- a/Makefile
+++ b/Makefile
@@ -24,7 +24,7 @@ BINS=a8eol atr2xfd atrsize axe blob2c blob2xex cart2xex cxrefbas dumpbas fenders
 SCRIPTS=dasm2atasm diffbas a8diff colorize-amsb abas2html
 MANS=a8eol.1 xfd2atr.1 atr2xfd.1 blob2c.1 cart2xex.1 fenders.1 xexsplit.1 xexcat.1 atrsize.1 rom2cart.1 unmac65.1 axe.1 dasm2atasm.1 blob2xex.1 xexamine.1 xex1to2.1 unprotbas.1 protbas.1 renumbas.1 dumpbas.1 vxrefbas.1 cxrefbas.1 listbas.1 a8cat.1 a8xd.1 whichbas.1 diffbas.1 a8diff.1 bas2aplus.1 listamsb.1 colorize-amsb.1 abas2html.1
 MAN5S=xex.5
-MAN7S=atascii.7 fauxtari.7 amsb.7
+MAN7S=atascii.7 fauxtari.7 amsb.7 ossintbas.7
 DOCS=README.txt CHANGES.txt equates.inc *.dasm LICENSE ksiders/atr.txt
 PSFS=fonts/fauxtari-8.psf fonts/fauxtari-16.psf fonts/fauxtari-24.psf
 BDFS=fonts/fauxtari-8.bdf fonts/fauxtari-16.bdf fonts/fauxtari-24.bdf
@@ -189,6 +189,8 @@ manpages: $(MANS) $(MAN5S) $(MAN7S)
 
 amsb.7: amsb.rst manhdr7.rst manftr.rst amsb_content.rst
 
+ossintbas.7: ossintbas.rst manhdr7.rst manftr.rst ossintbas_content.rst
+
 %.7: %.rst manhdr7.rst manftr.rst
 	$(RST2MAN) $< > $@
 
diff --git a/ossintbas.7 b/ossintbas.7
new file mode 100644
index 0000000..19cbc3a
--- /dev/null
+++ b/ossintbas.7
@@ -0,0 +1,380 @@
+.\" 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 "OSSINTBAS" 7 "2025-03-25" "0.2.2" "Urchlay's Atari 8-bit Tools"
+.SH NAME
+ossintbas \- OSS Integer BASIC Notes
+.SH DESCRIPTION
+.sp
+OSS Integer BASIC is a BASIC interpreter from OSS, similar to BASIC XL
+and BASIC XE. It was never released as a commercial product, and was
+eventually released into the Public Domain.
+.sp
+It appears to be complete and free of major bugs. There is no manual
+for it, so I\(aqm documenting the differences between Integer BASIC and
+BASIC XL/XE here, as I discover them.
+.sp
+For more info on the release:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+https://forums.atariage.com/topic/257029\-oss\-d\-day\-part\-3\-integer\-basic\-source\-code\-now\-in\-pd/
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH NUMERICS
+.sp
+All numbers are signed 16\-bit integers. There is no floating point support
+at all.
+.sp
+Two\(aqs complement is used, so bit 15 is the sign bit, and \fI\-1\fP is
+represented as \fI$FFFF\fP\&.
+.sp
+The range is \fI\-32768\fP to \fI32767\fP\&. Somewhat confusingly (but also
+usefully), positive numbers in the range \fI32768\fP to \fI65535\fP can be
+entered in program code, or as response to \fBINPUT\fP, etc... but when
+they are \fBPRINT\fPed, they will appear as negative numbers. This
+is unlike Apple\(aqs Integer BASIC, for instance. It was probably done
+so that BASIC code could use the familiar memory locations. Example:
+\fBPEEK(53279)\fP to read the console keys. It would be very annoying if
+this had to be written as \fBPEEK(\-12257)\fP\&... although it does work
+if written that way (Apple\-style).
+.sp
+Although floating point is not supported, it\(aqs possible to enter
+numbers with a decimal point or even scientific notation. These will
+silently be converted to integers, with rounding. If the result is
+outside the range \fI\-32768\fP to \fI65535\fP, you\(aqll get an \fBERROR\- 3\fP\&.
+This applies to numbers entered as part of the program as well as
+those entered in response to \fBINPUT\fP, or \fBREAD\fP from \fBDATA\fP
+lines.
+.SH COMMANDS
+.sp
+\fBVBLANKWAIT\fP
+.INDENT 0.0
+.INDENT 3.5
+Pause and wait for a vertical blank interrupt to occur.
+.sp
+Abbreviation: \fBV.\fP
+.UNINDENT
+.UNINDENT
+.sp
+\fBVINC\fP \fI<var>\fP
+.INDENT 0.0
+.INDENT 3.5
+Increment (add 1 to) a variable. This is about 30% faster than
+\fBA=A+1\fP\&. Abbreviate as \fBVD.\fP\&.
+.sp
+Abbreviation: \fBVI.\fP
+.UNINDENT
+.UNINDENT
+.sp
+\fBVDEC\fP \fI<var>\fP
+.INDENT 0.0
+.INDENT 3.5
+Decrement (subtract 1 from) a variable. Abbreviate as \fBVD.\fP\&.
+.sp
+Abbreviation: \fBVD.\fP
+.UNINDENT
+.UNINDENT
+.sp
+\fBVCONST\fP \fI<num>\fP, \fI<var>\fP
+.INDENT 0.0
+.INDENT 3.5
+Add a constant to \fIvar\fP\&. There are 8 constants, numbered 0 through
+7. They are set with the \fBSET\fP command, using arguments 16 to 23
+to set the constants. Example: \fBSET 16,10\fP sets constant 0 to 123,
+and \fBVCONST 0,A\fP adds 10 to A.
+.sp
+If \fI<num>\fP is greater than 7, the variable will be
+unchanged. \fBSET\fP won\(aqt accept a number higher than 23 for its first
+argument, so there\(aqd be no way to set any constants other than 0
+to 7 anyway.
+.sp
+When Integer BASIC first starts up, the constants are initialized
+to what amounts to garbage values. You can examine them with
+\fBSYS(16)\fP through \fBSYS(23)\fP, but it\(aqs a bad idea to depend on
+them because the values are different between the disk and cartridge
+versions of Integer BASIC.
+.sp
+Using VCONST is about 15% faster than just adding a number to a
+variable.
+.sp
+Abbreviation: \fBVC.\fP
+.UNINDENT
+.UNINDENT
+.SH FUNCTIONS
+.sp
+\fBRUN(0)\fP
+.INDENT 0.0
+.INDENT 3.5
+Returns the run (coldstart) address of the interpreter. \fB? USR(RUN(0))\fP
+restarts Integer BASIC. The \fI0\fP is a \(aqdummy\(aq argument (ignored, like \fBFRE(0)\fP).
+.UNINDENT
+.UNINDENT
+.SH OPERATORS
+.sp
+\fB!\fP
+.INDENT 0.0
+.INDENT 3.5
+Binary OR. Infix operator.
+.UNINDENT
+.UNINDENT
+.sp
+\fB&\fP
+.INDENT 0.0
+.INDENT 3.5
+Binary AND. Infix operator.
+.UNINDENT
+.UNINDENT
+.sp
+\fB%\fP
+.INDENT 0.0
+.INDENT 3.5
+Binary exclusive OR (XOR). Infix operator.
+.UNINDENT
+.UNINDENT
+.sp
+\fB<<\fP
+.INDENT 0.0
+.INDENT 3.5
+Left shift, like C. Infix operator. Result is the expression on the left,
+shifted left by the number of bits on the right. Examples: \fB1<<4\fP
+is 16, \fB255<<1\fP is 510.
+.sp
+Bits shifted off the left end of the number are lost. Zeroes are
+shifted in, for the low\-order bit(s). Shifting anything left 16 times
+results in zero. Since bit 15 is the sign bit, shifting a 1 into bit
+15 will result in a negative number.
+.UNINDENT
+.UNINDENT
+.sp
+\fB>>\fP
+.INDENT 0.0
+.INDENT 3.5
+Right shift, like C. Infix operator. Result is the expression
+on the left, shifted to the right, by the number of bits on the
+right. Examples: \fB16>>4\fP is 1, \fB255>>1\fP is 127.
+.sp
+Bits shifted off the right end of the number are lost. Zeroes are
+shifted in, for the high\-order bit(s). Shifting any negative number
+to the right will result in a positive numbers, since a zero will be
+shifted into the sigh bit.
+.UNINDENT
+.UNINDENT
+.sp
+\fB^&\fP
+.INDENT 0.0
+.INDENT 3.5
+Binary NAND. Like AND, but inverts the bits in the result. Infix operator.
+.UNINDENT
+.UNINDENT
+.sp
+\fB^!\fP
+.INDENT 0.0
+.INDENT 3.5
+Binary NOR. Infix operator.
+.UNINDENT
+.UNINDENT
+.sp
+\fB^%\fP
+.INDENT 0.0
+.INDENT 3.5
+Binary NXOR. Infix operator.
+.UNINDENT
+.UNINDENT
+.sp
+\fB\e\fP
+.INDENT 0.0
+.INDENT 3.5
+Modulus. Infix operator. Result of \fBX&Y\fP is the remainder of \fBX/Y\fP\&.
+.sp
+\fINOTE\fP that this is \fBbroken\fP in the cartridge version of Integer BASIC,
+though it works correctly in the disk version. See \fBBUGS\fP, below.
+.UNINDENT
+.UNINDENT
+.SH COMPATIBILITY
+.sp
+Integer BASIC can\(aqt LOAD programs that were SAVEd by any other BASIC,
+and programs SAVEd by Integer BASIC can\(aqt be LOADed in any other
+BASIC. Use LIST and ENTER instead.
+.sp
+Actually, the disk and cartridge versions of Integer BASIC can\(aqt even
+LOAD each others\(aq programs. They use a different set of token numbers.
+This is because the cartridge version includes the \fBHITCLR\fP command,
+but the disk version does not.
+.sp
+The \fBINT()\fP function exists in Integer BASIC, but it doesn\(aqt actually
+do anything. Seems to be provided for compatibility with other BASICs.
+.SS Missing Commands
+.sp
+Integer BASIC has the full command set of the BASIC XL cartridge,
+minus these commands:
+.sp
+\fBDEG\fP \fBRAD\fP \fBRGET\fP \fBRPUT\fP
+.sp
+The cartridge version of Integer BASIC has the \fBHITCLR\fP command
+(from BASIC XE), but the disk version does not.
+.sp
+The BASIC XL extension disk commands (\fBLOCAL\fP, \fBEXIT\fP,
+\fBPROCEDURE\fP, \fBCALL\fP, \fBSORTUP\fP, and \fBSORTDOWN\fP) don\(aqt exist in
+Integer BASIC. If there was ever an extensions disk for Integer BASIC,
+nobody\(aqs found it yet.
+.sp
+The extra commands in BASIC XE (\fBEXTEND\fP, \fBINVERSE\fP, \fBNORMAL\fP,
+\fBBLOAD\fP, and \fBBSAVE\fP) are not supported.
+.SS Missing Operators/Functions
+.INDENT 0.0
+.TP
+.B \fB^\fP
+There is no exponentiation operator; \fB2^2\fP is a syntax error.
+.TP
+.B \fBATN()\fP, \fBCLOG()\fP, \fBCOS()\fP, \fBEXP()\fP, \fBLOG()\fP, \fBSIN()\fP
+There are no trigonometric functions in Integer BASIC. These can
+be used as array variable names, if you wish.
+.TP
+.B \fBUSING\fP
+BASIC XL and XE\(aqs "PRINT USING" doesn\(aqt exist in Integer BASIC.
+.UNINDENT
+.SH BUGS
+.SS Modulo Arithmetic
+.sp
+The \fB\e\fP (modulus) operator returns incorrect results in the
+cartridge version of Integer BASIC. This program demonstrates the
+bug:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+10 For I=1 To 10
+20   ? I,I\e3,I\-(I/3)*3
+30 Next I
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+When run with the disk version, the results are correct:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+1         1         1
+2         2         2
+3         0         0
+4         1         1
+5         2         2
+6         0         0
+7         1         1
+8         2         2
+9         0         0
+10        1         1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The same program run with the cartridge version gives:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+1         254       1
+2         255       2
+3         0         0
+4         1         1
+5         2         2
+6         253       0
+7         254       1
+8         255       2
+9         0         0
+10        1         1
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+This is obviously wrong.
+.sp
+If you\(aqre writing a real program in Integer BASIC, I recommend
+avoiding the \fB\e\fP operator entirely. Write something like \fBX\-X/Y*Y\fP
+instead.
+.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),
+\fBlistamsb\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.
+.
diff --git a/ossintbas.rst b/ossintbas.rst
new file mode 100644
index 0000000..38fe649
--- /dev/null
+++ b/ossintbas.rst
@@ -0,0 +1,14 @@
+=========
+ossintbas
+=========
+
+-----------------------
+OSS Integer BASIC Notes
+-----------------------
+
+.. include:: manhdr7.rst
+
+.. include:: ossintbas_content.rst
+
+.. include:: manftr.rst
+
diff --git a/ossintbas_content.rst b/ossintbas_content.rst
new file mode 100644
index 0000000..acdd9b0
--- /dev/null
+++ b/ossintbas_content.rst
@@ -0,0 +1,245 @@
+DESCRIPTION
+===========
+
+OSS Integer BASIC is a BASIC interpreter from OSS, similar to BASIC XL
+and BASIC XE. It was never released as a commercial product, and was
+eventually released into the Public Domain.
+
+It appears to be complete and free of major bugs. There is no manual
+for it, so I'm documenting the differences between Integer BASIC and
+BASIC XL/XE here, as I discover them.
+
+For more info on the release::
+
+  https://forums.atariage.com/topic/257029-oss-d-day-part-3-integer-basic-source-code-now-in-pd/
+
+NUMERICS
+========
+
+All numbers are signed 16-bit integers. There is no floating point support
+at all.
+
+Two's complement is used, so bit 15 is the sign bit, and *-1* is
+represented as *$FFFF*.
+
+The range is *-32768* to *32767*. Somewhat confusingly (but also
+usefully), positive numbers in the range *32768* to *65535* can be
+entered in program code, or as response to **INPUT**, etc... but when
+they are **PRINT**\ed, they will appear as negative numbers. This
+is unlike Apple's Integer BASIC, for instance. It was probably done
+so that BASIC code could use the familiar memory locations. Example:
+**PEEK(53279)** to read the console keys. It would be very annoying if
+this had to be written as **PEEK(-12257)**\... although it does work
+if written that way (Apple-style).
+
+Although floating point is not supported, it's possible to enter
+numbers with a decimal point or even scientific notation. These will
+silently be converted to integers, with rounding. If the result is
+outside the range *-32768* to *65535*, you'll get an **ERROR- 3**.
+This applies to numbers entered as part of the program as well as
+those entered in response to **INPUT**, or **READ** from **DATA**
+lines.
+
+COMMANDS
+========
+
+**VBLANKWAIT**
+
+  Pause and wait for a vertical blank interrupt to occur.
+
+  Abbreviation: **V.**
+
+**VINC** *<var>*
+
+  Increment (add 1 to) a variable. This is about 30% faster than
+  **A=A+1**. Abbreviate as **VD.**.
+
+  Abbreviation: **VI.**
+
+**VDEC** *<var>*
+
+  Decrement (subtract 1 from) a variable. Abbreviate as **VD.**.
+
+  Abbreviation: **VD.**
+
+**VCONST** *<num>*, *<var>*
+
+  Add a constant to *var*. There are 8 constants, numbered 0 through
+  7. They are set with the **SET** command, using arguments 16 to 23
+  to set the constants. Example: **SET 16,10** sets constant 0 to 123,
+  and **VCONST 0,A** adds 10 to A.
+
+  If *<num>* is greater than 7, the variable will be
+  unchanged. **SET** won't accept a number higher than 23 for its first
+  argument, so there'd be no way to set any constants other than 0
+  to 7 anyway.
+
+  When Integer BASIC first starts up, the constants are initialized
+  to what amounts to garbage values. You can examine them with
+  **SYS(16)** through **SYS(23)**, but it's a bad idea to depend on
+  them because the values are different between the disk and cartridge
+  versions of Integer BASIC.
+
+  Using VCONST is about 15% faster than just adding a number to a
+  variable.
+
+  Abbreviation: **VC.**
+
+
+FUNCTIONS
+=========
+
+**RUN(0)**
+
+  Returns the run (coldstart) address of the interpreter. **? USR(RUN(0))**
+  restarts Integer BASIC. The *0* is a 'dummy' argument (ignored, like **FRE(0)**\).
+
+OPERATORS
+=========
+
+**!**
+
+  Binary OR. Infix operator.
+
+**&**
+
+  Binary AND. Infix operator.
+
+**%**
+
+  Binary exclusive OR (XOR). Infix operator.
+
+**<<**
+
+  Left shift, like C. Infix operator. Result is the expression on the left,
+  shifted left by the number of bits on the right. Examples: **1<<4**
+  is 16, **255<<1** is 510.
+
+  Bits shifted off the left end of the number are lost. Zeroes are
+  shifted in, for the low-order bit(s). Shifting anything left 16 times
+  results in zero. Since bit 15 is the sign bit, shifting a 1 into bit
+  15 will result in a negative number.
+
+**>>**
+
+  Right shift, like C. Infix operator. Result is the expression
+  on the left, shifted to the right, by the number of bits on the
+  right. Examples: **16>>4** is 1, **255>>1** is 127.
+
+  Bits shifted off the right end of the number are lost. Zeroes are
+  shifted in, for the high-order bit(s). Shifting any negative number
+  to the right will result in a positive numbers, since a zero will be
+  shifted into the sigh bit.
+
+**^&**
+
+  Binary NAND. Like AND, but inverts the bits in the result. Infix operator.
+
+**^!**
+
+  Binary NOR. Infix operator.
+
+**^%**
+
+  Binary NXOR. Infix operator.
+
+**\\**
+
+  Modulus. Infix operator. Result of **X&Y** is the remainder of **X/Y**.
+
+  *NOTE* that this is **broken** in the cartridge version of Integer BASIC,
+  though it works correctly in the disk version. See **BUGS**, below.
+
+
+COMPATIBILITY
+=============
+
+Integer BASIC can't LOAD programs that were SAVEd by any other BASIC,
+and programs SAVEd by Integer BASIC can't be LOADed in any other
+BASIC. Use LIST and ENTER instead.
+
+Actually, the disk and cartridge versions of Integer BASIC can't even
+LOAD each others' programs. They use a different set of token numbers.
+This is because the cartridge version includes the **HITCLR** command,
+but the disk version does not.
+
+The **INT()** function exists in Integer BASIC, but it doesn't actually
+do anything. Seems to be provided for compatibility with other BASICs.
+
+Missing Commands
+----------------
+
+Integer BASIC has the full command set of the BASIC XL cartridge,
+minus these commands:
+
+**DEG** **RAD** **RGET** **RPUT**
+
+The cartridge version of Integer BASIC has the **HITCLR** command
+(from BASIC XE), but the disk version does not.
+
+The BASIC XL extension disk commands (**LOCAL**, **EXIT**,
+**PROCEDURE**, **CALL**, **SORTUP**, and **SORTDOWN**) don't exist in
+Integer BASIC. If there was ever an extensions disk for Integer BASIC,
+nobody's found it yet.
+
+The extra commands in BASIC XE (**EXTEND**, **INVERSE**, **NORMAL**,
+**BLOAD**, and **BSAVE**) are not supported.
+
+Missing Operators/Functions
+---------------------------
+
+**^**
+  There is no exponentiation operator; **2^2** is a syntax error.
+
+**ATN()**, **CLOG()**, **COS()**, **EXP()**, **LOG()**, **SIN()**
+  There are no trigonometric functions in Integer BASIC. These can
+  be used as array variable names, if you wish.
+
+**USING**
+  BASIC XL and XE's "PRINT USING" doesn't exist in Integer BASIC.
+
+BUGS
+====
+
+Modulo Arithmetic
+-----------------
+
+The **\\** (modulus) operator returns incorrect results in the
+cartridge version of Integer BASIC. This program demonstrates the
+bug::
+
+  10 For I=1 To 10
+  20   ? I,I\3,I-(I/3)*3
+  30 Next I
+
+When run with the disk version, the results are correct::
+
+  1         1         1
+  2         2         2
+  3         0         0
+  4         1         1
+  5         2         2
+  6         0         0
+  7         1         1
+  8         2         2
+  9         0         0
+  10        1         1
+
+The same program run with the cartridge version gives::
+
+  1         254       1
+  2         255       2
+  3         0         0
+  4         1         1
+  5         2         2
+  6         253       0
+  7         254       1
+  8         255       2
+  9         0         0
+  10        1         1
+
+This is obviously wrong.
+
+If you're writing a real program in Integer BASIC, I recommend
+avoiding the **\\** operator entirely. Write something like **X-X/Y\*Y**
+instead.