initial commit

1 files changed, 239 insertions, 0 deletions

diff --git a/fenders.rst b/fenders.rst
new file mode 100644
index 0000000..9c4f1c7
--- /dev/null
+++ b/fenders.rst
@@ -0,0 +1,239 @@
+.. RST source for fenders(1) man page. Convert with:
+..   rst2man.py fenders.rst > fenders.1
+.. rst2man.py comes from the SBo development/docutils package.
+
+=======
+fenders
+=======
+
+---------------------------------------------------------------
+Install Fenders 3-sector loader in boot sectors of an ATR image
+---------------------------------------------------------------
+
+.. include:: manhdr.rst
+
+SYNOPSIS
+========
+
+*fenders* [*-hrcsiv*] [-t *title*] *infile.atr* [*outfile.atr*]
+
+DESCRIPTION
+===========
+
+**fenders** replaces the boot sectors of an ATR image  with  a  menu-driven
+"game dos" binary loader.
+
+When  the  disk  is  booted,  a disk directory menu is displayed on the
+screen.  To load a binary  (XEX/COM/BIN/etc)  file,  press  the  letter
+shown for that file. Other file types may not be loaded (and will cause
+the Atari to crash).
+
+The installed bootloader overwrites sectors 1-3 of the image
+(and  sector 720, for double-density images). This is the same code
+installed by the Atari-based **Fenders 3-sector** loader installer
+utility.
+
+
+OPTIONS
+=======
+
+-h
+      Print this help message.
+
+-r
+      DON'T reboot (coldstart) the Atari if Reset is pressed. The  default is to coldstart.
+
+-c
+      Rotate colors during load. May cause problems with some games.
+
+-s
+      Screen  off  after load. May cause problems with some games, but
+      may fix graphics corruption for other games. YMMV.
+
+-i
+      In-place update. The input file is renamed to end in **~**  (tilde),
+      and  the  output is written to the original filename. May not be
+      used when reading from standard input.
+
+-v
+      Set inverse video bit in title. This causes the  title  text  to
+      appear  in  red and/or blue on the Atari, instead of the default
+      orange and green colors.
+
+-t
+      Set the menu title. May up to 20 characters;  default  is *atari
+      arcade*.  Will be truncated to 20 characters if a longer title is
+      given. See MENU TITLE, below. Note that you'll have to quote the
+      title  if it contains spaces or other characters that have meaning to your shell.
+
+infile
+      The ATR image to read from. It must be either  single-density
+      and  at  least  368 sectors long, or double-density and at least
+      720 sectors long.  You may use **-** for *infile* to read  from
+      standard input (unless **-i** is used).
+
+outfile
+      The  ATR  image  to create, which will contain all the files
+      from the input image, plus the Fenders  boot  loader.   You  may
+      omit  *outfile*  or use **-** to write to standard output.  *outfile* is
+      ignored when the **-i** option is used.
+
+If both *infile* and *outfile* are omitted, the default  is  to  read  from
+standard input and write to standard output.
+
+NOTES
+=====
+
+**fenders**  will abort, if asked to write to standard output when standard
+output is a terminal. This is to avoid spewing binary garbage  to  your
+terminal.
+
+The  **-r**, **-c**, **-s**, and **-t** options actually modify the **fenders** 6502 object
+code before writing it to the ATR image.
+
+The Atari **fenders** installer's default is to not coldstart, which
+tends to  cause  the  Atari  to lock up when Reset is pressed. The
+author believes that rebooting the Atari is more useful than locking
+it  up,  so **fenders** causes the coldstart by default.
+
+The Atari **fenders** installer contains a bug: the meanings of the "Rotate
+color" and "Screen off after load" options are reversed.  **fenders**  does
+not duplicate this bug.
+
+The disk density doesn't have to be specified, because **fenders** reads it
+from the ATR header. The loader's 6502 object code  is  different,  for
+single- and double-density disks.
+
+The  double-density  version  of  the  loader isn't actually a 3-sector
+loader.  The first 384 bytes of its code are stored in the 3 boot  sectors, and the last 256 bytes of code are actually read from sector 720.
+When installing the boot loader on a double-density disk, sector 720 is
+**overwritten**.  Any data that may have been there is lost. On most disks,
+sector 720 is either unusable by DOS, or not used unless  the  disk  is
+completely full, so this is less of a problem than you might think.
+
+**fenders**  and  the  **fenders** boot-loader code will work with DOS
+2.5 "enhanced density" formatted floppies, but only partially: files
+that  use sectors above 720 will not appear in the menu (these are the
+same files that DOS 2.5 lists with <> around the filename).
+
+**fenders** only works on Atari DOS 2.x and compatible (MyDOS, DOS  XL,  et
+al) single-sided disk images, either single-density (720 sectors, 90K),
+double-density (720 sectors, 180K), or "1050  enhanced"  density  (1040
+sectors, 130K, although 1050 enhanced density images must be in DOS 2.5
+format, *not* MyDOS, and see **LIMITATIONS** below).  Other non-standard  DOS
+formats  such  as SpartaDOS or Atari DOS 3.0 and 4.0 are not supported.
+Atari DOS 1.0 may or may not work (untested).
+
+The **fenders** boot loader source code distributed with **fenders**
+is not the original  source  code  (which  has never been
+released). The author of **fenders** spent a couple of days with a
+disassembly of  the  object  code and reverse engineered (labelled,
+commented) it so that humans can read it, provided they are humans who
+speak 6502 assembly. The  *fenders.dasm* and  *fendersdbl.dasm*  files
+can be assembled with the DASM cross assembler. The resulting object
+code is identical with the original  **fenders** object  code  (which
+the  author  read  from a disk image in the first place).
+
+Contrary to what you may  have  read,  the  Fenders boot  loader  code
+doesn't  have  to  be  rewritten  to a disk if you add/delete files. It
+reads the disk directory, and can cope with changes just fine.  Even  a
+heavily fragmented filesystem won't cause any problems.
+
+MENU TITLE
+==========
+
+The menu title (set with **-t**) is stored in sector 3 for a
+single-density disk or sector 720 of a double-density disk, in Atari
+internal  screen codes (which are not the same as either ASCII or
+ATASCII). fenders converts the title into internal codes, so the user
+doesn't have to  worry about this.
+
+The  menu  title is displayed in "GRAPHICS 2" mode, which can only
+display 64 different characters, including uppercase, numbers, and
+(most) punctuation, but NOT including lowercase or inverse video.
+
+However, lowercase letters are displayed as different-colored
+uppercase letters, and inverse characters are also displayed with
+different  colors.   The  boot  loader  uses  the default Atari
+colors, as set by the Atari OS.
+
+The title is limited to 20 characters because that's  the  width  of  a
+GRAPHICS 2 line of text on the Atari.
+
+The character set used by GRAPHICS 2 consists of:
+
+- The space character.
+
+- The letters **A-Z**.
+
+- The numbers **0-9**.
+
+- Punctuation: **!** **"** **#** **$** **%** **&** **'** **(** **)** **\*** **+** **,** **-** **.** **/** **:** **;** **<** **=** **>** **?** **@** **[** **\\** **]** **^** **_**
+
+Uppercase letters, numbers, and punctuation are displayed in orange (or
+blue, if **-v** is used).
+
+Lowercase letters are displayed in green (or red, with **-v**).
+
+The characters ` { | } ~ are displayed as green (or red) versions of
+@ [ \ ] ^, respectively.
+
+Currently, it's not possible to mix  normal  (orange/green)  characters
+with  inverse  (blue/red) with fenders, unless your terminal provides a
+way for you to enter ASCII characters with their high  bits  set.  Some
+versions of xterm(1x) allow this with the Alt or Meta key.
+
+LIMITATIONS
+===========
+
+**fenders**  should  warn  if  the  disk image contains more than 20 files,
+since they won't all be displayed in the menu.
+
+Double-density images less than 720 sectors long are not  handled,
+although they could be with a little more work.
+
+For  double-density  disks,  the  VTOC  and sector link bytes should
+be checked to see if sector 720 is in use, rather than just blindly
+overwriting it. On a single-density DOS 2.0S disk, sector 720 is
+marked "in use" in the VTOC when the disk is formatted, but will never
+be used for file storage.
+
+No checking for non-standard formats (SpartaDOS, DOS 3, MyDOS with
+subdirectories, dedicated bootdisks, etc) is done.
+
+If an "enhanced" 1050 density disk image has the bootloader  installed,
+it  won't  display  the  files  using sectors above 720 (the ones which
+would appear as *<filename.ext>* in the DOS 2.5 directory).
+
+Actually, the above limitations are a direct result of  the  fact  that
+**fenders**  deals  with the disk image at the "sector" level, and contains
+no code that understands the files, directory, or VTOC  on  the  image.
+The original Atari-based Fenders installer shares the same limitations,
+so the author doesn't really consider them to be  bugs,  although  they
+may be addressed in a future version of **fenders**.
+
+Note  that  the  bootloader only displays up to 20 files on the screen.
+This shouldn't be a real problem (how many games can you fit on a  180K
+floppy?), but no warning or error is given if there are too many files.
+
+The  bootloader  only supports standard SIO disk speed (19200bps).  The
+only way to make it support high-speed SIO is to use the  APE  Warp  OS
+(or some other high-speed patched OS) on the Atari.
+
+BUGS
+====
+
+There should be an option to delete DOS.SYS and DUP.SYS from the image,
+but there isn't. The original Fenders installer has this option.
+
+When used with an image whose size according to the ATR header
+doesn't match  the  actual  image  file  size,  **fenders** may produce
+a broken or zero-length output file. If in doubt, use **atrcheck** to
+validate the  image before use.
+
+There  should  be a way to install an arbitrary 3-sector (384-byte)
+binary file in the boot sectors of an image. This can be done with
+**dd**, of course, but its syntax is difficult to remember, and typos are
+prone to wipe out the file you're working with.
+
+.. include:: manftr.rst