From 480ab4060b2762490e72a2a89ddf3d106f1402e1 Mon Sep 17 00:00:00 2001
From: Sergey Matveev <stargrave@stargrave.org>
Date: Tue, 22 Jun 2021 14:28:41 +0300
Subject: [PATCH] Fixed URL

---
 doc/index.texi |  2 +-
 doc/rules.texi | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 98 insertions(+), 1 deletion(-)
 create mode 100644 doc/rules.texi

diff --git a/doc/index.texi b/doc/index.texi
index 1ce43f5..f84fc4d 100644
--- a/doc/index.texi
+++ b/doc/index.texi
@@ -27,7 +27,7 @@ If you are not familiar with the redo, here are advisable links to read:
 
 @itemize
 @item @url{https://redo.readthedocs.io/en/latest/, apenwarr/redo documentation}
-@item @url{http://web.archive.org/web/20201231033027/http://jdebp.eu/FGA/introduction-to-redo.html, Introduction to redo}
+@item @url{http://jdebp.uk/FGA/introduction-to-redo.html, Introduction to redo}
 @item @url{https://apenwarr.ca/log/20101214, The only build system that might someday replace make... is djb redo}
 @item @url{https://habr.com/ru/post/517490/,, Make на мыло, redo сила} (on russian)
 @end itemize
diff --git a/doc/rules.texi b/doc/rules.texi
new file mode 100644
index 0000000..dedcf5b
--- /dev/null
+++ b/doc/rules.texi
@@ -0,0 +1,97 @@
+@node Usage rules
+@unnumbered Usage rules
+
+@itemize
+
+@item Target is the single file.
+Target's result probably won't create file at all.
+
+@item Build rules for the target @file{target} are placed in
+@file{target.do} file.
+
+@item By default @file{.do} file is run as @code{/bin/sh -e} script.
+If @command{redo} is run with an @option{-x} argument, then
+@code{/bin/sh -ex} is used instead.
+
+@item Executable @file{.do} file is run as is, by direct execution.
+
+@item Targets can be placed in other directories, probably with
+relatives paths.
+
+@item Following @file{.do} files are searched for @file{dir/base.a.b} target:
+
+@example
+dir/base.a.b.do
+dir/default.a.b.do
+dir/default.b.do
+dir/default.do
+default.a.b.do
+default.b.do
+default.do
+@end example
+
+and for @file{../a/b/xtarget.y} target:
+
+@example
+./../a/b/xtarget.y.do
+./../a/b/default.y.do
+./../a/b/default.do
+./../a/default.y.do
+./../a/default.do
+./../default.y.do
+./../default.do
+@end example
+
+@item @file{.do} file search goes up to @file{/} by default, but can be
+    limited with either @env{$REDO_TOP_DIR} environment variable, or by
+    having @file{.redo/top} file in it.
+
+@item @file{.do} runs in the same directory where it is placed.
+
+@item @file{.do} runs with the three arguments:
+    @itemize
+    @item @code{$1} -- name of the target.
+    @item @code{$2} -- base name of the target. Equals to @code{$1} if
+        it is not @file{default.*} file. Otherwise it lacks the extension.
+@example
+a.b.c.do       -> $2=a.b.c
+default.do     -> $2=a.b.c
+default.c.do   -> $2=a.b
+default.b.c.do -> $2=a
+@end example
+    @item @code{$3} -- path to the temporary file, that will be renamed
+        to the target itself. It is relative to the file in the target
+        directory.
+    @end itemize
+
+@item @file{.do}'s @code{stdout} is captured and written to the
+    @code{$3} file. You have to produce either @code{stdout} output, or
+    use @code{$3} directly, but not both.
+
+@item If there was no @code{stdout} output and no @code{$3} file is
+    explicitly created, then no output file is created at all. Target
+    does not produce anything, it is "empty".
+
+@item @code{stderr} is not captured at all and can be seen by default.
+
+@item Empty targets are considered always out-of-date.
+
+@item Dependency information is recorded by @command{redo-ifchange}
+    command invocation. It takes list of dependencies (targets), on
+    whose the currently build target is dependant. Current @file{.do}
+    file is implicitly added as a dependency.
+
+@item If no @command{redo-ifchange}'s dependency target exists, then it
+    is build (according to build rules in corresponding @file{.do}). If
+    dependency has not been changed, then it is not rebuilt.
+
+@item Non-existent files dependencies are created with
+    @command{redo-ifcreate} command. If specified dependency target file
+    appears, then current target will be rebuilt. Intermediate higher
+    priority @file{.do} files dependency is implicitly recorded. For
+    example, if you @file{foo} target currently uses @file{default.do}
+    script, then @file{foo.do} is automatically recorded as a
+    non-existent dependency, forcing @file{foo} to be rebuilt if
+    @file{foo.do} appears.
+
+@end itemize
-- 
2.44.0