Reorganize and expand docs

1 files changed, 17 insertions, 278 deletions

diff --git a/README.txt b/README.txt
index 6d9738b..df75265 100644
--- a/README.txt
+++ b/README.txt
@@ -1,10 +1,11 @@
 Taipan for Atari 800
+--------------------
 
 This is a work in progress. It's a port of the C version for Linux and
-curses, modified to look and play more like the original Apple II version.
+curses, modified to look and play more like the Apple II version.
 
 Currently the game is playable and complete, but has a few known bugs
-(see "Bugs" section below) and probably a few unknown ones too.
+(see BUGS.txt) and probably a few unknown ones too.
 
 The latest version of the source can be found here:
 https://slackware.uk/~urchlay/repos/taipan
@@ -15,288 +16,26 @@ https://slackware.uk/~urchlay/src/taipan.xex
 
 ...though it might be outdated.
 
-Linux/curses port can be found here:
+The Linux/curses port I used as a starting point can be found here:
 http://www.ibiblio.org/pub/linux/games/textrpg/
 
-Original Apple II BASIC source, plus a browser version of the game,
+The Apple II BASIC source, plus a browser version of the game,
 can be found here: http://www.taipangame.com/
 
 What's missing:
 
-- Large integer (or floating point) support for Debt and Cash (the
-  Bank is floating point though). As a side effect of this, the "negative
-  interest" bug/feature is missing.
+I mention this up front, because some players consider this a major
+issue: The "negative interest" bug/feature/cheat doesn't work. If you
+never heard of it, don't worry about it: It's more fun to play without
+cheating anyway.
 
-Build Requirements:
 
-- make. I use GNU make 3.82, and occasionally test with an old
-  version of BSD make (which works).
+Further Documentation
+---------------------
 
-- cc65. Originally I used version 2.13.3, and part way through I
-  upgraded to a git snapshot dated December 29, 2015. Building with
-  cc65-2.3.13 is probably broken right now, but it will be supported
-  again.
-
-- gcc. I use version 4.8.2. Probably any version will do. It's only
-  needed for convfont.c (and there's nothing gcc-specific about it,
-  so really you just need any C compiler, see HOSTCC in the Makefile).
-
-- perl. I use version 5.18.1, probably any 5.x version will work.
-
-- perl's Image::Magick module (which in turn requires the C ImageMagick
-  library). I use version 6.8.6, probably any recent version will do.
-
-- git. You don't exactly *need* this to build the code, but if you
-  have it, the git hash will be built into the binary and appear on
-  the title screen.
-
-- A UNIX/POSIX environment. At least, you need a 'cat' command and
-  a shell that does I/O redirection. Linux, BSD, and Mac OS X should
-  be fine. If you're on Windows, try Cygwin.
-
-If you plan to edit the port status screen, you'll need the Atari800
-emulator. It's also handy for actually playing the game, whether you
-build it or use the provided binary.
-
-
-Building:
-
-Hopefully you can just type "make" to create the taipan.xex binary. If
-it doesn't work, you're likely missing one or more of the requirements
-listed above.
-
-If you'd prefer a cartridge image, "make cart" will build both a raw image
-(taipan.rom) and an image with an Atari800 CART header (taipan.cart).
-
-
-Running:
-
-The game binary is called "taipan.xex". It's a standard Atari DOS
-'binary load' file, which expects to be run with BASIC disabled and no
-cartridges inserted.
-
-You can run it on a real Atari computer: any 400/800/XL/XE model should
-be fine, so long as it has at least 48K of RAM. Use a SIO2PC cable and
-software like Atariserver (Linux) or APE (Windows) to serve the game to
-the Atari. If you can come up with a way to actually copy it to a real
-floppy disk, you probably want a bootable DOS disk with Taipan renamed
-to AUTORUN.SYS.
-
-It's also possible to run Taipan in an emulator, such as Atari800,
-Atari++, or Altirra. For Atari800, you should be able to do this:
-
-atari800 -nobasic taipan.xex
-
-The cartridge image is a 64KB XEGS bankswitched cartridge (what Atari800
-calls "type 13"). It can be run in the emulator thus:
-
-atari800 taipan.cart
-
-For burning to an EPROM, you'll need to build or scavenge a cartridge
-with the correct banking logic, and burn taipan.rom to a 64KB chip.
-
-Unlike the .xex version, the cartridge will work on a 32KB Atari.
-
-Coming soon: You will also be able to purchase a Taipan cartridge from
-the AtariAge store.
-
-
-License:
-
-The legal status of this is quite murky. The original game is still
-copyrighted, though quite a few clones of it have been made for various
-platforms over the years with no complaints from the copyright holder.
-
-This Atari port includes font and graphics data ripped straight from
-the original Apple game, plus more font data ripped from the Atari 800's
-OS ROM.
-
-The Linux port of taipan, according to its .lsm file, is GPL (version
-uspecified). My C code is definitely a derivative work, so it's GPL
-also. The assembly code and host tools (convfont, mkcart) are my own work,
-and I release them under the GPL (version 2).
-
-Notes:
-
-The Atari executable file format allows for concatenating executables.
-The result is still a valid executable. I use this to load the splash
-screen and custom font directly into memory before the main program loads.
-The Makefile documents how all this works, but it might seem pretty
-hairy if you're new to the Atari, Makefiles, and/or Perl.
-
-The Apple version of the game was expected to be run on a monochrome
-monitor. Like many other ports from the Apple to the Atari, there will
-be color artifacts when using a composite monitor. For best results,
-use a monochrome monitor. If you can't, at least try using a color
-monitor with S-Video (separate chroma/luma) inputs. If all else fails,
-try turning the color knob all the way down (and the contrast as high
-as you can stand it). In emulators, you can just disable artifacting.
-
-On PAL systems, the ship explosions and sinking animations will be 20%
-slower, and the prompt timeouts will be 20% longer (1 sec => 1.2 sec). I
-don't think this is a real issue (it's not like Taipan is a fast-paced
-arcade game).
-
-BUGS! At least these:
-
-- The "negative interest" bug is currently missing, due to using
-  unsigned values for debt. Plus, it's cheating. I'm undecided
-  whether or not to use a bignum for debt; if I do, it will be
-  possible to have negative debt.
-
-- Not really a bug, but, the interest calculation for debt is slightly
-  different, due to using integer math. Very small debt amounts will grow
-  much faster than they should, then stabilize and converge towards the
-  correct values over time. This only happens when you have less than
-  10 in debt, which (at least for me) is a pretty rare situation.
-
-- A few things in the screen layout are slightly off comapred to
-  the Apple version. Would really like to get it exact.
-
-- The 'Please limit your firm name to 22 characters' prompt is missing.
-  The Apple version actually allows you to type all you want until you
-  press Enter. This port works like the Linux version: as soon as you type
-  the 22nd character, it acts like you pressed Enter after it.  A good
-  compromise might be to allow up to 22 characters, then any keypress
-  other than backspace or enter will show the "please limit" prompt.
-
-- Damaged ship graphics need work. I don't have enough unused font
-  characters to duplicate the Apple bitmapped graphics exactly, plus
-  each damage location must fit entirely within a character cell... but a
-  couple of my damaged sections are pretty hokey-looking. Also, now that
-  I'm using the graphical title screen, I have a few more characters I
-  can redefine as damaged ship sections.
-
-Deliberate differences between the Apple II and Atari ports:
-
-1. "Press ESC for help" rather than ESC to start. Starting the game is
-   done with the space bar or return key.
-
-2. I made it possible to disable the sound, since it's kinda repetitive
-   and annoying, plus the game "freezes" while sounds are playing (no
-   threading on Atari!) which slows down gameplay.
-
-3. Added a way to change the background color and text brightness. Only
-   4 brightness levels, but all 16 Atari hues are available.
-
-4. Prompts that only accept one character no longer require pressing Enter.
-   Gameplay is more streamlined this way. Apple and Linux are inconsistent:
-   some prompts need Enter, some don't. In the Atari port, the only prompts
-   that require Enter are:
-   - naming your firm
-   - entering an amount of cash or items (but not if you hit A for "all")
-
-5. "We have 5 guns" is in an inverse video box. I think it looks nicer, and
-   it matches the "You can afford 5" inverse video box on the trading
-   screen.
-
-6. The + that indicates more ships offscreen is inverse video. I find
-   that I don't notice it's there, if it's normal video.
-
-7. "You're ship is overloaded" => "Your ship is overloaded". Sorry,
-   grammar nazi.
-
-8. Updating the port status screen, and text printing in general, happens
-   faster and cleaner-looking, due to using C and asm rather than BASIC,
-   and also because the static parts of the screen aren't redrawn unless
-   they need to be. (Grammar nazi? That's a run-on sentence...)
-
-10. Apple uses floating point, no practical limit on cash/bank/debt.
-    Atari currently uses 32-bit unsigned longs for cash and debt,
-    though the bank is now floating point. This leads to these gameplay
-    changes:
-
-    - If you try to make a sale, take out a loan, or withdraw from the bank
-      an amount that would put you over 4.3 billion cash, you get a
-      message "you cannot carry so much cash", and the transaction is
-      aborted.
-
-    - If your debt goes above 2 billion, you die and the game is over.
-
-    Making cash a floating point value is possible, but not worth the
-    effort as it's a *terrible* idea to carry billions (or even millions)
-    of cash around, due to the possibility of getting robbed. By the time
-    someone plays the game long enough to earn billions in cash, he'll know
-    to leave most of it in the bank, not carry it around.
-
-11. On Apple, price of General Cargo isn't always an integer (e.g. 6.5).
-
-12. On Apple, dead enemy ships sink one scanline at a time, and there are
-    at least 2 sinking speeds. On Atari, it's one character (8 scanlines)
-    at a time, and the speed is always the same.
-
-13. When entering numeric amounts, the Atari Shift-Delete key works as
-    expected.
-
-14. When entering numeric amounts, pressing K or M inserts 3 or 6 zeroes.
-    This means you can type e.g. 100,000 as 100K, and 10,000,000 as 10M.
-
-15. When playing on an 800, the standard Atari keyclicks will be heard.
-    Disabling these on an 800 is non-trivial. On XL/XE machines, they are
-    disabled to mimic the Apple version.
-
-
-Differences between the Apple II original and Linux port:
-
-1. Linux has an 80-column screen layout, Apple is 40.
-2. Apple version uses a custom font (actually, two, but I'm ignoring that).
-3. Apple has sound, Linux does not.
-4. Apple has graphical title screen, Linux has ASCII art.
-5. Apple has graphical ships during battles, Linux has ASCII art.
-6. On Apple, price of General Cargo isn't always an integer (e.g. 6.5).
-   As a consequence, the cash and bank amounts aren't always ints either.
-7. On Apple, some Y/N prompts (like 'Do you have business with Elder Brother
-   Wu') you can press Enter for No. Linux port waits until you hit Y or N.
-8. On Apple, ships show damage (get holes in them) as they get shot up.
-9. On Linux, you can overpay McHenry (though you get no benefit from it).
-   On Apple, payment amount gets clamped to the repair price, so you can
-   e.g. be asked to pay 50,000 when you have 70,000 and safely enter A
-   (you'll end up 100% repaired and still have 20,000 cash).
-10. On Apple, dead enemy ships sink one scanline at a time, and there are
-    at least 2 sinking speeds. On Linux, it's one character at a time.
-
-The plan for the Atari port is to mimic the Apple version as closely as
-possible... except #6 above. It doesn't really add anything to the game,
-and it complicates the code more than I want to deal with. Also #10
-will probably not happen (to me, the slow ship-sinking of the Apple
-version is annoying anyway).
-
-Right now, items 1, 2, 3, 4, 5, 7, 8, and 9 are implemented Apple-style;
-and 6, 10 are Linux-style.
-
-Future Ideas:
-
-I may do a "Taipan Plus" at some point. The regular Taipan game will be
-faithful to the original, and the Plus version could have some or all of:
-
-- More ports to dock at, some of which might have their own warehouses,
-  repair yards, etc.
-
-- More trade goods, not all of which are available at all ports.
-
-- Actual market trends, rather than a base price + random number. There
-  might be news events that cause prices to go up/down (e.g. Arms are
-  up at Saigon because there's a gang war in progress, Opium is up at
-  some port but the chances of getting busted are higher). This feature
-  actually exists in Art Canfil's TRS-80 Taipan "version 10".
-
-- Ability to control a fleet of ships. Each one will either be a cargo
-  ship or a warship.
-
-- A "Turbo Combat" feature like one of the phone versions I've seen. You
-  set your orders and hit Turbo, and it finishes the fight instantly,
-  but you can't change your mind about your orders (fight until you win
-  or die, or run until you escape or die).
-
-- Special missions. Someone at some port needs you to transport documents
-  or whatever, to some other port... you will almost certainly be attacked
-  by whoever's trying to get the documents though.
-
-- Rival trading companies. Their activities can influence prices, and
-  you can fight them and possibly salvage actual cargo.
-
-- Variable passage of time. Distant ports take longer to get to. Also,
-  winds or ship damage can slow you down.
-
-I dunno how many of the above will fit in the Atari's RAM. Probably have
-to rewrite the whole game from scratch in assembly before adding features.
+GAMEPLAY.txt - user's manual, explains how to play Taipan.
+RUNNING.txt - instructions on how to run Taipan.
+BUILDING.txt - build instructions, for compiling Taipan yourself.
+BUGS.txt - guess what this is?
+NOTES.txt - implementation details, blue-sky plans.
+LICENSE.txt - legal stuff. Or possibly not.