Update docs (#480)

* new mdbook version with built-in Nim highlighting support
* describe examples in a dedicated page
* fixes

.github/workflows/doc.yml

@@ -22,7 +22,7 @@ jobs:
         with:
           crate: mdbook
           use-tool-cache: true
-          version: "0.4.35"
+          version: "0.4.36"
       - uses: actions-rs/install@v0.1
         with:
           crate: mdbook-toc
@@ -37,7 +37,7 @@ jobs:
         with:
           crate: mdbook-admonish
           use-tool-cache: true
-          version: "1.13.1"
+          version: "1.14.0"
 
       - uses: jiro4989/setup-nim-action@v1
         with:

docs/src/SUMMARY.md

@@ -1,5 +1,5 @@
 - [Introduction](./introduction.md)
-- [Getting started](./getting_started.md)
+- [Examples](./examples.md)
 
 # User guide
 
@@ -8,3 +8,7 @@
 - [Errors and exceptions](./error_handling.md)
 - [Tips, tricks and best practices](./tips.md)
 - [Porting code to `chronos`](./porting.md)
+
+# Developer guide
+
+- [Updating this book](./book.md)

docs/src/async_procs.md

@@ -2,8 +2,8 @@
 
 Async procedures are those that interact with `chronos` to cooperatively
 suspend and resume their execution depending on the completion of other
-async procedures which themselves may be waiting for I/O to complete, timers to
-expire or tasks running on other threads to complete.
+async procedures, timers, tasks on other threads or asynchronous I/O scheduled
+with the operating system.
 
 Async procedures are marked with the `{.async.}` pragma and return a `Future`
 indicating the state of the operation.
@@ -25,6 +25,9 @@ echo p().type # prints "Future[system.void]"
 
 ## `await` keyword
 
+The `await` keyword operates on `Future` instances typically returned from an
+`async` procedure.
+
 Whenever `await` is encountered inside an async procedure, control is given
 back to the dispatcher for as many steps as it's necessary for the awaited
 future to complete, fail or be cancelled. `await` calls the
@@ -53,13 +56,13 @@ waitFor p3()
 
 ```admonition warning
 Because `async` procedures are executed concurrently, they are subject to many
-of the same risks that typically accompany multithreaded programming
+of the same risks that typically accompany multithreaded programming.
 
 In particular, if two `async` procedures have access to the same mutable state,
 the value before and after `await` might not be the same as the order of execution is not guaranteed!
 ```
 
-## Raw procedures
+## Raw async procedures
 
 Raw async procedures are those that interact with `chronos` via the `Future`
 type but whose body does not go through the async transformation.
@@ -83,7 +86,7 @@ proc rawFailure(): Future[void] {.async: (raw: true).} =
   fut
 ```
 
-Raw functions can also use checked exceptions:
+Raw procedures can also use checked exceptions:
 
 ```nim
 proc rawAsyncRaises(): Future[void] {.async: (raw: true, raises: [IOError]).} =

docs/src/examples.md

@@ -0,0 +1,18 @@
+# Examples
+
+Examples are available in the [`docs/examples/`](https://github.com/status-im/nim-chronos/tree/master/docs/examples/) folder.
+
+## Basic concepts
+
+* [cancellation](https://github.com/status-im/nim-chronos/tree/master/docs/examples/cancellation.nim) - Cancellation primer
+* [timeoutsimple](https://github.com/status-im/nim-chronos/tree/master/docs/examples/timeoutsimple.nim) - Simple timeouts
+* [timeoutcomposed](https://github.com/status-im/nim-chronos/tree/master/docs/examples/examples/timeoutcomposed.nim) - Shared timeout of multiple tasks
+
+## TCP
+
+* [tcpserver](https://github.com/status-im/nim-chronos/tree/master/docs/examples/tcpserver.nim) - Simple TCP/IP v4/v6 echo server
+
+## HTTP
+
+* [httpget](https://github.com/status-im/nim-chronos/tree/master/docs/examples/httpget.nim) - Downloading a web page using the http client
+* [twogets](https://github.com/status-im/nim-chronos/tree/master/docs/examples/twogets.nim) - Download two pages concurrently

docs/src/introduction.md

@@ -7,12 +7,34 @@ transformation features provided by Nim.
 Features include:
 
 * Asynchronous socket and process I/O
-* HTTP server with SSL/TLS support out of the box (no OpenSSL needed)
+* HTTP client / server with SSL/TLS support out of the box (no OpenSSL needed)
 * Synchronization primitivies like queues, events and locks
-* Cancellation
+* [Cancellation](./concepts.md#cancellation)
 * Efficient dispatch pipeline with excellent multi-platform support
 * Exception [effect support](./guide.md#error-handling)
 
+## Installation
+
+Install `chronos` using `nimble`:
+
+```text
+nimble install chronos
+```
+
+or add a dependency to your `.nimble` file:
+
+```text
+requires "chronos"
+```
+
+and start using it:
+
+```nim
+{{#include ../examples/httpget.nim}}
+```
+
+There are more [examples](./examples.md) throughout the manual!
+
 ## Platform support
 
 Several platforms are supported, with different backend [options](./concepts.md#compile-time-configuration):
@@ -22,10 +44,6 @@ Several platforms are supported, with different backend [options](./concepts.md#
 * OSX / BSD: [`kqueue`](https://en.wikipedia.org/wiki/Kqueue) / `poll`
 * Android / Emscripten / posix: `poll`
 
-## Examples
-
-Examples are available in the [`docs/examples/`](https://github.com/status-im/nim-chronos/docs/examples) folder.
-
 ## API documentation
 
 This guide covers basic usage of chronos - for details, see the