Various documentation changes

diff --git a/doc/cmds.texi b/doc/cmds.texi
index 19cd5f09327bad6430b65089ee6c1056012311a5..1483b7f204569cb0c43cf6b70c424bf2fc90c87b 100644 (file)
--- a/doc/cmds.texi
+++ b/doc/cmds.texi
@@ -6,11 +6,12 @@
 @item redo-ifchange, redo-ifcreate, redo-always
 
 @item redo
 @item redo-ifchange, redo-ifcreate, redo-always
 
 @item redo

-    Same as redo-ifchange, but forcefully and sequentially run specified
-    targets.
+    Same as @command{redo-ifchange}, but forcefully and sequentially run
+    specified targets.

 
 @item redo-log
 
 @item redo-log

-    Display TAI64N timestamped last @command{stderr} of the target.
+    Display @url{http://cr.yp.to/libtai/tai64.html, TAI64N} timestamped
+    last @command{stderr} of the target.

 
 @item redo-stamp
     Record stamp dependency. Nothing more, dummy. Read about
 
 @item redo-stamp
     Record stamp dependency. Nothing more, dummy. Read about

diff --git a/doc/faq.texi b/doc/faq.texi
index 02ea26b9872df96a5b33f5c3d6be25edda8be63c..1c6def3ffa8473be75a65b981e0d17f7b6514614 100644 (file)
--- a/doc/faq.texi
+++ b/doc/faq.texi
@@ -5,9 +5,10 @@
 @section Hashing and stamping
 
 All targets are checksummed if their @file{ctime} differs from the
 @section Hashing and stamping
 
 All targets are checksummed if their @file{ctime} differs from the

-previous one. @command{apenwarr/redo} gives many reasons why every time
-checksumming is bad, but in my opinion in practice all of them do not
-apply.
+previous one. @command{apenwarr/redo} gives
+@url{https://redo.readthedocs.io/en/latest/FAQImpl/#why-not-always-use-checksum-based-dependencies-instead-of-timestamps, many reasons}
+why every time checksumming is bad, but in my opinion in practice all of
+them do not apply.

 
 @itemize
 @item Aggregate targets and willing to be out-of-date ones just must not
 
 @itemize
 @item Aggregate targets and willing to be out-of-date ones just must not


@@ -18,26 +19,26 @@ apply.
 @end itemize
 
 DJB's proposal with both @file{stdout} and @file{$3} gives that ability
 @end itemize
 
 DJB's proposal with both @file{stdout} and @file{$3} gives that ability

-to control your desired behaviour. Those who does not capture
-@file{stdout} -- failed. Those who creates an empty file if no
+to control your desired behaviour. Those who do not capture
+@file{stdout} -- failed. Those who create an empty file if no

 @file{stdout} was written -- failed.
 
 redo is a tool to help people. Literally all targets can be safely
 @code{redo-stamp < $3}-ed, reducing false positive out-of-dates. Of
 course, with the correct @file{stdout}/@file{$3} working and placing
 necessary results in @file{$3}, instead of just silently feeding them in
 @file{stdout} was written -- failed.
 
 redo is a tool to help people. Literally all targets can be safely
 @code{redo-stamp < $3}-ed, reducing false positive out-of-dates. Of
 course, with the correct @file{stdout}/@file{$3} working and placing
 necessary results in @file{$3}, instead of just silently feeding them in

-redo-stamp.
+@command{redo-stamp}.

 
 redo implementations are already automatically record -ifchange on
 @file{.do} files and -ifcreate on non-existing @file{.do} files. So why
 
 redo implementations are already automatically record -ifchange on
 @file{.do} files and -ifcreate on non-existing @file{.do} files. So why

-they can not record redo-stamp the same way implicitly? No, Zen of
-Python does not applicable there, because -ifchange/-ifcreate contradict
-it already.
+they can not record @command{redo-stamp} the same way implicitly? No,
+Zen of Python does not applicable there, because -ifchange/-ifcreate
+contradict it already.

 
 Modern cryptographic hash algorithms and CPUs are so fast, that even all
 read and writes to or from hard drive arrays can be easily checksummed
 
 Modern cryptographic hash algorithms and CPUs are so fast, that even all
 read and writes to or from hard drive arrays can be easily checksummed

-and transparently compressed, as ZFS with LZ4 and Skein/BLAKE[23]
-algorithms demonstrate us.
+and transparently compressed, as ZFS with LZ4/Zstandard and
+Skein/BLAKE[23] algorithms demonstrate us.

 
 @command{goredo} includes @command{redo-stamp}, that really records the
 stamp in the @file{.dep} file, but it does not play any role later. It
 
 @command{goredo} includes @command{redo-stamp}, that really records the
 stamp in the @file{.dep} file, but it does not play any role later. It


@@ -56,8 +57,6 @@ then just remove @file{foo/.redo/bar.dep}.
 
 @command{goredo}, together with @command{apenwarr/redo}, rebuilds target
 once per @strong{run}.
 
 @command{goredo}, together with @command{apenwarr/redo}, rebuilds target
 once per @strong{run}.

-Always rebuilds during every redo invocation, but only once during it
-building.

 @url{http://news.dieweltistgarnichtso.net/bin/redo-sh.html#why-built-twice, redo-sh}
 has other opinion, that is why its @file{redo-sh.tests/always_rebuild_1}
 will fail. Rebuilding of always-ed targets even during the same build
 @url{http://news.dieweltistgarnichtso.net/bin/redo-sh.html#why-built-twice, redo-sh}
 has other opinion, that is why its @file{redo-sh.tests/always_rebuild_1}
 will fail. Rebuilding of always-ed targets even during the same build

diff --git a/doc/features.texi b/doc/features.texi
index 5d2b634df5504a4b84c5eeec8cf7048c4cb1f52b..9145312fe547e5cd9d8aa74e3068e1776dc27f26 100644 (file)
--- a/doc/features.texi
+++ b/doc/features.texi
@@ -25,8 +25,8 @@
 @item target's @file{stderr} can be stored on the disk with
     @url{http://cr.yp.to/libtai/tai64.html, TAI64N} timestamp prefixes
     for each line. To convert them to localtime you can use either
 @item target's @file{stderr} can be stored on the disk with
     @url{http://cr.yp.to/libtai/tai64.html, TAI64N} timestamp prefixes
     for each line. To convert them to localtime you can use either

-    tai64nlocal utility from @url{http://cr.yp.to/daemontools.html,
-    daemontools}, or similar one:
+    @command{tai64nlocal} utility from
+    @url{http://cr.yp.to/daemontools.html, daemontools}, or similar one:

     @code{go get go.cypherpunks.ru/tai64n/cmd/tai64nlocal}
 
 @end itemize
     @code{go get go.cypherpunks.ru/tai64n/cmd/tai64nlocal}
 
 @end itemize

diff --git a/doc/notes.texi b/doc/notes.texi
index a74a001fdaba4bcda19d793911fbf8c85fcfdf44..4922f7150415d7b77c18e3a08748802d8156e605 100644 (file)
--- a/doc/notes.texi
+++ b/doc/notes.texi
@@ -14,7 +14,8 @@
 @item target's completion messages are written after they finish
 @item executable @file{.do} is run as is, non-executable is run with
     @code{/bin/sh -e[x]}
 @item target's completion messages are written after they finish
 @item executable @file{.do} is run as is, non-executable is run with
     @code{/bin/sh -e[x]}

-@item tracing (-x) can be obviously done only for non-executable @file{.do}
+@item tracing (@option{-x}) can be obviously done only for
+    non-executable @file{.do}

 @item parallizable build is done only during @command{redo-ifchange} for
     human convenience: you can globally enable @env{REDO_JOBS}, but
     still do for example: @code{redo htmls infos index upload}
 @item parallizable build is done only during @command{redo-ifchange} for
     human convenience: you can globally enable @env{REDO_JOBS}, but
     still do for example: @code{redo htmls infos index upload}

diff --git a/doc/state.texi b/doc/state.texi
index d4fa9dbfa753de896a020bacce36c6c80ffc7708..5313ae1817857ec8d963b51e5cd6a8d536320218 100644 (file)
--- a/doc/state.texi
+++ b/doc/state.texi
@@ -5,8 +5,7 @@ Dependency and build state is kept inside @file{.redo} subdirectory in
 each directory related the build. Each corresponding target has its own,
 recreated with every rebuild, @file{.dep} file. It is
 @url{https://www.gnu.org/software/recutils/, recfile}, that could have
 each directory related the build. Each corresponding target has its own,
 recreated with every rebuild, @file{.dep} file. It is
 @url{https://www.gnu.org/software/recutils/, recfile}, that could have

-various dependency information (@file{dep.rec} with the schema
-included):
+various dependency information. For example:

 
 @example
 Build: 80143f04-bfff-4673-950c-081d712f573d
 
 @example
 Build: 80143f04-bfff-4673-950c-081d712f573d


@@ -24,3 +23,6 @@ Type: always
 Type: stamp
 Hash: 5bbdf635932cb16b9127e69b6f3872577efed338f0a4ab6f2c7ca3df6ce50cc9
 @end example
 Type: stamp
 Hash: 5bbdf635932cb16b9127e69b6f3872577efed338f0a4ab6f2c7ca3df6ce50cc9
 @end example

+
+And the schema definition:
+@verbatiminclude ../dep.rec