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,24 +198,26 @@ 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` 
+`redo-ifchange [targets...]`
-:   to build a sub-target only if the sub-target's
+:   to declare dependencies on the given files, and build them if
-    dependencies have changed.
+    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`.
+    rebuilt, even if none of its dependencies have changed.
-    (This might happen if the current target has
+    (You might need this for targets that depend on more than just
-    dependencies other than the contents of files.)
+    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
@@ -224,6 +226,23 @@ one or more of the following commands:
     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)