From 95478a2cedcc3511096d0d8dbfffe6f863ff6051 Mon Sep 17 00:00:00 2001
From: Evan Martin <martine@danga.com>
Date: Sat, 4 Dec 2010 16:14:48 -0800
Subject: rename docs

---
 README          |   1 +
 README.asciidoc | 228 --------------------------------------------------------
 build.ninja     |   4 +-
 manual.asciidoc | 228 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 231 insertions(+), 230 deletions(-)
 create mode 100644 README
 delete mode 100644 README.asciidoc
 create mode 100644 manual.asciidoc

diff --git a/README b/README
new file mode 100644
index 0000000..de7c975
--- /dev/null
+++ b/README
@@ -0,0 +1 @@
+See manual.html.
diff --git a/README.asciidoc b/README.asciidoc
deleted file mode 100644
index b348459..0000000
--- a/README.asciidoc
+++ /dev/null
@@ -1,228 +0,0 @@
-Ninja
-=====
-
-Introduction
-------------
-
-Ninja is yet another build system.  It takes as input a file
-describing interdependencies of files (typically source code and
-output executables) and orchestrates building them, _quickly_.
-
-Ninja joins a sea of other build systems.  Its distinguishing goal is
-to be fast.  It is born from my work on the Chromium browser project,
-which has well over 20,000 source files and whose other build systems
-(including one built from custom non-recursive Makefiles) take tens of
-seconds to rebuild after changing one file, even on a fast computer.
-
-Here are some of the design goals of Ninja:
-
-* very fast (i.e., instant) incremental builds, even for very large
-  projects.
-
-* very little implicit policy; "explicit is better than implicit".
-
-* get dependencies correct, and in particular situations that are
-  difficult to get right with Makefiles (e.g. outputs should have an
-  implicit dependency on the command line used to generate them; using
-  gcc's `-M` flags for header dependencies).
-
-* when convenience and speed are in conflict, prefer speed.
-
-Some explicit _non-goals_:
-
-* convenient syntax for writing build files by hand.  _You should
-  generate your ninja files using another program_.  This is how we
-  sidestep many policy decisions.
-
-* built-in rules. _Out of the box, ninja has no rules for
-  e.g. compiling C code._
-
-* build-time customization of the build. _Options belong in
-  the program that generates the ninja files_.
-
-To restate, Ninja manages to be simpler and faster than other build
-systems by being much more stupid.  It has no built-in behavior
-describing how to build C source, or build libraries, or install
-binaries.  You instead decide this policy when you create your
-project's `.ninja` files.  Customization and configuration are out of
-scope; instead you should provide customization in the system that
-generates your `.ninja` files, like how autoconf provides
-`./configure`.
-
-Getting started
----------------
-
-The included `bootstrap.sh` should hopefully produce a working `ninja`
-binary, by first blindly compiling all non-test files together then
-re-building ninja using itself.
-
-Usage is currently just
-
-----------------
-ninja target
-----------------
-
-where `target` is a known output described by `build.ninja` in the
-current directory.
-
-Creating .ninja files
-~~~~~~~~~~~~~~~~~~~~~
-A build file (default name: `build.ninja`) provides a list of _rules_
-along with a list of _build_ statements saying how to build files
-using the rules.  The only other syntax is a way of declaring
-(immutable) variables.
-
-Conceptually, `build` statements describe the dependency graph of your
-project, while `rule` statements describe how to generate the files
-along a given edge of the graph.
-
-Here's a basic `.ninja` file that demonstrates most of the syntax.
-
----------------------------------
-cflags = -Wall
-
-rule cc
-  command = gcc $cflags -c $in -o $out
-
-build foo.o: cc foo.c
----------------------------------
-
-Rules
-~~~~~
-
-Rules begin with a line consisting of the `rule` keyword and a name
-for the rule.  Then follows an indented set of `key = value` lines.
-
-The basic example above declares a new rule named `cc`, along with the
-command to run.  (In the context of a rule, the `command` key is
-special and defines the command to run.  A full list of special keys
-is provided in the reference.)
-
-Variables begin with a `$` and are described more fully later, but
-here `$in` expands to the list of input files (`foo.c`) and `$out` to
-the output file (`foo.o`) for the command.
-
-
-Build statements
-~~~~~~~~~~~~~~~~
-
-Build statements begin with the `build` keyword, and have the format
-+build _outputs_: _rulename_ _inputs_+.  Such a declaration says that
-all of the output files are derived from the input files.  When the output
-files are missing or when the inputs change, ninja will run the rule
-to regenerate the outputs.
-
-The basic example above describes how to build `foo.o`, using the `cc`
-rule.
-
-A build statement may be followed by an indented set of `key = value`
-pairs, much like a rule.  These bindings will shadow any bindings when
-evaluating the variables in the command.  For example:
-
-----------------
-cflags = -Wall -Werror
-rule cc
-  command = gcc $cflags -c $in -o $out
-
-# If left unspecified, builds get the outer $cflags.
-build foo.o: cc foo.c
-
-# But you can can shadow variables like cflags for a particular build.
-build special.o: cc.special.c
-  cflags = -Wall
-----------------
-
-
-Variables
-~~~~~~~~~
-Despite the non-goal of being convenient to write by hand, to keep
-build files readable (debuggable), Ninja supports declaring bindings
-(variables).  A declaration like the following
-
-----------------
-cflags = -g
-----------------
-
-Can be used on the right side of an equals sign like this:
-
-----------------
-rule cc
-  command = gcc $cflags -c $in -o $out
-----------------
-
-Variables can also be referenced using curly braces like `${in}`.
-
-Variables might better be called "bindings", in that a given variable
-cannot be changed, only shadowed.  Within a larger Ninja project,
-different _scopes_ allow variable values to be overridden.  XXX finish
-describing me.
-
-Ninja file reference
---------------------
-A file is a series of declarations.  A declaration can be one of:
-
-1. A rule declaration, which begins with +rule _rulename_+.
-2. A build edge, which looks like +build _outputs_: _rulename_ _inputs_+
-3. Variable declarations, which look like +_variable_ = _value_+.
-
-Comments begin with `#` and extend to the end of the line.
-
-Newlines are significant, but they can be escaped by putting a `\`
-before them.
-
-Whitespace is only significant if it's at the beginning of a line.  If
-a line is intended more than the previous one, it's considered part of
-its parent's scope; if it is indented less than the previous one, it
-closes the previous scope.
-
-Rule declarations
-~~~~~~~~~~~~~~~~~
-
-A `rule` block contains a list of `key = value` declarations that
-affect the processing of the rule.  Here is a full list of special
-keys.
-
-`command` (_required_):: the command line to run.
-
-`depfile`:: path to an optional `Makefile` that contains _implicit
-  dependencies_.  Implicit dependencies are inputs to a build that are
-  not given on the command line; the best example is how `gcc` has the
-  `-M` family of flags to output the list of headers a given `.c` file
-  depends on.
-+
-----
-rule cc
-  depfile = $out.d
-  command = gcc -MMD -MF $out.d [other gcc flags here]
-----
-
-`description`:: a short description of the command, used to pretty-print
-  the command as it's running.  _XXX not implemented yet_.
-
-Special variables
-~~~~~~~~~~~~~~~~~
-`builddir` is a directory for intermediate build output.  (The name
-comes from autoconf.)  It is special in a few ways:
-
-1. It gets a shorter alias: `@`.
-2. It is implicitly a directory and has a `/` appended if needed.
-3. It may be used in the filenames of a `build` line.
-
-You must still be explicit in your rules.  In the following
-example, the files prefixed with `@` will end up in the `out/`
-subdirectory.
-
-----------------
-builddir = out
-build @intermediate_file: combine @generated_file source_file
-
-# Equivalent rule:
-# build out/intermediate_file: combine out/generated_file source_file
-----------------
-
-XXX I hacked in a special `$root` only understood in builddir -- fix
-the semantics here, is this path relative or absolute?
-
-Evaluation and scoping
-~~~~~~~~~~~~~~~~~~~~~~
-XXX talk about where variables live, nested scopes etc
diff --git a/build.ninja b/build.ninja
index 50bbe4e..981a6a6 100644
--- a/build.ninja
+++ b/build.ninja
@@ -63,8 +63,8 @@ build graph.png: gengraph @graph.dot
 rule asciidoc
   command = asciidoc -a toc $in
 
-build README.html: asciidoc README.asciidoc
-build doc: phony | README.html
+build manual.html: asciidoc manual.asciidoc
+build doc: phony | manual.html
 
 # Use the built-in phony rule and an order-only dependency
 # to make building "all" build all targets.
diff --git a/manual.asciidoc b/manual.asciidoc
new file mode 100644
index 0000000..b348459
--- /dev/null
+++ b/manual.asciidoc
@@ -0,0 +1,228 @@
+Ninja
+=====
+
+Introduction
+------------
+
+Ninja is yet another build system.  It takes as input a file
+describing interdependencies of files (typically source code and
+output executables) and orchestrates building them, _quickly_.
+
+Ninja joins a sea of other build systems.  Its distinguishing goal is
+to be fast.  It is born from my work on the Chromium browser project,
+which has well over 20,000 source files and whose other build systems
+(including one built from custom non-recursive Makefiles) take tens of
+seconds to rebuild after changing one file, even on a fast computer.
+
+Here are some of the design goals of Ninja:
+
+* very fast (i.e., instant) incremental builds, even for very large
+  projects.
+
+* very little implicit policy; "explicit is better than implicit".
+
+* get dependencies correct, and in particular situations that are
+  difficult to get right with Makefiles (e.g. outputs should have an
+  implicit dependency on the command line used to generate them; using
+  gcc's `-M` flags for header dependencies).
+
+* when convenience and speed are in conflict, prefer speed.
+
+Some explicit _non-goals_:
+
+* convenient syntax for writing build files by hand.  _You should
+  generate your ninja files using another program_.  This is how we
+  sidestep many policy decisions.
+
+* built-in rules. _Out of the box, ninja has no rules for
+  e.g. compiling C code._
+
+* build-time customization of the build. _Options belong in
+  the program that generates the ninja files_.
+
+To restate, Ninja manages to be simpler and faster than other build
+systems by being much more stupid.  It has no built-in behavior
+describing how to build C source, or build libraries, or install
+binaries.  You instead decide this policy when you create your
+project's `.ninja` files.  Customization and configuration are out of
+scope; instead you should provide customization in the system that
+generates your `.ninja` files, like how autoconf provides
+`./configure`.
+
+Getting started
+---------------
+
+The included `bootstrap.sh` should hopefully produce a working `ninja`
+binary, by first blindly compiling all non-test files together then
+re-building ninja using itself.
+
+Usage is currently just
+
+----------------
+ninja target
+----------------
+
+where `target` is a known output described by `build.ninja` in the
+current directory.
+
+Creating .ninja files
+~~~~~~~~~~~~~~~~~~~~~
+A build file (default name: `build.ninja`) provides a list of _rules_
+along with a list of _build_ statements saying how to build files
+using the rules.  The only other syntax is a way of declaring
+(immutable) variables.
+
+Conceptually, `build` statements describe the dependency graph of your
+project, while `rule` statements describe how to generate the files
+along a given edge of the graph.
+
+Here's a basic `.ninja` file that demonstrates most of the syntax.
+
+---------------------------------
+cflags = -Wall
+
+rule cc
+  command = gcc $cflags -c $in -o $out
+
+build foo.o: cc foo.c
+---------------------------------
+
+Rules
+~~~~~
+
+Rules begin with a line consisting of the `rule` keyword and a name
+for the rule.  Then follows an indented set of `key = value` lines.
+
+The basic example above declares a new rule named `cc`, along with the
+command to run.  (In the context of a rule, the `command` key is
+special and defines the command to run.  A full list of special keys
+is provided in the reference.)
+
+Variables begin with a `$` and are described more fully later, but
+here `$in` expands to the list of input files (`foo.c`) and `$out` to
+the output file (`foo.o`) for the command.
+
+
+Build statements
+~~~~~~~~~~~~~~~~
+
+Build statements begin with the `build` keyword, and have the format
++build _outputs_: _rulename_ _inputs_+.  Such a declaration says that
+all of the output files are derived from the input files.  When the output
+files are missing or when the inputs change, ninja will run the rule
+to regenerate the outputs.
+
+The basic example above describes how to build `foo.o`, using the `cc`
+rule.
+
+A build statement may be followed by an indented set of `key = value`
+pairs, much like a rule.  These bindings will shadow any bindings when
+evaluating the variables in the command.  For example:
+
+----------------
+cflags = -Wall -Werror
+rule cc
+  command = gcc $cflags -c $in -o $out
+
+# If left unspecified, builds get the outer $cflags.
+build foo.o: cc foo.c
+
+# But you can can shadow variables like cflags for a particular build.
+build special.o: cc.special.c
+  cflags = -Wall
+----------------
+
+
+Variables
+~~~~~~~~~
+Despite the non-goal of being convenient to write by hand, to keep
+build files readable (debuggable), Ninja supports declaring bindings
+(variables).  A declaration like the following
+
+----------------
+cflags = -g
+----------------
+
+Can be used on the right side of an equals sign like this:
+
+----------------
+rule cc
+  command = gcc $cflags -c $in -o $out
+----------------
+
+Variables can also be referenced using curly braces like `${in}`.
+
+Variables might better be called "bindings", in that a given variable
+cannot be changed, only shadowed.  Within a larger Ninja project,
+different _scopes_ allow variable values to be overridden.  XXX finish
+describing me.
+
+Ninja file reference
+--------------------
+A file is a series of declarations.  A declaration can be one of:
+
+1. A rule declaration, which begins with +rule _rulename_+.
+2. A build edge, which looks like +build _outputs_: _rulename_ _inputs_+
+3. Variable declarations, which look like +_variable_ = _value_+.
+
+Comments begin with `#` and extend to the end of the line.
+
+Newlines are significant, but they can be escaped by putting a `\`
+before them.
+
+Whitespace is only significant if it's at the beginning of a line.  If
+a line is intended more than the previous one, it's considered part of
+its parent's scope; if it is indented less than the previous one, it
+closes the previous scope.
+
+Rule declarations
+~~~~~~~~~~~~~~~~~
+
+A `rule` block contains a list of `key = value` declarations that
+affect the processing of the rule.  Here is a full list of special
+keys.
+
+`command` (_required_):: the command line to run.
+
+`depfile`:: path to an optional `Makefile` that contains _implicit
+  dependencies_.  Implicit dependencies are inputs to a build that are
+  not given on the command line; the best example is how `gcc` has the
+  `-M` family of flags to output the list of headers a given `.c` file
+  depends on.
++
+----
+rule cc
+  depfile = $out.d
+  command = gcc -MMD -MF $out.d [other gcc flags here]
+----
+
+`description`:: a short description of the command, used to pretty-print
+  the command as it's running.  _XXX not implemented yet_.
+
+Special variables
+~~~~~~~~~~~~~~~~~
+`builddir` is a directory for intermediate build output.  (The name
+comes from autoconf.)  It is special in a few ways:
+
+1. It gets a shorter alias: `@`.
+2. It is implicitly a directory and has a `/` appended if needed.
+3. It may be used in the filenames of a `build` line.
+
+You must still be explicit in your rules.  In the following
+example, the files prefixed with `@` will end up in the `out/`
+subdirectory.
+
+----------------
+builddir = out
+build @intermediate_file: combine @generated_file source_file
+
+# Equivalent rule:
+# build out/intermediate_file: combine out/generated_file source_file
+----------------
+
+XXX I hacked in a special `$root` only understood in builddir -- fix
+the semantics here, is this path relative or absolute?
+
+Evaluation and scoping
+~~~~~~~~~~~~~~~~~~~~~~
+XXX talk about where variables live, nested scopes etc
-- 
cgit v0.12

