+They are intended to remove the tedium of frequently repeated patterns while
+remaining short enough to easily comprehend and modify.
+
+For those eager to jump right in, all functions have comments in the source
+code containing a text description as well as both call and return stacks.
+Simply `#include` the relevant file, setup your call stack per the
+documentation and then `JSR` to the stdlib function of your choice.
+
+Some functions, like `deepdup`, `stackrotate` and `stackrotatereverse`, ease
+stack manipulations by allowing easy access to elements deep on the stack.
+Similarly, `slurp` and `spew` help move bulk data between the stack and heap.
+
+User interactions were also targeted. The included `printf` function provides a
+variety of substitutions to ease user interactions. For user input, `get user
+string` and `atoi` allow easy creation of basic user interfaces.
+
+The library includes a variety of bitwise logic functions as well as heap
+manipulation functions and a handful of math functions including a random
+number generator.
+
+
+# Instructions #
+
+Before we can use this library, we must `#include` it in our program. Looking
+at the "Entry Points" table below, if we wanted to call `deepdup` we would need
+to `#include <stack.pvvs>` in our code, but where?
+
+Recall that VVhitespace processes our code from top to bottom. Thus, it is
+always safe to `#include` files at the bottom, after our program's text. This
+way the files are included in our source code but won't be accidentally
+executed by the interpreter. For example:
+
+ @ Put two elements on the stack.
+ SSSTTTTSTSSN | PUSH 244
+ SSSTN | PUSH 1
+ @ Duplicate the deeper element.
+ SSSTSN | PUSH 2 (argument to deepdup)
+ NSTTTSSN | JSR > 1100 (deepdup)
+ NNN | DIE
+ #include <stack.pvvs>
+
+What about that `PUSH 2` instruction that is an argument to `deepdup`? If we
+check `stack.pvvs`, we will find the following comment above the `deepdup`
+function:
+
+ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+ @ Name:
+ @ deepdup
+ @ Description:
+ @ Duplicates an item deep on the stack, placing the duplicate on TOS.
+ @ By default, maximum depth is 13.
+ @ True maximum depth is (max depth of stackrotate & stackrotatereverse)-1.
+ @ Call Stack:
+ @ stack word n
+ @ ...
+ @ stack word 1
+ @ dupdepth <-- TOS
+ @ Return Stack: (dupdepth=3)
+ @ stack word n
+ @ ...
+ @ stack word 1
+ @ copy of stack word 3 <-- TOS
+ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+ NSSVTTSSN | Mark: 1100 (deepdup)
+ ...
+
+From the "Call Stack" example, we can see that `deepdup` requires a `dupdepth`
+argument on the TOS. Since we wanted to duplicate the second item on the stack,
+we used `PUSH 2` immediately before calling `deepdup`.
+
+In addition to the call stack, the code comments also show you what to expect
+on the return stack, as well as any other information you might need in order
+to use the function.
+
+
+# Resource Reservations #
projects / vvhitespace / commitdiff