Even more doc cleanups.

Documentation/Contributing.md

@@ -9,7 +9,7 @@ versions of redo were distributed under the GNU LGPL, but this [changed in
 2018](https://groups.google.com/forum/#!topic/redo-list/wLMZMxtn4wo).)
 
 minimal/do is in the public domain so that it's as easy as possible
-to include inside your own projects for people who don't
+to include inside your own projects, to help end users who don't
 have a copy of redo.
 
 
@@ -42,6 +42,11 @@ The best things you can do for redo are:
 - Convince your favourite OS distro to build and include (up to date!) redo
   packages.
 
+- Help proofreading this documentation, and send patches or pull requests
+  with improvements.
+
+- Join the mailing list (below) to discuss design changes or bugs.
+
 - Tell your friends!
 
 
@@ -60,5 +65,3 @@ It's okay to send a message directly to the mailing list
 without subscribing first.  If you reply to someone who writes to the
 list, please leave them in the cc: list, since if they
 haven't subscribed, they won't get your reply otherwise. 
-
-

Documentation/FAQBasics.md

@@ -1,4 +1,30 @@
-# Does redo make cross-platform builds easy?
+# Help! redo rebuilds every time, even if dependencies are clean!
+
+Many people are confused by this at first.  The `redo` command *always*
+rebuilds the target you requested.  If you want to only conditionally
+rebuild the target, use `redo-ifchange`.
+
+The same rule applies inside .do scripts.  If a .do script calls `redo dep`,
+then it will always redo the target called dep.  If it called `redo-ifchange
+dep`, it will only redo dep if its dependencies have changed.
+
+Typically, you want your toplevel `all.do` script to use `redo-ifchange`. 
+But a `clean.do` script probably should use `redo`, because you want it to
+always clean up your extra files.  A `test.do` probably also uses `redo` for
+its testing sub-tasks, because you might want to run your tests repeatedly.
+
+For rationale, see [Why does 'redo target' redo even unchanged
+targets?](../FAQSemantics/#why-does-redo-target-redo-even-unchanged-targets)
+
+
+# I'm using redo-ifchange. How does redo decide my target is clean/dirty?
+
+You can see (recursively) which dependencies checked by redo, and whether
+they are clean or dirty, by using `redo -d` (which is short for
+"dependencies" or "debug", whichever you prefer).
+
+
+# Does redo make cross-platform or multi-platform builds easy?
 
 A lot of build systems that try to replace make do it by trying to provide a
 lot of predefined rules.  For example, one build system I know includes
@@ -46,13 +72,14 @@ To activate it, you can add a line like this to your .bashrc:
 # Do end users have to have redo installed in order to build my project?
 
 No.  We include a very short and simple shell script
-called `do` in the `minimal/` subdirectory of the redo project.  `do` is like
+called `do` in the `minimal/` subdirectory of the redo project.
+`minimal/do` is like
 `redo` (and it works with the same `*.do` scripts), except it doesn't
 understand dependencies; it just always rebuilds everything from the top.
 
-You can include `do` with your program to make it so non-users of redo can
+You can include `do` with your program so that non-users of redo can
 still build your program.  Someone who wants to hack on your program will
-probably go crazy unless they have a copy of `redo` though.
+probably go crazy unless they install a copy of `redo` though.
 
 Actually, `redo` itself isn't so big, so for large projects where it
 matters, you could just include it with your project.

Documentation/index.md

@@ -169,8 +169,8 @@ easily be linked from this document.  Here are a few open source examples:
   Buildroot](https://github.com/apenwarr/buildroot/tree/redo) that uses redo
   in order to clean up its dependency logic.
 
-* You can also find some limited examples in the
+* You can also find some curated examples in the
-  [`t/111-example/`](t/111-example) subdir of the redo project itself.
+  [Documentation/cookbook/](https://github.com/apenwarr/redo/tree/master/Documentation/cookbook/) subdir of the redo project itself.
 
 * A [github search for all.do](https://github.com/search?p=9&q=path%3A%2F+extension%3Ado+filename%3A%2Fall.do&type=Code)
   shows an ever-growing number of projects using redo.
@@ -234,7 +234,8 @@ of these links):
 - catenate's [credo](https://github.com/catenate/credo), a (very
   rearchitected) variant written for the Inferno Shell.
 
-The redo design is so simple and elegant that many individuals have been
+The original redo design is so simple and elegant that many individuals
+have been
 inspired to (and able to) write their own version of it.  In the honoured
 tradition of Unix's `make`, they (almost) all just use the same name,
 `redo`.  Unfortunately, many of these
@@ -242,5 +243,16 @@ implementations are unmaintained, slightly incompatible with the "standard"
 redo semantics, and/or have few or no automated tests.
 
 At the time of this writing, none of them except apenwarr/redo (ie.  this
-project) support parallel builds (`redo -j`).  For large projects,
+project) support parallel builds (`redo -j`) or log linearization
-parallel builds are usually considered essential.
+(`redo-log`).  For large projects, parallel builds are usually considered
+essential.
+
+The [automated tests](https://github.com/apenwarr/redo/tree/master/t) in
+this version of redo are almost, but not quite, appropriate for testing any
+redo implementation.  If you really must write a new version of redo, we
+invite you to thoroughly test it against the existing test suite to ensure
+compatibility.  You can also steal our tests (with attribution, of course)
+and include them in your own source package.  We'd also love it it you
+contribute more automated tests when you find a bug, or send us patches if
+you find a test which is accidentally incompatible (as opposed to finding a
+real bug) with other redo implementations.

mkdocs.yml

@@ -3,22 +3,24 @@ theme: readthedocs
 docs_dir: Documentation
 site_dir: website
 strict: true
+repo_url: https://github.com/apenwarr/redo
+edit_uri: edit/master/Documentation
 extra_javascript:
   - fetchcode.js
 
 pages:
   - Introduction: index.md
   - Getting Started: GettingStarted.md
+  - Contributing.md
   - Cookbook:
-    - Hello World: cookbook/hello.md
+    - Hello World (hello.do, redo-ifchange): cookbook/hello/index.md
-    - Using default.do (text processing): cookbook/defaults.md
+    - Text processing example (default.do, redo-whichdo, redo-always, redo-stamp): cookbook/defaults/index.md
   - FAQ:
     - Basics: FAQBasics.md
     - Semantics: FAQSemantics.md
     - Interop with make: FAQInterop.md
     - Parallel Builds: FAQParallel.md
     - Implementation Details: FAQImpl.md
-  - Contributing.md
   - Reference Manual:
     - redo(1): redo.md
     - redo-ifchange(1): redo-ifchange.md