#lang scribble/doc

@(require 
   scheme/sandbox
   scheme/enter
   scribble/manual
   scribble/eval)

@(define box-eval (make-base-eval))
@(define-syntax ex
   (syntax-rules ()
     ((_ () . args)
      (interaction #:eval box-eval . args))
     ((_ . args)
      (defs+int #:eval box-eval . args))))

@(define (indented strs)
   (apply string-append
          (map (lambda (x) (string-append "    " x))
               strs)))

@(define-syntax-rule (forth . strs)
   (verbatim
    (let ((code (indented 'strs)))
       (box-eval `(forth-compile ,code))
      code)))

@title{Staapl's PIC18 Forth}

@section{Introduction}

This is a transcript of a Forth session with a PIC18F1220
Microcontroller. This is a literate program written using PLT Scheme's
Scribble documentation system. All code fragments are evaluated during
the generation of this document. No cheats!

To get started, instantiate the namespace.
@ex[()
    (require (planet zwizwa/staapl/prj/pic18))
    ]

The simplest way to evaluate code in this namespace is to pass a
string to @scheme[forth-compile] or a filename to
@scheme[forth-load/compile]. In this document, code that occurs like
this:

@forth{
  : abc 123 ;
  : def abc 1 + ;
}

is passed verbatim to the compiler using the first method. The
accumulated code can be viewed using

@ex[()
    (print-code)
    ]

To save collected binary code to an Intel HEX file use

@ex[()
    (save-ihex "/tmp/example.hex")]

To get rid of code without saving or uploading use
@ex[()
    (kill-code!)
    ]

@section{Interaction}

Forth traditionally has two modes: compile mode and interpret
mode. We've just met compile mode. In Staapl, interpret mode is called
@emph{command} mode, because it's a bit more general than
interpretating of on-target Forth words.


