doc: Spruce things up a bit.

2 files changed, 38 insertions, 28 deletions

diff --git a/doc/api/time.texi b/doc/api/time.texi
index cc637f2..0b74782 100644
--- a/doc/api/time.texi
+++ b/doc/api/time.texi
@@ -7,14 +7,10 @@ loop.  This manual refers to a ``tick'' as the smallest unit of time.
 There are a user-defined amount of ticks in a real world second, but
 by default it is 60.
 
-Sly includes several useful modules for working with time.  Coroutines
-are procedures that can be paused and resumed, agendas are procedure
-schedulers, and signals built atop both agendas and coroutines to
-provide a high-level functional reactive programming API.
-
-For most use-cases, the signal module should be used exclusively, but
-the agenda and coroutine modules are useful for building new
-high-level abstractions.
+Sly includes several useful modules for working with time.  For nearly
+all use-cases, the signal module should be used exclusively, but the
+agenda and coroutine modules are useful for building the foundation
+for new high-level abstractions.
 
 @menu
 * Signals::                     Functional reactive programming.
@@ -31,19 +27,29 @@ high-level abstractions.
 
 Game state is a function of time.  The player's score, the current
 stage, an enemy's hit points, etc. all change in response to events
-that happen at discrete points in time.  Typically, this means that a
-number of callback procedures are registered to respond to events
-which mutate the relevant data structures.  However, this approach,
-while simple and effective, comes at the price of readability,
-reproducibility, and expression.  Instead of explicitly mutating data
-and entering ``callback hell'', Sly abstracts and formalizes the
-process using a functional reactive programming style.
+that happen at discrete points in time.  In traditional game engines
+this means that a number of callback procedures are registered to
+respond to events which mutate the relevant data structures to update
+the state of the game world.  However, this approach, while simple and
+effective, comes at the price of readability, reproducibility, and
+expression.  Callback-heavy code can be very difficult to read because
+the control flow is not made obvious by the structure of the code
+itself and requires more cognitive effort to trace the effects of
+events.  Furthermore, mutation-heavy, imperative code introduces a
+class of bugs that are not present in functional programs, order of
+operations bugs, that make large programs difficult to reason about.
+Therefore, we believe that imperative event callbacks are too
+low-level to express asynchronous programs in an understandable way.
+Instead of explicitly mutating data and entering ``callback hell'',
+Sly abstracts and formalizes the process using a functional reactive
+programming style.
 
 In Sly, time-varying values are called ``signals'', and they are
 defined in a declarative and functional manner.  Rather than
-describing the process of mutation procedurally, one describes the
-relationships between signals instead.  The result is a ``signal
-graph'', a directed acyclic graph of event responses.
+describing the process of mutation procedurally, one @emph{declares}
+the relationships between signals and how values are transformed as
+they propagate.  The result is a ``signal graph'', a directed acyclic
+graph of event responses, that makes data flow explicit.
 
 @example
 (define-signal position
@@ -130,11 +136,14 @@ Create a new signal whose value is a list of the values stored in
 @var{signals}.
 @end deffn
 
-@deffn {Scheme Procedure} signal-map @var{proc} @var{signal} . @var{rest}
-Create a new signal that applies @var{proc} to the values of
-@var{SIGNAL}.  More than one input signal may be specified, in which
-case @var{proc} must accept as many arguments as there are input
-signals.
+@deffn {Scheme Procedure} signal-map @var{proc} @var{signal} @dots{}
+Create a new signal that applies @var{proc} to the values stored in
+one or more @var{signals}.
+@end deffn
+
+@deffn {Scheme Procedure} signal-map-maybe @var{proc} @var{signal} @dots{}
+Create a new signal that applies @var{proc} to the values of one or
+more @var{signals} @emph{if} all of them are not @code{#f}.
 @end deffn
 
 @deffn {Scheme Procedure} signal-sample-on @var{value-signal} @var{sample-signal}
@@ -180,6 +189,12 @@ the signal @var{predicate} is true, or the value of the signal
 @var{off} otherwise.
 @end deffn
 
+@deffn {Scheme Procedure} signal-if @var{predicate} @var{on} @var{off}
+Create a new signal whose value is the result of evaluating
+@var{consequent} when the value of the signal @var{predicate} is
+truth, otherwise @var{alternate} is evaluated.
+@end deffn
+
 @deffn {Scheme Procedure} signal-constant @var{constant} @var{signal}
 Create a new signal whose value is always @var{constant} no matter the
 value received from @var{signal}.
diff --git a/doc/api/utils.texi b/doc/api/utils.texi
index 4c7c39f..4eeb9d1 100644
--- a/doc/api/utils.texi
+++ b/doc/api/utils.texi
@@ -102,11 +102,6 @@ from the same thread that is running the game loop.
 Return a memoizing version of @code{proc}.
 @end deffn
 
-@deffn {Scheme Syntax} forever @var{body} @dots{}
-Evaluate @code{body} in an unbounded loop.  Useful in coroutines that
-have no end.
-@end deffn
-
 @deffn {Scheme Syntax} trampoline @var{proc-name}
 Create a new procedure that applies the procedure bound to
 @code{proc-name} with all given arguments.