From 29c59165396eb842d92367fca74c4e459ea25900 Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Mon, 25 May 2020 14:17:19 +0200
Subject: Review (temp dir)

---
 doc/testscript.cli                |  2 +-
 libbuild2/build/script/script.hxx | 17 ++++++++++++-----
 libbuild2/script/script.hxx       |  4 ++--
 3 files changed, 15 insertions(+), 8 deletions(-)

diff --git a/doc/testscript.cli b/doc/testscript.cli
index 665446e..5b36c5e 100644
--- a/doc/testscript.cli
+++ b/doc/testscript.cli
@@ -943,7 +943,7 @@ Alternatively, we can use an absolute path:
 \
 
 Inside the scope working directory filesystem names that start with \c{stdin},
-\c{stdout}, \c{stderr}, as well as, \c{cmd-} are reserved.
+\c{stdout}, and \c{stderr}.
 
 To execute a test scope its commands (including variable assignments) are
 executed sequentially and in the order specified. If any of the commands
diff --git a/libbuild2/build/script/script.hxx b/libbuild2/build/script/script.hxx
index f8306e1..ec603a7 100644
--- a/libbuild2/build/script/script.hxx
+++ b/libbuild2/build/script/script.hxx
@@ -81,13 +81,20 @@ namespace build2
         //
         variable_map vars;
 
-        // Temporary directory for the script run (see build2::script::
-        // environment::temp_dir for details).
+        // Temporary directory for the script run.
         //
         // Currently this directory is removed regardless of the script
-        // execution success or failure. Later, to ease the troubleshooting,
-        // we may invent the build2 option suppressing the directory removal
-        // on failure.
+        // execution success or failure. Later, to help with troubleshooting,
+        // we may invent an option that suppresses the removal of temporary
+        // files in general.
+        //
+        // This directory is available to the user via the $~ special
+        // variable. Note, however, that the following filesystem entry
+        // prefixes are reserved:
+        //
+        // stdin*
+        // stdout*
+        // stderr*
         //
         auto_rmdir temp_dir;
 
diff --git a/libbuild2/script/script.hxx b/libbuild2/script/script.hxx
index 22747a8..359bb36 100644
--- a/libbuild2/script/script.hxx
+++ b/libbuild2/script/script.hxx
@@ -363,7 +363,7 @@ namespace build2
       // using the rm or mv builtins will fail the script execution. Must be
       // an absolute path.
       //
-      const dir_path& work_dir;
+      const dir_path& work_dir; // @@ dir_path_name
       const string&   work_dir_name; // Directory name for diagnostics.
 
       // If non-empty, then any attempt to remove or move a filesystem entry
@@ -371,7 +371,7 @@ namespace build2
       // builtins will fail the script execution, unless the --force option is
       // specified for the builtin. Must be an absolute path, unless is empty.
       //
-      const dir_path& sandbox_dir;
+      const dir_path& sandbox_dir; // @@ dir_path_name
       const string&   sandbox_dir_name; // Directory name for diagnostics.
 
       // Used by the script running machinery to create special files in it.
-- 
cgit v1.1