extracts okay, formats okay, no insertion into images, still must use dd to build...

[bif-6809/bif-6809.git] / README.TXT

diff --git a/README.TXT b/README.TXT
index dd04ea8..4d19008 100644 (file)
--- a/README.TXT
+++ b/README.TXT
@@ -1,14 +1,14 @@
 Information about BIF as of April 2019.\r
 \r
 Information about BIF as of April 2019.\r
 \r

-       Joel Matthew Rees, Amagasaki, Hyogo, Japan.\r
+       Author: Joel Matthew Rees, Amagasaki, Hyogo, Japan.\r

                                        https://ja.osdn.net/projects/bif-6809/\r
                                        https://ja.osdn.net/projects/bif-6809/\r

-                                       joel.rees+knock@gmail.com\r
+                                       joel.rees+knock at gmail dot com\r

                                        http://reiisi.blogspot.com\r
                                        https://defining-computers.blogspot.com/\r
                                        https://ja.osdn.net/users/reiisi/\r
                                        https://sourceforge.net/u/reiisi/profile/\r
                                        etc.\r
                                        http://reiisi.blogspot.com\r
                                        https://defining-computers.blogspot.com/\r
                                        https://ja.osdn.net/users/reiisi/\r
                                        https://sourceforge.net/u/reiisi/profile/\r
                                        etc.\r

-       Copyright 2000, 2019 Joel Matthew Rees\r
+       Copyright from 2000 to 2019 Joel Matthew Rees\r

 \r
 -----\r
 \r
 \r
 -----\r
 \r


@@ -39,26 +39,35 @@ any purpose with or without fee is hereby granted, provided that the
 accompanying copyright notices and this permission notice appear in \r
 all copies.\r
 \r
 accompanying copyright notices and this permission notice appear in \r
 all copies.\r
 \r

-THE SOFTWARE IS PROVIDED “AS IS” AND ISC DISCLAIMS ALL WARRANTIES \r
-WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF \r
-MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY \r
-SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES \r
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN \r
-AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, \r
-ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS \r
-SOFTWARE.\r
+THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHORS DISCLAIM ALL \r
+WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED \r
+WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE\r
+AUTHORS BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL \r
+DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR \r
+PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER \r
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR \r
+PERFORMANCE OF THIS SOFTWARE.\r

 =========\r
 \r
 I add here the stipulation that I claim right to the word "BIF" as \r
 the name of a programming language.\r
 \r
 If you are going to distribute or redistribute the obect or source of \r
 =========\r
 \r
 I add here the stipulation that I claim right to the word "BIF" as \r
 the name of a programming language.\r
 \r
 If you are going to distribute or redistribute the obect or source of \r

-bif in any of its forms, it really makes no sense not to include the \r
-BIFDOC.TXT and this README.TXT. If you do something like that and \r
-you or anyone that gets the results has problems with it, and you come \r
-to me looking for help, expect to be teased mercilessly about it. And \r
-expect to be on the bottom of my priority list, not out of spite, \r
-out of self-protection.\r
+bif in any of its forms, it really makes no sense at all to fail to \r
+include either the BIFDOC.TXT file and this README.TXT file.\r
+\r
+In the present world, it also makes no sense to fail to include the \r
+source code, or at least a link to a known good repository -- such as \r
+\r
+https://ja.osdn.net/projects/bif-6809/\r
+https://ja.osdn.net/projects/bif-6809/scm/git/bif-6809/\r
+\r
+\r
+If you do something like that and you or anyone that gets the \r
+resulting distribution has problems with it, and somebody comes \r
+to me looking for help, expect to be teased mercilessly about it. \r
+And expect to be on the bottom of my priority list, not out of \r
+spite, out of self-protection.\r

 \r
 -----\r
 \r
 \r
 -----\r
 \r


@@ -146,6 +155,13 @@ Forth style screen listings.
 The program stripln can be used to strip line numbers from such screen \r
 listings, as well. \r
 \r
 The program stripln can be used to strip line numbers from such screen \r
 listings, as well. \r
 \r

+I really should put in more work on the tools for converting between \r
+normal text files and Forth/BIF screens, but those projects aren't even \r
+on my back burners any more. Maybe later. In the meantime, you're \r
+welcome to take a crack at it.\r
+\r
+-----\r
+\r

 The documentation is ASCII text, with CR/LF line termination, and should\r
 be examined carefully by anyone considering a port.  Bear in mind that\r
 it was written toward Color Computer users.\r
 The documentation is ASCII text, with CR/LF line termination, and should\r
 be examined carefully by anyone considering a port.  Bear in mind that\r
 it was written toward Color Computer users.\r


@@ -156,108 +172,242 @@ process of trying to split it up into modules. I haven't had enough time
 to finish the modularization, yet, either. (Getting an iBook so I could \r
 work on the train just gave me more things to do on the train.)\r
 \r
 to finish the modularization, yet, either. (Getting an iBook so I could \r
 work on the train just gave me more things to do on the train.)\r
 \r

-Files in this distribution --\r
+-----\r
+\r
+There are four subdirectories at this point:\r
+\r
+* junkbox -- \r
+\r
+Various tools I've used. Most are one-time tools that might be useful \r
+again in a similar situation.\r
+\r
+* edtasm_v --\r
+\r
+This is where I'm recreating what I used at college, to use as a baseline\r
+in further projects. The code here can be assembled by the disk-based \r
+EDTASM+ tools. \r
+\r
+Put the EDTASM+ disk (image) in the 1st drive (Coco drive 0) and the \r
+source code disk (image) in the 2nd (Coco drive 1). Assemble with \r
+something like\r
+\r
+   AD BIF6809X.BIN:1 /WE\r
+\r
+to save the binary in BIF6809X on the 2nd drive (Coco drive 1) and \r
+wait for errors so you can see what happened before it scrolls off \r
+the screen.\r
+\r
+I've essentially frozen my work on this version, to provide a point\r
+of reference if someone wants to port BIF-6809 to a non-Coco machine.\r
+\r
+See BIFDOC.TXT for further information about use.\r
+\r
+* cross_v --\r
+\r
+I have been using the lwtools assembler and the MAME imgtool utility \r
+as the basis of a cross-assembly environment. (See the commands.txt \r
+file for clues.) At this point, assembly is successful, and execution \r
+succeeds to the point of being able to load the post-fix assembler \r
+which I put together for college, which resides in the tools.dsk image.\r

 \r
 \r

-6809 Assembly Language Source files:\r
+This code is essentially a mirror of edtasm_v, with source code changes\r
+that allow assembly using the lwtools assembler, and line endings \r
+friendly to *nix tools.\r
+\r
+Again, see BIFDOC.TXT for further information about use.\r
+\r
+* reorg_v\r
+\r
+Now that I have the baseline sort-of re-established, and am able \r
+to compile the post-fix assembler and other tools, I'll use the \r
+cross-development tools to reorganize and restructure the code \r
+to make it more generally useful. \r
+\r
+That work will start in reorg_v.\r
+\r
+\r
+===================\r
+\r
+Files --\r
+\r
+-----\r
+* Top-level directory, ./ :\r

 \r
 README.TXT\r
        this file.\r
 \r
 README.TXT\r
        this file.\r

+\r

 BIFDOC.TXT\r
        general explanations, including descriptions of every word.\r
 BIFDOC.TXT\r
        general explanations, including descriptions of every word.\r

+\r
+commands.txt\r
+       *nix command lines that I want to remember. May be useful.\r
+\r
+-----\r
+* edtasm_v/ and cross_v/ :\r
+\r

 BIFU.I\r
        structure of the per-user variable page.\r
 BIFU.I\r
        structure of the per-user variable page.\r

+\r

 BIF.M\r
        macros, including the inner interpreter (basis of the virtual machine),\r
        the dictionary (symbol table) structure offsets,\r
        and invocations for the fundamental objects.\r
 BIF.M\r
        macros, including the inner interpreter (basis of the virtual machine),\r
        the dictionary (symbol table) structure offsets,\r
        and invocations for the fundamental objects.\r

+\r

 BIFDP.A\r
        things kept in the direct page, \r
        including the behaviours for the fundamental objects (was not a good idea after all),\r
        and the index to the per user variable page. \r
 BIFDP.A\r
        things kept in the direct page, \r
        including the behaviours for the fundamental objects (was not a good idea after all),\r
        and the index to the per user variable page. \r

+\r

 BIFST.A\r
        cold and warm boot routines and the initial value table for the per-user variable page.\r
 BIFST.A\r
        cold and warm boot routines and the initial value table for the per-user variable page.\r

+\r

 BIF.ASM\r
        the main source file (includes other parts),\r
        basic expression evaluation, more of the inner interpreter, \r
        basic vocabulary access, basic symbol parsing.\r
 BIF.ASM\r
        the main source file (includes other parts),\r
        basic expression evaluation, more of the inner interpreter, \r
        basic vocabulary access, basic symbol parsing.\r

+\r

 BIFB.A\r
        basic I/O, more of the inner interpreter, extended expression evaluation,\r
        the rest of the basic symbol table access.\r
 BIFB.A\r
        basic I/O, more of the inner interpreter, extended expression evaluation,\r
        the rest of the basic symbol table access.\r

+\r

 BIF1.A\r
        data movers, common expression evaluation,\r
        stack pointer access, more of the inner interpreter,\r
        high-level compiler.\r
 BIF1.A\r
        data movers, common expression evaluation,\r
        stack pointer access, more of the inner interpreter,\r
        high-level compiler.\r

+\r

 BIF1B.A\r
        common expression evaluation, extended expression evaluation,\r
        innards of the high-level compiler, more of the high-level compiler,\r
        compiler directive.\r
 BIF1B.A\r
        common expression evaluation, extended expression evaluation,\r
        innards of the high-level compiler, more of the high-level compiler,\r
        compiler directive.\r

+\r

 BIF2.A\r
        more common expression evaluation, common constants,\r
        I/O constants, character typing constants,\r
        symbol table globals, compiler globals, parser globals, I/O globals.\r
 BIF2.A\r
        more common expression evaluation, common constants,\r
        I/O constants, character typing constants,\r
        symbol table globals, compiler globals, parser globals, I/O globals.\r

+\r

 BIF2B.A\r
        compiler globals, more high-level compiler,\r
        more common expression evaluation, formatted output.\r
 BIF2B.A\r
        compiler globals, more high-level compiler,\r
        more common expression evaluation, formatted output.\r

+\r

 BIF3.A\r
        more basic symbol table, symbol table, more compiler, more formatted output,\r
        more data movers, more low-level parser (formatted input), more I/O,\r
        more extended expression evaluation, more expression evaluation, \r
        more compiler directives, an extension to the inner interpreter.\r
 BIF3.A\r
        more basic symbol table, symbol table, more compiler, more formatted output,\r
        more data movers, more low-level parser (formatted input), more I/O,\r
        more extended expression evaluation, more expression evaluation, \r
        more compiler directives, an extension to the inner interpreter.\r

+\r

 BIF3B.A\r
        more formatted output, more innards of the high-level compiler,\r
        more high-level compiler.\r
 BIF3B.A\r
        more formatted output, more innards of the high-level compiler,\r
        more high-level compiler.\r

+\r

 BIF4.A\r
        more innards of the expression evaluator, more common expression evaluation,\r
        more I/O (buffer handling).\r
 BIF4.A\r
        more innards of the expression evaluator, more common expression evaluation,\r
        more I/O (buffer handling).\r

+\r

 BIF4B.A\r
        more high-level compiler, more compiler directive.\r
 BIF4B.A\r
        more high-level compiler, more compiler directive.\r

+\r

 BIF5.A\r
        more innards of the high-level compiler, more I/O (buffering),\r
        disk access, error handling, more formatted output.\r
 BIF5.A\r
        more innards of the high-level compiler, more I/O (buffering),\r
        disk access, error handling, more formatted output.\r

+\r

 BIF5B.A\r
        more error handling, screen-based sector (character) editor.\r
 BIF5B.A\r
        more error handling, screen-based sector (character) editor.\r

+\r

 BIF6.A\r
        more parser (formatted input), I/O (terminal), compiler (input),\r
        symbol table (lookup).\r
 BIF6.A\r
        more parser (formatted input), I/O (terminal), compiler (input),\r
        symbol table (lookup).\r

+\r

 BIF6B.A\r
        symbol table, compiler innards, null vector test, \r
        more screen-based sector editor.\r
 BIF6B.A\r
        symbol table, compiler innards, null vector test, \r
        more screen-based sector editor.\r

+\r

 BIF7.A\r
        compiler, formatted output, compiler directives\r
 BIF7.A\r
        compiler, formatted output, compiler directives\r

+\r

 BIF7B.A\r
        error handling, symbol tables, compiler directives.\r
 BIF7B.A\r
        error handling, symbol tables, compiler directives.\r

+\r
+bifsource.dsk\r
+       The Color Computer Disk Extended BASIC format disk image with \r
+       the above assembly language source files readable under EDTASM+ . \r
+\r
+       Under cross_v, the only interesting file in bifsource.dsk is the \r
+       object file, BIF6809.BIN, which is the output of the lwtools \r
+       assembler. I'm reusing the disk image from edtasm_v for my own \r
+       convenience. \r
+\r
+tools.dsk\r
+       The startup disk for the FORTH/BIF system. \r
+\r
+       You basically want this disk (image) in your first drive whenever\r
+       bif-6809 is running.\r
+\r
+       Important contents include the following:\r
+\r
+       SCREEN 0: Human readable index. (Forth had no file system of its own.)\r
+\r
+       SCREEN 4: Human readable error message text. \r
+\r
+       SCREEN 6: Basic disk SCREEN (sector, for Coco) listing and editing tools.\r
+\r
+       SCREEN 16: Post-fix assembler.\r
+\r
+       Once you get used to it, you can copy the error messages in \r
+       SCREEN 4 of the tools.dsk (image) to a fresh disk (image) and \r
+       use it instead. (And you'll probably want SCREENs 6-15, as well.)\r
+\r
+blank.dsk (not present)\r
+       You can make blank, unformatted disk images with a *nix command\r
+       something like\r
+\r
+       dd if=/dev/zero of=blank.dsk bs=256 count=630\r
+\r
+-----\r
+* reorg_v\r
+\r
+(More later.)\r
+\r
+\r
+-----\r
+* junkbox\r
+\r

 stripln.c,\r
 32col.c, \r
        C language source and Macintosh executables for stripping line \r
        numbers and reformatting 32 column source code "screens". The two \r
        XXX.GXX.out files below are output of the 32col program.\r
 \r
 stripln.c,\r
 32col.c, \r
        C language source and Macintosh executables for stripping line \r
        numbers and reformatting 32 column source code "screens". The two \r
        XXX.GXX.out files below are output of the 32col program.\r
 \r

------\r
-\r
-Hopefully, I will shortly have time to reconstruct useful things from the \r
-following files on the tools.dsk disk image and/or the cs431 disk image:\r
-\r

 TOOLS.G00, TOOLS.G00.out\r
        FORTH source for disk listing, screen handling, definition dumping, \r
        sector copying, forward referencing, buffer maintenance, \r
        experimenting with hardware, double (32 bit) integer math, etc.,\r
        and a post-fix assembler.\r
 TOOLS.G00, TOOLS.G00.out\r
        FORTH source for disk listing, screen handling, definition dumping, \r
        sector copying, forward referencing, buffer maintenance, \r
        experimenting with hardware, double (32 bit) integer math, etc.,\r
        and a post-fix assembler.\r

+\r
+       This is how I brought the contents of the tools.dsk image with \r
+       me. Probably not useful to anyone except me.\r
+\r

 PAIRS.G28, PAIRS.G28.out\r
 PAIRS.G28, PAIRS.G28.out\r

-       a "database" example from one of my FORTH books.\r
+       a "database" example from one of my FORTH books. Might be \r
+       interesting for those wondering how the dictionary (symbol\r
+       table) works.\r
+\r

 TOOLS_G00_ERRORS.text\r
        Contains the tools output readable in regular text editor format \r
        and the error messages, with their corresponding number in \r
        hexadecimal. I should make a separate file for the error messages\r
        (or something).\r
 \r
 TOOLS_G00_ERRORS.text\r
        Contains the tools output readable in regular text editor format \r
        and the error messages, with their corresponding number in \r
        hexadecimal. I should make a separate file for the error messages\r
        (or something).\r
 \r

-and\r
+       This may be useful for understanding the contents of tools.dsk .\r

 \r
 SCR33.ARR\r
 \r
 SCR33.ARR\r

-       arrays for CS431.\r
+       One way to do arrays. Probably not useful for anyone except me.\r
+\r

 SCR34.LOC\r
 SCR34.LOC\r

-       some math for CS431.\r
+       Some random math. Probably not useful for anyone except me.\r
+\r

 SCR40.431\r
 SCR40.431\r

-       test suite for CS431.\r
+       A test suite. Probably not useful for anyone except me.\r

 \r
 \r

+===================\r

 \r
 \r
 \r
 \r