Clean up manual

Fix broken links, minor rewrite text rewrites, organize files to make linking
work in both manual and github web view.

Author: rinon

README.md

@@ -3,13 +3,15 @@
 # What is C2Rust?
 
 C2Rust helps you migrate C99-compliant code to Rust. It provides:
-- a C to Rust translator, 
-- a Rust code refactoring tool, and
-- a way to cross-check the C code against the new Rust code.
+- a C to Rust translator
+- a Rust code refactoring tool
+- tools to cross-check execution of the C code against the new Rust code
 
-The translator (or transpiler), produces unsafe Rust code that closely mirrors the input C code. The primary goal of the translator is to produce code that is functionally identical to the input C code. Generating safe or idomatic Rust is *not* a goal for the translator. Rather, we think the best approach is to gradually clean up the translator using dedicated refactoring tools. See the `c2rust-refactor` directory to learn about the `c2rust-refactor` tool that we are working on.
-Some refactoring will have to be done by hand which may introduce errors. We provide plugins for `clang` and `rustc` so you can compile and run two binaries and check that they behave identically (at the level of function calls).
-See details in the `cross-checks` directory and in the cross checking [tutorial](docs/cross-check-tutorial.md). Here's the big picture:
+The translator (or transpiler), produces unsafe Rust code that closely mirrors the input C code. The primary goal of the translator is to produce code that is functionally identical to the input C code. Generating safe or idomatic Rust is *not* a goal for the translator. Rather, we think the best approach is to gradually rewrite the translated Rust code using dedicated refactoring tools. To this end, we are building a refactoring tool that rewrites unsafe auto-translated Rust into safer idioms (see [c2rust-refactor](c2rust-refactor/)).
+
+Some refactoring will have to be done by hand which may introduce errors. We provide plugins for `clang` and `rustc` so you can compile and run two binaries and check that they behave identically (at the level of function calls). For details on cross-checking see the [cross-checks](cross-checks) directory and the cross checking [tutorial](docs/cross-check-tutorial.md).
+
+Here's the big picture:
 
 ![C2Rust overview](docs/c2rust-overview.png "C2Rust overview")
 
@@ -30,13 +32,13 @@ C2Rust requires LLVM 6 or 7 and its corresponding libraries and clang compiler.
         pacman -S base-devel llvm clang cmake
 
 
-- **OS X:** (XCode command-line tools and recent LLVM (we recommend the Homebrew version) are required.)
+- **OS X:** XCode command-line tools and recent LLVM (we recommend the Homebrew version) are required.
 
         xcode-select --install
         brew install llvm python3 cmake
 
 
-A rust installation with [Rustup](https://rustup.rs/) is also required on all platforms.
+Finally, a rust installation with [Rustup](https://rustup.rs/) is required on all platforms.
 
 
 ## Building C2Rust
@@ -53,7 +55,9 @@ If you have trouble with cargo build, the [developer docs](docs/README-developer
 
 # Translating C to Rust
 
-The translation tool first needs to know the existing compiler commands used to build the C code. To provide this information, you will need to generate a [standard](https://clang.llvm.org/docs/JSONCompilationDatabase.html) `compile_commands.json` file. Many build systems can automatically generate this file, as it is used by many other tools, but see [below](#generating-compile_commandsjson-files) for recommendations on how to generate this file for common build processes.
+The translator needs access to the exact compiler commands used to build the C code. To provide this information, you will need a [standard](https://clang.llvm.org/docs/JSONCompilationDatabase.html) `compile_commands.json` file. Many build systems can automatically generate this file, as it is used by many other tools, but see [below](#generating-compile_commandsjson-files) for recommendations on how to generate this file for common build processes.
+
+Once you have a `compile_commands.json` file describing the C build, translate the C code to Rust with the following command:
 
     $ ./scripts/transpile.py path/to/compile_commands.json
 
@@ -78,7 +82,7 @@ in this translator. The translator will attempt to skip function definitions tha
 ## Generating `compile_commands.json` files
 
 The `compile_commands.json` file can be automatically created using
-either `cmake`, `intercept-build`, or `bear` (Linux only).
+either `cmake`, `intercept-build`, or `bear`.
 
 It may be a good idea to remove optimizations(`-OX`) from the compile commands
 file, as there are optimization builtins which we do not support translating.
@@ -100,7 +104,7 @@ Intercept build is distributed with clang and recommended for makefile projects
 	$ intercept-build make
 	$ intercept-build xcodebuild
 
-### ... with `bear`
+### ... with `bear` (linux only)
 
 When building on Linux, *Bear* is automatically built by the
 `build_translator.py` script and installed into the `dependencies`
@@ -113,7 +117,7 @@ directory.
 
 > Are there release binaries? Can I install C2Rust with Cargo?
 
-We hope to release binaries that you can `cargo install` soon(tm).
+We plan to release a cargo package that you can `cargo install` soon(tm).
 
 > I translated code on platform X but it didn't work correctly on platform Y
 

book.toml

@@ -11,3 +11,9 @@ command = "cargo run --bin mdbook-include_md --quiet --"
 
 [preprocessor.generator_dispatch]
 command = "python3 manual/preprocessors/generator_dispatch.py"
+
+[output.html]
+
+# Uncomment the following to enable link-checking. This should not be enabled by
+# default because linkcheck has false positives due to our use of symlinks.
+# [output.linkcheck]

c2rust-refactor/README.md

@@ -19,7 +19,7 @@ Build `c2rust-refactor` with `cargo build`.
 
 Flags for `c2rust-refactor` are described by `c2rust-refactor --help`.
 
-See [the command documentation](../_generated/c2rust-refactor-commands.md) for a list of commands,
+See [the command documentation](commands.html) for a list of commands,
 including complete usage and descriptions. 
 Multiple commands can be separated by an argument consisting of a single
 semicolon, as in `c2rust-refactor cmd1 arg1 \; cmd2 arg2`.
@@ -51,7 +51,7 @@ by a command is described in the command's documentation; by default, most
 commands that use marks operate on `target`.
 
 The most flexible way of marking nodes is by using the
-[`select`](../_generated/c2rust-refactor-commands.md#select) command.  See the command
+[`select`](commands.html#select) command.  See the command
 documentation and `src/select/mod.rs` for details.  Note that marks are not
 preserved across `c2rust-refactor` invocations, so you usually want to run
 `select` followed by the command of interest using the `;` separator mentioned

c2rust-refactor/doc/select.md

@@ -39,8 +39,8 @@ function-by-function basis.
 
 The remainder of this tutorial describes `select` and related mark-manipulation
 commands.  For details of how marks affect various transformation commands, see
-the [command documentation](c2rust-refactor-commands.md) or read about the
-[`marked!` pattern](refactor-rewrite.md#marked) for `rewrite_expr` and other
+the [command documentation](commands.html) or read about the
+[`marked!` pattern](rewrite.md#marked) for `rewrite_expr` and other
 pattern-matching commands.
 
 
@@ -432,11 +432,10 @@ selected node.  `last` does the same with the last selected node.  "First" and
 ordered as expected, and a parent node come "after" all of its children.
 
 The `first` and `last` operations are most useful for finding places to insert
-new nodes (such as with the [`create_item`
-command](c2rust-refactor-commands.md#create_item)) while ignoring details such
-as the specific names or kinds of the nodes around the insertion point.  For
-example, we can use `last` to easily select the last item in a module.  First,
-we select all the module's items:
+new nodes (such as with the [`create_item` command](commands.html#create_item))
+while ignoring details such as the specific names or kinds of the nodes around
+the insertion point.  For example, we can use `last` to easily select the last
+item in a module.  First, we select all the module's items:
 
 ```rust refactor-target hidden
 mod m {
@@ -457,7 +456,7 @@ clear_marks ;
 select target 'item(m); child(kind(item)); last;'
 ```
 
-Now we could use [`create_item`](c2rust-refactor-commands.md#create_item) to
+Now we could use [`create_item`](commands.html#create_item) to
 insert a new item after the last existing one.
 
 ### `marked`

docs/README-developers.md

@@ -2,8 +2,8 @@
 
 There are three ways to build the C2Rust project:
 
-- Using **Vagrant**. See our [vagrant README](../vagrant/README.md).
-- Using **Docker**. See our [docker README](../docker/README.md).
+- [Using **Vagrant**](../vagrant/).
+- [Using **Docker**](../docker/).
 - **Manually**, as explained below.
 
 The previous two options automatically install all prerequisites during provisioning. You can also provision a macOS or Linux system manually.
@@ -49,7 +49,7 @@ C2Rust (indirectly) uses the [clang-sys](https://crates.io/crates/clang-sys) cra
 
 # Building dependencies from source
 
-To develop on components that interact with LLVM, we recommend building against a local copy of LLVM. This will ensure that you have debug symbols and IDE integration for both LLVM and C2Rust. However, building C2Rust from source with LLVM takes a while. For a shorter build that links against prebuilt LLVM and clang system libraries, you should be able to `cargo build` in the `c2rust-transpile` directory (see the general [README](../README.md)).
+To develop on components that interact with LLVM, we recommend building against a local copy of LLVM. This will ensure that you have debug symbols and IDE integration for both LLVM and C2Rust. However, building C2Rust from source with LLVM takes a while. For a shorter build that links against prebuilt LLVM and clang system libraries, you should be able to `cargo build` in the `c2rust-transpile` directory (see the general [README](../)).
 
 The following from source full build script has been tested on recent versions of macOS and Ubuntu:
 
@@ -58,9 +58,9 @@ The following from source full build script has been tested on recent versions o
 
 # Testing (Optional)
 
-Tests are found in the [`tests`](../tests) folder. If you build the translator successfully, you should be able to run the tests with:
+Tests are found in the [`tests`](../tests/) folder. If you build the translator successfully, you should be able to run the tests with:
 
     $ ./scripts/test_translator.py tests
 
-This basically tests that the original C file and translated Rust file produce the same output when compiled and run. More details about tests are in [this README](../tests/README.md).
+This basically tests that the original C file and translated Rust file produce the same output when compiled and run. More details about tests can be found in the [tests folder](../tests/).
 

examples/README.md

@@ -0,0 +1,21 @@
+# Example translations
+
+The following example translations illustrate how to run C2Rust on real
+codebases. Each example has been modified if necessary to prepare it for
+translation with C2Rust and each has accompanying documentation on how to
+translate the example.
+
+The robotfindskitten example is accompanied by a demonstration of the
+refactoring tool rewriting the unsafe translated Rust into idiomatic, safe Rust.
+
+- [json-c](json-c/)
+- [urlparser](urlparser/)
+- [qsort](qsort/)
+- [tmux](tmux/)
+- [grabc](grabc/)
+- [libxml2](libxml2/)
+- [snudown](snudown/)
+- [genann](genann/)
+- [lil](lil/)
+- [xzoom](xzoom/)
+- [robotfindskitten](robotfindskitten/)

examples/robotfindskitten/refactor.md

@@ -1,4 +1,6 @@
-# Collapsing `ncurses` macros
+# Translating and refactoring robotfindskitten
+
+## Collapsing `ncurses` macros
 
 We begin with a little cleanup.  Some `ncurses` functions used in
 `robotfindskitten` are actually implemented as macros, which are expanded by
@@ -94,7 +96,7 @@ checkpoint where results can be cached, so that later refactoring commands can
 be tweaked without rerunning all the previous steps.
 
 
-# String formatting
+## String formatting
 
 Our next step is to replace calls to C string-formatting functions (such as
 `printf`) with wrappers using Rust's `format_args!` macro.  Since
@@ -110,7 +112,7 @@ accept the `std::fmt::Arguments` produced by the `format_args!` macro.  The
 second step then replaces the `printf` call with a call to a wrapper that does
 accept `std::fmt::Arguments`.
 
-## `printf` format argument conversion
+### `printf` format argument conversion
 
 We run a few commands to mark the nodes involved in string formatting, before
 finally running the `convert_format_args` command to perform the actual
@@ -155,7 +157,7 @@ clear_marks ;
 clear the marks, but we don't want to `commit` these changes until we've fixed
 the type errors introduced in this step.
 
-## Creating a `printf` wrapper
+### Creating a `printf` wrapper
 
 As a reminder, we currently have code that looks like this:
 
@@ -201,7 +203,7 @@ commit the changes:
 commit ;
 ```
 
-## Other string formatting functions
+### Other string formatting functions
 
 Aside from `printf`, `robotfindskitten` also uses the `ncurses` `printw` and
 `mvprintw` string-formatting functions.  The refactoring script for `printw` is
@@ -267,7 +269,7 @@ commit ;
 ```
 
 
-# Static string constant - `ver`
+## Static string constant - `ver`
 
 `robotfindskitten` defines a static string constant, `ver`, to store the game's
 version.  Using `ver` is currently unsafe, first because its Rust type is a raw
@@ -295,7 +297,7 @@ Simply replacing `*mut c_char` with `&str` introduces type errors throughout
 the crate.  The initializer for `ver` still has type `*mut c_char`, and all
 uses of `ver` are still expecting a `*mut c_char`.
 
-## Fixing `ver`'s initializer
+### Fixing `ver`'s initializer
 
 Fixing the `ver` initializer is straightforward: we simply remove all the
 casts, then convert the binary string (`&[u8]`) literal to an ordinary string
@@ -317,7 +319,7 @@ bytestr_to_str ;
 delete_marks target ;
 ```
 
-## Fixing `ver`'s uses
+### Fixing `ver`'s uses
 
 `ver`'s initializer is now well-typed, but its uses are still expecting a `*mut
 c_char` instead of a `&str`.  To fix these up, we use the `type_fix_rules`
@@ -333,7 +335,7 @@ __t`), then wrap the original expression in a call to `.as_ptr()`.  This turns
 out to be enough to fix all the errors at uses of `ver`.
 
 
-## Making `ver` immutable
+### Making `ver` immutable
 
 Now that all type errors have been corrected, we can finish our refactoring of
 `ver`.  We make it immutable, then commit all the changes to disk.
@@ -346,7 +348,7 @@ commit ;
 ```
 
 
-# Static string array - `messages`
+## Static string array - `messages`
 
 Aside from `ver`, `robotfindskitten` contains a static array of strings, called
 `messages`.  Like `ver`, accessing `messages` is unsafe because each element is
@@ -387,7 +389,7 @@ commit ;
 ```
 
 
-# Heap-allocated array - `screen`
+## Heap-allocated array - `screen`
 
 `robotfindskitten` uses a heap-allocated array to store information about each
 object on the screen.  The initial translation gives this array the type `*mut
@@ -407,7 +409,7 @@ create_item 'extern crate c2rust_runtime;' inside ;
 
 Now we can proceed with the actual refactoring.
 
-## Converting to `CBlockPtr`
+### Converting to `CBlockPtr`
 
 We actually perform the conversion from `*mut` to `CArray` via an intermediate
 step, using `CBlockPtr`.  This is another type provided by `c2rust_runtime`,
@@ -505,5 +507,5 @@ done, and we can commit the changes:
 commit ;
 ```
 
-## Converting to `CArray`
+### Converting to `CArray`