Updates to User Guide and Snap Description

mdbook/src/Chapters/Introduction.md

@@ -1,30 +1,17 @@
 <p align="center"> <img width="1024" src ="https://github.com/frossm/rpncalc/raw/master/graphics/ReadmeHeader.jpg"> </p> 
 
 # INTRODUCTION
-RPNCalc is the command-line based Reverse Polish Notation (RPN) calculator.  RPN calculators make it very simple to do complex calculations, especially if there are parentheses involved.  For a quick example, consider solving for x with the following:
+RPNCalc is the command-line based Reverse Polish Notation (RPN) calculator.  RPN calculators make it very simple to do complex calculations, especially if there are parentheses involved.  In essence, you enter your numbers first, then the operator.
 
-`x = SQRT((((5+3) * 8)/2) ^ 6)`
+So, to add 2 and 3 to get 5, you would first add the number 2 to the stack:  `2 [Enter]`.  Then you would add 5 to the stack (pushing the 2 to the second position:  `3 [Enter]`.  Now, to add them y ou would enter: `+ [Enter]` and RPNCalc would remove the 2 and 3 from the stack, add them, and push 5 back onto the stack.
 
-This can be tricky with a traditional calculator.  However, with a RPN Calculator, to solve for x you would start on the inner calculation and work outwards by entering the following:
+The following example can be tricky to get your head around in a traditional calculator but is quite easy with RPN.  The chapter `What is an RPN Calculator` will go through solving this step by step.
 
-- `5`
-- `3`
-- `+`
-- `8`
-- `*`
-- `2`
-- `/`
-- `6`
-- `^`
-- `SQRT`
+`x = SQRT(((((5+3) * 8)/2) * (2+1)) ^ 2)`
 
-(This can also be dramatically shortened using the `NumOps` shortcut - see the `Operands` chapter)
+RPN is based on a Last In First Out (LIFO) stack framework which sounds complicated, but makes intuitive sense when you use it.  You can think of it as a stack of plates.  When you put one on the top of the stack, everyone other one shifts down by one. On a RPN calculator, there is no equal sign, but there is an enter key to put a value onto the stack.  The chapter on `Stacks` talks more about how this works with RPNCalc.
 
-RPN is based on a Last In First Out (LIFO) stack framework which sounds complicated, but makes intuitive sense when you use it.  On a RPN calculator, there is no equal sign, but there is an enter key to put a value onto the stack.  
-
-So, in the above example, when you enter **`5 [ENTER]`** , 5 is put on top of the stack.  You then enter **`3 [ENTER]`** which add that to the top.  5 is pushed down to 2nd.  When **`+`** is entered, the top two stack items are removed from the stack, added, and the result is placed on the top.  I'll talk more about stacks and how RPNCalc uses them in future chapters.
-
-If you have not heard of reverse Polish notation, or just have a passion for various calculator notations (and seriously, who doesn't?), you can read more about RPN on [Wikipedia](https://en.wikipedia.org/wiki/Reverse_Polish_notation).
+If you have not heard of reverse Polish notation, or just have a passion for various calculator notations (and seriously, who doesn't?), you can read more about RPN on [Wikipedia](https://en.wikipedia.org/wiki/Reverse_Polish_notation) or a (very) quick summary in the `What is an RPN Calculator` chapter.
 
 
 ## A Brief History of RPNCalc

mdbook/src/Chapters/WhatIsRPN.md

@@ -0,0 +1,67 @@
+<img align="right" width="175" src="../Images/WhatIsRPN.jpg">
+
+# What is an RPN Calculator?
+
+For me, the way I learned to use RPN back in the early 1990s was to `start on the inside and work your way out`.  Just look at the inner most calculations, and start working yourself back out.  It also helps if you also understand the order of operations for match operands.
+
+### Order of Operations - *PEMDAS*
+
+|Order||Description|
+|-----||-----------|
+|1|P|Parentheses First|
+|2|E|Exponents - Powers and Square Roots, etc.|
+|3|MD|Multiplication and Division (left-to-right)|
+|4|AS|Addition and Subtraction (left-to-right)|
+
+### Walkthrough of the Example from the Introduction Page
+
+`x = SQRT( ((((5+3) * 8)/2) * (2+1)) ^ 2 )`
+
+This can be tricky with a traditional calculator.  However, with a RPN Calculator, to solve for x you would start on the inner calculation and work outwards.  Looking at the equation, `5 + 3` is about the lowest so lets start there.  We'll walk through each step and explain what's happening.  Go ahead and start RPNCalc and follow along - it's much easier to do it and see the stack rather than just reading it here.
+
+|Command|Explanation|
+|-------|-----------|
+|`c [Enter]`| Clear the stack if there is anything on it|
+|`5 [Enter]`| The top of the stack (`line1`) contains a 5|
+|`3 [Enter]`| 3 has been added to the top of the stack (`line1`) pushing 5 to `line2`|
+|`+ [Enter]`| 3 and 5 have been removed from the stack, added, and 8 pushed to `line1`|
+|`8 [Enter]`| 8 is added to `line1`, pushing the other 8 to `line2`|
+|`* [Enter]`| Remove 8 and 8 from the stack, multiply, and push the result to `line1`|
+|`2 [Enter]`| Add 2 to the stack pushing down 64|
+|`/ [Enter]`| Divide 64 (`line2`) by 8 (`line1`)|
+|`2 [Enter]`| Add 2 to the stack|
+|`1 [Enter]`| Add 1 to the stack|
+|`+ [Enter]`| Add 2 and 1.  They will be removed and 3 will be pushed|
+|`* [Enter]`| Multiply the 3 to the 64 you had in `line1`|
+|`2 [Enter]`| Add 2 to the stack|
+|`^ [Enter]`| Take `line2` to the power of `line1`|
+|`SQRT [Enter]`| Takes the square root of `line1` pushing the result to the stack|
+
+The result is 96 which ends up on the top (`line1`) of an empty stack.  I'll talk more about stacks and how RPNCalc uses them in future chapters.
+
+*By the way, this can also be dramatically shortened using the `NumOps` shortcut - see the `Operands` chapter for more information.*
+
+
+### Traditional RPN Notation Limitations in RPNCalc
+
+Please note that RPNCalc doesn't implement every RPN convention and there are a few as of yet unimplemented items.
+
+For example, this won't work in RPNCalc:
+
+`10 + 10 + 10` can't be solved by entering `10 [Enter] 10 [Enter] 10 [Enter] + + [Enter]` as RPNCalc only allows one operand per command entry.  You'll need an `[Enter]` between the last two `+` signs.  Using the `NumOp` shortcut, this is an efficient way to solve that equation:
+
+`10 [Enter] 10+ [Enter] 10+ [Enter]`
+
+<hr> 
+
+## Wikipedia:
+
+The following is directly from [Wikipedia](https://en.wikipedia.org/wiki/Reverse_Polish_notation).  There is a lot more information there, but here are a few highlights.
+
+### Explanation
+
+In reverse Polish notation, the operators follow their operands; for instance, to add 3 and 4 together, one would write `3 4 +` rather than `3 + 4`. If there are multiple operations, operators are given immediately after their final operands (often an operator takes two operands, in which case the operator is written after the second operand); so the expression written `3 − 4 + 5` in conventional notation would be written `3 4 − 5 +` in reverse Polish notation: 4 is first subtracted from 3, then 5 is added to it. An advantage of reverse Polish notation is that it removes the need for parentheses that are required by infix notation. While `3 − 4 × 5` can also be written `3 − (4 × 5)`, that means something quite different from `(3 − 4) × 5`. In reverse Polish notation, the former could be written `3 4 5 × −`, which unambiguously means `3 (4 5 ×) −` which reduces to `3 20 −` (which can further be reduced to -17); the latter could be written `3 4 − 5 ×` (or `5 3 4 − ×`, if keeping similar formatting), which unambiguously means `(3 4 −) 5 ×`.
+
+### Practical implications
+
+In comparison, testing of reverse Polish notation with algebraic notation, reverse Polish has been found to lead to faster calculations, for two reasons. The first reason is that reverse Polish calculators do not need expressions to be parenthesized, so fewer operations need to be entered to perform typical calculations. Additionally, users of reverse Polish calculators made fewer mistakes than for other types of calculators. Later research clarified that the increased speed from reverse Polish notation may be attributed to the smaller number of keystrokes needed to enter this notation, rather than to a smaller cognitive load on its users. However, anecdotal evidence suggests that reverse Polish notation is more difficult for users to learn than algebraic notation.

mdbook/src/SUMMARY.md

@@ -1,9 +1,10 @@
 # Summary
 
 - [Introduction](./Chapters/Introduction.md)
+- [What is an RPN Calculator](./Chapters/WhatIsRPN.md)
 - [Installation](./Chapters/Installation.md)
-- [High Level Usage](./Chapters/HighLevelUsage.md)
 - [Stacks](./Chapters/Stacks.md)
+- [High Level Usage](./Chapters/HighLevelUsage.md)
 - [Command Line Options](./Chapters/CommandLineOptions.md)
 - [Operands](./Chapters/Operands.md)
 - [Calculator Commands](./Chapters/CalculatorCommands.md)

snap/snapcraft.yaml

@@ -5,16 +5,15 @@ description: |
   RPNCalc is an easy to use command line based Reverse Polish
   Notation (RPN) calculator.
   
-  RPNCalc is the command-line based Reverse Polish Notation (RPN) calculator.
   RPN calculators make it very simple to do complex calculations, especially
-  if there are parentheses involved or order of operations is imporant.
+  if there are parentheses involved or order of operations is imporant. Take a look
+  at the user guide for more information on RPN Calculators.
   
-  For a quick summary of usage, run the program with the -h switch or head
-  over to the homepage for detailed usage instructions.
+  For a quick summary of RPNCalc usage, run the program with the -h switch or head
+  over to the User Guide for detailed usage instructions.
   
   Homepage: https://github.com/frossm/rpncalc
-  
-  Here is a link to the full RPNCalc user guide: https://frossm.github.io/RPNCalc-UserGuide
+  RPNCalc user guide: https://frossm.github.io/RPNCalc-UserGuide
 
 grade: stable
 confinement: strict