misc

documentation/0.6.0/0.0 Title to TOC.md

@@ -0,0 +1,77 @@
+# AppleIIAsm Technical Manual v0.6.0
+
+---
+
+Written and edited by Nathan Riggs (so far), 2020.
+
+---
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+---
+
+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](0_1_License.md)
+2. [Preface](1_Preface.md)
+3. [Introduction](1_5_Introduction.md)
+4. [Package Overiew](2_Package_Overview.md)
+5. [Software Architecture](2_5_Software_Architecture.md)
+6. Macro/Subroutine Quick References
+   - [Disk 1 -- REQUIRED Macros and Subroutines](3_Quick_Reference_D1_REQUIRED.md)
+   - Disk 2 -- 
+7. Detailed References and Source Code Listings
+   - [Disk 1: Required Library and Aliases](30_Detailed_Reference_D1_REQUIRED.md)
+8. Appendices
+   - Supplemental Texts
+   - Further Reference
+   - Optimizations
+     - Typical Assembly Opimizations
+     - Architecture Clobbering Optimizations

documentation/0.6.0/0_1_License.md

@@ -1,10 +0,0 @@
-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.
-
----

documentation/0.6.0/0_3_Table_of_Contents_GH.md

@@ -1,18 +0,0 @@
-## Table of Contents
-
-1. [License](0_1_License.md)
-2. [Preface](1_Preface.md)
-3. [Introduction](1_5_Introduction.md)
-4. [Package Overiew](2_Package_Overview.md)
-5. [Software Architecture](2_5_Software_Architecture.md)
-6. Macro/Subroutine Quick References
-   - [Disk 1 -- REQUIRED Macros and Subroutines](3_Quick_Reference_D1_REQUIRED.md)
-   - Disk 2 -- 
-7. Detailed References and Source Code Listings
-   - [Disk 1: Required Library and Aliases](30_Detailed_Reference_D1_REQUIRED.md)
-8. Appendices
-   - Supplemental Texts
-   - Further Reference
-   - Optimizations
-     - Typical Assembly Opimizations
-     - Architecture Clobbering Optimizations

documentation/0.6.0/0_Title.md

@@ -1,8 +0,0 @@
-# AppleIIAsm Technical Manual v0.6.0
-
----
-
-Written and edited by Nathan Riggs (so far; se license), 2020.
-
----
-

documentation/0.6.0/30.0 Detailed_Reference_D1_REQUIRED.md

@@ -2,24 +2,26 @@
 
 
 
+
+
 ## PART I: REQUIRED LIBRARY
 
-The first disk in the AppleIIAsm Collection includes all of the macros, subroutines, hooks and reserved memory locations required for the rest of the library to function properly. Note that "Functioning properly" only applies to unmodified codebases; highly optimized code that makes the library barely recognizable may not use the same standard procedures. 
+The first disk in the AppleIIAsm Collection includes all of the macros, subroutines, vectors and reserved memory locations required for the rest of the library to function properly. Note that "Functioning properly" only applies to unmodified codebases; highly optimized code that makes the library barely recognizable may not use the same standard procedures. 
 
-You may consider the files on this disk to provide the overall software architecture for the rest of the library. However, one of the goals is to be able to remove or alter major components of the architecture---the girders, you might say---in order to lighten the building as a whole while still keeping its basic structure intact.
+You may consider the files on this disk to provide the overall software architecture for the rest of the library (as outline in the Software Architecture section). However, one of the goals is to be able to remove or alter major components of the architecture---the girders, you might say---in order to lighten the building as a whole while still keeping its basic structure intact. That is, a good deal of effort is done to make this package of libraries as easy for beginners to use as possible while also allowing for substantial changes to the architecture to allow for further optimization after the fact.
 
 
 
 ## Required Components 
 
-Basically, the following components will be covered in this chapter, via looking at the header, macros and subroutines:
+Basically, the following components will be first covered in this chapter, via looking at the header, macros and subroutines:
 
 - Special memory locations and variables (especially on the zero\-page)
 - Macros for checking Literal versus indirect parameters
 - Most common kinds of parameter passing
 - Checking for a string or an address being passed as a parameter
 
-Since this will encompass the same group of macros, the information will be contained in a section of its own However, many more macros have yet to be covered, and will be so largely in alphabetical order. 
+Since this will encompass the same group of macros, the information will be contained in a section of its own However, many more macros have yet to be covered, and will be so largely in alphabetical order. There are times, however, when it makes sense to group together subroutines or macros non-alphabetically; this is done on occasion.
 
 The next components are the `_PRN` and `_WAIT` macros, alternatives of which are technically found on other disks but are useful enough to also include in the required library; the subroutines for these will be covered as well..\ However, following that will be a long series of macros that being with "B," which are versions of 6502 branch instructions that allow for longer calls. These are useful enough to include in the required library, and take up little enough space in terms of bytes and cycles that their inclusion here is negligible.
 
@@ -263,12 +265,34 @@ As stated in earlier sections of this text, each file contains its own heading w
 * POKE  : STORE ADDR VAL IN A  *
 *,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,*
 *
+** LIBRARY-SPECIFIC VARIABLES
+*
+]RIGHT   DS    1
+]LEFT    DS    1
+]LENGTH  DS    1
+]A       DS    1          ; REGISTER .A BACKUP
+]X       DS    1          ; REGISTER .X BACKUP
+]Y       DS    1          ; REGISTER .Y BACKUP
+]C       DS    1          ; CARRY FLAG BACKUP
+]Z       DS    1          ; ZERO FLAG BACKUP
+]N       DS    1          ; NEGATIVE FLAG BACKUP
+]O       DS    1          ; OVERFLOW FLAG BACKUP
+]HEXTAB  ASC   "0123456789ABCDEF"
+*
+** LIBRARY-SPECIFIC HOOKS
+*
+]COUT    EQU   $FDF0      ; SCREEN OUTPUT ROUTINE
+]KYBD    EQU   $C000      ; KEYBOARD INPUT
+]STROBE  EQU   $C010      ; KEYBOARD STROBE
+*
 ```
 
 A typical macro file header includes the name of the file at the top, followed by a short paragraph that describes what these macros are for. Then, the (main) author and his or her contact information is listed, along with the last date of revision, the Operating system targeted, and the Assembler used. Unless this project grow far beyond my original intentions, these will all likely remain the same, save for revision dates.
 
 What follows then is a listing of all subroutine files that are used by the macros in the file; luckily, there is only one subroutine file in use for the required library. After that, a listing of macros available in the file are listed, with extremely brief descriptions of what they are for; more detailed descriptions can be found in the headers of the macros themselves. A bit strangely, this macro file header contains fewer subroutine listings that most others and more macro listing than most other file headers, as you will see.
 
+Also note that this header carries with it some key variables that are used in the rest of the library. This is usually relegated to the HEAD file of a library, but assembly variables, rather than hooks, are often defined within the file they are used.
+
 ---
 
 
@@ -975,7 +999,7 @@ BEEP      MAC                  ; ROUTINE BEEP
 
 ## LONG BRANCHES
 
-Long branches are branching macros that work pretty much exactly like the branching mechanism they represent, except they can jump to an address beyond a single page away. This is especially helpful in prototyping, as normal branching routines often start failing once you begin to add content between the branching instruction and the address to branch to.
+Long branches are branching macros that work pretty much exactly like the branching mechanism they represent, except they can jump to an address beyond a single page away. This is especially helpful in prototyping, as normal branching routines often start failing once you begin to add content between the branching instruction and the address to branch to. However, without quite a bit of reworking, using these macros also makes your code non-relocatable, as specific addresses are `JMP'd` to that may no longer exist as first envisioned.
 
 ### THE BCCL MACRO
 
@@ -2988,3 +3012,24 @@ Currently, there are few instruction set macro substitutions for the z80 process
 | `RET` | `RTS` equivalent | 1 | 6 |
 | `SCF` | `SEC` equivalent | 1 | 2 |
 
+
+
+## DEMOS
+
+At the the end of each library, a demo is provided that shows the macros being used as they should be (or could be). These demos are not meant to be exhaustive, but are meant to merely illustrate how the macro is called, what paramaters it might require, and so on. By and large, the demos are all kept fairly simple due to the fact that 1) they cannot interact with the macros and subroutines provided by other libraries, and 2) they are meant for beginners to see how a macro works and not much else. More complicated demos are planned for future disks in the package, and some of them are already finished (though in need of updating to the current version).
+
+The demo file listed here is the same `DEMO.REQUIRED` file on the disk. Note that most of the heavier descriptions of the macros are done in commenting in order to cut down on the demo file size in bytes, but `_PRN` and `_WAIT` are particularly used in demo files to give some context when the demo itself is executed. Note also that demo files, like all other files, have unique headings before the code proper begins.
+
+## DEMO.REQUIRED
+
+```asm
+
+
+```
+
+[Return to Table of Contents](./0.0 Title to TOC)
+[Next: Detailed Reference: Standard Input and Output, Disk 2]()
+
+
+
+

documentation/0.6.0/The New Merlin Users' Guide/The New Users' Quick Guide to Merlin Pro 8 in DOS 3.3.md

@@ -0,0 +1,84 @@
+# The New Users' "Quick" Guide to DOS 3.3 Merlin Pro 8 
+
+---
+
+Nathan Riggs
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+---
+
+## Table of Contents
+
+Foreward
+
+Introduction
+
+1. But Why?
+2. About this Text
+3. Don't Abandon Bredon!
+4. Main Audience Assumptions
+5. System Requirements
+6. Additional Reading
+
+I. What's New?
+
+1. Old is the New New
+2. Emulators
+3. Hardware Replacements
+4. GitHub and Company
+
+II. The Main Menu
+
+1. 
+
+III. The Source Editor
+
+IV. Assembly Space
+
+V. Syntax, Labels and Variables
+
+VI. Macros 
+
+VII. Pseudo-Opcodes
+
+VIII. 
+
+
+
+---
+
+## Foreword
+
+This guide is for those of you crazy folk out there who, like myself, choose to use a nearly 40 year-old assembler instead of take advantage of the myriad "better" options available today, in 2020. There are many reasons you might choose to do this: like me, you might be in the middle of something like an archeological media dig, or perhaps reenactment, that allows you to better understand the woes and weariness of assembly programming when it was still a highly relevant language to use. You might be wanting to assemble a program on original hardware, for whatever reason, or you might just be a plain old masochist. This booklet is definitely for the former two, but if you're in it for some pleasurable pain, I'd say go straight to the original manual itself.
+
+But that does bring up a good point: if an original manual exists, and is comprehensive (it is, by all means), then why does one need a new guide today, "quick" or otherwise?
+
+
+
+
+
+
+