From ad2d9d98d6a0c1bd766c943269d1006a7e36c506 Mon Sep 17 00:00:00 2001
From: "T.v.Dein" <git@daemon.de>
Date: Mon, 6 Nov 2023 20:12:31 +0100
Subject: [PATCH] Doc/improve (#4)

* add interactiveness to features, add keybindings to doc
* added commands
---
 README.md |  5 ++++-
 rpn.go    | 48 +++++++++++++++++++++++++++++++++++++++++++++-
 rpn.pod   | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 108 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 6d9673f..7082e77 100644
--- a/README.md
+++ b/README.md
@@ -15,10 +15,13 @@ Features:
 - various stack manipulation commands
 - basic math operators
 - advanced math functions (not yet complete)
-- provides interactive repl
 - can be used on the commandline
 - can calculate data in batch mode (also from STDIN)
 - extensible with custom LUA functions
+- provides interactive repl
+- completion
+- history
+
 
 ## Working principle
 
diff --git a/rpn.go b/rpn.go
index 8890af5..15197ff 100644
--- a/rpn.go
+++ b/rpn.go
@@ -111,7 +111,9 @@ DESCRIPTION
     switch or debug toggle command), then the backup stack is also being
     displayed.
 
-    The stack can be reversed using the reverse command.
+    The stack can be reversed using the reverse command. However, sometimes
+    only the last two values are in the wrong order. Use the swap command to
+    exchange them.
 
     You can use the shift command to remove the last number from the stack.
 
@@ -145,8 +147,52 @@ DESCRIPTION
         log10 log1p log2 logb pow round roundtoeven sin sinh tan tanh trunc y0
         y1 copysign dim hypot
 
+    Commands:
+
+        batch                toggle batch mode
+        debug                toggle debug output
+        dump                 display the stack contents
+        clear                clear the whole stack
+        shift                remove the last element of the stack
+        reverse              reverse the stack elements
+        swap                 exchange the last two stack elements
+        show                 show the last 5 items of the stack
+        history              display calculation history
+        help|?               show this message
+        quit|exit|c-d|c-c    exit program
+
     Refer to https://pkg.go.dev/math for details about those functions.
 
+INTERACTIVE REPL
+    While you can use rpn in the command-line, the best experience you'll
+    have is the interactive repl (read eval print loop). Just execute "rpn"
+    and you'll be there.
+
+    In interactive mode you can use TAB completion to complete commands,
+    operators and functions. There's also a history, which allows you to
+    repeat complicated calculations (as long as you've entered them in one
+    line).
+
+    There are also a lot of key bindings, here are the most important ones:
+
+    ctrl-c + ctrl-d
+        Exit interactive rpn
+
+    ctrl-z
+        Send rpn to the backgound.
+
+    ctrl-a
+        Beginning of line.
+
+    ctrl-e
+        End of line.
+
+    ctrl-l
+        Clear the screen.
+
+    ctrl-r
+        Search through history.
+
 EXTENDING RPN USING LUA
     You can use a lua script with lua functions to extend the calculator. By
     default the tool looks for "~/.rpn.lua". You can also specify a script
diff --git a/rpn.pod b/rpn.pod
index 93b293a..c965396 100644
--- a/rpn.pod
+++ b/rpn.pod
@@ -154,8 +154,65 @@ Math functions:
     log10 log1p log2 logb pow round roundtoeven sin sinh tan tanh trunc y0
     y1 copysign dim hypot
 
+Commands:
+
+    batch                toggle batch mode
+    debug                toggle debug output
+    dump                 display the stack contents
+    clear                clear the whole stack
+    shift                remove the last element of the stack
+    reverse              reverse the stack elements
+    swap                 exchange the last two stack elements
+    show                 show the last 5 items of the stack
+    history              display calculation history
+    help|?               show this message
+    quit|exit|c-d|c-c    exit program
+
+
 Refer to https://pkg.go.dev/math for details about those functions.
 
+=head1 INTERACTIVE REPL
+
+While you can use rpn in the command-line, the best experience you'll
+have is the interactive repl (read eval print loop). Just execute
+C<rpn> and you'll be there.
+
+In interactive mode you can use TAB completion to complete commands,
+operators and functions. There's also a history, which allows you to
+repeat complicated calculations (as long as you've entered them in one
+line).
+
+There are also a lot of key bindings, here are the most important
+ones:
+
+=over
+
+=item ctrl-c + ctrl-d
+
+Exit interactive rpn
+
+=item ctrl-z
+
+Send rpn to the backgound.
+
+=item ctrl-a
+
+Beginning of line.
+
+=item ctrl-e
+
+End of line.
+
+=item ctrl-l
+
+Clear the screen.
+
+=item ctrl-r
+
+Search through history.
+
+=back
+
 =head1 EXTENDING RPN USING LUA
 
 You can use a lua script with lua functions to extend the