Reorganize and expand docs

7 files changed, 515 insertions, 278 deletions

diff --git a/BUGS.txt b/BUGS.txt
new file mode 100644
index 0000000..9d9f429
--- /dev/null
+++ b/BUGS.txt
@@ -0,0 +1,30 @@
+Bug List for Atari 8-bit Taipan
+-------------------------------
+
+- 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 compared 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 would 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.
diff --git a/BUILDING.txt b/BUILDING.txt
new file mode 100644
index 0000000..3a7adf5
--- /dev/null
+++ b/BUILDING.txt
@@ -0,0 +1,47 @@
+Build Requirements for Atari 8-bit Taipan:
+
+- make. I've used GNU make 3.82 and 4.1. I also occasionally test
+  with an old version of BSD make, but not often. If you can't get
+  BSD make to work for you, install gmake from ports/pkgsrc or whatever
+  your platform uses.
+
+- cc65. At least version 2.15. 2.13.x and 2.14 are specifically known
+  not to work. To build the regular executable (taipan.xex), you can
+  use any version from 2.15 to 2.19 (latest as of this writing). To
+  build the cartridge image, you specifically need cc65 2.15 (newer
+  versions won't do, until I fix it).
+
+- gcc. I've used versions 4.8.2 and 5.5.0. 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 used version 5.18.1 and later upgraded to 5.22.2. Probably
+  any 5.x version will work.
+
+- perl's Image::Magick module (which in turn requires the C ImageMagick
+  library). I've used versions 6.8.6 and 6.9.4, 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). You'll
+specifically need cc65 version 2.15 for this (for now, anyway).
diff --git a/GAMEPLAY.txt b/GAMEPLAY.txt
new file mode 100644
index 0000000..ab937ee
--- /dev/null
+++ b/GAMEPLAY.txt
@@ -0,0 +1,128 @@
+
+Note: This manual is nowhere near complete!
+
+User's Manual for Atari 8-bit Taipan
+------------------------------------
+
+To play Taipan, first load the game from disk or insert the
+cartridge. See RUNNING.txt for details on how to load the game.
+
+
+Gameplay Summary
+----------------
+
+Taipan is turn-based. Each turn consists of a trading phase (when your
+ship is in port) and a transport phase (when your ship is sailing to
+another port). If you're attacked by pirates during transport, there
+is also a combat phase.
+
+During trading, you can buy and sell cargo at any port. Hong Kong is
+your home port: that's where your bank and warehouse are located,
+so when you're in Hong Kong you have the option to Visit Bank and
+Transfer Cargo.
+
+Hong Kong is also where the shipyard is located. If your ship is
+damanged, repairs are available (for a price) when you arrive in
+Hong Kong.
+
+There's also a gentleman known as Elder Brother Wu in Hong Kong. He
+loans money and collects donations for the local church, and is
+rumored to have connections with Li Yuen's pirate gang.
+
+When you're ready to leave port, choose Quit Trading from the menu.
+You'll be asked for a destination, and then your ship will set sail.
+This is the transport phase of the turn.
+
+During transport, you might encounter a storm at sea. If this
+happens when your ship is heavily damaged, there's a chance your
+ship will sink, so make sure to keep your ship in good repair. Even
+a well-maintained ship can be blown off course (to some other port
+besides your chosen destination).
+
+You also might get attacked by pirates. If this happens, you enter the
+combat phase of the turn. Otherwise, you'll arrive in port and begin
+your next turn.
+
+During combat, you have three choices: Fight, Run, or Throw Cargo. If
+your ship doesn't have any guns, don't bother trying to fight. Running
+away is always an option, but the enemy will chase you, so you can't
+always escape right away. Throw Cargo means you have your crew throw
+some of your cargo into the water, in hopes that it will distract the
+pirates or satisfy their greed, allowing you to get away safely.
+
+When the battle first starts, you choose between Fight, Run, or Throw
+Cargo. During the fight, you can change your orders at any time by
+pressing the key for the new order (F, R, or T).
+
+
+Details
+-------
+
+Once the game is loaded, you'll see the title screen, with a picture
+of a sailing ship (a lorcha, to be exact). At the title screen, you
+can customize gameplay before starting the game, using these keystrokes:
+
+B - Change background color. This cycles through all 16 hues available
+    on the Atari.
+T - Change text brightness. Cycles through 4 levels, from bright to dark.
+S - Enable/disable sound. This controls the "whistle" alert sounds in the
+    game, but not the key click sound. On XL/XE machines, the keyclick
+    will be disabled; on 400/800 it will be enabled.
+Space or Return - Start the game. For the disk version, the rest of the
+    game will load from disk (once it's loaded, you can turn off the drive;
+    Taipan doesn't use it). For the cartridge version, the game starts
+    immediately.
+Escape - Shows help, listing the above keystrokes on the bottom line of the
+    screen. Each press of Escape cycles to the next keystroke.
+
+When the game starts, the first thing you'll do is "name your firm". This
+is the name of your trading company, and can be anything you like, up to
+22 characters. The name doesn't affect gameplay; it's just for fun.
+
+The next screen offers you the choice of starting with either:
+
+1 - Cash, and a debt (but no guns)
+2 - 5 guns, no cash, and no debt.
+
+Your ship has a cargo capacity of 60 units either way, but each gun
+takes up 10 units so option 2 gives you only 10 units for carrying
+cargo. Later in the game, you'll get the options to buy guns and
+upgrade your ship to higher capacity.
+
+If you choose option 1, you can start trading immediately, but
+remember to pay back your debt to Elder Brother Wu (he lives in Hong
+Kong; go there to make payments). Very Bad Things can happen to those
+who ignore this advice. The debt has interest that accrues every turn,
+so don't wait too long. You'll also have to run if you get attacked
+(or throw cargo, once you've bought some): You won't have guns to
+fight back with, at first.
+
+With option 2, it takes longer to start trading. You'll have to sail
+around to different ports, waiting to be attacked by pirates. If you
+defeat them in battle, you'll collect plunder from them in the form
+of cash, which you can use to start trading. However, you won't get
+very rich with only 10 cargo units on your ship, so upgrade as soon
+as you get the offer!
+
+Once you've made the choice, the game proper begins. You'll start out in
+Hong Kong. Whenever you're in a port, the Status screen is displayed. This
+shows lots of information [todo, fill in]
+
+Trading in the world of Taipan works just like real life: buy low and sell high.
+There are 4 cargo types, in order from least expensive to most:
+
+General Cargo - this is the miscellaneous stuff that cargo ships
+carry. It might be raw materials (sugar, tar, coffee, pig iron), or
+finished goods (casks of wine, clothing, jewelry). To simplify gameplay,
+these are lumped together as one category.
+
+Arms - Weaponry. Muskets (flintlock and otherwise), swords, etc. You
+can't use these to fight other ships; they're just cargo, but
+commanding a better price than General Cargo.
+
+Silk - Bolts of raw silk cloth. Pretty expensive stuff.
+
+Opium - A highly addictive drug, but not without medical uses. It's
+risky to trade in opium becase it's illegal in most ports. However,
+the potential gains may be worth the risk.
+
diff --git a/LICENSE.txt b/LICENSE.txt
new file mode 100644
index 0000000..4c3d426
--- /dev/null
+++ b/LICENSE.txt
@@ -0,0 +1,39 @@
+License Info for Atari 8-bit Taipan
+-----------------------------------
+
+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 (whoever that actually is).
+
+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). It's very obviously a derivative work of the Apple
+BASIC version, so I'm not sure it was really legal to release as
+GPL. But it's been out there for decades unchallenged... My C code is
+definitely a derivative work of the Linux port, so it's GPL also. The
+assembly code and host tools (convfont, mkcart, etc) are my own work,
+and I release them under the GPL (version 2).
+
+I'm not sure how to handle binary redistributions. Most people are
+just going to grab the taipan.xex file and use it, and it'll end up in
+various Atari archives. If I *don't* provide a binary, *nobody but me*
+will ever play this game (seriously, there aren't a lot of Atari 8-bit
+gamers who also would know how to set up a build environment for cc65,
+or even be interested in trying).
+
+Since the Atari is such a limited platform, I can't really include
+e.g. clickable (or even copy/pastable) links pointing to the
+source. Including the text of the GPL in the binary is impossible,
+or at least impractical: the GPLv2 license is around 18KB in size, or
+approximately half the usable memory in an Atari, or 2/3 the size
+of the existing Taipan binary.
+
+I hate to be this way but... I'm going to just allow binary
+redistribution, unless/until the author of the Linux Taipan C game
+complains about it. And when he does, I'm going to ask him if he
+actually got permission from the author of the Apple BASIC version to
+release his derivative work as GPL.
diff --git a/NOTES.txt b/NOTES.txt
new file mode 100644
index 0000000..6d8d37f
--- /dev/null
+++ b/NOTES.txt
@@ -0,0 +1,174 @@
+Notes for Atari 8-bit Taipan
+----------------------------
+
+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).
+
+
+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:
+
+- A 5200 version. Most of the existing code will work there, but there's
+  no keyboard, have to use the keypad on the joystick. Y/N prompts could
+  use 1/0 and/or the side buttons, naming the firm would go away (just
+  hardcode "Atari, Inc" or somesuch as the firm name), entering amounts
+  would use the keypad (# and * for A and Enter, maybe the side buttons
+  for K and M). Cargo types might be 1 for General Cargo, 2 for Arms,
+  etc (have to display that on screen), and have "1-Fight, 2-Run, 3-Throw
+  Cargo" in combat.
+
+- Seen on a web version of Taipan played on a phone: A Turbo option for
+  combat. Basically you press T to skip all the delays. It's still
+  possible to change your orders in mid-fight, but you have to be
+  quick. My implementation of this will make Turbo a toggle, not sure
+  if the web version does that. There will be some kind of indicator
+  "Press T for Turbo", which changes to "Turbo mode: Press T for normal",
+  something like that.
+
+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.
+
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.
diff --git a/RUNNING.txt b/RUNNING.txt
new file mode 100644
index 0000000..87b53d2
--- /dev/null
+++ b/RUNNING.txt
@@ -0,0 +1,80 @@
+Running Taipan on a real or emulated Atari
+------------------------------------------
+
+Even though this version of Taipan is written more-or-less in C,
+it's not portable to other platforms. You can't compile it for Linux
+or Windows. To run it, you have to use an Atari 8-bit computer, real
+or emulated.
+
+Disk Executable
+---------------
+
+The game binary is called "taipan.xex". It's a standard Atari DOS
+'binary load' file, which expects to be run with no cartridges
+inserted. It may or may not work with a cartridge in, depending on
+which cart (some don't allow disk boots, and it has to be an 8K cart,
+not 16K). On XL/XE machines, you don't have to hold down Option to
+disable BASIC.
+
+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 40K 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. Other options are MyPicoDOS (supports fast SIO if your
+drive does) and Fenders 3-sector loader.
+
+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
+
+For atari++, use:
+
+  atari++ -image.1 taipan.xex
+
+For Altirra, try this:
+
+  Altirra /run taipan.xex
+
+For 64-bit builds of Altirra:
+
+  Altirra64 /run taipan.xex
+
+[Altirra instructions courtesy of MoparStephen, with thanks]
+
+
+Cartridge
+---------
+
+The cartridge image is a 32KB XEGS bankswitched cartridge (what
+Atari800 and Altirra call "type 12"). Two ROM images are built:
+
+taipan.cart is a "tagged" cartridge image, for use with emulators that
+know how to read the cartridge type from the CAR header.
+
+taipan.rom is the raw ROM image, exactly 32KB in size. Use this with
+emulators that don't understand CAR headers. This is also what you'd
+use on real hardware. For burning to an EPROM, you'll need to build
+or scavenge a cartridge with the correct banking logic, and burn
+taipan.rom (the raw ROM image) to a 32KB chip. You could also use a
+multi-cart (flash or similar).
+
+The cartridge can be run in the Atari800 emulator thus:
+
+  atari800 taipan.cart
+
+For atari++, use the raw ROM image, since it doesn't support .cart
+images:
+
+  atari++ -cartpath taipan.rom -carttype xegs
+
+For Altirra, one of these should work:
+
+  Altirra taipan.cart
+  Altirra64 taipan.cart
+
+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. Maybe.