initial commit

1 files changed, 114 insertions, 0 deletions

diff --git a/axe.rst b/axe.rst
new file mode 100644
index 0000000..01e8a10
--- /dev/null
+++ b/axe.rst
@@ -0,0 +1,114 @@
+.. RST source for axe(1) man page. Convert with:
+..   rst2man.py axe.rst > axe.1
+.. rst2man.py comes from the SBo development/docutils package.
+
+===
+axe
+===
+
+--------------
+ATR/XFD Editor
+--------------
+
+.. include:: manhdr.rst
+
+SYNOPSIS
+========
+
+**axe** [*-alvtu*] [*-b newimage*] [*-D file*] [*-x file*] [*-w file*] [*-c dirname*] [*-t*] [*-d sector*] [*imagefile*]
+
+DESCRIPTION
+===========
+
+**axe** allows the user to access files stored inside a single-density
+Atari DOS 2.0S disk image (ATR or XFD). It can list the directory,
+copy files into and out of the image, delete files in the image,
+create a new image (either blank or containing files), and dump various
+low-level information about the image's filesystem structure.
+
+OPTIONS
+=======
+
+Standard Options:
+-----------------
+
+-b *filename*
+  Create blank ATR image file called *filename*. If *filename*
+  already exists, it will be overwritten with no warning.
+
+-c *directory*
+  Create new ATR *imagefile* with contents of *directory*. If *imagefile*
+  already exists, it will be overwritten with no warning. Similar to **tar cf**.
+
+-D *file*
+  Delete *file* from *imagefile*. Ignores "locked" bit.
+
+-t *directory*
+  Extract all files in image to *directory*, which will be created and
+  must not already exist. Similar to **tar xf**.
+
+-u
+  Unix <-> Atari newline/EOL translation (use for text files only; breaks other file types).
+
+-w *file*
+  Write *file* to *imagefile*, overwrites if *file* already exists. Ignores "locked" bit.
+
+-x *file*
+  Extract (read) file from *imagefile*, write to current directory.
+
+Debugging Options:
+------------------
+
+-a
+  List all directory entries, even deleted/empty ones.
+
+-d *sector*
+  Dump a sector in decimal, hex, and binary.
+
+-l
+  Trace and print sector links for all files on disk.
+
+-v
+  Dump VTOC (sector 360) in decimal, hex, and binary.
+
+LIMITATIONS
+===========
+
+**axe** is ancient code, from last century. It has various design
+flaws and bugs. At this point, it would be better to rewrite it from
+scratch than to try & fix the existing code.
+
+Only Atari DOS 2.0S and 100% compatible single-density disk images are
+supported. MyDOS images will work, but there's no support for MyDOS
+subdirectories. There's no support for e.g. SpartaDOS or Atari DOS
+3.0/4.0. Atari DOS 2.5 enhanced density images will work, the same
+way they work on DOS 2.0S: files using the extra sectors will not be
+readable, and **axe** won't write to the extra sectors. Atari DOS 1.0
+images (which are *very* rare) can at least have the directory listed,
+but I wouldn't recommend writing to them.
+
+The "file locked" (aka read-only) bit is ignored when writing, and
+there's no way to lock or unlock files, though locked files do appear
+with \* next to the name in the directory listing.
+
+It's possible to create files in a disk image with invalid filenames,
+e.g. beginning with a number, or containing punctuation. Atari DOS
+might or might not be able to even delete such files, but **axe** will
+be able to if it happens.
+
+One known bug: when writing a file to an image, if the file's size
+is a multiple of 125 (the number of data bytes per sector), an extra
+sector is allocated (with 0 data bytes in it). This doesn't actually
+cause a problem for Atari DOSes (it just wastes space on the disk),
+but it prevents simple-minded XEX loaders like Fenders from being able
+to load the file (technically this is a bug in Fenders, too). Atari
+DOSes actually can create files like this if they're opened for
+append, then closed without writing new data.
+
+**axe** does nothing with the boot sectors (sectors 1-3) of the disk
+image. When creating a new image, the boot sectors will be blank (all
+zeroes), meaning the disk won't be bootable. If DOS.SYS is written to
+an image with a DOS boot record, the boot record won't be updated with
+the first sector of DOS.SYS, so the disk won't be bootable.
+
+.. include:: manftr.rst