Transition to rustbook.

aturon · aturon · commit 3e98b5d13f61 · 2014-07-31T16:12:26.000-07:00
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# Rust Guidelines [working title]
+% Rust Guidelines [working title]
 
 This document collects the emerging principles, conventions, abstractions, and
 best practices for writing Rust code.
@@ -17,21 +17,11 @@ official.
 
 ### Building the document
 
-Like http://rustbyexample.com/, this guidelines document is written as
-a [gitbook](https://github.com/GitbookIO/gitbook). You can install `gitbook` by running
-
-```
-npm install gitbook -g
-```
-
-After installing, just run
-
-```
-gitbook serve
-```
-
-in the root of the repository to continuously serve your local copy of
-the guidelines.
+Like http://rustbyexample.com/, this guidelines document is written in
+the [`gitbook`](https://github.com/GitbookIO/gitbook) style. It can be
+compiled with a prototype tool,
+[`rustbook`](https://github.com/aturon/rust-book) that provides a
+minimal subset of `gitbook`'s functionality on top of `rustdoc`.
 
 ### Guideline statuses
 
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -45,12 +45,6 @@
     * [Unit testing](testing/unit.md)
 * [FFI, platform-specific code](platform.md)
 * [APIs for a changing Rust](changing/README.md)
-    * [Pre-1.0 changes](changing/pre-1.0.md)
-    * [Post-1.0 changes](changing/post-1.0.md)
+    * [Pre-1.0 changes](changing/pre-1-0.md)
+    * [Post-1.0 changes](changing/post-1-0.md)
     * [Timing unclear](changing/unclear.md)
-* [Todo]()
-    * [Containers and iteration]()
-    * [The visitor pattern]()
-    * [Concurrency]()
-    * [Documentation]()
-    * [Macros]()
diff --git a/changing/README.md b/changing/README.md
@@ -1,4 +1,4 @@
-# API design for a changing Rust
+% API design for a changing Rust
 
 A number of planned Rust features will drastically affect the API design
 story. This section collects some of the biggest features with concrete examples
diff --git a/changing/post-1-0.md b/changing/post-1-0.md
@@ -1,4 +1,4 @@
-# Post-1.0 changes
+% Post-1.0 changes
 
 ### Higher-kinded types
 
diff --git a/changing/pre-1-0.md b/changing/pre-1-0.md
@@ -1,4 +1,4 @@
-# Pre-1.0 changes
+% Pre-1.0 changes
 
 ### `std` facade
 
diff --git a/changing/unclear.md b/changing/unclear.md
@@ -1,4 +1,4 @@
-# Changes with unclear timing
+% Changes with unclear timing
 
 ### Associated items
 
diff --git a/errors/README.md b/errors/README.md
@@ -1,3 +1,3 @@
-# Errors
+% Errors
 
 > **[FIXME]** Add some general text here.
diff --git a/errors/ergonomics.md b/errors/ergonomics.md
@@ -1,4 +1,4 @@
-# Ergonomic error handling
+% Ergonomic error handling
 
 Error propagation with raw `Result`s can require tedious matching and
 repackaging. This tedium is largely alleviated by the `try!` macro,
diff --git a/errors/handling.md b/errors/handling.md
@@ -1,4 +1,4 @@
-# Handling errors
+% Handling errors
 
 ### Use task isolation to cope with failure. [FIXME]
 
diff --git a/errors/propagation.md b/errors/propagation.md
@@ -1,4 +1,4 @@
-# Propagation
+% Propagation
 
 > **[FIXME]** We need guidelines on how to layer error information up a stack of
 > abstractions. But this will require landing some library support for layered
diff --git a/errors/signaling.md b/errors/signaling.md
@@ -1,4 +1,4 @@
-# Signaling errors [RFC]
+% Signaling errors [RFC]
 
 Errors fall into one of three categories:
 
diff --git a/features/README.md b/features/README.md
@@ -1,4 +1,4 @@
-# Guidelines by language feature
+% Guidelines by language feature
 
 Rust provides a unique combination of language features, some new and some
 old. This section gives guidance on when and how to use Rust's features, and
diff --git a/features/crates.md b/features/crates.md
@@ -1,4 +1,4 @@
-# Crates
+% Crates
 
 > **[OPEN]** What general guidelines should we provide for crate design?
 
diff --git a/features/functions-and-methods/README.md b/features/functions-and-methods/README.md
@@ -1,4 +1,4 @@
-# Functions and methods
+% Functions and methods
 
 ### Prefer methods to functions if there is a clear receiver. **[RFC]**
 
diff --git a/features/functions-and-methods/convenience.md b/features/functions-and-methods/convenience.md
@@ -1,4 +1,4 @@
-# Convenience methods
+% Convenience methods
 
 ### Provide small, coherent sets of convenience methods. **[RFC]**
 
diff --git a/features/functions-and-methods/input.md b/features/functions-and-methods/input.md
@@ -1,4 +1,4 @@
-# Input to functions and methods
+% Input to functions and methods
 
 ### Let the client decide when to copy and where to place data. [RFC]
 
diff --git a/features/functions-and-methods/output.md b/features/functions-and-methods/output.md
@@ -1,4 +1,4 @@
-# Output from functions and methods
+% Output from functions and methods
 
 ### Don't overpromise. [FIXME]
 
diff --git a/features/let.md b/features/let.md
@@ -1,4 +1,4 @@
-# Let binding
+% Let binding
 
 ### Always separately bind RAII guards. [RFC]
 
diff --git a/features/loops.md b/features/loops.md
@@ -1,4 +1,4 @@
-# Loops
+% Loops
 
 ### Prefer `for` to `while`. [RFC]
 
diff --git a/features/match.md b/features/match.md
@@ -1,4 +1,4 @@
-# Pattern matching
+% Pattern matching
 
 ### Dereference `match` targets when possible. [RFC]
 
diff --git a/features/modules.md b/features/modules.md
@@ -1,4 +1,4 @@
-# Modules
+% Modules
 
 > **[OPEN]** What general guidelines should we provide for module design?
 
diff --git a/features/traits/README.md b/features/traits/README.md
@@ -1,4 +1,4 @@
-# Traits
+% Traits
 
 Traits are probably Rust's most complex feature, supporting a wide range of use
 cases and design tradeoffs. Patterns of trait usage are still emerging.
diff --git a/features/traits/common.md b/features/traits/common.md
@@ -1,4 +1,4 @@
-# Common traits
+% Common traits
 
 ### Eagerly implement common traits. [RFC]
 
diff --git a/features/traits/extensions.md b/features/traits/extensions.md
@@ -1,4 +1,4 @@
-# Using traits to add extension methods
+% Using traits to add extension methods
 
 > **[FIXME]** Elaborate.
 
diff --git a/features/traits/generics.md b/features/traits/generics.md
@@ -1,4 +1,4 @@
-# Using traits for bounds on generics
+% Using traits for bounds on generics
 
 The most widespread use of traits is for writing generic functions or types. For
 example, the following signature describes a function for consuming any iterator
diff --git a/features/traits/objects.md b/features/traits/objects.md
@@ -1,4 +1,4 @@
-# Using trait objects
+% Using trait objects
 
 > **[OPEN]** What are uses of trait objects other than heterogeneous collections?
 
diff --git a/features/traits/overloading.md b/features/traits/overloading.md
@@ -1,4 +1,4 @@
-# Using traits for overloading
+% Using traits for overloading
 
 > **[FIXME]** Elaborate.
 
diff --git a/features/traits/reuse.md b/features/traits/reuse.md
@@ -1,4 +1,4 @@
-# Using traits to share implementations
+% Using traits to share implementations
 
 > **[FIXME]** Elaborate.
 
diff --git a/features/types/README.md b/features/types/README.md
@@ -1,4 +1,4 @@
-# Data types
+% Data types
 
 ### Use custom types to imbue meaning; do not abuse `bool`, `Option` or other core types. **[RFC]**
 
diff --git a/features/types/conversions.md b/features/types/conversions.md
@@ -1,4 +1,4 @@
-# Conversions between types
+% Conversions between types
 
 ### Associate conversions with the most specific type involved. **[RFC]**
 
diff --git a/features/types/newtype.md b/features/types/newtype.md
@@ -1,4 +1,4 @@
-# The newtype pattern
+% The newtype pattern
 
 A "newtype" is a tuple or `struct` with a single field. The terminology is borrowed from Haskell.
 
diff --git a/ownership/README.md b/ownership/README.md
@@ -1,3 +1,3 @@
-# Ownership and resource management
+% Ownership and resource management
 
 > **[FIXME]** Add general remarks about ownership/resources here.
diff --git a/ownership/builders.md b/ownership/builders.md
@@ -1,4 +1,4 @@
-# The builder pattern
+% The builder pattern
 
 Some data structures are complicated to construct, due to their construction needing:
 
diff --git a/ownership/cell-smart.md b/ownership/cell-smart.md
@@ -1,4 +1,4 @@
-# Cells and smart pointers
+% Cells and smart pointers
 
 > **[FIXME]** Add guidelines about when to use Cell, RefCell, Rc and
 > Arc (and how to use them together).
diff --git a/ownership/constructors.md b/ownership/constructors.md
@@ -1,4 +1,4 @@
-# Constructors
+% Constructors
 
 ### Define constructors as static, inherent methods. [RFC]
 
diff --git a/ownership/destructors.md b/ownership/destructors.md
@@ -1,4 +1,4 @@
-# Destructors
+% Destructors
 
 Unlike constructors, destructors in Rust have a special status: they are added
 by implementing `Drop` for a type, and they are automatically invoked as values
diff --git a/ownership/raii.md b/ownership/raii.md
@@ -1,4 +1,4 @@
-# RAII
+% RAII
 
 Resource Acquisition is Initialization
 
diff --git a/platform.md b/platform.md
@@ -1,4 +1,4 @@
-# FFI and platform-specific code **[OPEN]**
+% FFI and platform-specific code **[OPEN]**
 
 > **[FIXME]** Not sure where this should live.
 
diff --git a/safety/README.md b/safety/README.md
@@ -1,4 +1,4 @@
-# Safety and guarantees
+% Safety and guarantees
 
 > **[OPEN]** Is there a better phrase than "strong guarantees" that encompasses
 > both e.g. memory safety and e.g. data structure invariants?
diff --git a/safety/lib-guarantees.md b/safety/lib-guarantees.md
@@ -1,4 +1,4 @@
-# Library-level guarantees
+% Library-level guarantees
 
 Most libraries rely on internal invariants, e.g. about their data, resource
 ownership, or protocol states. In Rust, broken invariants cannot produce
diff --git a/safety/unsafe.md b/safety/unsafe.md
@@ -1,4 +1,4 @@
-# Using `unsafe`
+% Using `unsafe`
 
 ### Unconditionally guarantee safety, or mark API as `unsafe`. **[RFC]**
 
diff --git a/style/README.md b/style/README.md
@@ -1,4 +1,4 @@
-# Style
+% Style
 
 This section gives a set of strict rules for styling Rust code.
 
diff --git a/style/braces.md b/style/braces.md
@@ -1,4 +1,4 @@
-# Braces, semicolons, and commas
+% Braces, semicolons, and commas
 
 ### Opening braces always go on the same line. [RFC]
 
diff --git a/style/comments.md b/style/comments.md
@@ -1,4 +1,4 @@
-# Comments [RFC]
+% Comments [RFC]
 
 ### Avoid block comments.
 
diff --git a/style/imports.md b/style/imports.md
@@ -1,4 +1,4 @@
-# Imports
+% Imports
 
 The imports of a crate/module should consist of the following
 sections, in order, with a blank space between each:
diff --git a/style/naming.md b/style/naming.md
@@ -1,4 +1,4 @@
-# Naming conventions
+% Naming conventions
 
 ### General conventions [RFC]
 
diff --git a/style/organization.md b/style/organization.md
@@ -1,4 +1,4 @@
-# Organization
+% Organization
 
 > **[OPEN]** What else?
 
diff --git a/style/whitespace.md b/style/whitespace.md
@@ -1,4 +1,4 @@
-# Whitespace [RFC]
+% Whitespace [RFC]
 
 * Lines must not exceed 99 characters.
 * Use 4 spaces for indentation, _not_ tabs.
diff --git a/testing/README.md b/testing/README.md
@@ -1,4 +1,4 @@
-# Testing
+% Testing
 
 > **[FIXME]** Add some general remarks about when and how to unit
 > test, versus other kinds of testing. What are our expectations for
diff --git a/testing/unit.md b/testing/unit.md
@@ -1,4 +1,4 @@
-# Unit testing
+% Unit testing
 
 Unit tests should live in a `test` submodule at the bottom of the module they
 test. Mark the `test` submodule with `#[cfg(test)]` so it is only compiled when
diff --git a/todo.md b/todo.md
@@ -0,0 +1,5 @@
+* [Containers and iteration]()
+* [The visitor pattern]()
+* [Concurrency]()
+* [Documentation]()
+* [Macros]()
