xexcat: tweak doc.

2 files changed, 32 insertions, 17 deletions

diff --git a/xexcat.1 b/xexcat.1
index 8b94f98..522bedf 100644
--- a/xexcat.1
+++ b/xexcat.1
@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "XEXCAT" 1 "2024-04-27" "0.2.1" "Urchlay's Atari 8-bit Tools"
+.TH "XEXCAT" 1 "2024-04-28" "0.2.1" "Urchlay's Atari 8-bit Tools"
 .SH NAME
 xexcat \- Concatenate Atari 8-bit executables (XEX) into a single XEX file.
 .\" RST source for xexcat(1) man page. Convert with:
@@ -41,13 +41,14 @@ xexcat \- Concatenate Atari 8-bit executables (XEX) into a single XEX file.
 \fBxexcat\fP [\fB\-hvc\fP] [\fB\-f\fP \fI1\fP | \fI2\fP] [\fB\-l\fP \fIaddress\fP [\fB\-r\fP \fIaddress\fP]  [\fB\-i\fP  \fIaddress\fP] [\fB\-o\fP  \fIoutfile.xex\fP] [\fIinfile.xex\fP] [\fIinfile.xex ...\fP]
 .SH DESCRIPTION
 .sp
-\fBxexcat\fP  reads  one or more Atari executables (XEX/BIN/COM/etc)
-from the given filenames, and writes a single Atari  executable
-containing  all the segments from all the input files to \fIoutfile\fP\&.
+\fBxexcat\fP reads one or more Atari executables (XEX/BIN/COM/etc),
+or \fBdasm\fP(1) \fB\-f1\fP, \fB\-f2\fP files; it writes a single Atari
+executable containing all the segments from all the input files to
+\fIoutfile\fP\&.
 .sp
-To  read  from  standard input, \fIinfile\fP may be omitted, or given as
-\fB\-\fP\&. To write to standard output, \fB\-o\fP \fIoutfile\fP may be  omitted,
-or  given  as \fB\-o\-\fP\&.
+To read from standard input, \fIinfile\fP may be omitted, or given as
+\fB\-\fP\&. To write to standard output, \fB\-o\fP \fIoutfile\fP may be omitted,
+or given as \fB\-o\-\fP\&.
 .sp
 The  output  file  is  a valid Atari executable, including the
 required \fI$FFFF\fP header for the first segment. If there are multiple
@@ -91,12 +92,16 @@ load address of the first segment.
 .UNINDENT
 .INDENT 0.0
 .TP
-.B \-f 1|2
+.B \fB\-f\fP \fI1\fP | \fI2\fP
 Input file(s) are \fBdasm\fP(1) object files created by \fB\-f1\fP or
 \fB\-f2\fP options, rather than .xex files. \fB\-f1\fP files can\(aqt contain
 run or init addresses, so you\(aqll probably want to use \fB\-r\fP,
 \fB\-a\fP, and/or \fB\-i\fP with these. \fB\-f2\fP files can contain run or
-init addresses. The output file is still a .xex file.
+init addresses. The output file is still a .xex file. Note that this
+flag affects all input files: if you\(aqre trying to join a \fBdasm\fP
+file with a .xex file, it must be done in two steps: convert the
+\fBdasm\fP file to a .xex, then combine the two .xex files with a
+second run of \fBxexcat\fP\&.
 .UNINDENT
 .INDENT 0.0
 .TP
diff --git a/xexcat.rst b/xexcat.rst
index a91130f..cfb9a64 100644
--- a/xexcat.rst
+++ b/xexcat.rst
@@ -20,13 +20,14 @@ SYNOPSIS
 DESCRIPTION
 ===========
 
-**xexcat**  reads  one or more Atari executables (XEX/BIN/COM/etc)
-from the given filenames, and writes a single Atari  executable
-containing  all the segments from all the input files to *outfile*.
+**xexcat** reads one or more Atari executables (XEX/BIN/COM/etc),
+or **dasm**\(1) **-f1**, **-f2** files; it writes a single Atari
+executable containing all the segments from all the input files to
+*outfile*.
 
-To  read  from  standard input, *infile* may be omitted, or given as
-**-**. To write to standard output, **-o** *outfile* may be  omitted,
-or  given  as **-o-**.
+To read from standard input, *infile* may be omitted, or given as
+**-**. To write to standard output, **-o** *outfile* may be omitted,
+or given as **-o-**.
 
 The  output  file  is  a valid Atari executable, including the
 required *$FFFF* header for the first segment. If there are multiple
@@ -69,12 +70,16 @@ OPTIONS
   "Automatic" run address: Force the output file's run address to the
   load address of the first segment.
 
--f 1|2
+**-f** *1* | *2*
   Input file(s) are **dasm**\(1) object files created by **-f1** or
   **-f2** options, rather than .xex files. **-f1** files can't contain
   run or init addresses, so you'll probably want to use **-r**,
   **-a**, and/or **-i** with these. **-f2** files can contain run or
-  init addresses. The output file is still a .xex file.
+  init addresses. The output file is still a .xex file. Note that this
+  flag affects all input files: if you're trying to join a **dasm**
+  file with a .xex file, it must be done in two steps: convert the
+  **dasm** file to a .xex, then combine the two .xex files with a
+  second run of **xexcat**.
 
 -h
   Print a short help message and exit.
@@ -118,6 +123,11 @@ 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.
 
+The **dasm** **-f1** file format is also the native binary format for
+the Commodore 8-bit machines (PET, 64, etc), so you can use **xexcat**
+to load Commodore code & data into an Atari... though of course the
+code won't run correctly on the Atari.
+
 EXIT STATUS
 ===========