Update README.md

- Fixed Bressenham algorithm on STDIO disk
- updated internal documentation
- added signed math routines
- added if/then macros to REQUIRED

.gitattributes

@@ -0,0 +1,5 @@
+# Example of a `.gitattributes` file which reclassifies `.rb` files as Java:
+T.* linguist-language=Assembly
+
+# Replace any whitespace in the language name with hyphens:
+#*.glyphs linguist-language=OpenStep-Property-List

README.md

@@ -1,11 +1,76 @@
 # AppleIIAsmLib
 
-A general purpose ASM libriary for the Apple II. Assembled in Merlin 8 Pro.
+A general purpose ASM libriary for the Apple II. Assembled in Merlin 8 Pro. While this source is currently in constant flux, save for "stable" releases, [you may find the project's current technical documentation, v0.6.1 here](https://github.com/nathanriggs/AppleIIAsm-Collection/tree/master/documentation/AppleIIAsm%20Library%20Collection%20Technical%20Manual/0.6.1).
+
+Since this is in flux, you may also find [the previous documentation,v0.5.0, here](https://github.com/nathanriggs/AppleIIAsm-Collection/blob/master/documentation/AppleIIAsm%20Library%20Collection%20Technical%20Manual/0.5.0/AppleIIAsm%20Manual%20v0.5.0.pdf). Note that this documentation is in .pdf format.
 
 # Updates
 
-__27-sep-2019__
+__02-aug-2022__
+
+I am currently in the process of redesigning how the entire library works, so updates on this won't be piecemeal again until that is finished; if not, the library as a whole would not work together until the updates are finished. A lot of the documentation is changing, and I'm additionally rewriting and optimizing a lot of code. Of particular note is that the next version of the library will not force you to use the RETURN memory location for passing back data from subroutines, and switching every case of passing addresses via the registers to hold high bytes in .A instead of .X (to keep in line with standard practice of the day).
+
+I don't have a 100% clear finish date, but the updates are substantial so don't expect anything within a couple of months. In the meantime, if you would like to contribute, please fork this instead of contributing here until the update is done.
+
+__15-jun-2022__
+
+Wow! It's been a year since any updates. Life happened. But I am currently working on v0.7.0 of the library. This will be incompatible with all past versions, but if you only used macros, and didn't call the subroutines yourself, the changes should be minimal. You should expect the first round of changes to update by the end of the month, which will mostly consist of rewritten required routines. Then, we'll resume the running TODO lists.
+
+__05-jun-2021__
+
+_TODO FOR NEXT REVISION (v0.6.1)_
+
+- <s>add page flipping to stdio, which requires adding to each subroutine</s>
+- fix 8-bit bresenham in <s>stdio and</s> lores
+- <s>reorganize mac files on stdio</s>
+- <s>delete pct,gcf,lcm in math collection</s>
+- <s>add modulus subroutines/macros to math</s>
+- add/fix memory catalog subroutine/macro in DOS
+- change dos fmfil, etc. to be subroutines to decrease bytes
+- fix 16bit bresenham in hires
+- add bresenham circle routine to hires
+- add rect, frect routines to hires
+- <s>add signed macros to math collection</s>
+- <s>add floating point examples to math collection, if room exists</s>
+- revise all documentation to reflect changes (also previous changes)
+
+__05-JUN-2021__
+
+- Updated all required collection macros and subroutines on every disk
+- Revised all subroutines and macros to fit with new zero page names
+
+__03-JUN-2021__
+
+- Updated all disks as part of a small reorganization of the REQUIRED library collection
+- Added High Resolution Graphics Disk
+- Added Apple II Internal Speaker Disk
+- Rewrote all documentation in markdown
+
+__19-JAN-2020__
+
+- **Really** Finished all goals previously made on 17-DEC-2019, and then some
+- Began reworking Disk 2: STDIO to conform to new software architecture and documentation
+- next version will be 0.6.1, but no package will be created due to incompatibilities between libraries. From this point onward, releases will only be made if the entire collection is inter-compatible. The second digit will increase, and the third digit reset, in order to reflect compatible versus incomplatible current versions at this point. Later down the road, this version system will simply reflect major versus minor changes.
+- updated base README.md to point toward documentation
+
+__17-DEC-2019__
+
+- Currently working on version 0.6.0, which includes:
+  - an updated architecture
+  - deliberate use of markdown for documentation
+    - with the eventual goal of translating it to Madoko, a markdown variant that allows for more visual control on a printend page
+  - Still transforming entire disk system to adhere to a singular software architecture. 
+  - Added Alias macros for 8080 and z80 instruction sets.
+  - Major changes to Disk 1, including merger of REQUIRED and COMMON libraries
+
+__27-SEP-2019__
 
 - As of version 0.5.0, updates will occur on a disk-by-disk basis (as well as appropriate changes to the documentation). 
 - version 0.5.0 pretty much breaks any prior work that used the library. While future updates won't be so extreme, now that a stable system is in place, this is to be expected in any update prior to an official version 1.0.
 - The main documentation has been moved to a .docx and pdf file, rather than here, due to the length of the document. In the future, this file will be changed to a more open format, as well as converted into a hard-copy friendly design.
+
+## Documentation
+
+- You can find documentation to the current version being revised, 0.6.0, [in the documentation section](https://github.com/nathanriggs/AppleIIAsmLib/blob/master/documentation/0.6.0/0_3_Table_of_Contents_GH.md) 
+- You can find documentation for the current stable version, 0.5.0, [also in the appropriate documentation section](https://github.com/nathanriggs/AppleIIAsmLib/blob/master/documentation/0.5.0/) 
+

bin/README.md

@@ -0,0 +1,3 @@
+You will find the current disks being worked on here. Commits to these files, unfortunately, may spam the documentation.
+
+Note that the core part of the collection is numbered, while there rest has yet to be decided on or incorporated.

documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/0.0 Title_to_TOC.md

@@ -0,0 +1,97 @@
+# AppleIIAsm Technical Manual v0.6.0
+
+---
+
+Written and edited by Nathan Riggs (so far), 2021.
+
+---
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+---
+
+### License
+
+Copyright 2020 Nathan Riggs
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
+
+(http://www.apache.org/licenses/LICENSE-2.0)
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and
+limitations under the License.
+
+---
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+---
+
+## Table of Contents
+
+1. [License](#license)
+2. [Preface](1.0%20Preface.md)
+3. [Introduction](2.0%20Introduction.md)
+4. [Package Overiew](3.0%20Package_Overview.md)
+5. [Software Architecture](4.0%20Software_Architecture.md)
+6. [Macro/Subroutine Quick References](5.0%20Quick_Reference_TOC.md)
+7. - [Quick Reference Introduction](5.0%20Quick_Reference_TOC.md)
+   - [Disk 1 -- REQUIRED Macros](6.0%20Quick_Reference_D1_MAC.REQUIRED.md)
+   - [Disk 2 -- STDIO Macros](7.0%20Quick_Reference_D2_MAC.STDIO.md)
+   - [Disk 3 -- ARRAYS Macros](8.0%20Quick_Reference_D3_MAC.ARRAYS.md)
+   - [Disk 4 -- MATH Macros](9.0%20quick_reference_d4_mac.math.md)
+   - [Disk 5 -- STRING Macros](10.0%20quick_reference_d5_mac.strings.md)
+   - [Disk 6 -- DOS Macros](11.0%20quick_reference_d6_mac.dos.md)
+   - [Disk 7 -- CONVERT Macros](12.0%20quick_reference_d7_mac.convert.md)
+   - [Disk 8 -- LORES Macros](13.0%20quick_reference_d8_mac.lores.md)
+   - [Disk 9 -- HIRES Macros](14.0%20quick_reference_d9_mac.hires.md)
+   - [Disk 10 -- SPEAKER Macros](15.0%20quick_reference_d10_mac.speaker.md)
+7. Detailed References and Source Code Listings
+   - [Disk 1: Required Library and Aliases](30.0%20Detailed_Reference_D1_REQUIRED.md)
+   - [Disk 2: STDIO Macros and Subroutines](31.0%20Detailed_Reference_D2_STDIO.md)
+   - [Disk 3: Array Macros and Subroutines](32.0%20Detailed_Reference_D3_Arrays.md)
+   - [Disk 4: Basic Math Macros and Subroutines](33.0%20Detailed_Reference_D4_MATH.md)
+   - [Disk 5: String Manipulation Macros and Subroutines](34.0%20Detailed_Reference_D5_STRINGS.md)
+   - [Disk 6: Apple DOS Macros and Subroutines](35.0%20Detailed_Reference_D6_DOS.md)
+   - [Disk 7: Data Type Conversion Macros and Subroutines](36.0%20Detailed_Reference_D7_CONVERT.md)
+   - [Disk 8: Low Resolution Macros and Subroutines](37.0%20Detailed_Reference_D8_LORES.md)
+   - [Disk 9: High Resolution Macros and Subroutines](38.0%20Detailed_Reference_D9_HIRES.md)
+   - [Disk 10: Internal Macros and Subroutines](39.0%20Detailed_Reference_D10_SPEAKER.md)
+8. Appendices
+   - Supplemental Texts
+   - Further Reference
+   - Optimizations
+     - Typical Assembly Optimizations
+     - Architecture Clobbering Optimizations

documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/1.0 Preface.md

@@ -0,0 +1,32 @@
+## Preface   
+
+This is the first complete reference manual for the _AppleIIAsm_ macro and subroutine library. Currently, this library is in the alpha stages of development: not all disks (collections) are complete, there may be some bugs here and there, and major workflow decisions might still be in flux. However, this version, 0.7.0, represents a major step forward in functionality, optimization and standardization, and at least for what is complete--the first eleven disks, the technical manual, AppleChop introduction  as well as some demos--the collection can be reasonably considered to be stable. That does not, of course, mean that there are any guarantees.
+
+I started this project as research into how the Apple II works as a platform for another book I am writing, and eventually became interested in the cohesive technical documentation (or sometimes lack thereof) that was available to beginning coders in the heyday of the Apple II as well as those looking to learn Apple II (6502) Assembly today. Having no prior experience with Assembly language, I began coding these libraries as part of my own learning process while trying to write subroutines that provided much of the functionality afforded by Applesoft BASIC. Eventually, this became a beast of its own, and what you’re reading here is (part) of the result.
+
+As the library collections grow and morph, so will this document. If nothing else, I hope that the collection and its accompanying documentation helps hobbyists, researchers, and otherwise self-hating hopeless nerds learn and accomplish what they want or need---at least as much as it has helped, and harmed, me.
+
+
+
+Nathan Riggs
+
+ 
+
+---
+
+
+
+[Return to Table of Contents](0.0%20Title_to_TOC)
+[Next: Introduction](2.0%20Introduction.md)
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 
+
+ 

documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/10.0 Quick_Reference_D5_MAC.STRINGS.md

@@ -0,0 +1,40 @@
+# Disk 5: Strings and Substrings
+
+
+
+The Strings Collection of the AppleIIAsm Library is dedicated to macros used for handling strings and substrings. In particular, this refers to the default type of string: those with a preceding length-byte. If these macros need to be used on another type of string, such as a null-terminated string, then the `STRPC` macro should be used on the string first to convert it to a preceding length-byte type.
+
+The strings collection can be divided further into two categories: those that deal with whole strings and those that deal with substrings exclusively. This is currently reflected in the fact that the macros are held in separate files and use different demos.
+
+
+
+---
+
+
+
+### MAC.STRINGS.ASM
+
+| MACRO   | DEPENDENCY         | PARAMETERS                                | ACTION               | DESTROYS | CYCLES | BYTES |
+| ------- | ------------------ | ----------------------------------------- | -------------------- | -------- | ------ | ----- |
+| `SCMP`  | `SUB.STRCOMP.ASM`  | ]1 = First string<br />]2 = Second string | Compare strings      | NZCV     | 110+   | 67    |
+| `SCAT`  | `SUB.STRCAT.ASM`   | ]1 = First string<br />]2 = Second string | Concatenate strings  | NZCV     | 170+   | 113   |
+| `STRIM` | `SUB.STRIM.ASM`    | ]1 = String<br />]2 = Token               | Trim string          | NZCV     | 123+   | 80    |
+| `STRUP` | `SUB.STRUPPER.ASM` | ]1 = String                               | Convert to uppercase | NZCV     | 114+   | 64    |
+| `SLO`   | `SUB.STRLOWER.ASM` | ]1 = String                               | Convert to lowercase | NZCV     | 113+   | 64    |
+| `SREV`  | `SUB.STRREV.ASM`   | ]1 = String                               | Reverse a string     | NZCV     | 70+    | 41    |
+| `SCAP`  | `SUB.STRCAP.ASM`   | ]1 = String                               | Capitalize sentences | NZCV     | 192+   | 117   |
+
+
+
+
+
+### MAC.SUBSTRINGS.ASM
+
+| MACRO  | DEPENDENCY           | PARAMETERS                                             | ACTION                      | DESTROYS | CYCLES | BYTES |
+| ------ | -------------------- | ------------------------------------------------------ | --------------------------- | -------- | ------ | ----- |
+| `SPOS` | `SUB.SUBPOS.ASM`     | ]1 = String<br />]2 = Substring                        | Get substring position      | NZCV     | 205+   | 136   |
+| `SCPY` | `SUB.SUBCOPY.ASM`    | ]1 = Source string<br />]2 = Index<br />]3 = Length    | Copy substring              | NZCV     | 95+    | 71    |
+| `SDEL` | `SUB.SUBDEL.ASM`     | ]1 = Source string<br />]2 = Index<br />]3 = Length    | Delete substring            | NZCV     | 135+   | 79    |
+| `SINS` | `SUB.SUBINS.ASM`     | ]1 = Source string<br />]2 = Substring<br />]3 = Index | Insert substring            | NZCV     | 177+   | 111   |
+| `STOK` | `SUB.SUBTOK.ASM`     | ]1 = String<br />]2 = Token<br />]3 = Token number     | Find tokenized substring    | NZCV     | 182+   | 118   |
+| `SCNT` | `SUB.SUBCHARCNT.ASM` | ]1 = String<br />]2 = Character                        | Count character occurrences | NZCV     | 88+    | 57    |

documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/11.0 Quick_Reference_D6_MAC.DOS.md

@@ -0,0 +1,59 @@
+# Disk 6: Apple DOS
+
+
+
+The DOS Collection of the AppleIIAsm Library consists of macros and subroutines dedicated to interfacing with Apple DOS, providing an abstraction layer for the programmer on top of the lower level routines used by DOS such as the file manager and RWTS. All of the basic functions of DOS are available for use, save for specific macros dedicated solely to reading and writing text files. The reasoning for this is that 1) unless you are interfacing with a BASIC program or another system, text files are largely unnecessary (binary files work better), and 2) text file manipulation often requires creating a system of your own since there is no simple default way to read the end of a file. The macros and routines that do exist can be used to create your own custom system for reading and writing text files.
+
+Of all the collections in the library, the DOS collection is perhaps the most convoluted and has the largest overhead due to the more complex nature of its functionality. There are many subroutines and macros that are meant to be used only by the collection itself, though the enterprising programmer may of course utilize them. These are described in the detailed listings.
+
+
+
+---
+
+
+
+### MAC.DOSREQ.ASM
+
+| MACRO   | DEPENDENCY   | PARAMETERS                                                   | ACTION                                                       | DESTROYS | CYCLES | BYTES |
+| ------- | ------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- | ------ | ----- |
+| `FMFIL` | HEAD.DOS.ASM | ]1 = Command <br/>]2 = Slot<br />]3 = Drive<br />]4 = Volume<br />]5 = Record | Fill most common parameters of the File Manager.             | NZCV     | 603    | 303   |
+| `FMNAM` | HEAD.DOS.ASM | ]1 = String Address                                          | Copy a string to the file name parameter in the File Parameter List. | NZCV     | 117    | 70    |
+| `FRWB`  | HEAD.DOS.ASM | ]1 = Read/Write flag <br />]2 = Command<br />]3 = Slot<br />]4 = Drive<br />]5 = Volume<br />]6 = Record<br />]7 = Byte Offset<br />]8 = Write Byte | Read or write a byte from or to a file. Use `FRWRTB` and `FRDB` instead of this, both of which call this macro. | NZCV     | 779    | 404   |
+| `FWRTB` | HEAD.DOS.ASM | ]1 = Slot<br />]2 = Drive<br />]3 = Volume<br />]4 = Record<br />]5 = Byte Offset<br />]6 = Write Byte | Write a byte to a file.                                      | NZCV     | 665    | 337   |
+| `FRDB`  | HEAD.DOS.ASM | ]1 = Slot<br />]2 = Drive<br />]3 = Volume<br />]4 = Record<br />]5 = Byte Offset<br />]6 = Write Byte (always 0) | Read a byte from a file.                                     | NZCV     | 700    | 357   |
+| `FRWR`  | HEAD.DOS.ASM | ]1 = Read/Write flag<br />]2 = Command<br />]3 = Slot<br />]4 = Drive<br />]5 = Volume<br />]6 = Record<br />]7 = Byte Offset<br />]8 = Range Address<br />]TEMP = Range Length | Read or write a range of bytes in a file. Use `FRDR` or `FWRTR` instead of this macro directly. | NZCV     | 846    | 451   |
+| `FRDR`  | HEAD.DOS.ASM | ]1 = Slot<br />]2 = Drive<br />]3 = Volume<br />]4 = Record<br />]5 = Byte Offset<br />]6 = Range Address<br />]7 = Range Length | Read a range of bytes from a file.                           | NZCV     | 697    | 361   |
+| `FWRTR` | HEAD.DOS.ASM | ]1 = Slot<br />]2 = Drive<br />]3 = Volume<br />]4 = Record<br />]5 = Byte Offset<br />]6 = Range Address<br />]7 = Range Length | Write a range of bytes to a file.                            | NZCV     | 940    | 509   |
+| `sRWTS` | HEAD.DOS.ASM | ]1 = Slot<br />]2 = Drive<br />]3 = Volume <br />]4 = Track<br />]5 = Sector<br />]6 = Buffer<br />]7 = Command | Set the most common RWTS parameters.                         | NZCV     | 228    | 141   |
+| `GRWTS` | HEAD.DOS.ASM | none                                                         | Execute the RWTS routine.                                    | NZCV     | 19     | 11    |
+
+
+
+
+
+### MAC.DOSFM.ASM
+
+| MACRO   | DEPENDENCY     | PARAMETERS                                                   | ACTION            | DESTROYS | CYCLES | BYTES |
+| ------- | -------------- | ------------------------------------------------------------ | ----------------- | -------- | ------ | ----- |
+| `FCAT`  | HEAD.DOS.ASM   | ]1 = Slot <br />]2 = Drive                                   | Catalog.          | NZCV     | 657    | 348   |
+| `FULCK` | HEAD.DOS.ASM   | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive         | File unlock.      | NZCV     | 629    | 353   |
+| `FLOCK` | HEAD.DOS.ASM   | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive         | File lock.        | NZCV     | 172    | 116   |
+| `FDEL`  | HEAD.DOS.ASM   | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive         | File delete.      | NZCV     | 791    | 412   |
+| `FVFY`  | HEAD.DOS.ASM   | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive         | File verify.      | NZCV     | 791    | 411   |
+| `FCLOS` | HEAD.DOS.ASM   | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive         | File close.       | NZCV     | 797    | 415   |
+| `FRENM` | HEAD.DOS.ASM   | ]1 = Filename address<br />]2 = New filename address<br />]3 = Slot<br />]4 = Drive | File rename.      | NZCV     | 927    | 578   |
+| `FOPEN` | HEAD.DOS.ASM   | ]1 = Filename address<br />]2 = Slot<br />]3 = Drive<br />]4 = Volume<br />]5 = Record | File open.        | NZCV     | 828    | 433   |
+| `BLOAD` | SUB.FBLOAD.ASM | ]1 = Filename address<br />]2 = Load address<br />]3 = Slot<br />]4 = Drive<br />]5 = Volume | Load binary file. | NZCV     | 3768   | 2735  |
+| `BSAVE` | SUB.FBSAVE.ASM | ]1 = Filename address<br />]2 = Load address<br />]3 = Range length<br />]4 = Slot<br />]5 = Drive<br />]6 = Volume | Save binary file. | NZCV     | 5300   | 2758  |
+
+
+
+### MAC.DOSMORE.ASM
+
+| MACRO   | DEPENDENCY | PARAMETERS | ACTION                                       | DESTROYS | CYCLES | BYTES |
+| ------- | ---------- | ---------- | -------------------------------------------- | -------- | ------ | ----- |
+| `DVER`  | none       | none       | Get DOS version.                             | NZCV     | 28     | 18    |
+| `DOSIN` | none       | none       | Check if DOS is loaded.                      | NZCV     | 17     | 12    |
+| `ABAS`  | none       | none       | Check if Applesoft is loaded.                | NZCV     | 40     | 29    |
+| `IBEX`  | none       | none       | Check if Integer Basic program is running.   | NZCV     | 17     | 12    |
+| `ABEX`  | none       | none       | Check if Applesoft Basic program is running. | NZCV     | 26     | 18    |

documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/12.0 Quick_Reference_D7_MAC.CONVERT.md

@@ -0,0 +1,36 @@
+# Disk #7: Conversion
+
+
+
+The Conversion Collection contains macros and subroutines for converting between different data types. This currently includes macros for converting a:
+
+- numeric value to an integer string
+- integer string to a numeric value
+- numeric value to a hexadecimal string
+- hexadecimal string to a numeric value
+- numeric value to a binary string
+- binary string to a numeric value
+
+In future revisions, other conversions will include:
+
+- string type conversions (preceding length byte, null-terminated, etc.)
+- string to array
+- array to string
+
+Note that some of these subroutines are redundant due to the fact that some conversions are already available in the ROM. However, for the sake of understanding how these conversions work, they are provided here if for nothing more than illustration.
+
+
+
+---
+
+
+
+| MACRO   | DEPENDENCY         | PARAMETERS                       | ACTION                                      | DESTROYS | CYCLES | BYTES |
+| ------- | ------------------ | -------------------------------- | ------------------------------------------- | -------- | ------ | ----- |
+| `I2STR` | SUB.HEX2INTASC.ASM | ]1 = Value to convert or address | Convert numeric value to integer string     | NZCV     | 290    | 172   |
+| `STR2I` | SUB.INTASC2HEX.ASM | ]1 = String address              | Convert integer string to numeric value     | NZCV     | 415    | 196   |
+| `H2STR` | SUB.HEX2HEXASC.ASM | ]1 = Value to convert or address | Convert numeric value to hexadecimal string | NZCV     | 97     | 59    |
+| `STR2H` | SUB.HEXASC2HEX.ASM | ]1 = String address              | Convert hexadecimal string to numeric value | NZCV     | 116    | 71    |
+| `B2STR` | SUB.HEX2BINASC.ASM | ]1 = Value to convert or address | Convert numeric value to binary string      | NZCV     | 262    | 167   |
+| `STR2B` | SUB.BINASC2HEX.ASM | ]1 = String address              | Convert binary string to numeric value      | NZCV     | 501    | 331   |
+

documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/13.0 Quick_Reference_D8_MAC.LORES.md

@@ -0,0 +1,38 @@
+# Disk #8: Low Resolution Graphics
+
+
+
+The LoRes collection contains macros and subroutines for creating and displaying low resolution graphics on the Apple II. This includes macros to:
+
+- plot low resolution pixels
+- set the working low resolution page and the viewing low resolution page
+- set the low resolution mode: full screen or mixed
+- plot horizontal, vertical and diagonal lines
+- plot a low resolution circle
+- get a low resolution pixel's color value
+- print a low resolution character to the screen
+
+
+
+---
+
+
+
+
+
+| MACRO     | DEPENDENCY | PARAMETERS                                                   | ACTION                                            | DESTROYS | CYCLES | BYTES |
+| --------- | ---------- | ------------------------------------------------------------ | ------------------------------------------------- | -------- | ------ | ----- |
+| `LWORKPG` | none       | ]1 = page number                                             | set the working page                              | NZCV     | 27+    | 20    |
+| `LVIEWPG` | none       | ]page number                                                 | set the viewing page                              | NZCV     | 21+    | 16    |
+| `LRGF`    | none       | none                                                         | set full page mode                                | NZCV     | 12+    | 9     |
+| `LRGP`    | none       | none                                                         | set mixed page mode (partial)                     | NZCV     | 12+    | 9     |
+| `LFCLR`   | `LRGFCLR`  | ]1 = color code                                              | fill screen with specified color (full screen)    | NZCV     | 139+   | 92    |
+| `LPCLR`   | `LRGPCLR`  | ]1 = color code                                              | fill screen with specified color (partial)        | NZCV     | 125+   | 86    |
+| `LPLOT`   | `LRPLOT`   | ]1 = X coordinate<br />]2 = Y coordinate<br />]3 = color code | plot a low resolution pixel to the working page   | NZCV     | 148+   | 107   |
+| `LLINE`   | `LRBLINE`  | ]1 = X origin<br />]2 = X destination<br />]3 = Y-origin<br />]4 = Y destination<br />]5 = color | plot an arbitrary line                            | NZCV     | 441+   | 297   |
+| `LCIRC`   | `LRCIRCLE` | ]1 = Center x position<br />]2 = Center y position<br />]3 = Circle radius<br />]4 = Color | plot a circle to low resolution page              | NZCV     | 2437+  | 520   |
+| `LVLIN`   | `LRVLINE`  | ]1 = Y origin<br />]2 = Y destination<br />]3 = X coordinate<br />]4 = color | plot a vertical line to the low resolution page   | NZCV     | 250+   | 164   |
+| `LHLIN`   | `LRHLINE`  | ]1 = X origin<br />]2 = X destination<br />]3 = Y coordinate<br />]4 = color | plot a horizontal line to low resolution page     | NZCV     | 246+   | 161   |
+| `LRGET`   | `LRGETPIX` | ]1 = X coordinate<br />]2 = Y coordinate                     | get color value of low resolution pixel           | NZCV     | 110+   | 71    |
+| `LCHAR`   | `LRCHAR`   | ]1 = X coordinate<br />]2 = Y coordinate<br />]3 = address of 3-byte character<br />]4 = color | plot a large character to the low resolution page | NZCV     | 441+   | 439   |
+

documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/14.0 Quick_Reference_D9_MAC.HIRES.md

@@ -0,0 +1,35 @@
+# Disk #9: High Resolution Graphics
+
+
+
+The HiRes collection contains macros and subroutines for plotting and displaying high resolution graphics. This includes macros to:
+
+- Flip between HiRes pages, both as working pages and viewing pages
+- Plot a single HiRes pixel
+- Fill the HiRes page with a given color
+- Plot horizontal, vertical and diagonal lines
+- Plot text characters to the HiRes screen, individually or as a string
+- Plot entire bytes to the HiRes screen, easily allowing for the plotting of tiles
+
+
+
+---
+
+
+
+
+
+| MACRO     | DEPENDENCY | PARAMETERS                                                   | ACTION                                             | DESTROYS | CYCLES | BYTES |
+| --------- | ---------- | ------------------------------------------------------------ | -------------------------------------------------- | -------- | ------ | ----- |
+| `HBSET`   | none       | ]1 = X position<br />]2 = Y position<br />]3 = color         | Set a byte on the HiRes page                       | NZCV     | 54     | 37    |
+| `HBGET`   | none       | ]1 = X position<br />]2 = Y position                         | Get a byte value from the HiRes page               | NZCV     | 49     | 30    |
+| `HVIEWPG` | none       | ]1 = Page number                                             | Set the viewing HiRes page                         | NZCV     | 19     | 14    |
+| `HWORKPG` | none       | ]1 = Page number                                             | Set the working HiRes page                         | NZCV     | 27     | 20    |
+| `HPLOT`   | `HRPLOT`   | ]1 = X position<br />]2 = Y position<br />]3 = Color         | Plot a single pixel to the HiRes page              | NZCV     | 348+   | 14    |
+| `HCLR`    | `HCLEAR`   | ]1 = Color                                                   | Fill the HiRes page with the specified color       | NZCV     | 96+    | 5     |
+| `HLIN`    | `HRHLINE`  | ]1 = X origin<br />]2 = X destination<br />]3 = Y position<br />]4 = Color | Plot a horizontal line to the HiRes page           | NZCV     | 494+   | 34    |
+| `VLIN`    | `HRVLINE`  | ]1 = Y origin<br />]2 = Y destination<br />]3 = X position<br />]4 = Color | Plot a vertical line to the HiRes page             | NZCV     | 449+   | 30    |
+| `LINE`    | `HRBLINE`  | ]1 = X origin<br />]2 = Y origin<br />]3 = X Destination<br />]4 = Y destination<br />]5 = Color | Plot a diagonal line to the HiRes page             | NZCV     | 825+   | 42    |
+| `HCHAR`   |            | ]1 = X position<br />]2 = Y position<br />]3 = byte to print | Plot a text character to the HiRes page            | NZCV     | 432+   | 296   |
+| `HSTR`    |            | ]1 = X position<br />]2 = Y position<br />]3 = String address<br />]4 = Offset value | Plot a string of text characters to the HiRes page | NZCV     | 767+   | 37    |
+

documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/15.0 Quick_Reference_D10_MAC.SPEAKER.md

@@ -0,0 +1,22 @@
+# Disk #10: The Internal Speaker
+
+
+
+The Speaker collection contains macros and subroutines for outputting sound on the Apple II internal speaker. Currently, this is limited to square wave notes and song playing, as well as as few standard sound effects. Ideally, future updates will include a subroutine using duty-cycling that is capable of producing elemental "instruments" for a variety of timbres. 
+
+
+
+| MACRO   | DEPENDENCY           | PARAMETERS | ACTION                                  | DESTROYS | CYCLES | BYTES |
+| ------- | -------------------- | ---------- | --------------------------------------- | -------- | ------ | ----- |
+| `STMPO` | `SETTEMPO`           |            | Set the tempo                           | NZCV     | 240    | 6     |
+| `PNOTE` | `PLAYNOTE` `REDTONE` |            | Play note in song                       | NZCV     | 172+   | 3     |
+| `SSONG` | none                 |            | Set song sequence                       | NZCV     | 48     | 36    |
+| `NEXTN` | none                 |            | Advance to next note in song            | NZCV     | 24     | 17    |
+| `PREVN` | none                 |            | Move to previous note in song           | NZCV     | 28     | 17    |
+| `RSTRT` | none                 |            | Restart song index                      | NZCV     | 16     | 12    |
+| `FFWRD` | none                 |            | Fast forward a number of notes in song  | NZCV     | 27     | 19    |
+| `REWND` | none                 |            | Rewind a number of notes in song        | NZCV     | 35     | 25    |
+| `PTONE` | `REDTONE`            |            | Play a non-song tone                    | NZCV     | 220+   | 18    |
+| `PFREQ` | `REDTONE`            |            | Play a non-song frequency               | NZCV     | 214+   | 15    |
+| `PSONG` | `PNOTE` `NEXTN`      |            | Play an entire song sequence            | NZCV     | 226+   | 42    |
+| `SFX`   | `SOUNDFX`            |            | Play a sound effect from the collection | NZCV     | 1962   | 18    |

documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/2.0 Introduction.md

@@ -0,0 +1,89 @@
+ 
+
+## Introduction
+
+The AppleIIAsm Library is an array of subroutines and macros for the Apple II line of computers, aimed at providing a stable set of assembly routines for most common tasks. Additionally, this library is meant to ease the transition between programming in Applesoft BASIC and 6502 Assembly by not only providing the basic data structures and functions found in higher-level languages but also by providing a set a macros--currently dubbed AppleChop--that simulates the design and workflow of BASIC. A companion booklet to this library, *From Applesoft to AppleChop to Assembly,* provides a framework for making that transition.
+
+These subroutines and macros are written for the Merlin 8 Pro assembler, which should run on any Apple II with 64k of memory (programs assembled with Merlin 8 Pro will run on machines with less than 64k, however). Since we are using 6502 Assembly here, it should not be too difficult to port the subroutines to other assemblers and even other systems like the Commodore 64, Nintendo Entertainment System, BBC Micro, and more. For a guide on using the Merlin Pro 8 Assembler, see the other companion booklet, *The New Merlin Pro 8 Quick Start User Guide*.
+
+It should be noted that the core libraries in this collection---those on disks one to eleven---should be compatible with every iteration of the Apple II family, from the original Apple II in 1977 to the Apple IIGS in 1986. Disks beyond that core collection are considered bonus disks, and are dedicated to either creating libraries for specialized hardware (such as much of the IIGS, or the Mockingboard) or are there to serve as more complicated and integrated demos for the user to peruse. 
+
+**Who is this manual for?**
+
+The primary audience for this manual is someone who is already familiar with 6502 Assembly or is at least trying to learn it; that is, novices. Like all manuals, this is primarily a reference: beyond this introduction and early sections of Part I, this manual is not meant to be read straight through. Feel free to flip back and forth as you wish!
+
+**Who is this manual NOT for?**
+
+This manual is definitely not for someone completely unexposed to Assembly language, but nor is it really aimed at 6502 experts. The collection itself can be used by beginner and expert alike, but whereas this manual would likely confuse the absolute beginner, an expert interested in optimizing their work (and these subroutines) will not find much help here. For those well-versed in 6502 Assembly, this collection might better serve as a prototyping system that then gets torn apart and optimized; for those barely versed in 6502 Assembly, this library, and especially the AppleChop collection, will best serve to ease the transition between a standard knowledge of BASIC and the quirks of Assembly language (commenting is excessive in the libraries for this very reason). Both extremes may find this collection useful, but for wildly different reasons.
+
+As someone who spends a *lot* of time thinking about, writing about, and teaching different facets of technical writing (in its broadest sense), I can confirm the following: there are thousands of books written about the 6502 architecture and Assembly programming. I can also confirm that these books---as well as most websites---tend to approach the subject from a "writerly" position rather than a reader-centered one; that is, written for engineers and computer scientists who have already spent a lot of time and money understanding the theory, learning the jargon, and training themselves to be able to do things by muscle memory. That's great for established engineers, mathematicians, computer scientists and the like, as well as those who can afford to dedicate years of their lives (and again, gobs of $$$) to obtain a degree that qualifies them as entry level in the field. It is not so great, however, for beginners, hobbyists, or those trying to study it from a non-engineering theoretical perspective. That is, at least, part of the gap I am hoping to fill; after all, this book is part of my research for writing another book aimed at a non-technical audience.
+
+That said, I myself would have failed quite readily without at least a few key texts and websites, and it would be remiss to not list them here. And if you're committed to learning this, know that there is no good replacement to sitting down, typing out a listing from a book, assembling it and then trying to figure out what the hell you just did---or what you did wrong! There is no doing without learning, and there is no learning without doing. At risk of pontificating, I believe many of us have forgotten this mantra, and the internet has not helped matters. 
+
+**Why Merlin Pro 8? Why not something...modern?**
+
+Understanding how coding for a specific platform and a specific era works is not merely a matter of knowledge, but a matter of practice. Much of the way development happens, in computer software or not, is predicated on the apparatus in place that allows for it. Changing that apparatus, whether it be adding modern components like multiple open files, faster assembly, easier access and legibility and so on changes your understanding of how everything worked (and works). Especially with an ancient (and largely obsolete) language like 6502 assembly, few people are learning it to accomplish a practical task. Instead, we are approaching the topic more like an archaeologist or historical reenactor: going through the same motions to understand the topic cohesively. This is explained more thoroughly in the Preface.
+
+That said, there is nothing inherently wrong with using modern tools--it just does not fit the goals for writing this library. Brutal Deluxe software has rewritten a more modern version of Merlin 16, and the CC65 compiler/assembler makes contemporary 6502 development far more efficient and less frustrating overall. If Merlin 8 Pro feels too dated--and to many, it will feel hopelessly so--by all means use these modern software packages. Just be aware that some substantial effort may be involved in rewriting the code here for different assemblers. If you must, I would suggest using an Apple II emulator like _AppleWin_ with a high speed setting for compile time---though be careful if so, as it is easy to miss error interruptions.
+
+**Further Resources**
+
+While beginners are welcome to use this library, and it is partially aimed at those who are trying to learn 6502 Assembly on the Apple II, a cohesive and thorough guide to 6502 programming is beyond the scope of this manual. For a better understanding of the hardware, programming, and culture surrounding the Apple II, I would suggest consulting the following sources.
+
+__*6502 Programming Books*__
+
+- Roger Wagner, Chris Torrence. [*Assembly Lines: The Complete Book*](https://www.amazon.com/Assembly-Lines-Complete-Roger-Wagner/dp/1312089407/). May 10, 2017. <https://www.amazon.com/Assembly-Lines-Complete-Roger-Wagner/dp/1312089407/>
+- Lance A. Leventhal, Winthrop Saville. *6502 Assembly Language Subroutines*. 1982.
+- Don Lancaster. *Assembly Cookbook for the Apple II, IIe*. 1984, 2011.
+- Mark Andrews. _Apple Roots: Assembly Language Programming for the Apple IIe and IIc_. 1986.
+- CW Finley, Jr., Roy E. Meyers. *Assembly Language for the Applesoft Programmer*. 1984.
+- Randy Hyde. *Using 6502 Assembly Language*. 1981.
+- Glen Bredon. *Merlin Pro Instruction Manual*. 1984.
+- JS Anderson. *Microprocessor Technology*. 1994. (also covers z80 architecture)
+
+__*6502 Programming Websites*__
+
+- [CodeBase64](http://codebase64.org/doku.php). <http://codebase64.org/doku.php>
+- [6502.org](http://www.6502.org/). <http://www.6502.org/>
+- [Easy6502](http://skilldrick.github.io/easy6502/). <http://skilldrick.github.io/easy6502/>
+
+__*Apple II Books*__
+
+- Bill Martens, Brian Wiser, William F. Luebbert, Phil  Daley. [*What's Where in the Apple, Enhanced Edition: A Complete Guide to the Apple \]\[      Computer*.](https://www.amazon.com/gp/product/136517364X/) October 11, 2016. <https://www.amazon.com/gp/product/136517364X/>
+- David Flannigan. [*The New Apple II Users' Guide*](https://www.amazon.com/gp/product/0615639879/). June 6, 2012. https://www.amazon.com/gp/product/0615639879/
+- David L. Craddock. [*Break Out: How the Apple II Launched the PC Gaming Revolution*](https://www.amazon.com/gp/product/0764353225/). September 28, 2017. https://www.amazon.com/gp/product/0764353225/
+- Steven Weyhrich. [*Sophistication ;&amp; Simplicity: The Life and Times of the Apple II Computer*](https://www.amazon.com/gp/product/0986832278/). December 1, 2013. https://www.amazon.com/gp/product/0986832278/
+- Ken Williams, Bob Kernagham, Lisa Kernagham. [*Apple II Computer Graphics*](https://www.amazon.com/gp/product/B01FIXG7ZK/). November 3, 1983. <https://www.amazon.com/gp/product/B01FIXG7ZK/>
+- Lon Poole. [*Apple II Users' Guide*.](https://www.amazon.com/gp/product/0931988462/).     1981. <https://www.amazon.com/gp/product/0931988462/>
+- Jeffrey Stanton. *Apple Graphics and Arcade Game Design*. 1982.
+- Apple. *Apple Monitors Peeled*. 1981.
+- Apple. _Apple II/IIe/IIc/IIgs Technical Reference Manual._
+
+*__Apple II Websites__*
+
+- [Apple II Text Files](http://textfiles.com/apple/.windex.html). <http://textfiles.com/apple/.windex.html>
+- [Apple II Programming](http://apple2.org.za/gswv/a2zine/faqs/csa2pfaq.html). <http://apple2.org.za/gswv/a2zine/faqs/csa2pfaq.html>
+- [The Asimov Software Archive](https://ftp.apple.asimov.net/). <https://ftp.apple.asimov.net/>
+- [Apple II Online](https://apple2online.com/index.php). <https://apple2online.com/index.php>
+- [Juiced.GS: A Quarterly Apple II Journal](https://juiced.gs/). <https://juiced.gs/>
+
+_**Related GitHub Projects**_
+
+A number of folk are doing work on 6502 or the Apple II on GitHub. While I cannot possibly list each and every one (that's what the search function is for!), these are projects I have found particularly useful, informative, entertaining, or inspiring.
+
+- [Prince of Persia Apple II Source Code](https://github.com/fabiensanglard/Prince-of-Persia-Apple-II), by Jordan Mechner. <https://github.com/fabiensanglard/Prince-of-Persia-Apple-II>
+- [WeeGUI, a small  gui for the Apple II](https://github.com/blondie7575/WeeGUI). <https://github.com/blondie7575/WeeGUI>
+- [Two-lines or less Applesoft programs](https://github.com/thelbane/Apple-II-Programs) --- a lot can be accomplished! <https://github.com/thelbane/Apple-II-Programs>
+- [Doss33FSProgs](https://github.com/deater/dos33fsprogs), programs for manipulating the DOS 3.3 filesystem. <https://github.com/deater/dos33fsprogs>
+- [ADTPro](https://github.com/ADTPro/adtpro), a requirement for anyone working with real Apple II hardware today. <https://github.com/ADTPro/adtpro>
+- [CC65](https://github.com/cc65), a modern cross-compiling C compiler and assembler for 6502 systems. <https://github.com/cc65>
+- [PLASMA: The Proto-Language Assembler for All](https://github.com/dschmenk/PLASMA) --- this was originally written for the Apple II alone, but has recently expanded to other systems. <https://github.com/dschmenk/PLASMA>
+
+
+
+---
+
+
+
+[Return to Table of Contents](0.0%20Title_to_TOC)
+[Next: Package Overiew](3.0%20Package_Overview.md)

documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/3.0 Package_Overview.md

@@ -0,0 +1,50 @@
+## Package Overview
+
+The **AppleIIAsm** package library consists of 25 disks that contain thematically related subroutines, demos and utilities, as well as extra disks that hold minified versions of every subroutine for convenience. The contents of each disk and collection are covered in Part II: Detailed Descriptions and Listings. The disks are ordered as follows:
+
+- **Disk 0**	BOOT (for setting up own environment)
+
+### CORE COLLECTIONS
+
+ - **Disk 1**	REQUIRED (Required and Common Libraries)
+ - **Disk 2**	STDIO (Standard Input and Output Library)
+ - **Disk 3**	ARRAYS (Array Library) 
+ - **Disk 4**	MATH (Math Library) 
+ - **Disk 5**	STRINGS (String Library)
+ - **Disk 6**	DOSFILE (DOS 3.3 File Input and Output Library)
+ - **Disk 7**	CONVERT (Data Type Conversion Library)
+ - **Disk 8**	LORES (Low Resolution Graphics Library)
+ - **Disk 9**	SPEAKER (Mono Speaker Library)
+ - **Disk 10**	HIRES (High Resolution Graphics Library)
+ - **Disk 11**	DETECT (Hardware Detection Library)
+ - **Disk 12**	APPLECHOP (AppleChop High-Level Library)
+
+### DEMOS AND UTILITIES
+
+ - **Disk 13**	MINIDISKA (Minified Libraries Disk A)
+ - **Disk 14**	MINIDISKB (Minified Libraries Disk B)
+ - **Disk 15**	UTILS (Utilities Disk)
+ - **Disk 16**	DEMOSA (Demo Disk A)
+ - **Disk 17**	DEMOSB (Demo Disk B)
+
+### MACHINE-SPECIFIC LIBRARIES
+
+ - **Disk 18**	80COL (80-Column Text Library)
+ - **Disk 19**	MOCKINGBOARD (Mockingboard Sound Card Library)
+ - **Disk 20**	DBLLORES (Double Low Resolution Graphics Library)
+ - **Disk 21**	DBLHIRES (Double High Resolution Graphics Lib)
+ - **Disk 22**	 MISC (Miscellaneous subroutine library)
+ - **Disk 23**	IIGS GS/OS 6.04 Library (3.5" diskette)
+ - **Disk 24**	IIGSAUDIO (IIGS AUDIO library) (3.5" diskette)
+ - **Disk 25**	IIGSGRAPHICS (IIGS Additional Graphics Mode Libraries) (3.5" diskette)
+
+
+
+---
+
+
+
+
+
+[Return to Table of Contents](0.0%20Title_to_TOC)
+[Software Architecture](4.0%20Software_Architecture.md)

documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/4.0 Software_Architecture.md

@@ -0,0 +1,130 @@
+# AppleIIASM Architecture
+
+AppleIIAsmLib follows certain conventions due to hardware limitations, operating system requirements, ease of reading, program flow and just plain old personal preference. While there might be times when these conventions are eschewed or changed entirely, you can reasonably expect, and be expected to follow, adherence to the following architecture. Note that this architecture is designed to be fairly easily break apart in order to help with optimization after initial prototype is finished.
+
+### Naming Conventions
+
+**_Files_**
+
+Given the lack of directory structures in DOS 3.3, we are using a filename prefixes to indicate file types rather than suffixes. The extensions should be applied to a filename in this order:
+
+ - **MIN**: signifies that the code has been stripped of comments
+ - **HEAD**: indicates that this should be included first before the rest of the library. It holds hooks, variables, and subroutines necessary for the rest of the library to function.
+ - **SUB**: signifies that the file holds a subroutine
+ - **MAC**: signifies a collection of macros
+ - **LIB**: signifies a collection of subroutines
+ - **DEMO**: signifies that the program is a sub-library demo
+ - **\<FILENAME\>**: the actual name of the subroutine, macro, our other file.
+
+Additionally, Merlin Appends a ".S" to the end of a filename if it is saved as a source, and prepends the file with "T." to signify it being a text file. This prepended T. overrides our own naming conventions.
+
+**_Sample Filenames_**
+
+ - T.MIN.MAC.STDIO
+ - T.SUB.TFILLA
+ - T.MIN.LIB.REQUIRED
+ - T.DEMO.STDIO
+
+**_Variables_**
+
+In Merlin Pro 8, assembler variables are preceded by a ] sign. These variables are temporarily assigned, and can be overwritten further down in the code. Unless highly impractical, constant hooks should use native assembly's system of assigning labels (just the label), as should hook entry points. The exception to this is within macro files, as these could easily lead to label conflicts.
+
+**_Local Hooks_**
+
+Local labels are preceded by a : sign (colon) in Merlin Pro 8. When at all possible, local subroutines should have local labels. This does not apply to Merlin variables.
+
+**_Macros_**
+
+Macros should be named with regard to mnemonic function, when possible, and should not exceed five characters unless absolutely necessary. Additionally, macros may use the following prefixes to signify their classification:
+
+ - @: signifies a higher-level control structure, such as @IF,@ELSE,@IFX.
+ - \_: signifies a macro mostly meant to be used internally, though it may have limited use outside of that context.
+
+### Commenting Conventions
+
+**_Inline Comments_**
+
+For the sake of beginners, at least every other directive should have an inline comment that describes what that line, or two lines, is accomplishing. Inline comments are added at the end of a line with a semicolon to denote the comment. Note that the audience for these comments are readers who may not have a good grasp of 6502 Assembly, so they should be as descriptive as possible.
+
+**_File Headers_**
+
+If the file does not hold a single subroutine, every file should include a header with the following information:
+
+ - A brief description of the file
+ - Any subroutines or macros that are included in the file, along with brief descriptions of each.
+ - Operating System, Main Author, Contact Information, Date of Last Revision, and intended Assembler. 
+ - If the file contains a collection of macros, the subroutines used by the macros should be listed as well.
+
+**_Subroutine Headers_**
+
+All subroutines require headers that document its input, output, register, flag and memory destructions, minimum number of cycles used, and the size of the subroutine in bytes. Headers should all follow the same basic format, and a single space should be used to denote section inclusion.
+
+**_Macro Headers_**
+
+Macro headers should include a brief description of the macro, a listing of the parameters with short descriptions thereof, and a sample usage section. 
+
+**_Other Comments_**
+
+If a section of code needs more explanation than can be explained at the end of a line (a common issue, since there is limited space on the Apple II screen), these should be placed just above the code in question using asterisks to denote the line is a comment. Have a blank comment line before and after the comment with only one asterisk, while using two asterisks for the lines with actual comments.
+
+### Parameter Passing
+
+**_Macro Parameters_**
+
+In general, macro parameters follow a specific hierarchy of order, with the exception of rare cases where another order makes more sense. The hierarchy is as follows:
+
+**Source \> Destination \> Index \> Value \> Other**
+
+Additionally, parameters passed to macros, when addresses are concerned, follow a strict distinction between literal addresses and indirect addresses. If the address passed is a literal value (preceded by # in Merlin Pro 8), then that is the actual address of the data in question. If, however, the address passed is non-literal, then the two-byte value at that address is used as the intended address to be used.
+
+### Subroutine Parameters
+
+Subroutines are passed parameters by way of the registers, zero-page location values, or via the stack. Which one of these are used depends on the number of bytes being passed; different methods are used in order to maximize speed based on the needs of a subroutine.
+
+If there are less than four bytes of data being passed, the registers are used; when a 16-bit address is being passed, it is convention to pass the low byte in .A and the high byte in .X.
+
+If there are between four and ten total bytes in need of passing, the zero page is used. The locations used are defined in HEAD.REQUIRED, and specify three areas for 16-bit (two-byte word) values and four areas for 8-bit (single-byte) values. These are labeled as WPAR1, WPAR2, WPAR3, BPAR1, BPAR2, BPAR3, and BPAR4, respectively.
+
+As a last resort, parameters are passed via that stack. This should, however, be a rare occurrence, as it is the slowest method available of passing parameters. Thankfully, since most of the subroutines in the library are meant to provide basic higher-level functionality, there is little need for recourse to this option.
+
+By and large, all parameters should be one or two-byte values; if a string, array or other data type is being passed, its address is passed rather than the data itself. 
+
+Since the method of passing parameters can change from subroutine to subroutine, it is highly suggested to use the macros that call the subroutines when possible.
+
+### Main Source Sequencing
+
+After necessary assembler directives, files should be loaded in the following order:
+
+ - HEAD.REQUIRED is always loaded first (PUT).
+ - MAC.REQUIRED always follows second (USE).
+ - Any additional HEAD  files should be loaded afterwards (PUT).
+ - Any MAC files being utilized should be loaded next.
+ - Now comes the source of the main listing that the programmer will write.
+ - After the main source, LIB.REQUIRED should be included (PUT).
+ - Then, any needed subroutine (SUB) files should be included (PUT).
+ - Any user-created PUT or USE files should be placed at the very end.
+
+### Miscellaneous Standards
+
+**_Subroutine Independence_**
+
+Beyond needing the core required library files as well as the header files for the library collection in question, a subroutine should be able to operate independently of other subroutines in the library. This will generally mean some wasted bytes here and there, but this can be remedied by the end programmer if code size is a major concern.
+
+**_Control Structures_**
+
+While a number of helpful, higher-level control structures are included as part of the core required library, subroutines in the library itself should refrain from using this shorthand. Control Structure Macros are preceded with a '@' sign to signify their classification as such. Exceptions can be given to control structures that merely extend existing directives for better use, such as BEQW being used to branch beyond the normal byte limit; such macros forego the preceding @-sign.
+
+**_ASM Suffix_**
+
+The .ASM suffix on most files in the collection are mainly used for GitHub and modern operating systems to associate the dumped text version of the source with a filetype.
+
+
+
+---
+
+
+
+[Return to Table of Contents](0.0%20Title_to_TOC)
+
+[Quick Reference Introduction](5.0%20Quick_Reference_TOC.md)
+

documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/5.0 Quick_Reference_TOC.md

@@ -0,0 +1,21 @@
+# Quick Reference: Macros
+
+- [Disk 1: REQUIRED Collection Macros](./6.0%20Quick_Reference_D1_MAC.REQUIRED.md)
+- [Disk 2: STDIO Collection Macros](./7.0%20Quick_Reference_D2_MAC.STDIO.md)
+- [Disk 3: Arrays Collection Macros](./8.0%20Quick_Reference_D3_MAC.ARRAYS.md)
+- [Disk 4: Math Collection Macros](./9.0%20Quick_Reference_D4_MAC.MATH.md)
+- [Disk 5: Strings Collection Macros](./10.0%20Quick_Reference_D5_MAC.STRINGS.md)
+
+
+
+
+
+
+
+---
+
+
+
+[Return to Table of Contents](0.0%20Title_to_TOC)
+
+[Disk 1 -- REQUIRED Macros and Subroutines](6.0%20Quick_Reference_D1_MAC.REQUIRED.md)

documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/6.0 Quick_Reference_D1_MAC.REQUIRED.md

@@ -0,0 +1,106 @@
+## Disk 1 Macros: The Required Collection
+
+Disk 1: REQUIRED contains three main macro files, unlike most disks which only contain a single macro file. They are as follows:
+
+- [MAC.REQUIRED.ASM](#macrequiredasm)
+  - Contains all of the Macros required by the rest of the library collection. This must always be included in the main program. This also contains emulation macros for a select number of 65C02 instructions, if limited to a 6502 instruction set.
+- [MAC.ALIAS.8080.ASM](#macalias8080asm)
+  - These are aliases for some instructions in the 8080 instruction set. Note that these may not work exactly like the 8080 versions, and are considered works-in-progress.
+- [MAC.ALIAS.Z80.ASM](#macaliasz80asm)
+  - These are aliases for some instructions in the Z80 instruction set. Like with the previous alias file, these are works-in-progress.
+
+Be sure to consult the detailed reference for Disk 1: The Required Library for further explanation of how the macros work, their source code, and an explanation of the source code of any subroutines the macros may rely upon.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+### MAC.REQUIRED.ASM
+
+| MACRO | DEPENDENCY | PARAMETERS | ACTION | DESTROYS | CYCLES | BYTES |
+| --- | --- | --- | --- | --- | --- | --- |
+| `_AXLIT` | none | **\]1** = memory address | Determine if address sent is direct or indirect and parse accordingly in registers.<br /><br /> **.A** = address low byte<br />**.X** = address high byte |NZ|8|6|
+| `_AXSTR` | `_AXLIT` | **\]1** = memory address | Determine if literal string or address is sent and parse accordingly.<br /><br />.**A** = address low byte<br />.**X** = address high byte |NZ|11|9+|
+| `_ISLIT` | none | **\]1** = memory address | Determine if address sent is direct or indirect and parse accordingly onto the stack<br /><br />.**A** = address low byte<br />.**X** = address high byte |NZ|14|8|
+| `_ISSTR` | `_ISLIT` | **\]1** = memory address | Determine if parameter is a literal string or address and parse address accordingly to the stack.<br /><br />.**A** = address low byte<br />.**X** = address high byte |NZ|13 or 8|10+ or 6|
+| `_MLIT` | none | **\]1** = memory address<br />**\]2** = destination ZP address | Determine if address sent is direct or indirect and parse accordingly to zero page<br /><br />.**A** = address low byte <br />.**X** = address high byte |NZ|16|12|
+| `_MSTR` | `_ISLIT` | **\]1** = memory address<br />**\]2** = destination ZP address | Determine if parameter passed is a literal string and parse address accordingly to the zero page<br /><br />.**A** address low byte <br />.**X** = address high byte |NZ|15 or 8|14+ or 6|
+| `_PRN` | `__P` | **\]1** = string to print | Print a literal string to the screen. |NZCV|161+|9+|
+| `_WAIT` | `__w` | none | Loop until a button is pressed.<br /><br />.**A** = keypress value |NZ|14+|10|
+| `BEEP` | none | **\]1** = length of beep | Make beeping sound | NZC | 108+ | 15 |
+| `CLRHI` | none | none | high nibble of .**A** cleared | NZC | 10 | 6 |
+| `DUMP` | `_AXLIT`;<br />`__DUMP` | **\]1** = memory address<br />**\]2** = number of bytes to dump | Dump a region of memory to the screen<br /><br />.**A** = number of bytes displayed |NZCV|811+|16|
+| `GBIT` | none | **\]1** = byte to check<br />**\]2** = bit mask | Get bit from .**A** at specified location in byte.<br /><br />.**A** = 0 or 1 | NZ | 14 | 15 |
+
+
+
+---
+
+
+
+### MAC.ALIAS.8080.ASM
+
+| MACRO | DEPENDENCIES | PARAMETERS | ACTION | CYCLES | BYTE |
+| ----- | ------------ | ---------- | ------ | ------ | ---- |
+| `CALL` |none|label to `JSR` to| mimics `JSR` instruction | 6 | 3 |
+|`RET`|none|none| mimics `RTS` instruction|6|1|
+|`JA`|none|label to `JMP` to| `JMP` if .**A** > `CMP`|14|9|
+|`JAE`|none|label to `JMP` to| `JMP` if .**A** >= `CMP`|8|4|
+|`JB`|none|label to `JMP` to| `JMP` if .**A** < `CMP`|8|4|
+|`JBE`|none|label to `JMP` to| `JMP` if .**A** <= `CMP`|1|6|
+|`JC`|none|label to `JMP` to| `JMP` if .**C** = 1|8|4|
+|`JE`|none|label to `JMP` to| `JMP` if **EQUAL**|8|4|
+|`JG`|none|label to `JMP` to| `JA`|11|9|
+|`JGE`|none|label to `JMP` to| `JAE`|8|4|
+|`JL`|none|label to `JMP` to| `JB`|8|4|
+|`JLE`|none|label to `JMP` to| `JBE`|11|6|
+|`JNC`|none|label to `JMP` to| `JMP` if .**C** = 0|8|4|
+|`JNE`|none|label to `JMP` to| `JMP` if **NOT EQUAL**|8|4|
+|`JZ`|none|label to `JMP` to| `JMP` if .**Z** = 1|8|4|
+|`JNZ`|none|label to `JMP` to| `JMP` if .**Z** = 0|8|4|
+|`JS`|none|label to `JMP` to| `JMP` if **SIGNED**|8|4|
+|`JNS`|none|label to `JMP` to| `JMP` if **NOT SIGNED**|8|4|
+|`JO`|none|label to `JMP` to| `JMP` if **OVERFLOW** = 1|8|4|
+|`JNO`|none|label to `JMP` to| `JMP` if **OVERFLOW** = 0|8|4|
+|`ANC`|none|**\]1** = first addend<br />**\]2** = second addend| Add No Carry (ADD in 8080)|12|8|
+|`SNC`|none|**\]1** = Minuend<br />**\]2** = Subtrahend| Subtract No Carry (SUB in 8080)|12|8|
+|`PUSHA`|none|none| Push All Registers|30|14|
+|`PULLA`|none|none| Pull All Registers|19|24|
+|`POPA`|none|none| `PULLA`|19|24|
+
+
+
+---
+
+
+
+### MAC.ALIAS.Z80.ASM
+
+| MACRO | DEPENDENCIES | PARAMETERS | ACTION | CYCLES | BYTE |
+| ----- | ------------ | ---------- | ------ | ------ | ---- |
+|`CPL`|none|none| Invert bits in .**A**|2|2|
+|`JP`|none|label to `JMP` to| `JMP` equivalent|5|1|
+|`LD`|none|????| move value from source to destination (non-operational)|?|?|
+|`POP`|none|none| `PLA` equivalent|4|1|
+|`SCF`|none|none| `SEC` equivalent|2|1|
+
+
+
+
+
+---
+
+
+
+[Return to Table of Contents](0.0%20Title_to_TOC)
+
+[Disk 2 Quick Reference -- STDIO Macros and Subroutines](7.0%20Quick_Reference_D2_MAC.STDIO.md)

documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/7.0 Quick_Reference_D2_MAC.STDIO.md

@@ -0,0 +1,114 @@
+## Disk 2 Macros: The STDIO Collection
+
+Disk 2: STDIO contains four macro files, each dedicated to different aspects of standard input and output. They are:
+
+- [MAC.COUT.STDOUT.ASM](#mac.cout.stdout.asm)
+  - This package contains macros that use the Apple II's COUT functionality. This can range from simple printing to the screen and moving the cursor position to word-wrapping a null-terminated string to the screen until the entire string is read.
+- [MAC.SCRMEM.STDIO.ASM](#mac.scrmeme.stdio.asm)
+  - This package contains macros that deal directly with screen memory. This means that the macros tend to be **fast**, at least compared to COUT; thus, most of the macros found here have to do with plotting more complicated shapes to the screen rather than focus on simple text output alone. It should be noted that because these macros do not inform COUT of any screen memory changes, they do not exactly play well with using COUT.
+- [MAC.STDIN.ASM](#mac.stdin.asm)
+  - These macros focus on input from the keyboard and paddles. More unique input devices, like a mouse, may be supported in the future.
+- [MAC.MISC.STDIO.ASM](#mac.misc.stdio.asm)
+  - This package contains macros that do not easily fit in with any of the preceding three groupings. Some of these macros may move to different packages in the future, as their relevance to one set of functionalities rather than another becomes more apparent.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+### MAC.COUT.STDOUT.ASM
+
+| MACRO   | DEPENDENCY             | PARAMETERS                                                   | ACTION                                                       | DESTROYS | CYCLES | BYTES |
+| ------- | ---------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- | ------ | ----- |
+| `CURB`  | none                   | ]1 = # of spaces                                             | Move cursor backward                                         | NZCV     | 10+    | 7     |
+| `CURD`  | none                   | ]1 = # of spaces                                             | Move cursor Downward                                         | NZCV     | 10+    | 7     |
+| `CURF`  | none                   | ]1 = # of spaces                                             | Move cursor forward                                          | NZCV     | 10+    | 7     |
+| `CURU`  | none                   | ]1 = # of spaces                                             | Move cursor upward                                           | NZCV     | 10+    | 7     |
+| `PRN`   | `DPRINT`<br />`XPRINT` | ]1 = Memory address or literal string                        | Print a literal string or a null-terminated string to the display | NZCV     | 159+   | 34    |
+| `SCPOS` | none                   | ]1 = Column <br/>]2 = Row                                    | Set Cursor Position                                          | NZCV     | 10+    | 8     |
+| `SETCX` | none                   | ]1 = Column                                                  | Set Cursor Column                                            |          | 10+    | 8     |
+| `SETCY` | none                   | ]1 = Row                                                     | Set Cursor Row                                               | NZCV     | 4+     | 5     |
+| `SPRN`  | `PRNSTR`               | ]1 = memory address of string                                | Display a regular string                                     | NZCV     | 147+   | 35    |
+| `TMORE` | `TXTMORE`              | ]1 = String Address<br />]2 = Line Length<br />]3 = Pause Interval | Word-wrap a null-terminated string to the display, pausing either at a regular line interval or every time a linefeed is encountered. | NZCV     | 482+   | 472   |
+
+
+
+---
+
+
+
+### MAC.SCRMEM.STDIO.ASM
+
+| MACRO   | DEPENDENCY | PARAMETERS                                                   | ACTION                                                       | DESTROYS | CYCLES | BYTES |
+| ------- | ---------- | ------------------------------------------------------------ | ------------------------------------------------------------ | -------- | ------ | ----- |
+| `CPUT`  | `TXTPUT`   | ]1 = X-pos<br/>]2 = Y-pos<br/>]3 = character                 | Plot a character at the given X,Y coordinate                 | NZCV     | 91+    | 31    |
+| `RCPOS` | none       | ]1 = Column <br/>]2 = Row                                    | Return a character located on screen at given coordinate     | NZCV     | 10+    | 6     |
+| `SPUT`  | `STRPUT`   | ]1 = X-pos<br>]2 = Y-pos<br>]3 = String address              | Plot a string at the given X,Y coordinate                    | NZCV     | 124+   | 50    |
+| `TCIRC` | `TCIRCLE`  | ]1 = Center X-position<br>]2 = Center Y-position<br>]3 = Radius<br>]4 = Fill value | Create a circle with a text character and display it at given screen coordinates | NZCV     | 627+   | 290   |
+| `TCLR`  | `TXTCLR`   | ]1 = Fill Value                                              | Fill the text screen with a given character                  | NZCV     | 50+    | 42    |
+| `THLIN` | `THLINE`   | ]1 = X-pos origin<br>]2 = X-pos destination<br>]3 = Y-position <br>]4 = Fill value | Create a horizontal line on the screen made of a single fill character | NZCV     | 107+   | 38    |
+| `TVLIN` | `TVLINE`   | ]1 = Y-pos origin<br>]2 = Y-pos destination<br>]3 = X-position <br>]4 = Fill value | Create a vertical line on the screen made of a single fill character | NZCV     | 104+   | 45    |
+| `TLINE` | `TBLINE`   | ]1 = X origin <br>]2 = Y origin <br>]3 = X dest <br>]4 = Y dest <br>]5 = fill value | Create a diagonal line an X,Y origin to an X,Y destination with a single fill character | NZCV     | 305+   | 198   |
+| `TREC`  | `TRECT`    | ]1 = X Origin<br />]2 = Y Origin <br />]3 = X Destination<br />]4 = Y Destination<br />]5 = Fill Value | Create an unfilled rectangle on the text screen that is composed of a single character | NZCV     | 362+   | 115   |
+| `TRECF` | `TRECTF`   | ]1 = X origin <br>]2 = Y origin <br>]3 = X dest<br>]4 = Y dest<br>]5 = Fill vallue | Create a filled rectangle on the screen made of a single fill character | NZCV     | 157+   | 77    |
+
+
+
+---
+
+
+
+### MAC.STDIN.ASM
+
+| MACRO  | DEPENDENCY | PARAMETERS          | ACTION                                               | DESTROYS | CYCLES | BYTES |
+| ------ | ---------- | ------------------- | ---------------------------------------------------- | -------- | ------ | ----- |
+| `GKEY` | none       | none                | Wait for a keypress and hold the key value in **.A** | NZCV     | 11+    | 7     |
+| `INP`  | `SINPUT`   | none                | input a line of text from the keyboard               | NZCV     | 64+    | 41    |
+| `PBX`  | none       | ]1 = paddle button  | Read paddle button state                             | NZCV     | 8+     | 8     |
+| `PDL`  | none       | ]1 = paddle address | Read the specified paddle value (0..255)             | NZCV     | 8+     | 5     |
+| `WAIT` | none       | none                | wait for a keypress                                  | NZCV     | 9+     | 8     |
+
+
+
+---
+
+
+
+### MAC.MISC.STDIO.ASM
+
+| MACRO   | DEPENDENCY | PARAMETERS                             | ACTION                          | DESTROYS | CYCLES | BYTES |
+| ------- | ---------- | -------------------------------------- | ------------------------------- | -------- | ------ | ----- |
+| `COL40` | none       | none                                   | Enter 40-column mode            | NZCV     | 8+     | 5     |
+| `COL80` | none       | none                                   | Enter 80-column mode            | NZCV     | 8+     | 5     |
+| `DIE80` | none       | none                                   | End 80-column mode              | NZCV     | 8+     | 5     |
+| `TCTR`  | `TXTCENT`  | ]1 = short string <br>]2 = long string | Center a string in a given line | NZCV     | 47+    | 27    |
+
+
+
+---
+
+
+
+[Return to Table of Contents](0.0%20Title_to_TOC)
+
+[Disk 3 Quick Reference -- Array Macros and Subroutines](8.0%20Quick_Reference_D3_MAC.ARRAYS)
+
+
+
+
+

documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/8.0 Quick_Reference_D3_MAC.ARRAYS.md

@@ -0,0 +1,79 @@
+## Disk 3 Macros: The Array Collection
+
+Disk 3: ARRAYS contains four macro files that have the same kinds of macros for different kinds of arrays; that is, each macro file is dedicated to an array of 8-bits or 16-bits and one or two dimensions, and contains the functionality to initialize an array, get data from it and put data into it. The are as follows:
+
+- [MAC.ARR8B1D.ASM](#mac.arr8b1d.asm)
+  - This packages contains `DIM`, `GET` and `PUT` macros for eight-bit, one-dimensional arrays.
+- [MAC.ARR8B2D.ASM](#mac.arr8b2d.asm)
+  - This packages contains `DIM`, `GET` and `PUT` macros for eight-bit, two-dimensional arrays.
+- [MAC.ARR16B1D.ASM](#mac.arr16b1d.asm)
+  - This packages contains `DIM`, `GET` and `PUT` macros for sixteen-bit, one-dimensional arrays.
+- [MAC.ARR16B2S.ASM](#mac.arr16b2d.asm)
+  - This packages contains `DIM`, `GET` and `PUT` macros for sixteen-bit, two-dimensional arrays.
+
+
+
+
+
+
+
+
+
+### MAC.ARR8B1D.ASM
+
+| MACRO   | DEPENDENCY | PARAMETERS                                                   | ACTION                                            | DESTROYS | CYCLES | BYTES |
+| ------- | ---------- | ------------------------------------------------------------ | ------------------------------------------------- | -------- | ------ | ----- |
+| `DIM81` | `ADIM81`   | ]1 = Array addr <br>]2 = # of elements <br>]3 = element size <br>]4 = fill value | Initialize a 1D, 8-bit array                      | NZCV     | 234+   | 146   |
+| `GET81` | `AGET81`   | ]1 = Array addr <br>]2 = Element Index                       | Get a value from an element in a 1D, 8-bit array. | NZCV     | 193+   | 125   |
+| `PUT81` | `APUT81`   | ]1 = Source addr <br>]2 = Array addr <br>]3 = Element Index  | Put a value into an element in a 1D, 8-bit array. | NZCV     | 216+   | 131   |
+
+
+
+---
+
+
+
+### MAC.ARR8B2D.ASM
+
+| MACRO   | DEPENDENCY | PARAMETERS                                                   | ACTION                                            | DESTROYS | CYCLES | BYTES |
+| ------- | ---------- | ------------------------------------------------------------ | ------------------------------------------------- | -------- | ------ | ----- |
+| `DIM82` | `ADIM82`   | ]1 = Array addr <br>]2 = 1st dimension length <br>]3 = 2nd dimension length <br>]4 = fill value | Initialize a 2D, 8-bit array                      | NZCV     | 355+   | 228   |
+| `GET82` | `AGET82`   | ]1 = Array addr <br>]2 = 1st Dimension Index <br>]3 = 2nd Dimension Index | Get a value from an element in a 2D, 8-bit array. | NZCV     | 340+   | 255   |
+| `PUT82` | `APUT82`   | ]1 = Source addr <br>]2 = Destination addr <br>]3 = 1st Dimension Index <br>4] = 2nd Dimension Index | Put a value into an element in a 2D, 8-bit array. | NZCV     | 352+   | 223   |
+
+
+
+---
+
+
+
+### MAC.ARR16B1D.ASM
+
+| MACRO    | DEPENDENCY | PARAMETERS                                                   | ACTION                                             | DESTROYS | CYCLES | BYTES |
+| -------- | ---------- | ------------------------------------------------------------ | -------------------------------------------------- | -------- | ------ | ----- |
+| `DIM161` | `ADIM161`  | ]1 = Array Addr <br>]2 = # of elements <br>]3 = Element length <br>]4 = Fill Value | Initialize a 1D, 16-bit array                      | NZCV     | 271+   | 165   |
+| `GET161` | `AGET161`  | ]1 = Array addr <br>]2 = Element Index                       | Get a value from an element in a 1D, 16-bit array. | NZCV     | 223+   | 130   |
+| `PUT161` | `APUT161`  | ]1 = Source addr <br>]2 = Array addr <br>]3 = Element index  | Put a value into an element in a 1D, 16-bit array. | NZCV     | 238+   | 148   |
+
+
+
+----
+
+
+
+### MAC.ARR16B2D.ASM
+
+| MACRO    | DEPENDENCY | PARAMETERS                                                   | ACTION                                             | DESTROYS | CYCLES | BYTES |
+| -------- | ---------- | ------------------------------------------------------------ | -------------------------------------------------- | -------- | ------ | ----- |
+| `DIM162` | `ADIM162`  | ]1 = Array Address<br />]2 = First Dimension Element Count<br />]3 = Second Dimension Element Count<br />]4 = Byte size of Elements<br />]5 = Default Fill Value | Initialize a 2D, 16-bit array                      | NZCV     | 464+   | 373   |
+| `GET162` | `AGET162`  | ]1 = Array Address<br />]2 = First Dimension Element Address<br />]3 = Second Dimension Element Address | Get a value from an element in a 2D, 16-bit array. | NZCV     | 436+   | 263   |
+| `PUT162` | `APUT162`  | ]1 = Source Address<br />]2 = Destination Array Address<br />]3 = First Dimension Element Address<br />]4 = Second Dimension Element Address | Put a value into an element in a 2D, 16-bit array. | NZCV     | 352+   | 223   |
+
+
+
+---
+
+
+
+[Return to Table of Contents](0.0%20Title_to_TOC)
+

documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/9.0 Quick_Reference_D4_MAC.MATH.md

@@ -0,0 +1,125 @@
+# Disk 4: Basic Math and Pseudorandom Numbers
+
+
+
+The Basic Math collection contains macros and subroutines dedicated to addition, subtraction, multiplication and division operations, as well as a 16-bit comparison routine and several macros for generating pseudorandom numbers. These are grouped into several macro files, as such:
+
+
+
+- [MAC.D8BY.ASM](#mac.d8by.asm)
+  - This group contains macros that are used to divide an 8-bit number by a fixed constant between 2 and 10.
+- [MAC.M8BY.ASM](#mac.m8by.asm)
+  - This group contains macros that are used to multiply an 8-bit number by a fixed constant between 2 and 10.
+- [MAC.M16BY.ASM](#mac.m16by.asm)
+  - This group contains macros that are used to multiply a 16-bit number by a fixed constant between 2 and 10, as well as by 100.
+- [MAC.MATH8.ASM](#mac.math8.asm)
+  - This group contains macros for adding, subtracting, multiplying and dividing 8-bit numbers.
+- [MAC.MATH16.ASM](#mac.math16.asm)
+  - This group contains macros for adding, subtracting, multiplying and dividing 16-bit numbers. It also includes a macro for 16-bit comparison.
+- [MAC.MATHRND.ASM](#mac.mathrnd.asm)
+  - This group contains macros for managing and generating pseudorandom numbers.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+### MAC.D8BY.ASM
+
+| MACRO    | DEPENDENCY | PARAMETERS | ACTION                          | DESTROYS | CYCLES | BYTES |
+| -------- | ---------- | ---------- | ------------------------------- | -------- | ------ | ----- |
+| `D8BY2`  | none       | none       | Divide an 8-bit number by two   | NZCV     | 6      | 4     |
+| `D8BY3`  | none       | none       | Divide an 8-bit number by three | NZCV     | 29     | 19    |
+| `D8BY4`  | none       | none       | Divide an 8-bit number by four  | NZCV     | 8      | 5     |
+| `D8BY5`  | none       | none       | Divide an 8-bit number by five  | NZCV     | 34     | 21    |
+| `D8BY6`  | none       | none       | Divide an 8-bit number by six   | NZCV     | 36     | 21    |
+| `D8BY7`  | none       | none       | Divide an 8-bit number by seven | NZCV     | 33     | 19    |
+| `D8BY8`  | none       | none       | Divide an 8-bit number by eight | NZCV     | 10     | 6     |
+| `D8BY9`  | none       | none       | Divide an 8-bit number by nine  | NZCV     | 36     | 21    |
+| `D8BY10` | none       | none       | Divide an 8-bit number by ten   | NZCV     | 36     | 21    |
+
+
+
+### MAC.M8BY.ASM
+
+| MACRO    | DEPENDENCY | PARAMETERS | ACTION                            | DESTROYS | CYCLES | BYTES |
+| -------- | ---------- | ---------- | --------------------------------- | -------- | ------ | ----- |
+| `M8BY2`  | none       | none       | Multiply an 8-bit number by two   | NZCV     | 6      | 4     |
+| `M8BY3`  | none       | none       | Multiply an 8-bit number by three | NZCV     | 6      | 4     |
+| `M8BY4`  | none       | none       | Multiply an 8-bit number by four  | NZCV     | 8      | 5     |
+| `M8BY5`  | none       | none       | Multiply an 8-bit number by five  | NZCV     | 15     | 10    |
+| `M8BY6`  | none       | none       | Multiply an 8-bit number by six   | NZCV     | 15     | 10    |
+| `M8BY7`  | none       | none       | Multiply an 8-bit number by seven | NZCV     | 33     | 20    |
+| `M8BY8`  | none       | none       | Multiply an 8-bit number by eight | NZCV     | 10     | 6     |
+| `M8BY9`  | none       | none       | Multiply an 8-bit number by nine  | NZCV     | 18     | 11    |
+| `M8BY10` | none       | none       | Multiply an 8-bit number by ten   | NZCV     | 18     | 11    |
+
+
+
+### MAC.M16BY.ASM
+
+| MACRO     | DEPENDENCY | PARAMETERS | ACTION                                  | DESTROYS | CYCLES | BYTES |
+| --------- | ---------- | ---------- | --------------------------------------- | -------- | ------ | ----- |
+| `M16BY2`  | none       | none       | Multiply a 16-bit number by two         | NZCV     | 20     | 13    |
+| `M16BY3`  | none       | none       | Multiply a 16-bit number by three       | NZCV     | 47     | 32    |
+| `M16BY4`  | none       | none       | Multiply a 16-bit number by four        | NZCV     | 37     | 24    |
+| `M16BY5`  | none       | none       | Multiply a 16-bit number by five        | NZCV     | 46     | 30    |
+| `M16BY6`  | none       | none       | Multiply a 16-bit number by six         | NZCV     | 58     | 38    |
+| `M16BY7`  | none       | none       | Multiply a 16-bit number by seven       | NZCV     | 72     | 47    |
+| `M16BY8`  | none       | none       | Multiply a 16-bit number by eight       | NZCV     | 34     | 21    |
+| `M16BY9`  | none       | none       | Multiply a 16-bit number by nine        | NZCV     | 62     | 36    |
+| `M16BY10` | none       | none       | Multiply a 16-bit number by ten         | NZCV     | 66     | 39    |
+| `M16BY1H` | none       | none       | Multiply a 16-bit number by one hundred | NZCV     | 124    | 70    |
+
+
+
+### MAC.MATH8.ASM
+
+| MACRO  | DEPENDENCY | PARAMETERS                                  | ACTION                                 | DESTROYS | CYCLES | BYTES |
+| ------ | ---------- | ------------------------------------------- | -------------------------------------- | -------- | ------ | ----- |
+| `ADD8` | none       | ]1 = number to add <br />]2 = number to add | Add two 8-bit numbers                  | NZCV     | 21     | 15    |
+| `SUB8` | none       | ]1 = Minuend </br>]2 = Subtrahend           | Subtract one 8-bit number from another | NZCV     | 21     | 15    |
+| `MUL8` | `MULTU8`   | ]1 = Multiplicand<br />]2 = Multiplier      | Multiply two 8-bit numbers             | NZCV     | 97     | 56    |
+| `DIV8` | `DIVDU8`   | ]1 = Dividend<br />]2 = Divisor             | Divide one 8-bit number by another     | NZCV     | 75     | 43    |
+
+
+
+### MAC.MATH16.ASM
+
+| MACRO   | DEPENDENCY | PARAMETERS                                                   | ACTION                                  | DESTROYS | CYCLES | BYTES |
+| ------- | ---------- | ------------------------------------------------------------ | --------------------------------------- | -------- | ------ | ----- |
+| `ADD16` | `ADDIT16`  | ]1 = First number to add<br />]2 = Second number to add      | Add two 16-bit numbers                  | NZCV     | 78     | 51    |
+| `SUB16` | `SUBT16`   | ]1 = Minuend<br >]2 = Subtrahend                             | Subtract one 16-bit number from another | NZCV     | 79     | 51    |
+| `MUL16` | `MULTU16`  | ]1 = Multiplier<br />]2 = Multiplicand                       | Multiply two 16-bit numbers             | NZCV     | 144    | 91    |
+| `DIV16` | `DIVDU16`  | ]1 = Dividend<br />]2 = Divisor                              | Divide one 16-bit number by another     | NZCV     | 133    | 81    |
+| `CMP16` | `COMP16`   | ]1 = First Comparison Number <br />]2 = Second Comparison Number | Compare one 16-bit number to another    | NZCV     | 100    | 53    |
+
+
+
+### MAC.MATHRND.ASM
+
+| MACRO    | DEPENDENCY | PARAMETERS                            | ACTION                                                    | DESTROYS | CYCLES | BYTES |
+| -------- | ---------- | ------------------------------------- | --------------------------------------------------------- | -------- | ------ | ----- |
+| `RNDEOR` | none       | ]1 = Seed <br />]2 = EOR Index        | Set the seed and magic number value                       | NZCV     | 30     | 22    |
+| `RNDMZ`  | none       | ]1 = Seed<br />]2 = EOR Magic Number  | Set the seed and set the magic number index               | NZCV     | 56     | 35    |
+| `RND8`   | `RAND8`    | none                                  | Generate a value between 0 and 255                        | NZCV     | 51     | 30    |
+| `RAND`   | `RANDB`    | ]1 = Low bounds<br />]2 = High bounds | Generate a value between a given low value and high value | NZCV     | 263    | 171   |
+| `RND16`  | `RAND16`   | none                                  | Generate a value between 0 and 65,355                     | NZCV     | 101    | 63    |
+

documentation/AppleIIAsm Library Collection Technical Manual/0.6.1/README.md

@@ -0,0 +1,5 @@
+# README
+
+This is the current documentation for the entire collection, v0.6.0. Note that the documentation is incomplete because I am working my way through the changes and documentation disk-by-disk.
+
+To access the documentation in its current state thus far, start with [The Title and Table of Contents](0.0%20Title%20to%20TOC.md)

documentation/README.md

@@ -0,0 +1 @@
+This directory contains all of the documentations for each version of AppleIIAsm. Note that the latest version is the highest number, and thus is always at the top. However, keep in mind the that version may yet be unstable. Follow the documentation found in the latest stable release.