Merge pull request #310 from lalrpop/deploy-book

move the setup instrutions out of README and into the book

README.md

@@ -28,90 +28,17 @@ etc).
 
 ### Documentation
 
-There is [documentation available here] that covers a fair bit of the
-features of LALRPOP. For the more advanced things are not yet covered,
-it also points to tests that may help give the idea. This will eventually
-become a reference manual.
+[The LALRPOP book] covers all things LALRPOP -- or at least it intends
+to! Here are some tips:
 
-[documentation available here]: https://lalrpop.github.io/lalrpop/README.html
+- The [tutorial] covers the basics of setting up a LALRPOP parser.
+- For the impatient, you may prefer the [quick start guide] section, which describes
+  how to add LALRPOP to your `Cargo.toml`.
+- The [advanced setup] chapter shows how to configure other aspects of LALRPOP's
+  preprocessing.
 
-### Obligatory disclaimer
-
-LALRPOP is still in its relatively early days. Not all the features I
-want are there, and the error messages are sometimes a bit opaque. But
-it's quite powerful already. It's also [self-hosting], which is fun.
-
-[self-hosting]: https://github.com/nikomatsakis/lalrpop/blob/master/lalrpop/src/parser/lrgrammar.lalrpop
-
-### Using LALRPOP
-
-#### Configuring cargo
-
-There are two ways to use LALRPOP. The recommended way is to
-configure Cargo to automatically change all `.lalrpop` files
-into `.rs` files by adding a `build.rs` file. Here is a "cheat sheet"
-for how to do that.
-
-This section is for if you already know what you're doing and just
-want to copy-and-paste some code for adding LALRPOP to your Cargo
-project. To enable LALRPOP, add the following lines to your
-`Cargo.toml`:
-
-```
-[package]
-...
-build = "build.rs" # LALRPOP preprocessing
-
-# Add a dependency on the regex crate; this is not
-# needed if you are writing your own tokenizer by
-# hand (or if you are already using the regex crate)
-[dependencies.regex]
-version = "0.2.0"
-
-# Add a dependency on the LALRPOP runtime library:
-[dependencies.lalrpop-util]
-version = "0.14.0"
-
-[build-dependencies.lalrpop]
-version = "0.14.0"
-```
-
-And create a `build.rs` file that looks like:
-
-```rust
-extern crate lalrpop;
-
-fn main() {
-    lalrpop::process_root().unwrap();
-}
-```
-
-(If you already have a `build.rs` file, you should be able to just
-call `process_root` in addition to whatever else that file is doing.)
-
-That's it!
-
-#### More advanced configuration
-
-The `process_root` applies the default configuration: so it will
-transform `.lalrpop` files into `.rs` files *in-place* (in your `src`
-directory), and it will only do so if the `.lalrpop` file has actually
-changed. But you can also use the [`Configuration`][config] struct to
-get more detailed control.
-
-[config]: https://github.com/nikomatsakis/lalrpop/blob/master/lalrpop/src/api/mod.rs
-
-#### Running manually
-
-If you prefer, you can also run the `lalrpop` crate as an
-executable. Simply run `cargo install lalrpop` and then you will get a
-`lalrpop` binary you can execute, like so:
-
-```
-lalrpop file.lalrpop
-```
-
-This will generate `file.rs` for you. Note that it only executes if
-`file.lalrpop` is newer than `file.rs`; if you'd prefer to execute
-unconditionally, pass `-f` (also try `--help` for other options).
+[The LALRPOP book]: http://lalrpop.github.io/lalrpop/
+[quick start guide]: http://lalrpop.github.io/lalrpop/quick_start_guide.html
+[advanced setup]: http://lalrpop.github.io/lalrpop/advanced_setup.html
+[tutorial]: http://lalrpop.github.io/lalrpop/tutorial/index.html
 

doc/src/SUMMARY.md

@@ -2,6 +2,7 @@
 
 - [LALRPOP](README.md)
 - [Crash course on parsers](crash_course.md)
+- [Quick start guide](quick_start_guide.md)
 - [Tutorial](tutorial/index.md)
   - [Adding LALRPOP to your project](tutorial/001_adding_lalrpop.md)
   - [Parsing parenthesized numbers](tutorial/002_paren_numbers.md)
@@ -12,5 +13,7 @@
   - [Macros](tutorial/007_macros.md)
   - [Error recovery](tutorial/008_error_recovery.md)
 - [Writing a custom lexer](lexer_tutorial/index.md)
+- [Advanced setup](advanced_setup.md)
+  - [Using the Cargo `OUT_DIR`](out_dir.md)
 -----------
 [Contributors](misc/contributors.md)

doc/src/advanced_setup.md

@@ -0,0 +1,31 @@
+When you setup LALRPOP, you create a `build.rs` file that looks something
+like this:
+
+```rust
+extern crate lalrpop;
+
+fn main() {
+    lalrpop::process_root().unwrap();
+}
+```
+
+This `process_root()` call simply applies the default configuration:
+so it will transform `.lalrpop` files into `.rs` files *in-place* (in
+your `src` directory), and it will only do so if the `.lalrpop` file
+has actually changed. But you can also use the
+[`Configuration`][config] struct to get more detailed control.
+
+[config]: https://docs.rs/lalrpop/*/lalrpop/struct.Configuration.html
+
+For example, to **force** the use of colors in the output (ignoring
+the TTY settings), you might make your `build.rs` file look like so:
+
+```rust
+extern crate lalrpop;
+
+fn main() {
+    Configuration::new()
+        .always_use_colors()
+        .process_current_dir();
+}
+```

doc/src/out_dir.md

@@ -0,0 +1,24 @@
+One common request is to have LALRPOP generate its files into Cargo's
+**output directory**, rather than storing them 'in-place' within the
+module tree. This can be done through the following configuration:
+
+```rust
+extern crate lalrpop;
+
+fn main() {
+    Configuration::new()
+        .use_cargo_dir_conventions()
+        .process();
+}
+```
+
+In addition, because the modules are generated out of the `src`
+directory, for each `foo.lalrpop` file you can't simply have `mod
+foo;` in your source.  Instead, you must put the following in the
+parent module:
+
+```rust
+include!(concat!(env!("OUT_DIR"), "/path/to/foo.rs"));
+```
+
+Here the `path/to/foo.rs` should be relative to the `src` directory.

doc/src/quick_start_guide.md

@@ -0,0 +1,59 @@
+For getting started with LALRPOP, it's probably best if you read
+[the tutorial](tutorial/index.html), which will introduce you
+to the syntax of LALRPOP files and so forth. 
+
+But if you've done this before, or you're just the impatient sort,
+here is a quick 'cheat sheet' for setting up your project.  First, add
+the following lines to your `Cargo.toml`:
+
+```
+[package]
+...
+build = "build.rs" # LALRPOP preprocessing
+
+# The generated code depends on lalrpop-util.
+#
+# The generated tokenizer depends on the regex crate.
+#
+# (If you write your own tokenizer, or already have the regex
+# crate, you can skip this dependency.)
+[dependencies]
+lalrpop-util = "0.14.0"
+regex = "0.2.0"
+
+# Add a build-time dependency on the lalrpop library:
+[build-dependencies]
+lalrpop = "0.14.0"
+```
+
+Next create a `build.rs` file that looks like:
+
+```rust
+extern crate lalrpop;
+
+fn main() {
+    lalrpop::process_root().unwrap();
+}
+```
+
+(If you already have a `build.rs` file, you should be able to just
+call `process_root` in addition to whatever else that file is doing.)
+
+That's it! Note that `process_root` simply uses the default settings.
+If you want to configure how LALRPOP executes, see the
+[advanced setup](advanced_setup.html) section.
+
+#### Running manually
+
+If you prefer, you can also run the `lalrpop` crate as an
+executable. Simply run `cargo install lalrpop` and then you will get a
+`lalrpop` binary you can execute, like so:
+
+```
+lalrpop file.lalrpop
+```
+
+This will generate `file.rs` for you. Note that it only executes if
+`file.lalrpop` is newer than `file.rs`; if you'd prefer to execute
+unconditionally, pass `-f` (also try `--help` for other options).
+

doc/src/tutorial/001_adding_lalrpop.md

@@ -17,7 +17,7 @@ To start, let's use `cargo new` to make a new project. We'll call it
 > cargo new --bin calculator
 ```
 
-We now have to edit the generated [`calculator/Cargo.toml`][cargotoml]
+We now have to edit the generated [`calculator/Cargo.toml`](calculator/Cargo.toml)
 file to invoke the LALRPOP preprocessor. The resulting file should
 look something like:
 

publish.sh

@@ -39,14 +39,25 @@ publish lalrpop-util
 publish lalrpop-snap
 publish lalrpop
 
-printf "Updated version in README and tutorial..."
+printf "Updated version in docs etc..."
 perl -p -i -e 's/^version = "[0-9.]+"$/version = "'$VERSION'"/' \
-     README.md doc/tutorial.md doc/*/Cargo.toml >& $TMPDIR/publish-log || publish_fail
+     doc/*/Cargo.toml \
+     >& $TMPDIR/publish-log || publish_fail
 perl -p -i -e 's/^lalrpop = "[0-9.]+"$/lalrpop = "'$VERSION'"/' \
-     doc/tutorial.md doc/*/Cargo.toml >& $TMPDIR/publish-log || publish_fail
+     doc/src/*.md \
+     doc/src/tutorial/*.md \
+     doc/*/Cargo.toml \
+     >& $TMPDIR/publish-log || publish_fail
 perl -p -i -e 's/^lalrpop-util = "[0-9.]+"$/lalrpop-util = "'$VERSION'"/' \
-     doc/tutorial.md doc/*/Cargo.toml >& $TMPDIR/publish-log || publish_fail
-git add -f README.md doc/tutorial.md doc/*/Cargo.toml >& $TMPDIR/publish-log || publish_fail
+     doc/src/*.md \
+     doc/src/tutorial/*.md \
+     doc/*/Cargo.toml \
+     >& $TMPDIR/publish-log || publish_fail
+git add -f \
+    doc/src/*.md \
+    doc/src/tutorial/*.md \
+    doc/*/Cargo.toml \
+    >& $TMPDIR/publish-log || publish_fail
 printf "OK\n"
 
-printf "\nAll set. Do not forget to commit new README.md et al.\n"
+printf "\nAll set. **Do not forget to commit new changes.**\n"