blob2xex: add examples to man page.

2 files changed, 87 insertions, 3 deletions

diff --git a/blob2xex.1 b/blob2xex.1
index 51344f8..98652ba 100644
--- a/blob2xex.1
+++ b/blob2xex.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 "BLOB2XEX" 1 "2024-04-24" "0.2.1" "Urchlay's Atari 8-bit Tools"
+.TH "BLOB2XEX" 1 "2024-04-25" "0.2.1" "Urchlay's Atari 8-bit Tools"
 .SH NAME
 blob2xex \- Create Atari 8-bit executables from arbitrary data
 .\" RST source for blob2xex(1) man page. Convert with:
@@ -96,8 +96,51 @@ Print usage message and exit.
 Print version number and exit.
 .UNINDENT
 .SH EXAMPLES
+.SS Simple Example
 .sp
-TODO: come up with a few examples.
+You\(aqve written an Atari 8\-bit program that loads at \fB$2000\fP, which
+is also the run address. The assembler you used doesn\(aqt create Atari
+\&.xex files, so you\(aqve got a \fBprogram.bin\fP that\(aqs just raw object
+code. To turn it into a runnable .xex file, use:
+.INDENT 0.0
+.INDENT 3.5
+blob2xex program.xex \-l \(aq$2000\(aq \-r \(aq$2000\(aq program.bin
+.UNINDENT
+.UNINDENT
+.sp
+Notice the use of quotes around the addresses? That\(aqs because the
+$ character must be quoted, or the shell will try to interpret it
+as a variable reference. You could also have typed \fB$2000\fP or
+\fB0x2000\fP\&.
+.SS More Complex Example
+.sp
+Suppose you want to write a program that can run on an Atari 800,
+but you want to use the International Character Set font from the
+XL/XE machines. Also suppose that you have the XL ROM image as
+\fIatarixl.rom\fP\&.
+.sp
+The way to use the XL ICS font on the 800 is to load it somewhere
+in memory, on a 1K boundary. Suppose you\(aqve decided to load it at
+\fB$8000\fP\&.
+.sp
+Any good reference book or other documentation on the Atari XL/XE
+computers will tell you the ICS font is located at \fB$CC00\fP\&. The ROM
+image starts at \fB$C000\fP (the start of XL/XE ROM), so the font is
+located at offset \fB$0C00\fP within the ROM image. As always for Atari
+fonts, it\(aqs 1KB, or \fB$0400\fP bytes.
+.sp
+So you can create a .xex file of the ROM font with:
+.INDENT 0.0
+.INDENT 3.5
+blob2xex romfont.xex \-l 0x8000 \-o 0x0c00 \-s 0x0400 atarixl.rom
+.UNINDENT
+.UNINDENT
+.sp
+Since fonts aren\(aqt executable programs, there are no run (\fB\-r\fP) or
+init (\fB\-i\fP) address options.
+.sp
+The resulting \fIromfont.xex\fP can be combined with the rest of your
+program with \fBxexcat\fP(1).
 .SH COPYRIGHT
 .sp
 WTFPL. See \fI\%http://www.wtfpl.net/txt/copying/\fP for details.
diff --git a/blob2xex.rst b/blob2xex.rst
index 4166f64..3f80a0b 100644
--- a/blob2xex.rst
+++ b/blob2xex.rst
@@ -77,6 +77,47 @@ not **-l0x2000**.
 EXAMPLES
 ========
 
-TODO: come up with a few examples.
+Simple Example
+--------------
+
+You've written an Atari 8-bit program that loads at **$2000**, which
+is also the run address. The assembler you used doesn't create Atari
+.xex files, so you've got a **program.bin** that's just raw object
+code. To turn it into a runnable .xex file, use:
+
+  blob2xex program.xex -l '$2000' -r '$2000' program.bin
+
+Notice the use of quotes around the addresses? That's because the
+$ character must be quoted, or the shell will try to interpret it
+as a variable reference. You could also have typed **\$2000** or
+**0x2000**.
+
+More Complex Example
+--------------------
+
+Suppose you want to write a program that can run on an Atari 800,
+but you want to use the International Character Set font from the
+XL/XE machines. Also suppose that you have the XL ROM image as
+*atarixl.rom*.
+
+The way to use the XL ICS font on the 800 is to load it somewhere
+in memory, on a 1K boundary. Suppose you've decided to load it at
+**$8000**.
+
+Any good reference book or other documentation on the Atari XL/XE
+computers will tell you the ICS font is located at **$CC00**. The ROM
+image starts at **$C000** (the start of XL/XE ROM), so the font is
+located at offset **$0C00** within the ROM image. As always for Atari
+fonts, it's 1KB, or **$0400** bytes.
+
+So you can create a .xex file of the ROM font with:
+
+  blob2xex romfont.xex -l 0x8000 -o 0x0c00 -s 0x0400 atarixl.rom
+
+Since fonts aren't executable programs, there are no run (**-r**) or
+init (**-i**) address options.
+
+The resulting *romfont.xex* can be combined with the rest of your
+program with **xexcat**\(1).
 
 .. include:: manftr.rst