Docs: Add missing commands to redo.md, and add redo-whichdo.md.

Documentation/redo-whichdo.md

@@ -0,0 +1,112 @@
+% redo-ifchange(1) Redo %VERSION%
+% Avery Pennarun <apenwarr@gmail.com>
+% %DATE%
+
+# NAME
+
+redo-whichdo - show redo's search path for a .do file
+
+# SYNOPSIS
+
+redo-whichdo &lt;target>
+
+
+# DESCRIPTION
+
+`redo`(1) and `redo-ifchange`(1) build their targets by executing a ".do
+file" script with appropriate arguments.  .do files are searched starting
+from the directory containing the target, and if not found there, up the
+directory tree until a match is found.
+
+To help debugging your scripts when redo is using an unexpected .do file, or
+to write advanced scripts that "proxy" from one .do file to another, you
+can use `redo-whichdo` to see the exact search path that `redo` uses,
+and the arguments it would use to run the .do file once found.
+
+The output format contains lines in exactly the following order, which is
+intended to be easy to parse in `sh`(1) scripts:
+
+- Zero or more lines starting with "-", indicating .do files that were
+  checked, but did not exist.  If one of these files is created, the .do
+  script for your target would change.  You might
+  want to call `redo-ifcreate`(1) for each of these files.
+
+- Exactly one line starting with "+", indicating the .do file that was the
+  closest match.
+
+- Exactly one line starting with "1", indicating the first argument to the
+  matching .do file.
+
+- Exactly one line starting with "2", indicating the second argument to the
+  matching .do file.
+
+# EXAMPLE
+
+Here's a typical search path for a source file (`x/y/a.b.o`).  Because the
+filename contains two dots (.), at each level of the hierarchy, `redo` needs
+to search `default.b.o.do`, `default.o.do`, and `default.do`.
+
+        $ redo-whichdo x/y/a.b.o
+
+        - x/y/a.b.o.do
+        - x/y/default.b.o.do
+        - x/y/default.o.do
+        - x/y/default.do
+        - x/default.b.o.do
+        - x/default.o.do
+        - x/default.do
+        - default.b.o.do
+        + default.o.do
+        1 x/y/a.b.o
+        2 x/y/a.b
+
+You might use `redo-whichdo` to delegate from one .do script to another, 
+using code like this:
+
+        out=$3
+        redo-whichdo "$SRCDIR/$1" | {
+            x1= x2= dofile=
+            ifcreate=
+            while read a b; do
+                case $a in
+                  -)
+                    ifcreate="$ifcreate $b"
+                    ;;
+                  +)
+                    redo-ifcreate $ifcreate &&
+                    redo-ifchange "$b" || exit
+                    dopath="$b"
+                    dodir=$(dirname "$dopath")
+                    dofile=$(basename "$dopath")
+                    ;;
+                  1)
+                    x1="$b"
+                    ;;
+                  2)
+                    x2="$b"
+                    out="$PWD/$3"
+                    cd "$dodir" && . "./$dofile" "$x1" "$x2" "$out"
+                    exit
+                    ;;
+                esac
+            done
+            exit 3
+        }
+
+
+# REDO
+
+Part of the `redo`(1) suite.
+    
+# CREDITS
+
+The original concept for `redo` was created by D. J.
+Bernstein and documented on his web site
+(http://cr.yp.to/redo.html).  This independent implementation
+was created by Avery Pennarun and you can find its source
+code at http://github.com/apenwarr/redo.
+
+
+# SEE ALSO
+
+`redo`(1), `redo-ifchange`(1), `redo-ifcreate`(1)

Documentation/redo.md

@@ -198,32 +198,51 @@ redo is really the only kind of redo.
 When writing a .do script, it will probably need to run
 one or more of the following commands:
 
-`redo`
+`redo [targets...]`
 :   to build a sub-target unconditionally.
 
-`redo-ifchange` 
-:   to build a sub-target only if the sub-target's
-    dependencies have changed.
+`redo-ifchange [targets...]`
+:   to declare dependencies on the given files, and build them if
+    they don't yet exist or are outdated.
 
-`redo-ifcreate`
+`redo-ifcreate [sources...]`
 :   to tell redo that the current target must be rebuilt if
-    a particular file gets created.
+    the given source files (which must not yet exist) get created.
 
 `redo-always`
 :   to tell redo that the current target must always be
-    rebuilt, even if someone calls it using `redo-ifchange`.
-    (This might happen if the current target has
-    dependencies other than the contents of files.)
+    rebuilt, even if none of its dependencies have changed.
+    (You might need this for targets that depend on more than just
+    file contents. For example, the output of `ls *.c`
+    changes when files are created or deleted, but there is no way
+    for redo to know that without re-running the command.)
 
-`redo-stamp`
+`echo "stamp contents..." | redo-stamp`
 :   to tell redo that even though the current target has
     been rebuilt, it may not actually be any different from
     the previous version, so targets that depend on it
     might not need to be rebuilt.  Often used in
     conjunction with `redo-always` to reduce the impact of
     always rebuilding a target.
-    
-    
+
+
+There are also some less common ones:
+
+`redo-ood`
+:   Get a list of all known targets that have been built before, but
+    are currently out of date.
+
+`redo-targets`
+:   Get a list of all known targets that have been built before.
+
+`redo-sources`
+:   Get a list of all known redo source files that still exist.
+
+`redo-whichdo <target>`
+:   Explain the search path used to find a .do file for the given
+    target.
+
+
 # CREDITS
 
 The original concept for `redo` was created by D. J.
@@ -237,4 +256,5 @@ code at http://github.com/apenwarr/redo.
 
 `sh`(1), `make`(1),
 `redo-ifchange`(1), `redo-ifcreate`(1), `redo-always`(1),
-`redo-stamp`(1)
+`redo-stamp`(1), `redo-ood`(1), `redo-targets`(1), `redo-sources`(1),
+`redo-whichdo`(1)