suzanne.soy/whalesong
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fixing some compile-time issues in the docs due to the PLaneT2 transition

Browse Source
This commit is contained in:
Danny Yoo 2013-04-29 18:00:34 -06:00
parent 951ac74f85
commit ad106d5ab2
1 changed files with 43 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
whalesong/scribblings/manual.scrbl
View File

@ -1,8 +1,5 @@
#lang scribble/manual #lang scribble/manual
@(require planet/scribble @(require scribble/eval
planet/version
planet/resolver
scribble/eval
scribble/bnf scribble/bnf
racket/sandbox racket/sandbox
racket/port racket/port
@ -16,9 +13,9 @@
@(define-runtime-path git-head-path "../.git/refs/heads/master") @(define-runtime-path git-head-path "../.git/refs/heads/master")
@(require (for-label (this-package-in js) @(require (for-label whalesong/js
(this-package-in js/world)) whalesong/js/world)
(for-label (except-in (this-package-in lang/base) (for-label (except-in whalesong/lang/base
string? string?
printf printf
number->string number->string
@ -31,8 +28,8 @@
newline newline
current-output-port current-output-port
display)) display))
(for-label (this-package-in resource) (for-label whalesong/resource
(for-label (this-package-in web-world)))) (for-label whalesong/web-world)))
@ -244,8 +241,12 @@ Pacman.}
@subsection{Installing Whalesong} @subsection{Installing Whalesong}
[FIXME: this part needs revision since we're moving over to a PLaneT2
installation]
@;{
Before you begin, if you are using DrRacket, Before you begin, if you are using DrRacket,
@itemize[#:style 'ordered @itemize[#:style 'ordered
@item{Please go to the Racket submenu.} @item{Please go to the Racket submenu.}
@ -270,7 +271,7 @@ directory.
You should also see a @filepath{whalesong-gui} launcher that includes You should also see a @filepath{whalesong-gui} launcher that includes
a minimal graphical user interface. a minimal graphical user interface.
}
@ -312,7 +313,7 @@ restriction as quickly as possible.
Write a @filepath{hello.rkt} with the following content Write a @filepath{hello.rkt} with the following content
@filebox["hello.rkt"]{ @filebox["hello.rkt"]{
@codeblock{ @codeblock{
#lang planet dyoo/whalesong #lang whalesong
(display "hello world") (display "hello world")
(newline) (newline)
}} }}
@ -349,11 +350,11 @@ Visit @link["http://hashcollision.org/whalesong/examples/dom-play/dom-play.html"
@filebox["dom-play.rkt"]{ @filebox["dom-play.rkt"]{
@codeblock|{ @codeblock|{
#lang planet dyoo/whalesong #lang whalesong
;; Uses the JavaScript FFI, which provides bindings for: ;; Uses the JavaScript FFI, which provides bindings for:
;; $ and call-method ;; $ and call-method
(require (planet dyoo/whalesong/js)) (require whalesong/js)
;; insert-break: -> void ;; insert-break: -> void
(define (insert-break) (define (insert-break)
@ -382,7 +383,7 @@ Visit @link["http://hashcollision.org/whalesong/examples/dom-play/dom-play.html"
(insert-break) (insert-break)
(loop (add1 i))])) (loop (add1 i))]))
}|} }|}
This program uses the @link["http:/jquery.com"]{JQuery} API provided by @racketmodname[(planet dyoo/whalesong/js)], This program uses the @link["http:/jquery.com"]{JQuery} API provided by @racketmodname[whalesong/js],
as well as the native JavaScript FFI to produce output on the browser. as well as the native JavaScript FFI to produce output on the browser.
If we run Whalesong on this program, and view the resulting @filepath{dom-play.html} in our If we run Whalesong on this program, and view the resulting @filepath{dom-play.html} in our
web browser, we should see a pale, green page with some output. web browser, we should see a pale, green page with some output.
@ -413,7 +414,7 @@ with generated JavaScript binaries here:
@filebox["fact.rkt"]{ @filebox["fact.rkt"]{
@codeblock|{ @codeblock|{
#lang planet dyoo/whalesong #lang whalesong
(provide fact) (provide fact)
(define (fact x) (define (fact x)
(cond (cond
@ -573,13 +574,13 @@ get-javascript depend on.
@section{Including external resources} @section{Including external resources}
@defmodule/this-package[resource] @defmodule[whalesong/resource]
Programs may need to use external file @deftech{resource}s that aren't Programs may need to use external file @deftech{resource}s that aren't
themselves Racket programs, but instead some other kind of data. themselves Racket programs, but instead some other kind of data.
Graphical programs will often use @filepath{.png}s, and web-related Graphical programs will often use @filepath{.png}s, and web-related
programs @filepath{.html}s, for example. Whalesong provides the programs @filepath{.html}s, for example. Whalesong provides the
@racketmodname/this-package[resource] library to refer and use these @racketmodname[whalesong/resource] library to refer and use these
external resources. When Whalesong compiles a program into a package, external resources. When Whalesong compiles a program into a package,
these resources will be bundled alongside the JavaScript-compiled these resources will be bundled alongside the JavaScript-compiled
output. output.
@ -589,15 +590,15 @@ Defines a @tech{resource} with the given path name.
For example, For example,
@codeblock|{ @codeblock|{
#lang planet dyoo/whalesong #lang whalesong
(require (planet dyoo/whalesong/resource)) (require whalesong/resource)
(define-resource my-whale-image-resource "humpback.png") (define-resource my-whale-image-resource "humpback.png")
}| }|
} }
As a convenience, you can also write As a convenience, you can also write
@codeblock|{ @codeblock|{
#lang planet dyoo/whalesong #lang whalesong
(require (planet dyoo/whalesong/resource)) (require whalesong/resource)
(define-resource humpback.png) (define-resource humpback.png)
}| }|
which defines a variable named @racket[humpback.png] whose which defines a variable named @racket[humpback.png] whose
@ -626,9 +627,9 @@ Given a @tech{resource}, gets a URL.
For example, For example,
@codeblock|{ @codeblock|{
#lang planet dyoo/whalesong #lang whalesong
(require (planet dyoo/whalesong/resource) (require whalesong/resource
(planet dyoo/whalesong/image)) whalesong/image)
(define-resource my-whale-image-resource "humpback.png") (define-resource my-whale-image-resource "humpback.png")
@ -659,7 +660,7 @@ For example,
@section{The web-world API} @section{The web-world API}
@defmodule/this-package[web-world] @defmodule[whalesong/web-world]
The @tt{web-world} library allows you to write functional event-driven The @tt{web-world} library allows you to write functional event-driven
@link["http://world.cs.brown.edu"]{World} programs for the web; the @link["http://world.cs.brown.edu"]{World} programs for the web; the
@ -692,9 +693,9 @@ Once we're happy with the statics of our program, we can inject dynamic behavior
Write a file called @filepath{tick-tock.rkt} with the following content. Write a file called @filepath{tick-tock.rkt} with the following content.
@filebox["tick-tock.rkt"]{ @filebox["tick-tock.rkt"]{
@codeblock|{ @codeblock|{
#lang planet dyoo/whalesong #lang whalesong
(require (planet dyoo/whalesong/web-world) (require whalesong/web-world
(planet dyoo/whalesong/resource)) whalesong/resource)
(define-resource view.html) (define-resource view.html)
@ -724,8 +725,8 @@ Several things are happening here.
@itemize[ @itemize[
@item{We @racket[require] a few libraries to get us some additional @item{We @racket[require] a few libraries to get us some additional
behavior; in particular, @racketmodname/this-package[web-world] to let behavior; in particular, @racketmodname[whalesong/web-world] to let
us write event-driven web-based programs, and @racketmodname/this-package[resource] us write event-driven web-based programs, and @racketmodname[whalesong/resource]
to give us access to external @tech{resource}s.} to give us access to external @tech{resource}s.}
@item{We use @racket[define-resource] to refer to external files, like @filepath{view.html} that @item{We use @racket[define-resource] to refer to external files, like @filepath{view.html} that
@ -740,7 +741,7 @@ bind to many other kinds of web events (by using @racket[view-bind]).}
@subsection{@racket[big-bang] and its options} @subsection{@racket[big-bang] and its options}
@declare-exporting/this-package[web-world] @declare-exporting[whalesong/web-world]
@defproc[(big-bang [w world] @defproc[(big-bang [w world]
[h big-bang-handler] ...) world]{ [h big-bang-handler] ...) world]{
Start a big bang computation. The @racket[big-bang] consumes an initial world, Start a big bang computation. The @racket[big-bang] consumes an initial world,
@ -866,7 +867,7 @@ function will be called every time an event occurs.
@subsection{Views} @subsection{Views}
@declare-exporting/this-package[web-world] @declare-exporting[whalesong/web-world]
A @deftech{view} is a functional representation of the browser DOM A @deftech{view} is a functional representation of the browser DOM
tree. A view is always focused on an element, and the functions in tree. A view is always focused on an element, and the functions in
this subsection show how to traverse and manipulate the view. this subsection show how to traverse and manipulate the view.
@ -1104,7 +1105,7 @@ then focus moves to the parent.}
@subsection{Events} @subsection{Events}
@declare-exporting/this-package[web-world] @declare-exporting[whalesong/web-world]
An @deftech{event} is a structure that holds name-value pairs. An @deftech{event} is a structure that holds name-value pairs.
Whenever an event occurs in web-world, it may include some auxiliary Whenever an event occurs in web-world, it may include some auxiliary
information about the event. As a concrete example, location events information about the event. As a concrete example, location events
@ -1126,12 +1127,12 @@ Get an list of the event's keys.
@subsection{Dynamic DOM generation with xexps} @subsection{Dynamic DOM generation with xexps}
@declare-exporting/this-package[web-world] @declare-exporting[whalesong/web-world]
We often need to dynamically inject new dom nodes into an existing We often need to dynamically inject new dom nodes into an existing
view. As an example where the UI is entirely in code: view. As an example where the UI is entirely in code:
@codeblock|{ @codeblock|{
#lang planet dyoo/whalesong #lang whalesong
(require (planet dyoo/whalesong/web-world)) (require whalesong/web-world)
;; tick: world view -> world ;; tick: world view -> world
(define (tick world view) (define (tick world view)
@ -1221,7 +1222,7 @@ Coerses a view into a @tech{xexp}.
@subsection{Tips and tricks: Hiding standard output or directing it to an element} @subsection{Tips and tricks: Hiding standard output or directing it to an element}
@declare-exporting/this-package[web-world] @declare-exporting[whalesong/web-world]
For a web-world program, output is normally done by using For a web-world program, output is normally done by using
@racket[to-draw]. However, side effecting functions, such as @racket[to-draw]. However, side effecting functions, such as
@ -1273,7 +1274,7 @@ even if the id does not currently exist on the page.
@section{The JavaScript Foreign Function Interface} @section{The JavaScript Foreign Function Interface}
@defmodule/this-package[js]{ @defmodule[whalesong/js]{
[[This needs to describe what hooks we've got from the JavaScript side [[This needs to describe what hooks we've got from the JavaScript side
@ -1449,7 +1450,7 @@ Returns the height of the viewport.
@;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; @;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@subsection{Adding new event handlers to world programs with the FFI} @subsection{Adding new event handlers to world programs with the FFI}
@defmodule/this-package[js/world] @defmodule[whalesong/js/world]
@;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; @;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
The callback-driven asynchronous APIs in JavaScript can act as sources The callback-driven asynchronous APIs in JavaScript can act as sources
@ -1477,9 +1478,9 @@ require information that's produced at setup-time.
For example, we can reimplement some of the behavior of For example, we can reimplement some of the behavior of
@racket[on-location-change] with the following: @racket[on-location-change] with the following:
@codeblock|{ @codeblock|{
#lang planet dyoo/whalesong #lang whalesong
(require (planet dyoo/whalesong/js) (require whalesong/js
(planet dyoo/whalesong/js/world)) whalesong/js/world)
(define setup-geo (define setup-geo
(js-function->procedure (js-function->procedure