Collection of minor updates to WolframAutomata README.

[screensavers] / hacks / WolframAutomata / README.md

diff --git a/hacks/WolframAutomata/README.md b/hacks/WolframAutomata/README.md
index 88ecbe7..026b9cf 100644 (file)
--- a/hacks/WolframAutomata/README.md
+++ b/hacks/WolframAutomata/README.md
@@ -35,15 +35,11 @@ uses `-cell-size 2` and seeds the simulation with only a single active cell.
 ![Rule 73 Animated Screenshot](/screensavers/.git/blob_plain/HEAD:/hacks/WolframAutomata/screenshot_rule_73.gif)
 
 In situations where true randomness would lead to visually unappealing
-displays, this program provides random selection from curated lists. For
+displays, this program provides random selection from curated lists. As one
 example, to avoid randomly selecting visually indistinguishable colors like
 `dark red` and `brown` to depict on/off cells, the program includes a
 pre-selected list of color pairs that complement each other and chooses
-randomly from this list when the `-random-color` flag is passed.  Similarly, to
-avoid the visually uninteresting rules like rule 0, a rule which simply turns
-every cell off and keeps it off, the program includes a list of rulesets and
-starting seeds which are visually appealing, selecting randomly from this list
-when the `-random-rule` flag is passed.
+randomly from this list.
 
 
 Status
@@ -165,11 +161,11 @@ Individual cells may be displayed as any square number of pixels (e.g. 1x1,
 2x2, etc). Increasing the cell size may help with flickering on high DPI
 monitors displaying chaotic rulesets.
 
-If neither of the following two options are passed, the simulation selects
-whatever cell size it feels appropriate for the current simulation speed.
+If neither of the following two options are passed, the simulation behaves as
+though `-cell-size 2` was passed.
 
-  - **`-random-cell-size`**: Selects cell size of 2^N pixels for an `N`
-    randomly chosen in the inclusive range `0`-`5`.
+  - **`-random-cell-size`**: Randomly selects 1, 2, 4, 8, 16, or 32 as the cell
+    size on each reset of the simulation.
 
   - **`-cell-size N`**: Display each individual cell as an `N`x`N` square of
     pixels on the screen.
@@ -196,10 +192,75 @@ Note that the names provided as comments in `color_list[]` are X11 color names.
 CLI: Admiration
 ---------------
 
-When the simulation reaches its end as determined by flags like `-length N`, it
+When the simulation reaches its end as determined by flags like `-length N` it
 will pause for a period of time, allowing the viewer to examine it without
 interference from scrolling. By default, this 'admiration window' is five
 seconds long.
 
   - **`-admiration-delay N`**: At the end of a simulation, pause for `N`
     seconds before resetting for the next simulation.
+
+
+XScreensaver Integration
+========================
+
+In addition to running as a standalone program, WolframAutomata can be
+integrated into the XScreensaver framework.
+
+To accomplish this integration, begin by installing and configuring
+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
+configuring it 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`
+in the `screensavers/hacks/WolframAutomata/` folder and see the hack's visual
+output, you're ready to move on.
+
+At this point, copy the hack into your XScreensaver hack directory. For
+example, with prerequisite steps spelled out:
+
+    git clone git://git.subgeniuskitty.com/screensavers
+    cd screensavers/hacks/WolframAutomata
+    make clean all
+    cp WolframAutomata /usr/local/bin/xscreensaver-hacks/
+
+Now create the file `WolframAutomata.xml` wherever your system stores
+XScreensaver config files and populate it with the contents shown below. For
+example, on FreeBSD:
+
+    vi /usr/local/share/xscreensaver/config/WolframAutomata.xml
+
+    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.
+
+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.
+
+    vi ~/.xscreensaver
+
+    programs:                                                                     \
+                                    WolframAutomata -root -party-mode           \n\
+
+That's all. Now you can run `xscreensaver-demo` and select WolframAutomata just
+like any other hack.
+
+
+Screen Tearing
+==============
+
+Certain combinations of rules and display settings lead to full screen vertical
+scrolling of alternating light and dark pixels, or other difficult to display
+patterns. If your display doesn't include some type of vertical refresh
+synchronization, such output will look terrible.
+
+If stuck in this situation, changing the output of WolframAutomata to scroll
+horizontally may help, or simply increasing the cell size.
+