blob2xex: add examples to man page.

1 files changed, 45 insertions, 2 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.