update docs

Author: xvxx

Diff for: README.md

@@ -10,49 +10,53 @@ Only works on the `extensions` branch of https://github.com/dvkt/ldpl
 Usage
 -----
 
-For readline-like behavior, first set the `RL-PROMPT` text variable to a prompt then call the `RL-ACCEPT` subroutine:
+Any LDPL program using this extension must declare these three variables, even if you're not going to use them:
 
-    STORE "Type something: " IN RL-PROMPT
-    CALL RL-ACCEPT
-
-What the user inputs will be put into the `RL-INPUT` text variable:
-
-    DISPLAY "You entered: " RL-INPUT CRLF
+    DATA:
+    RL-INPUT is TEXT
+    RL-PROMPT is TEXT
+    RL-HISTORY-FILE is TEXT
 
-To save and load history, first set the `RL-HISTORY-FILE` text  variable to the location of your history file, then use the  `RL-LOAD-HISTORY` and `RL-SAVE-HISTORY` subroutines to load/save the history and the `RL-ADD-HISTORY` subroutine to add the value of `RL-INPUT` to the current history:
+- `RL-INPUT` will be filled with the user's input after prompting them.
+- `RL-PROMPT` will default to `> ` and allows you to customize the prompt shown to users. Optional.
+- `RL-HISTORY-FILE` can be set by you to the location of the history file for this program. Optional.
 
-    STORE "history.txt" IN RL-HISTORY
-    CALL RL-LOAD-HISTORY
-    # code that calls RL-ACCEPT
-    CALL RL-ADD-HISTORY
-    # then, before you exit:
-    CALL RL-SAVE-HISTORY
+To actually use the library, call the `RL-ACCEPT` subroutine to prompt the user for input:
 
-Setup
------
+    STORE "Type something: " IN RL-PROMPT
+    CALL EXTERNAL RL-ACCEPT
 
-To build a static archive for your platform, cd into this repo and run:
+What the user inputs will be put into the `RL-INPUT` text variable:
 
-    make
+    DISPLAY "You entered: " RL-INPUT CRLF
 
-This will create `ldplnoise.a`. Copy that file and `ldplnoise.h` into your LDPL project's root directory.
+So the above will print:
 
-Then compile your LDPL project:
+    Type something: <user types Dave and presses >
+    You entered: Dave
 
-    ldpl -i=ldplnoise.h your-code.ldpl
+To record history for a single session, call `RL-ADD-HISTORY` after calling `RL-ACCEPT`. The content of the `RL-INPUT` variable will be added to the history.
 
-You can test that the archive was created correctly by compiling `test.lsc` in this repo:
+To persist history across sessions, you need to save and load a history file. To do so, first set the `RL-HISTORY-FILE` text  variable to the location of your history file, then use the  `RL-LOAD-HISTORY` and `RL-SAVE-HISTORY` subroutines to load/save the history when your LDPL program begins and ends:
 
-    ldpl -i=ldplnoise.h test.lsc
-    ./test-bin
+    # ...program starts...
+    STORE "history.txt" IN RL-HISTORY
+    CALL EXTERNAL RL-LOAD-HISTORY
+    # ...main program code...
+    CALL EXTERNAL RL-ACCEPT
+    CALL EXTERNAL RL-ADD-HISTORY
+    # ...before the program exits...
+    CALL EXTERNAL RL-SAVE-HISTORY
 
-Most likely you'll want to include this entire repo in your LDPL project and, in your build process, create an archive using the following commands:
+Setup
+-----
 
-	c++ -c linenoise.hpp -std=gnu++11 -o linenoise.o
-	c++ -c ldplnoise.cpp -std=gnu++11 -o ldplnoise.o
-	ar -cvq ldplnoise.a ldplnoise.o linenoise.o
+The easy way to include LDPLNOISE in your project is to just clone this repo into it and tell the the `ldpl` compiler where to find `ldplnoise.cpp`:
 
-Then pass -i=ldplnoise.h to `ldpl` when compiling your project.
+    cd my-great-ldpl-project
+    git clone https://github.com/dvkt/ldplnoise
+    ldpl -i=ldplnoise/ldplnoise.cpp my-code.ldpl
+    ./my-code-bin
 
 Example
 -------
@@ -63,21 +67,21 @@ Example
 
 This should launch you into a basic prompt that echos what you type and remembers you history for that session. To exit, just type  "quit" or "exit", submit an empty line, or hit Ctrl-C.
 
-Check out `test.lsc` to see an example of using the extension.
+Check out `test.ldpl` to see an example of using the extension.
 
 LDPL API
 --------
 
 Variables:
 
-    RL-PROMPT is TEXT
-    RL-INPUT is TEXT
-    RL-HISTORY-FILE is TEXT
+    RL-PROMPT is TEXT        # prompt shown to user
+    RL-INPUT is TEXT         # the user's input after a RL-ACCEPT
+    RL-HISTORY-FILE is TEXT  # path to history file
 
 Subroutines:
 
-    RL-ACCEPT
-    RL-LOAD-HISTORY
-    RL-SAVE-HISTORY
-    RL-ADD-HISTORY
-
+    RL-ACCEPT        # main readline()-like prompt function. 
+    RL-LOAD-HISTORY  # load command history from RL-HISTORY-FILE 
+    RL-SAVE-HISTORY  # save command history to RL-HISTORY-FFILE
+    RL-ADD-HISTORY   # add content of RL-INPUT to the history
+                     # should be called after RL-ACCEPT