updated docs

RATIONALE.md

@@ -23,11 +23,12 @@ It also assumes the user has "rolled well enough", which is quite tricky to defi
 placing the die with the number you want facing up does not count.
 
 Unpredictability for the physical die comes from lack of precise control. Imperfections and
-microscopic details of where the die is rolling have a large impact. Quantum mechanics may
-also have an impact if a die collides and bounces enough. Also, a huge influence is how the
-die is thrown, and that comes from the person throwing it. No-one can control their nerves
+microscopic details of where the die is rolling have an impact. Quantum mechanics, which
+as far as we know is inherently probability-based, may also have an impact if a die collides
+and bounces enough. Also, a big influence, mechanically and philosophically, is how the
+die is thrown - and that comes from the person throwing it. No-one can control their nerves
 and muscles to a degree where they "roll well enough" but can consciously choose the
-exact result on the die. However, the impulse you give to a die when you throw it caused
+exact result on the die. However, the impulse you give to a die when you throw it is caused
 by your nerves, bones and muscles. This gives many people a feeling of agency and relationship
 to the end result. It may just be a random number, but in some sense it is *your random
 number because you generated it*.

README.md

@@ -44,31 +44,78 @@ Create a new generator:
 
     pool = PoolOfEntropy.new
 
-Get a random number:
+Get a random number. Not feeding the generator with any customisation
+means it is completely deterministic based on current internal state. The
+analogy here might be "trusting to Fate":
 
     pool.rand( 20 )
 
-Influence the next random number (but not any others):
+Influence the next random number (but not any others). This is analogous to
+shaking or throwing dice in a certain way. Only the next result from rand()
+is affected:
 
-    pool.modify_next( 'I hope this works! Whatever!' )
+    pool.modify_next( 'Shake the die.' )
     pool.rand( 20 )
 
     # Also
-    pool.modify_next( 'I hope this works! Whatever!' ).rand( 20 )
+    pool.modify_next( 'Shake the die.' ).rand( 20 )
 
-Influence all random numbers until change mind (but do not alter internal state):
+    # This next result will not be influenced,
+    # we re-join the deterministic sequence of the PRNG:
+    pool.rand
+
+Influence the next three random numbers. Data supplied to modify_next is
+put in a queue, first in, first out:
+
+    pool.modify_next( 'Shake the die lots.' )
+    pool.modify_next( 'Roll the die cautiously.' )
+    pool.modify_next( 'Drop the die from a great height and watch it bounce.' )
+
+    pool.rand  # influenced by 'Shake the die lots.'
+    pool.rand  # etc
+    pool.rand
+
+    pool.rand #  . . . and back to main sequence
+
+Influence all random numbers from this point forward. This is analogous to
+having a personal style of throwing dice, or perhaps a different environment
+to throw them in.
 
     pool.modify_all( 'Gawds help me in my hour of need!' )
 
-    # All these are modified in same way, the two modifier types "stack"
+    # All these are modified in same way
     pool.rand( 20 )
     pool.rand( 20 )
+
+    # The two modifier types "stack", and this is modified twice
     pool.modify_next( 'And I really mean it!' ).rand( 20 )
 
-Alter internal state of pool (aka customise or "collect entropy"):
+Remove modfiers:
+
+    # Just the "all" modifier
+    pool.modify_all( nil )
+
+    # Insert a pause into the "next" queue
+    pool.modify_next( nil )
+
+    # Re-set "next" and "all" modifiers
+    pool.clear_all_modifiers
+
+Alter internal state of pool. This mixes in any entropy in the supplied
+data, and changes the deterministic sequence going forward. This is
+analogous to long-term alterations to dice, the environment, or
+person throwing the dice.
 
     pool.add_to_pool( 'Purple is my favourite colour.' )
 
+All the inputs can be any length String, from any source. If the data
+contains *any* "true randomness" (however you want to define it, and however
+the String is formatted), then PoolOfEntropy
+will process that (using SHA-512) into unbiased results. If you care
+about your own source of randomness being more "important" than
+the initial state of the PRNG, or its continued deterministic ticking,
+then make use of the modifiers and/or add data to the pool frequently.
+
 ## More information
 
  * [Rationale](RATIONALE.md)