Add terminal save-restore feature to basta.fullscreen.

* README.md: Revised full screen documentation.

* basta.sh (basta.fullscreen): Recognize and consume
a -s option. If this is present, then issue the ANSI
escape sequence for saving the terminal before running
the command. Then issue the sequence for restoring
the terminal afterward.

2 files changed, 42 insertions, 8 deletions

diff --git a/README.md b/README.md
index 65a2879..2ca61b4 100644
--- a/README.md
+++ b/README.md
@@ -98,11 +98,35 @@ the full screen.
 Create `basta.fullscreen <program>` alias for each program that is to use
 the full terminal.
 
-The `basta.fulscreen` function works well with well-behaved programs which save
-and restore the terminal screen contents and cursor position.  Programs which
-do not save and restore the terminal can be handled with the alternative
-function `basta.fullscreen_alt`. Almost any program, including non-interactive
-batch programs, can be run in full screen with this function.
+The `basta.fullscreen` function works well with programs such as editors
+that use the full screen, and do not generate TTY-like output that scrolls the
+terminal. Some such programs save and restore the terminal screen.
+These work very well with `basta.fullscreen`.
+
+Programs that do not save and restore the terminal screen, or which generate
+some log messages before or after restoring the terminal screen, may cause a
+small cosmetic problem, like the Bash prompt appearing over top of a line of
+output from the program.  For the former category, full-screen programs
+which don't save and restore the terminal, one possible fix for the cosmetic
+issue is to use the `-s` (save and restore) option of `basta.fullscreen`,
+which saves and restores the terminal contents around the invocation of
+the program. For instance, many versions of the `top` utility are like this,
+and can be handled using:
+
+   ::text
+   alias top='basta.fullscreen -s top'
+
+Now the `top` command restores the terminal upon quitting.
+
+Programs which generate arbitrary scrolling output can be operated in full
+screen mode the function `basta.fullscreen_alt`. Almost any program, including
+non-interactive batch programs, can be run in full screen with this function.
+This function clears the screen and switches to the full scrolling area
+prior to running the program. Then when the program terminates, it checks
+the cursor position. The cursor position is assumed to be where the program
+produced its last line of output. The terminal is scrolled so that this
+last line of output is above the status area, which Basta then displays
+once again, and configures the scrolling region above it.
 
 Note for `git` users: though the `less` pager used by `git` normally saves
 and restores the terminal by default, `git` runs it in such a way that it does
@@ -114,9 +138,10 @@ then add the following `pager =` line to that section:
     [core]  # add if necessary
         pager = less -+Xn -+F
 
-Even with this setting, it is recommended to use
-`alias git='basta.fullscreen_alt'` because `git` does not always use the pager;
-under some invocations, `git` behaves as noninteractive program.
+Even with this setting, it is recommended to use `alias
+git='basta.fullscreen_alt git'` because `git` does not always use the pager;
+under some invocations, `git` behaves as noninteractive program
+which produces TTY-like scrolling output.
 
 ## Environment
 
diff --git a/basta.sh b/basta.sh
index c6dd608..4e92022 100644
--- a/basta.sh
+++ b/basta.sh
@@ -298,15 +298,24 @@ basta.fullscreen() {
   local realrows=$(( LINES + basta_prev_reserved_rows + 1 ))
   local exit=
   local saveint=$(trap -p INT)
+  local saveterm=
 
   trap : INT
 
+  if [ "$1" == "-s" ] ; then
+    shift
+    saveterm=y
+    printf $'\e[?1049h'
+  fi
+
   printf $'\e7\e[1;%sr\e8' $realrows
   stty rows $realrows
   basta_deferred_intr=WINCH
   LINES=$realrows command "$@"
   exit=$?
 
+  [ $saveterm ] && printf $'\e[?1049l'
+
   eval "$saveint"
 
   return $exit