update the book

book/en/src/SUMMARY.md

@@ -6,7 +6,6 @@
   - [Resources](./by-example/resources.md)
   - [Tasks](./by-example/tasks.md)
   - [Timer queue](./by-example/timer-queue.md)
-  - [Singletons](./by-example/singletons.md)
   - [Types, Send and Sync](./by-example/types-send-sync.md)
   - [Starting a new project](./by-example/new.md)
   - [Tips & tricks](./by-example/tips.md)

book/en/src/by-example/app.md

@@ -28,15 +28,14 @@ not required to use the [`cortex_m_rt::entry`] attribute.
 
 Within the pseudo-module the `app` attribute expects to find an initialization
 function marked with the `init` attribute. This function must have signature
-`[unsafe] fn()`.
+`fn(init::Context) [-> init::LateResources]`.
 
 This initialization function will be the first part of the application to run.
 The `init` function will run *with interrupts disabled* and has exclusive access
 to Cortex-M and device specific peripherals through the `core` and `device`
-variables, which are injected in the scope of `init` by the `app` attribute. Not
+variables fields of `init::Context`. Not all Cortex-M peripherals are available
-all Cortex-M peripherals are available in `core` because the RTFM runtime takes
+in `core` because the RTFM runtime takes ownership of some of them -- for more
-ownership of some of them -- for more details see the [`rtfm::Peripherals`]
+details see the [`rtfm::Peripherals`] struct.
-struct.
 
 `static mut` variables declared at the beginning of `init` will be transformed
 into `&'static mut` references that are safe to access.
@@ -61,7 +60,7 @@ $ cargo run --example init
 
 A function marked with the `idle` attribute can optionally appear in the
 pseudo-module. This function is used as the special *idle task* and must have
-signature `[unsafe] fn() - > !`.
+signature `fn(idle::Context) - > !`.
 
 When present, the runtime will execute the `idle` task after `init`. Unlike
 `init`, `idle` will run *with interrupts enabled* and it's not allowed to return

book/en/src/by-example/new.md

@@ -40,7 +40,7 @@ $ rm memory.x build.rs
    `timer-queue` feature.
 
 ``` console
-$ cargo add cortex-m-rtfm
+$ cargo add cortex-m-rtfm --allow-prerelease
 ```
 
 4. Write your RTFM application.
@@ -49,7 +49,7 @@ Here I'll use the `init` example from the `cortex-m-rtfm` crate.
 
 ``` console
 $ curl \
-    -L https://github.com/japaric/cortex-m-rtfm/raw/v0.4.0/examples/init.rs \
+    -L https://github.com/japaric/cortex-m-rtfm/raw/v0.5.0-alpha.1/examples/init.rs \
     > src/main.rs
 ```
 

book/en/src/by-example/resources.md

@@ -10,7 +10,7 @@ have enough information to optimize the access to the shared data.
 The `app` attribute has a full view of the application thus it can optimize
 access to `static` variables. In RTFM we refer to the `static` variables
 declared inside the `app` pseudo-module as *resources*. To access a resource the
-context (`init`, `idle`, `interrupt` or `exception`) must first declare the
+context (`init`, `idle`, `interrupt` or `exception`) one must first declare the
 resource in the `resources` argument of its attribute.
 
 In the example below two interrupt handlers access the same resource. No `Mutex`
@@ -30,7 +30,7 @@ $ cargo run --example resource
 
 The priority of each handler can be declared in the `interrupt` and `exception`
 attributes. It's not possible to set the priority in any other way because the
-runtime takes ownership of the `NVIC` peripheral; it's also not possible to
+runtime takes ownership of the `NVIC` peripheral thus it's also not possible to
 change the priority of a handler / task at runtime. Thanks to this restriction
 the framework has knowledge about the *static* priorities of all interrupt and
 exception handlers.
@@ -71,10 +71,10 @@ $ cargo run --example lock
 
 One more note about priorities: choosing a priority higher than what the device
 supports (that is `1 << NVIC_PRIO_BITS`) will result in a compile error. Due to
-limitations in the language the error is currently far from helpful: it will say
+limitations in the language the error message is currently far from helpful: it
-something along the lines of "evaluation of constant value failed" and the span
+will say something along the lines of "evaluation of constant value failed" and
-of the error will *not* point out to the problematic interrupt value -- we are
+the span of the error will *not* point out to the problematic interrupt value --
-sorry about this!
+we are sorry about this!
 
 ## Late resources
 

book/en/src/by-example/singletons.md

@@ -1,26 +0,0 @@
-# Singletons
-
-The `app` attribute is aware of [`owned-singleton`] crate and its [`Singleton`]
-attribute. When this attribute is applied to one of the resources the runtime
-will perform the `unsafe` initialization of the singleton for you, ensuring that
-only a single instance of the singleton is ever created.
-
-[`owned-singleton`]: ../../api/owned_singleton/index.html
-[`Singleton`]: ../../api/owned_singleton_macros/attr.Singleton.html
-
-Note that when using the `Singleton` attribute you'll need to have the
-`owned_singleton` in your dependencies.
-
-Below is an example that uses the `Singleton` attribute on a chunk of memory
-and then uses the singleton instance as a fixed-size memory pool using one of
-the [`alloc-singleton`] abstractions.
-
-[`alloc-singleton`]: https://crates.io/crates/alloc-singleton
-
-``` rust
-{{#include ../../../../examples/singleton.rs}}
-```
-
-``` console
-$ cargo run --example singleton
-{{#include ../../../../ci/expected/singleton.run}}```

book/en/src/by-example/tips.md

@@ -24,8 +24,8 @@ of tasks.
 
 You can use conditional compilation (`#[cfg]`) on resources (`static [mut]`
 items) and tasks (`fn` items). The effect of using `#[cfg]` attributes is that
-the resource / task will *not* be injected into the prelude of tasks that use
+the resource / task will *not* be available through the corresponding `Context`
-them (see `resources`, `spawn` and `schedule`) if the condition doesn't hold.
+`struct` if the condition doesn't hold.
 
 The example below logs a message whenever the `foo` task is spawned, but only if
 the program has been compiled using the `dev` profile.
@@ -37,7 +37,7 @@ the program has been compiled using the `dev` profile.
 ## Running tasks from RAM
 
 The main goal of moving the specification of RTFM applications to attributes in
-RTFM v0.4.x was to allow inter-operation with other attributes. For example, the
+RTFM v0.4.0 was to allow inter-operation with other attributes. For example, the
 `link_section` attribute can be applied to tasks to place them in RAM; this can
 improve performance in some cases.
 
@@ -78,8 +78,6 @@ $ cargo nm --example ramfunc --release | grep ' bar::'
 
 ## `binds`
 
-**NOTE**: Requires RTFM ~0.4.2
-
 You can give hardware tasks more task-like names using the `binds` argument: you
 name the function as you wish and specify the name of the interrupt / exception
 in the `binds` argument. Types like `Spawn` will be placed in a module named

book/en/src/by-example/types-send-sync.md

@@ -7,8 +7,7 @@ write plain functions that take them as arguments.
 The API reference specifies how these types are generated from the input. You
 can also generate documentation for you binary crate (`cargo doc --bin <name>`);
 in the documentation you'll find `Context` structs (e.g. `init::Context` and
-`idle::Context`) whose fields represent the variables injected into each
+`idle::Context`).
-function.
 
 The example below shows the different types generates by the `app` attribute.
 

book/en/src/preface.md

@@ -11,6 +11,9 @@ There is a translation of this book in [Russian].
 
 [Russian]: ../ru/index.html
 
+**HEADS UP** This is an **alpha** pre-release; there may be breaking changes in
+the API and semantics before a proper release is made.
+
 {{#include ../../../README.md:5:46}}
 
 {{#include ../../../README.md:52:}}