stacker doc

Hi Lalo,

Its been a while since I've had a Stacker question!

The answer is in the StackerCompiler::handle_while function in
StackerCompiler.cpp in projects/Stacker/lib/compiler. Apparently the
control value is only examined (not popped) for the "WHILE" operator.

Take for example the prime.st sample program. The first thing it does is
process the arguments with a WHILE loop:

WHILE
  do_one_argument
END

The do_one_argument relies on the fact that the initial stack contains
the program arguments and the argument count, like this:

argc
argv[0]
argv[1]
argv[2]
...

It begins by decrementing the top of the stack (argc) and swapping the
first two items, so the stack looks like:

argv[0]
argc-1
argv[1]
argv[2]
...

It then determines if that number (argc[0]) is prime or not and finally
does a DROP to remove the argument. This leaves the argument count on
the top of the stack again.

If the WHILE operator had popped the argc value from the top of the
stack, the algorithm above would not work.

The END operator does nothing except loop back to the top of the WHILE
loop to repeat the test.

Hence, by design, this operator has "no effect" on the stack other than
the effect produced by the definition named in the body of the
WHILE ... END loop. One of the reasons for this is that the WHILE loop
becomes quite general allowing the action taken by the body to increase
the stack, decrease it, or leave it alone.

I'll revise the documentation to be clearer about all this and review
the stack manipulation operators.

Thanks,

Reid.