Reworked CLI flags for starting seed in README and WolframAutomata source.

[screensavers] / hacks / WolframAutomata / README.md

diff --git a/hacks/WolframAutomata/README.md b/hacks/WolframAutomata/README.md
index 026b9cf..d3546d1 100644 (file)
--- a/hacks/WolframAutomata/README.md
+++ b/hacks/WolframAutomata/README.md
@@ -84,12 +84,30 @@ are re-randomized every time the simulation is reset, such as after a
 simulation completes or after resizing the window.
 
 
 simulation completes or after resizing the window.
 
 

+CLI: Rule Selection
+-------------------
+
+If neither of the following two options are passed, rules are randomly selected
+from `curated_ruleset_list[]` in `WolframAutomata.c`.
+
+  - **`-true-random-rule`**: Select a rule completely at random, NOT randomly
+    from a curated list. Note that many rules are visually uninteresting.
+
+  - **`-rule N`**: Select a specific rule where `N` is a Wolfram number. Values
+    from 0-255 inclusive are valid.
+
+

 CLI: Simulation Seed
 --------------------
 
 CLI: Simulation Seed
 --------------------
 

-If none of the following options are specified, the starting seed will contain
-randomly interspersed active/inactive cells at a 30/70, 50/50, or 70/30 ratio,
-itself also randomly selected.
+The following seed related CLI flags apply only when using the
+`-true-random-rule` or `-rule N` flags. Without these flags, the program draws
+rules from `curated_ruleset_list[]` which also includes curated seeds, all of
+which override any seed related CLI flags.
+
+If the curated rule list is not in use and none of the following options are
+specified, the starting seed will contain randomly interspersed active/inactive
+cells at a 30/70, 50/50, or 70/30 ratio, itself also randomly selected.

 
   - **`-seed-left`**: Seeds a single active cell on the left side of the
     display. All other cells are inactive.
 
   - **`-seed-left`**: Seeds a single active cell on the left side of the
     display. All other cells are inactive.


@@ -101,22 +119,22 @@ itself also randomly selected.
   - **`-seed-density N`**: Generates random seed with `N` percent active cells.
 
 
   - **`-seed-density N`**: Generates random seed with `N` percent active cells.
 
 

-CLI: Rule Selection
--------------------
+CLI: Simulation Length
+----------------------

 
 

-If neither of the following two options are passed, rules are randomly selected
-from `curated_ruleset_list[]` in `WolframAutomata.c`.
+If neither of the following two options are passed, the simulation runs as
+thought `-length 5000` was passed.

 
 

-  - **`-true-random-rule`**: Select a rule completely at random, NOT randomly
-    from a curated list. Note that many rules are visually uninteresting.
+  - **`-random-length`**: A random length smaller than 10,000 generations but
+    large enough to fill the screen is selected.

 
 

-  - **`-rule N`**: Select a specific rule where `N` is a Wolfram number. Values
-    from 1-255 inclusive are valid.
+  - **`-length N`**: Request `N` generations be simulated on each run.

 
 

-Note that, although Rule 0 is a valid set of rules, it is reused as a null
-value by the program and thus is ignored if passed as `-rule 0`. If you want to
-see Rule 0, choose any starting conditions you desire, then turn off your
-monitor and enjoy the resulting simulation.
+Note that an upper limit of 10,000 generations is enforced in order to avoid
+`BadAlloc` errors from some X servers.  For more details, read
+`WolframAutomata.c` starting around the comment, "The maximum number of
+generations is cell_size dependent. This is a soft limit and may be increased
+if ..."

 
 
 CLI: Simulation Speed
 
 
 CLI: Simulation Speed


@@ -136,24 +154,6 @@ though `-delay 25000` was passed.
     well respected.
 
 
     well respected.
 
 

-CLI: Simulation Length
-----------------------
-
-If neither of the following two options are passed, the simulation runs as
-thought `-length 5000` was passed.
-
-  - **`-random-length`**: A random length smaller than 10,000 generations but
-    large enough to fill the screen is selected.
-
-  - **`-length N`**: Request `N` generations be simulated on each run.
-
-Note that an upper limit of 10,000 generations is enforced in order to avoid
-`BadAlloc` errors from some X servers.  For more details, read
-`WolframAutomata.c` starting around the comment, "The maximum number of
-generations is cell_size dependent. This is a soft limit and may be increased
-if ..."
-
-

 CLI: Cell Dimensions
 --------------------
 
 CLI: Cell Dimensions
 --------------------
 


@@ -212,7 +212,7 @@ XScreensaver via whatever method is appropriate for your operating system. The
 following instructions assume the filesystem paths used by FreeBSD packages and
 ports; your paths may differ. After XScreensaver installation, ensure all
 pertinent config files are created by running `xscreensaver-demo` and
 following instructions assume the filesystem paths used by FreeBSD packages and
 ports; your paths may differ. After XScreensaver installation, ensure all
 pertinent config files are created by running `xscreensaver-demo` and

-configuring it for your system.
+configuring XScreensaver for your system.

 
 After XScreensaver is configured and working on your system, ensure that
 WolframAutomata runs in standalone mode on your system. If you can `make clean run`
 
 After XScreensaver is configured and working on your system, ensure that
 WolframAutomata runs in standalone mode on your system. If you can `make clean run`


@@ -235,19 +235,28 @@ example, on FreeBSD:
 
     TODO: Finish writing this file after the command line options are finalized.
 
 
     TODO: Finish writing this file after the command line options are finalized.
 

-The final step integrates WolframAutomata into an individual user's
-XScreensaver framework. If preferred, it could instead be done in the global
-XScreensaver config.
+The next step integrates WolframAutomata into an individual user's XScreensaver
+config via the file `~/.xscreensaver`. If preferred, it could instead be done
+in the global XScreensaver config.

 
 

-Add the WolframAutomata entry under the `programs:` label, in the same list as
-all the other hacks. Position in the list is irrelevant, but ensure you don't
-paste WolframAutomata's entry into the middle of pre-existing, multi-line
-entries.
+In the `~/.xscreensaver` file, create a WolframAutomata entry under the
+`programs:` label in the same list as all the other hacks. Position in the
+list is irrelevant, but ensure you don't paste WolframAutomata's entry into the
+middle of pre-existing, multi-line entries. For context, the example below
+includes a multi-line entry, a GL entry and a plain entry. All that is needed
+is to insert the WolframAutomata line somewhere in the `programs:` list, as
+demonstrated.

 
     vi ~/.xscreensaver
 
 
     vi ~/.xscreensaver
 

+    <snip>

     programs:                                                                     \
     programs:                                                                     \

-                                    WolframAutomata -root -party-mode           \n\
+                                    xplanet -vroot -wait 1 -timewarp 400          \
+                                      -label -origin moon                       \n\
+      GL:                           fireflies -root                             \n\
+                                    WolframAutomata -root                       \n\
+                                    blitspin -root                              \n\
+    <snip>

 
 That's all. Now you can run `xscreensaver-demo` and select WolframAutomata just
 like any other hack.
 
 That's all. Now you can run `xscreensaver-demo` and select WolframAutomata just
 like any other hack.