From 79585194e655f142e603bd397f86a9aceded5eb0 Mon Sep 17 00:00:00 2001
From: bbbradsmith <bbbradsmith@github.com>
Date: Thu, 28 Mar 2024 16:33:20 -0400
Subject: [PATCH 1/5] provide simple examples for using sim65 with C and
 assembly code

---
 doc/sim65.sgml | 40 +++++++++++++++++++++++++++++++++++++---
 1 file changed, 37 insertions(+), 3 deletions(-)

diff --git a/doc/sim65.sgml b/doc/sim65.sgml
index c2740bbad..e4b6762d4 100644
--- a/doc/sim65.sgml
+++ b/doc/sim65.sgml
@@ -124,11 +124,28 @@ Exit codes are limited to 8 bits.
 
 The standard C library high level file input and output is functional.
 A sim65 application can be written like a command line application,
-providing arguments to <tt/main/ and using the <tt/stdio.h/ interfaces.
+providing command line arguments to <tt/main/ and using the <tt/stdio.h/ interfaces
+to interact with the console or access files.
 
 Internally, file input and output is provided at a lower level by
 a set of built-in paravirtualization functions (<ref id="paravirt-internal" name="see below">).
 
+Example:
+
+<tscreen><verb>
+#include <stdio.h>
+int main()
+{
+    printf("Hello!\n");
+    return 5;
+}
+
+// Build and run:
+//   cc65 -o example.s example.c
+//   ca65 -o example.o example.s
+//   ld65 -t sim6502 -o example.prg example.o sim6502.lib
+//   sim65 example.prg
+</verb></tscreen>
 
 <sect>Creating a Test in Assembly<p>
 
@@ -141,11 +158,25 @@ and the sim65 library provides two ways to return an 8-bit exit code:
 
 <item>Return from <tt/_main/ with the exit code in <tt/A/.
 
-<item><tt/jmp exit/ with the code in <tt/A/.
+<item><tt/jmp exit/ with the code in <tt/A/. (<tt/.import exit/ from the sim65 library.)
 
 </itemize>
 
-The binary file has a 12 byte header:
+Example:
+
+<tscreen><verb>
+.export _main
+_main:
+    lda #5
+    rts
+
+; Build and run:
+;   ca65 -o example.o example.s
+;   ld65 -t sim6502 -o example.prg example.o sim6502.lib
+;   sim65 example.prg
+</verb></tscreen>
+
+Internally, the binary program file has a 12 byte header provided by the library:
 
 <itemize>
 
@@ -182,6 +213,9 @@ These use cc65 calling conventions, and are intended for use with the sim65 targ
 <item><tt/IRQ/ and <tt/NMI/ events will not be generated, though <tt/BRK/
 can be used if the IRQ vector at <tt/$FFFE/ is manually prepared by the test code.
 
+<item>The sim6502 or sim65c02 targets provide a default configuration,
+but if customization is needed, <tt/sim6502.cfg/ or <tt/sim65c02.cfg/ might be used as a template.
+
 </itemize>
 
 

From 89b709c7f87da4594d93f9a45c1a95b0b72b15bc Mon Sep 17 00:00:00 2001
From: bbbradsmith <bbbradsmith@github.com>
Date: Thu, 28 Mar 2024 16:55:55 -0400
Subject: [PATCH 2/5] make it clearer that explicit lib is required, note that
 exit is from stdlib.h, exit codes are unsigned, tweak "see below" for
 spacing, clarify that assembly can be used with C tests as well

---
 doc/sim65.sgml | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/doc/sim65.sgml b/doc/sim65.sgml
index e4b6762d4..c70e06412 100644
--- a/doc/sim65.sgml
+++ b/doc/sim65.sgml
@@ -115,12 +115,12 @@ PVExit ($01)
 
 <sect>Creating a Test in C<p>
 
-For a C test compiled and linked with <tt/--target sim6502/ the
+For a C test linked with <tt/--target sim6502/ and the <tt/sim6502.lib/ library,
 command line arguments to <tt/sim65/ will be passed to <tt/main/,
 and the return value from <tt/main/ will become sim65's exit code.
-The <tt/exit/ function may also be used to terminate with an exit code.
+The <tt/stdlib.h/ <tt/exit/ function may also be used to terminate with an exit code.
 
-Exit codes are limited to 8 bits.
+Exit codes are limited to an unsigned 8 bit value.
 
 The standard C library high level file input and output is functional.
 A sim65 application can be written like a command line application,
@@ -128,7 +128,7 @@ providing command line arguments to <tt/main/ and using the <tt/stdio.h/ interfa
 to interact with the console or access files.
 
 Internally, file input and output is provided at a lower level by
-a set of built-in paravirtualization functions (<ref id="paravirt-internal" name="see below">).
+a set of built-in paravirtualization functions (see <ref id="paravirt-internal" name="below">).
 
 Example:
 
@@ -149,9 +149,11 @@ int main()
 
 <sect>Creating a Test in Assembly<p>
 
-Assembly tests may similarly be assembled and linked with
-<tt/--target sim6502/ or <tt/--target sim65c02/.
-Define and export <tt/_main/ as an entry point,
+Though a C test may also link with assembly code,
+a pure assembly test can also be created.
+
+Link with <tt/--target sim6502/ or <tt/--target sim65c02/ and the corresponding library,
+define and export <tt/_main/ as an entry point,
 and the sim65 library provides two ways to return an 8-bit exit code:
 
 <itemize>
@@ -213,8 +215,8 @@ These use cc65 calling conventions, and are intended for use with the sim65 targ
 <item><tt/IRQ/ and <tt/NMI/ events will not be generated, though <tt/BRK/
 can be used if the IRQ vector at <tt/$FFFE/ is manually prepared by the test code.
 
-<item>The sim6502 or sim65c02 targets provide a default configuration,
-but if customization is needed, <tt/sim6502.cfg/ or <tt/sim65c02.cfg/ might be used as a template.
+<item>The <tt/sim6502/ or <tt/sim65c02/ targets provide a default configuration,
+but if customization is needed <tt/sim6502.cfg/ or <tt/sim65c02.cfg/ might be used as a template.
 
 </itemize>
 

From fa1a426c2968f1429e7129ea592065c2a57b73ce Mon Sep 17 00:00:00 2001
From: bbbradsmith <bbbradsmith@users.noreply.github.com>
Date: Tue, 16 Apr 2024 14:06:45 -0400
Subject: [PATCH 3/5] add -t sim6502 to cc65 and ca65 examples

---
 doc/sim65.sgml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/sim65.sgml b/doc/sim65.sgml
index c70e06412..ebd73c2cc 100644
--- a/doc/sim65.sgml
+++ b/doc/sim65.sgml
@@ -141,8 +141,8 @@ int main()
 }
 
 // Build and run:
-//   cc65 -o example.s example.c
-//   ca65 -o example.o example.s
+//   cc65 -t sim6502 -o example.s example.c
+//   ca65 -t sim6502 -o example.o example.s
 //   ld65 -t sim6502 -o example.prg example.o sim6502.lib
 //   sim65 example.prg
 </verb></tscreen>
@@ -173,7 +173,7 @@ _main:
     rts
 
 ; Build and run:
-;   ca65 -o example.o example.s
+;   ca65 -t sim6502 -o example.o example.s
 ;   ld65 -t sim6502 -o example.prg example.o sim6502.lib
 ;   sim65 example.prg
 </verb></tscreen>

From 4bc726ebe2d8148b132170a292291e811c5e4d2a Mon Sep 17 00:00:00 2001
From: bbbradsmith <bbbradsmith@users.noreply.github.com>
Date: Tue, 16 Apr 2024 16:41:00 -0400
Subject: [PATCH 4/5] clarify the meaning of the exit code unsigned limitation

---
 doc/sim65.sgml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/sim65.sgml b/doc/sim65.sgml
index ebd73c2cc..5cacf87cd 100644
--- a/doc/sim65.sgml
+++ b/doc/sim65.sgml
@@ -120,7 +120,7 @@ command line arguments to <tt/sim65/ will be passed to <tt/main/,
 and the return value from <tt/main/ will become sim65's exit code.
 The <tt/stdlib.h/ <tt/exit/ function may also be used to terminate with an exit code.
 
-Exit codes are limited to an unsigned 8 bit value.
+Exit codes are limited to an unsigned 8 bit value. (E.g. returning -1 will give an exit code of 255.)
 
 The standard C library high level file input and output is functional.
 A sim65 application can be written like a command line application,

From 8804dc7a5836828b40eaa10de333e16886197b7a Mon Sep 17 00:00:00 2001
From: bbbradsmith <bbbradsmith@users.noreply.github.com>
Date: Tue, 16 Apr 2024 16:56:13 -0400
Subject: [PATCH 5/5] give cl65 alternative

---
 doc/sim65.sgml | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/doc/sim65.sgml b/doc/sim65.sgml
index 5cacf87cd..962f07254 100644
--- a/doc/sim65.sgml
+++ b/doc/sim65.sgml
@@ -141,6 +141,10 @@ int main()
 }
 
 // Build and run:
+//   cl65 -t sim6502 -o example.prg example.c
+//   sim65 example.prg
+
+// Build and run, separate steps:
 //   cc65 -t sim6502 -o example.s example.c
 //   ca65 -t sim6502 -o example.o example.s
 //   ld65 -t sim6502 -o example.prg example.o sim6502.lib
@@ -173,6 +177,10 @@ _main:
     rts
 
 ; Build and run:
+;   cl65 -t sim6502 -o example.prg example.s
+;   sim65 example.prg
+
+; Build and run, separate steps:
 ;   ca65 -t sim6502 -o example.o example.s
 ;   ld65 -t sim6502 -o example.prg example.o sim6502.lib
 ;   sim65 example.prg