jarotsim documentation

src/jarotsim.gmo

@@ -1,16 +1,103 @@
 # jarotsim
 
-playground for the exploration and livecoding of turing machines. (work in progress)
+jarotsim is a playground for the discovery, exploration and livecoding of turing machines. 
+
+its objective is to promote experimentation and visualization of these foundational computational machines in a playful and joyful way. 
+
+=> ./img/screenshot_jarotsim_banner.png four rows of tiles, each one with a different pattern of tiles and with a bird with a hat in a different pose and position
+
+# download
+
+coming soon
+
+# the basics
+
+=> ./img/screenshot_jarotsim_detail.png a bird with a hat standing on a row of tiles with different designs
+
+the bird with a hat stands over a long, possibly infinite, row of tiles. 
+
+the bird with a hat stands in a pose, one out of four possible poses.
+
+the bird with a hat stands over one tile in the row, which has one out of four possible designs.
+
+the bird with a hat has a table of rules that tells what to do next.
+
+the table of rules is read as follows: given a specific pose of the bird with a hat, and a specific tile in the row where the bird with a hat is standing:
+
+* which other tile should the given tile be replaced for?
+* which should be the new pose of the bird with a hat?
+* in which direction should the bird with a hat move, in order to stand in a different tile?
+
+the process is repeated over and over again. it might never end, unless the table of rules tells the bird with a hat to stop.
+
+and yes, in case you didn't know yet, all of that is what a turing machine does!
+
+# modes
+
+jarotsim has two modes:
+
+* edit mode: where you can set up and modify the aspects of the procedure to follow.
+* timeline mode: where you can see several iterations of the process.
+
+## edit mode
+
+=> ./img/screenshot_jarotsim_edit.png screenshot of the edit mode as described below
+
+### top row: current state
+
+the top section of this screen allows you to modify:
+
+* the state of the row of tiles: click on a tile to rotate between the four possible designs
+* the current pose of the bird with a hat: click on the bird to rotate between the four possible poses
+* the position of the bird with a hat on the row of tiles: click on the arrows to shift the row right or left
+
+you can clear the row of tiles by clicking on the bin icon at the top right corner when you are in edit mode.
+
+### table of rules
+
+the rest of the screen allows you to modify the table of rules.
+
+there is one rule for each combination of pose and tile. therefore there are sixteen rules.
+
+depending on the size of the screen, you might be able to see them all, or you might need to use the arrows to rotate between the pages of the table.
+
+a rule consists of the following elements:
+
+* a combination of pose and tile at the top: you can't modify these
+* the tile design that will be used to replace the current tile: you can click on it to rotate between the four possible designs.
+* the pose of the bird in the next step: you can click on the bird to rotate between the four possible poses, and a fifth one that indicates that the bird will halt.
+* where in the row the bird should move, right or left of the current tile. you can click on the empty space at the left or right of the tile to have the bird move there.
+
+=> ./img/screenshot_jarotsim-rule-active.png an active rule as described above
+
+the table of rules highlights the rule that would currently apply, given the pose of the bird and the tile design where they are standing.
+
+the halt pose will hide the new tile design, and additionally it will never be highlighted.
+
+=> ./img/screenshot_jarotsim-rule-halt.png an halt rule as described above
+
+## timeline mode
+
+=> ./img/screenshot_jarotsim_timeline.png screenshot of the timeline mode as described below
+
+# toolbar
+
+the toolbar at the bottom has the following buttons, from left to right:
+
+* step: apply the current rule and get to the next step.
+* play/pause: have the bird with a hat move automatically according to the rules.
+* speed: rotate between three different speed levels for the automatic movement.
+* mode: allow you to toggle between edit and timeline mode.
+
+the toolbar can be used regardless of the mode that jarotsim is on. therefore you can e.g. see how the rules are applied live, and even modify them while the bird with a hat is moving.
+
+note that the bird will pause when it arrives at a rule with a halt pose. you won't be able to step or press play until you change the rule, the current pose, and/or the current tile design.
 
-=> ./img/screenshot_jarotsim-tapes.png screenshot of jarotsim showing a series of states of a turing machine, each of them consists in bird with a hat over a tape with different tiles
-=> ./img/screenshot_jarotsim-edit.png screenshot of jarotsim showing the edit mode: a single tape above, and four machine rules below
 
 # about
 
 jarotsim is inspired by {turingsim} as a simulator of turing-machine-based performances like {d-turing} or {mub}.
 
-it embraces computing for fun, play and learning.
-
 the objective is to have a graphical user interface where one can edit / livecode the rules of the machine and its tape, and explore their effects.
 
 for the moment the idea is to have a maximum of 4 states and 4 symbols. according to Wolfram, they should be more than enough to explore complex behaviors.