initial commit

1 files changed, 128 insertions, 0 deletions

diff --git a/xexsplit.rst b/xexsplit.rst
new file mode 100644
index 0000000..3a304c3
--- /dev/null
+++ b/xexsplit.rst
@@ -0,0 +1,128 @@
+.. RST source for xexsplit(1) man page. Convert with:
+..   rst2man.py xexsplit.rst > xexsplit.1
+.. rst2man.py comes from the SBo development/docutils package.
+
+.. TODO: add -n option (same as -v, but no output)?
+
+========
+xexsplit
+========
+
+--------------------------------------------------------------------------------------
+Split a multi-segment Atari 8-bit executable (XEX) into multiple single-segment files.
+--------------------------------------------------------------------------------------
+
+.. include:: manhdr.rst
+
+SYNOPSIS
+========
+
+*xexsplit* [*-hv*] *infile.xex* [*outfile-prefix*]
+
+DESCRIPTION
+===========
+
+xexsplit reads an Atari executable (XEX/BIN/COM/etc)  from  *infile*  and
+writes  each  segment  to a separate file. To read from standard input,
+infile may be omitted, or given as **-**.
+
+Output files are named **outfile-prefix.NNN.SSSS.EEEE**, where **NNN**  is
+the segment  number  (decimal,  3 digits, with leading zeroes), **SSSS**
+is the start address of the segment (4 digits, hex), and **EEEE** is the
+end  address of the segment (4 digits, hex). If *outfile-prefix* is
+omitted, the default prefix is **xexsplit.xex**.
+
+Each output file is a valid single-segment Atari executable,  including
+the  required  *$FFFF* header. They may be joined back together (possibly
+after being modified) with xexcat or plain old **cat**\(1).
+
+OPTIONS
+=======
+
+-h
+  Print a short help message and exit.
+
+-v
+  Verbose operation. Each  segment's  information  is  printed  to
+  standard error, including start/end address and length.
+
+NOTES
+=====
+
+The  terms  "Atari  executable", "binary load file", and "XEX file"
+all refer to the same thing. Also, there is no difference between
+Atari executables named with "XEX", "COM", "BIN", "EXE", etc. The
+Atari and its DOS don't care about the names, only the contents.
+
+It  is  not possible to use **-** to write to standard output. This makes
+sense, because there's no way to write multiple, separate files to stdout.
+
+The  output  filenames  were chosen so they will sort in the order they
+were created, when used with the shell's globbing. This means that  you
+can join them back into a single valid XEX file with a command like::
+
+  cat prefix.* > joined.xex
+
+or use **xexcat**\(1) instead of **cat**::
+
+  xexcat -o joined.xex prefix.*
+
+The Atari binary load format requires the *$FFFF*  header  only  for
+the first  segment  in  a file. The second and subsequent segments may
+also have a *$FFFF* header, but it's optional. **xexsplit**'s output
+files will always  have  the *$FFFF* header, regardless of whether
+the segments in the original file had it or not (in fact, **xexsplit**
+can  handle  an  invalid XEX  file  which is missing the initial $FFFF
+header for the first seg‐ ment).
+
+A segment starting at address **$02E2** contains  an  init  address.
+During loading, Atari DOSes JSR to the init address immediately
+after its segment has loaded. Init addresses are optinal; there's no
+rule that  says that every file has to have one. It's also normal
+and fairly common for there to be several init addresses in a
+multi-segment file. An init ad‐ dress segment is normally located
+right after the code segment it's in‐ tended to run, but this is not
+a requirement.
+
+A segment starting at address **$02E0** contains a run  address.
+After  all segments  have  been  loaded, Atari DOSes JSR to the run
+address to run the program just loaded. The run address is optional;
+a file containing no  run  address segment will simply be loaded into
+memory and not executed (user will be returned  to  the  DOS  menu).
+It's  legal  for  a multi-segment  file  to contain multiple run
+address segments, but only the last run address will actually be
+used. Normally, there is only one run  address; if there are more than
+one, only the last one is used.  The run address is normally the last
+segment in the file, but this is not a requirement.
+
+Attempting to run a single-segment file consisting of a run or init
+address only, will generally crash the Atari.
+
+Some  Atari  executables contain raw blocks of data, which are meant
+to be read into memory by the init  routine.  These  blocks  do  not
+have start/end  address  headers, so **xexsplit** is unable to handle
+them.  Raw data blocks usually occur in files created with "packer"
+or  "compressor"  programs, or occasionally in other large programs
+(Turbo BASIC is an example). Raw data blocks are generally found just
+after an init address segment. If you have an executable that loads
+just fine on a real Atari or emulator, but fails with **xexsplit**,
+a raw data block is usually the reason why.
+
+.. other sections we might want, uncomment as needed.
+
+.. FILES
+.. =====
+
+.. ENVIRONMENT
+.. ===========
+
+.. EXIT STATUS
+.. ===========
+
+.. BUGS
+.. ====
+
+.. EXAMPLES
+.. ========
+
+.. include:: manftr.rst