initial commit

1 files changed, 195 insertions, 0 deletions

diff --git a/xexsplit.1 b/xexsplit.1
new file mode 100644
index 0000000..c3a88e6
--- /dev/null
+++ b/xexsplit.1
@@ -0,0 +1,195 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "XEXSPLIT" 1 "2022-08-27" "0.2.0" "Urchlay's Atari 8-bit Tools"
+.SH NAME
+xexsplit \- Split a multi-segment Atari 8-bit executable (XEX) into multiple single-segment files.
+.\" 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)?
+.
+.SH SYNOPSIS
+.sp
+\fIxexsplit\fP [\fI\-hv\fP] \fIinfile.xex\fP [\fIoutfile\-prefix\fP]
+.SH DESCRIPTION
+.sp
+xexsplit reads an Atari executable (XEX/BIN/COM/etc)  from  \fIinfile\fP  and
+writes  each  segment  to a separate file. To read from standard input,
+infile may be omitted, or given as \fB\-\fP\&.
+.sp
+Output files are named \fBoutfile\-prefix.NNN.SSSS.EEEE\fP, where \fBNNN\fP  is
+the segment  number  (decimal,  3 digits, with leading zeroes), \fBSSSS\fP
+is the start address of the segment (4 digits, hex), and \fBEEEE\fP is the
+end  address of the segment (4 digits, hex). If \fIoutfile\-prefix\fP is
+omitted, the default prefix is \fBxexsplit.xex\fP\&.
+.sp
+Each output file is a valid single\-segment Atari executable,  including
+the  required  \fI$FFFF\fP header. They may be joined back together (possibly
+after being modified) with xexcat or plain old \fBcat\fP(1).
+.SH OPTIONS
+.INDENT 0.0
+.TP
+.B  \-h
+Print a short help message and exit.
+.TP
+.B  \-v
+Verbose operation. Each  segment\(aqs  information  is  printed  to
+standard error, including start/end address and length.
+.UNINDENT
+.SH NOTES
+.sp
+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\(aqt care about the names, only the contents.
+.sp
+It  is  not possible to use \fB\-\fP to write to standard output. This makes
+sense, because there\(aqs no way to write multiple, separate files to stdout.
+.sp
+The  output  filenames  were chosen so they will sort in the order they
+were created, when used with the shell\(aqs globbing. This means that  you
+can join them back into a single valid XEX file with a command like:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+cat prefix.* > joined.xex
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+or use \fBxexcat\fP(1) instead of \fBcat\fP:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+xexcat \-o joined.xex prefix.*
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+The Atari binary load format requires the \fI$FFFF\fP  header  only  for
+the first  segment  in  a file. The second and subsequent segments may
+also have a \fI$FFFF\fP header, but it\(aqs optional. \fBxexsplit\fP\(aqs output
+files will always  have  the \fI$FFFF\fP header, regardless of whether
+the segments in the original file had it or not (in fact, \fBxexsplit\fP
+can  handle  an  invalid XEX  file  which is missing the initial $FFFF
+header for the first seg‐ ment).
+.sp
+A segment starting at address \fB$02E2\fP contains  an  init  address.
+During loading, Atari DOSes JSR to the init address immediately
+after its segment has loaded. Init addresses are optinal; there\(aqs no
+rule that  says that every file has to have one. It\(aqs 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\(aqs in‐ tended to run, but this is not
+a requirement.
+.sp
+A segment starting at address \fB$02E0\fP 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\(aqs  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.
+.sp
+Attempting to run a single\-segment file consisting of a run or init
+address only, will generally crash the Atari.
+.sp
+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 \fBxexsplit\fP 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 \fBxexsplit\fP,
+a raw data block is usually the reason why.
+.\" other sections we might want, uncomment as needed.
+.
+.\" FILES
+.
+.\" =====
+.
+.\" ENVIRONMENT
+.
+.\" ===========
+.
+.\" EXIT STATUS
+.
+.\" ===========
+.
+.\" BUGS
+.
+.\" ====
+.
+.\" EXAMPLES
+.
+.\" ========
+.
+.SH COPYRIGHT
+.sp
+WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details.
+.SH AUTHOR
+.INDENT 0.0
+.IP B. 3
+Watson <\fI\%urchlay@slackware.uk\fP>; Urchlay on irc.libera.chat \fI##atari\fP\&.
+.UNINDENT
+.SH SEE ALSO
+.sp
+\fBa8eol\fP(1),
+\fBa8utf8\fP(1),
+\fBatr2xfd\fP(1),
+\fBatrsize\fP(1),
+\fBaxe\fP(1),
+\fBblob2c\fP(1),
+\fBcart2xex\fP(1),
+\fBdasm2atasm\fP(1),
+\fBfenders\fP(1),
+\fBrom2cart\fP(1),
+\fBunmac65\fP(1),
+\fBxexcat\fP(1),
+\fBxexsplit\fP(1),
+\fBxfd2atr\fP(1).
+.sp
+Any good Atari 8\-bit book: \fIDe Re Atari\fP, \fIThe Atari BASIC  Reference
+Manual\fP,  the  \fIOS Users\(aq Guide\fP, \fIMapping the Atari\fP, etc.
+.\" Generated by docutils manpage writer.
+.