doc: rewrite book intro (#389)

Author: molpopgen

book/src/introduction.md

@@ -1,22 +1,62 @@
 # Introduction <img align="right" width="73" height="45" src="https://raw.githubusercontent.com/tskit-dev/administrative/main/logos/svg/tskit-rust/Tskit_rust_logo.eps.svg">
 
-## Do you need `tskit-rust`?
+## Required background.
+
+* We assume familiarity with `tskit`. See [tskit.dev](https://tskit.dev).
+* Comfort with rust is required.
+  * [The book](https://doc.rust-lang.org/book/) is a good place to start.
+  * [The Rustonomicon](https://doc.rust-lang.org/nomicon/) is for those who wish to dig deeper into `unsafe` rust and FFI.
+    The 'nomicon is helpful for understanding how things like the `tskit` rust API can be built in the first place.
+
+## Conventions used in this document
+
+Here, `tskit` means the rust API.
+`tskit-c` and `tskit-python` refer to the C and Python APIs, respectively.
+
+The phrase "data model" refers to [this](https://tskit.dev/tskit/docs/stable/data-model.html). This document will make little sense without an understanding of the data model.
+
+## Relation to the C API
+
+Where necessary, we will note differences from the behavior of `tskit-c`.
+
+Much of the rust API works by calling the C API.
+We do not change the semantics of the C API.
+However, we do make stricter statements about the ownership relationships between types.
+For example, the C API can result in the following situation:
+
+* A heap-allocated table collection is used to record data about the ancestry of a sample.
+* That table collection is used to initialize a tree sequence.
+  The tree sequence is told to take ownership of the tables.
+
+This is a case where the C API requires that you respectfully no longer work with the heap-allocated table collection. To do so is undefined behavior.
+
+The rust API forbids such situations.
+The creation of a tree sequence from tables consumes the tables via a move operation.
+Thus, any further actions on the tables is a compiler error.
+
+This example is the kinds of differences between `tskit` and `tskit-c`.
+Undefined behavior is (close to) impossible with `tskit`.
+
+
+## Quick overview
+
+### Do you need `tskit-rust`?
 
 The use-cases for `tskit-rust` are the same as for `tskit-c`:
 
 1. Developing a new performance-oriented application.
 2. The input/output of this application will be a `.trees` file.
 
-## What does `tskit-rust` add?
+### What does `tskit-rust` add?
 
 Briefly, you get the performance of `C` and the strong safety guarantees of `rust`.
 
-## What is `tskit-rust` missing?
+### What is `tskit-rust` missing?
 
 The crate does not cover the entire `C` API.
 However, client code can make direct calls to that API via the module `tskit::bindings`.
 
-## Adding `tskit` as a dependency to a rust project
+### Adding `tskit` as a dependency to a rust project
 
 In your `Cargo.toml`:
 
@@ -28,15 +68,8 @@ tskit = "~X.Y.Z"
 The latest version to fill in `X.Y.Z` can be found [here](https://crates.io/crates/tskit).
 See [here](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html) for how to specify version numbers.
 
-### Feature flags.
+#### Feature flags.
 
 `tskit` defines several [cargo features](https://doc.rust-lang.org/cargo/reference/features.html).
 These are defined in the [API docs](https://docs.rs/tskit/latest/tskit/#optional-features).
 
-## Conventions used in this document
-
-We assume a working knowledge of rust.
-Thus, we skip over the details of things like matching idioms, etc.,
-and just `.unwrap()`.
-
-We also assume familiarity with the `tskit` [data model](https://tskit.dev/tskit/docs/stable/data-model.html).