Reorder book-based documentation (#8130)

On a high level, this is what this PR changed:

1. Move the CLI chapter before the API chapter.
    I think this makes sense because the CLI is more high-level.
    The same change was proposed in
    https://github.com/bytecodealliance/wasmtime/pull/7987.
1. Move some Rust and C examples from the "Examples" chapter into the API chapter.
1. Remove the original main C and Rust chapter introduction files.
    They contained mostly outdated or duplicate information.
1. Rename the "Examples" chapter to "Further Examples".
    (For lack of a better name.)
1. Rename "Embedding" to "API" at some places since API is a more generally known term.
    The term "embedding" is also slightly more confusing, I think,
    because the term nowadays also used a lot in LLM-related communication.
1. Read through the entire document and fix some outdated links and information.
1. Fix a missing subheading for Elixir (it was mentioned on the lang page, but not in the menu).

docs/SUMMARY.md

@@ -1,16 +1,13 @@
 # Summary
 
 - [Introduction](./introduction.md)
-- [Examples](./examples.md)
+- [Using the Wasmtime CLI](./cli.md)
-  - [Debugging WebAssembly](./examples-debugging.md)
+  - [Installation](./cli-install.md)
-    - [Debugging with `gdb` and `lldb`](./examples-debugging-native-debugger.md)
+  - [CLI Options](./cli-options.md)
-    - [Debugging with Core Dumps](./examples-debugging-core-dumps.md)
+  - [CLI Logging](./cli-logging.md)
-  - [Profiling WebAssembly](./examples-profiling.md)
+  - [Cache Configuration](./cli-cache.md)
-    - [Profiling with Perf](./examples-profiling-perf.md)
+- [Using the Wasmtime API](./lang.md)
-    - [Profiling with VTune](./examples-profiling-vtune.md)
+  - [Rust](./lang-rust.md)
-    - [Profiling with samply](./examples-profiling-samply.md)
-    - [Cross-platform Profiling](./examples-profiling-guest.md)
-  - [Embedding in Rust](./examples-rust-embed.md)
     - [Hello, world!](./examples-rust-hello-world.md)
     - [Calculating the GCD](./examples-rust-gcd.md)
     - [Using Linear Memory](./examples-rust-memory.md)
@@ -19,7 +16,7 @@
     - [Debugging](./examples-rust-debugging.md)
     - [Core Dumps](./examples-rust-core-dumps.md)
     - [Using Multi-Value](./examples-rust-multi-value.md)
-  - [Embedding in C](./examples-c-embed.md)
+  - [C](./lang-c.md)
     - [Hello, World!](./examples-c-hello-world.md)
     - [Calculating the GCD](./examples-c-gcd.md)
     - [Using Linear Memory](./examples-c-memory.md)
@@ -27,21 +24,23 @@
     - [Linking Modules](./examples-c-linking.md)
     - [Debugging](./examples-c-debugging.md)
     - [Using Multi-Value](./examples-c-multi-value.md)
-  - [Checking Guests' Memory Accesses](./wmemcheck.md)
-  - [Building a minimal embedding](./examples-minimal.md)
-- [Using WebAssembly from your language](./lang.md)
-  - [Rust](./lang-rust.md)
-  - [C](./lang-c.md)
   - [Python](./lang-python.md)
   - [.NET](./lang-dotnet.md)
   - [Go](./lang-go.md)
   - [Bash](./lang-bash.md)
   - [Ruby](./lang-ruby.md)
-- [Using the `wasmtime` CLI](./cli.md)
+  - [Elixir](./lang-elixir.md)
-  - [Installation](./cli-install.md)
+- [Further Examples](./examples.md)
-  - [CLI Options](./cli-options.md)
+  - [Debugging WebAssembly](./examples-debugging.md)
-  - [CLI Logging](./cli-logging.md)
+    - [Debugging with `gdb` and `lldb`](./examples-debugging-native-debugger.md)
-  - [Cache Configuration](./cli-cache.md)
+    - [Debugging with Core Dumps](./examples-debugging-core-dumps.md)
+  - [Profiling WebAssembly](./examples-profiling.md)
+    - [Profiling with Perf](./examples-profiling-perf.md)
+    - [Profiling with VTune](./examples-profiling-vtune.md)
+    - [Profiling with samply](./examples-profiling-samply.md)
+    - [Cross-platform Profiling](./examples-profiling-guest.md)
+  - [Checking Guests' Memory Accesses](./wmemcheck.md)
+  - [Building a minimal embedding](./examples-minimal.md)
 - [Stability](stability.md)
   - [Release Process](./stability-release.md)
   - [Tiers of support](./stability-tiers.md)

docs/cli-install.md

@@ -2,7 +2,7 @@
 
 Here we'll show you how to install the `wasmtime` command line tool. Note that
 this is distinct from embedding the Wasmtime project into another, for that
-you'll want to consult the [embedding documentation](embed.md).
+you'll want to consult the [embedding documentation](lang.md).
 
 The easiest way to install the `wasmtime` CLI tool is through our installation
 script. Linux and macOS users can execute the following:

docs/examples-c-embed.md

@@ -1,6 +1 @@
-# Embedding in C
+# C
-
-This section is intended to showcase the C embedding API for Wasmtime. Full
-reference documentation for the C API [can be found online][online]
-
-[online]: https://bytecodealliance.github.io/wasmtime/c-api/

docs/examples-profiling.md

@@ -20,14 +20,16 @@ platforms:
 - For Intel's x86 CPUs on Linux or Windows, we support
   [VTune](./examples-profiling-vtune.md).
 
-- For everything else, see the cross-platform profiler below.
+- For Linux and macOS, we support [samply](./examples-profiling-samply.md).
+
+- For everything else, see the [cross-platform
+  profiler](./examples-profiling-guest.md).
 
 The native profilers can measure time spent in WebAssembly guest code as well as
 time spent in the Wasmtime host and potentially even time spent in the kernel.
 This provides a comprehensive view of performance.
 
-If the native profiling tools don't work for you, Wasmtime also provides a
+The cross-platform-profiler can only measure time spent in WebAssembly guest
-[cross-platform profiler](./examples-profiling-guest.md). This profiler can only
+code, and its timing measurements are not as precise as the native profilers.
-measure time spent in WebAssembly guest code, and its timing measurements are
+However, it works on every platform that Wasmtime supports.
-not as precise as the native profilers. However, it works on every platform that
+
-Wasmtime supports.

docs/examples-rust-embed.md

@@ -1,6 +0,0 @@
-# Embedding in Rust
-
-This section is intended to showcase the Rust embedding API for Wasmtime. This
-is done through the [`wasmtime` crate](https://crates.io/crates/wasmtime). In
-addition to browsing the following examples you can also browse the [full API
-documentation](https://docs.rs/wasmtime).

docs/examples.md

@@ -1,4 +1,4 @@
-# Examples
+# Further Examples
 
 The examples contained in this section explain how to use Wasmtime in several
 common scenarios.

docs/lang-c.md

@@ -1,7 +1,6 @@
-# C
+# Embedding in C
 
-... more coming soon
+This section is intended to showcase the C embedding API for Wasmtime. Full
+reference documentation for the C API [can be found online][online].
 
-In the meantime, have a look at the [C API docs].
+[online]: https://bytecodealliance.github.io/wasmtime/c-api/
-
-[C API docs]: https://bytecodealliance.github.io/wasmtime/c-api/

docs/lang-rust.md

@@ -3,18 +3,16 @@
 This document shows an example of how to embed Wasmtime using the [Rust
 API][apidoc] to execute a simple wasm program. Be sure to also check out the
 [full API documentation][apidoc] for a full listing of what the [`wasmtime`
-crate][wasmtime] has to offer and the [book examples for
+crate][wasmtime] has to offer.
-Rust](./examples-rust-embed.md) for more information.
 
 [apidoc]: https://bytecodealliance.github.io/wasmtime/api/wasmtime/
 [wasmtime]: https://crates.io/crates/wasmtime
 
 ## Creating the WebAssembly to execute
 
-Creation of a WebAssembly file is generally covered by the [Writing
+We'll just assume that you've already got a wasm file on hand for the rest of
-WebAssembly chapter](./wasm.md), so we'll just assume that you've already got a
+this tutorial. To make things simple we'll also just assume you've got a
-wasm file on hand for the rest of this tutorial. To make things simple we'll
+`hello.wat` file which looks like this:
-also just assume you've got a `hello.wat` file which looks like this:
 
 ```wat
 (module

docs/lang.md

@@ -1,4 +1,4 @@
-# Using WebAssembly from your Language
+# Using the Wasmtime API
 
 Wasmtime can be used as a library to embed WebAssembly execution support
 within applications. Wasmtime is written in Rust, but bindings are available