From b256e5ce05c045e6d536c728776342a5c45c5995 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Tue, 9 Jun 2020 08:42:15 +0200
Subject: Update Testscript manual with notes on redirect aliases

---
 doc/testscript.cli | 52 ++++++++++++++++++++++++++++++++++++++++------------
 1 file changed, 40 insertions(+), 12 deletions(-)

(limited to 'doc')

diff --git a/doc/testscript.cli b/doc/testscript.cli
index 4c78e18..65f455f 100644
--- a/doc/testscript.cli
+++ b/doc/testscript.cli
@@ -1536,9 +1536,9 @@ stderr: '2'(out-redirect)
 
 in-redirect:  '<-'|\
               '<|'|\
-              ('<='|'<<<') <file>|\
-              ('<<='|'<<'){':'?'/'?} <here-end>|\
-              ('<<<='|'<'){':'?'/'?} <text>
+              ('<<<'|'<=') <file>|\
+              ('<<'|'<<='){':'?'/'?} <here-end>|\
+              ('<'|'<<<='){':'?'/'?} <text>
 
 out-redirect: '>-'|\
               '>|'|\
@@ -1546,9 +1546,9 @@ out-redirect: '>-'|\
               '>=' <file>|\
               '>+' <file>|\
               '>&' ('1'|'2')|\
-              ('>?'|'>>>') <file>|\
-              ('>>?'|'>>'){':'?'/'?}'~'? <here-end>|\
-              ('>>>?'|'>'){':'?'/'?}'~'? <text>
+              ('>>>'|'>?') <file>|\
+              ('>>'|'>>?'){':'?'/'?}'~'? <here-end>|\
+              ('>'|'>>>?'){':'?'/'?}'~'? <text>
 
 here-document:
   *<text>
@@ -1866,9 +1866,9 @@ $* a1>-
 \
 in-redirect:  '<-'|\
               '<|'|\
-              ('<='|'<<<') <file>|\
-              ('<<='|'<<'){':'?'/'?} <here-end>|\
-              ('<<<='|'<'){':'?'/'?} <text>
+              ('<<<'|'<=') <file>|\
+              ('<<'|'<<='){':'?'/'?} <here-end>|\
+              ('<'|'<<<='){':'?'/'?} <text>
 \
 
 The \c{stdin} data can come from a pipe, here-string (\c{<}), here-document
@@ -1879,6 +1879,20 @@ failed (unexpected input). However, whether this is detected and diagnosed is
 implementation-defined. To allow reading from the default \c{stdin} (for
 instance, if the test is really an example), the \c{<|} redirect is used.
 
+\N|The \c{<=}, \c{<<=}, and \c{<<<=} redirects are a stable syntax across
+various \c{build2} scripting language flavors (Testscript, Buildscript,
+etc). While the \c{<}, \c{<<}, and \c{<<<} redirects are their Testscript
+aliases with the mapping chosen to be more convenient for this flavor of the
+scripting language. This mapping is as follows:
+
+\
+<    <<<=  here-string
+<<   <<=   here-document
+<<<  <=    file
+\
+
+|
+
 Here-string and here-document redirects may specify the following redirect
 modifiers:
 
@@ -1905,9 +1919,9 @@ out-redirect: '>-'|\
               '>=' <file>|\
               '>+' <file>|\
               '>&' ('1'|'2')|\
-              ('>?'|'>>>') <file>|\
-              ('>>?'|'>>'){':'?'/'?}'~'? <here-end>|\
-              ('>>>?'|'>'){':'?'/'?}'~'? <text>
+              ('>>>'|'>?') <file>|\
+              ('>>'|'>>?'){':'?'/'?}'~'? <here-end>|\
+              ('>'|'>>>?'){':'?'/'?}'~'? <text>
 \
 
 The \c{stdout} and \c{stderr} data can go to a pipe (\c{stdout} only), file
@@ -1919,6 +1933,20 @@ stream (either \c{stdout} or \c{stderr}) is considered to have failed
 (unexpected output). To allow writing to the default \c{stdout} or \c{stderr}
 (for instance, if the test is really an example), the \c{>|} redirect is used.
 
+\N|The \c{>?}, \c{>>?}, and \c{>>>?} redirects are a stable syntax across
+various \c{build2} scripting language flavors (Testscript, Buildscript,
+etc). While the \c{>}, \c{>>}, and \c{>>>} redirects are their Testscript
+aliases with the mapping chosen to be more convenient for this flavor of the
+scripting language. This mapping is as follows:
+
+\
+>    >>>?  here-string comparison
+>>   >>?   here-document comparison
+>>>  >?    file contents comparison
+\
+
+|
+
 The \c{>!} redirect acts like \c{>-} if the build system verbosity level is
 below 2 and as \c{>|} otherwise. It is normally used to ignore diagnostics (as
 opposed to data) during normal operation but to still be able to examine it,
-- 
cgit v1.1