reorganizing guides

Author: boydm

guides/getting_started.md

@@ -198,6 +198,6 @@ Scenic.SensorPubSub service.
 
 ## What to read next?
 
-Next, you should read about the [structure of a scene](scene_structure.html).
+Next, you should read about the [structure of a scene](overview_scene.html).
 This will explain the parts of a scene, how to send and receive messages and how
 to push the graph to the ViewPort.

guides/overview_graph.md

@@ -8,17 +8,86 @@ screen, it pushes it to the Viewport.
 Graphs are made out of a handful of primitives, each of which knows how to draw
 one thing. When multiple primitives are put together, almost any standard UI can be drawn.
 
-For example, the graph below
+For example, the graph below shows the words "Hello World" around them.
 
+    @graph Graph.build(font: :roboto, font_size: 24)
+      |> text("Hello World", text_align: center, translate: {300, 300})
+      |> circle(100, stroke: {2, :green} translate: {300, 300})
+
+In the example above, the first line creates a new graph and assigns two font styles to its root. The next two lines form a pipeline that adds primitives to the root
+node of the new graph. Each of these primitives also assigns styles.
 
 ## Primitives
 
-## The Group
+There is a fixed set of primitives that Scenic knows how to draw. These form the base set of things that you can do. While they seem simple, when combined you draw pretty much any 2D UI that you need.
+
+[Read more about the primitives here.](overview_primitives.html)
+
+In general, each primitive renders one thing to the screen. The Group primitive is
+sort of like a `<div>` tag in html in that it creates a new node in the graph hierarchy that more primitives can be organized beneath.
+
+Each primitive can also be assigned styles and transforms, which affect how (or whether) they are drawn and where.
+
+## Styles
+
+In addition to the fixed set of primitives, there is also a fixed set of primitive styles. (Some components support more styles, but they really get boiled down to the primitive styles when it is time to render)
+
+[Read more about the styles here.](overview_styles.html)
+
+Styles are inherited down the graph hierarchy. This means that if you set a style on the root of a graph, or in a group, then any primitives below that node inherit those styles without needing to explicitly set them on every single primitive.
+
+For example, in the following graph, the font and font_size styles are set at the root. Both text primitives inherit those values, although the second one overrides the size with something bigger.
+
+    @graph Graph.build(font: :roboto, font_size: 24)
+      |> text("Hello World", translate: {300, 300})
+      |> text("Bigger Hello", font_size: 40, translate: {400, 300})
+
+
+## Transforms
+
+The final type of primitive control is transforms. Unlike html, which uses auto-layout to position items on the screen, Scenic moves primitives around using matrix based transforms. This is common in video games and provides powerful control of your primitives.
+
+A [matrix](https://en.wikipedia.org/wiki/Matrix_(mathematics)) is an array of numbers that can be used to change the positions, rotations, scale and more of locations.
+
+In Scenic, you will only rarely create matrices on your own (you can if you know what you are doing!), and will instead use the very easy transform helpers.
+
+[You can read about the transform types here.](overview_transforms.html)
+
+Transforms are inherited down the graph hierarchy. This means that if you place a rotation transform at the root of a graph, then all the primitives will be rotated around a common point.
+
+If you want to zoom in, scroll, or rotate a UI, or just pieces of the UI, you can do that very easily by applying transforms.
+
+In the example below, the first text line is translated, and the second is scaled bigger, and the whole graph rotated 0.4 radians.
+
+    @graph Graph.build(font: :roboto, font_size: 24, rotate: 0.4)
+      |> text("Hello World", translate: {300, 300})
+      |> text("Bigger Hello", font_size: 40, scale: 1.5)
 
-## Position, rotation, scale and more
 
 ## Modifying a graph
 
+Scenic was written specifically for Erlang/Elixir, which is a functional programming model with immutable data.
+
+As such, once you make a graph, it stays in memory unchanged - until you change it via `Graph.modify/3`. Technically you never change it (that's the immutable part), instead Graph.modify returns a new graph with different data in it.
+
+[Graph.modify/3](Scenic.Graph.html#modify/3) is the single Graph function that you will use the most.
+
+For example, lets go back to our graph with the two text items in it.
+
+    @graph Graph.build(font: :roboto, font_size: 24, rotate: 0.4)
+      |> text("Hello World", translate: {300, 300}, id: :small_text)
+      |> text("Bigger Hello", font_size: 40, scale: 1.5, id: :big_text)
+
+This time, we've assigned ids to both of the text primitives. This makes it easy to find and modify that primitive in the graph.
+
+    graph =
+      @graph
+      |> Graph.modify( :small_text, &text(&1, "Smaller Hello", font_size: 16))
+      |> Graph.modify( :big_text, &text(&1, "Bigger Hello", font_size: 60))
+
+Notice that the graph is modified multiple times in a pipeline. 
+
+
 ## Graph Internals
 
 

guides/overview_primitives.md

@@ -1,3 +1,15 @@
 # Styles Overview
 
-Coming soon
+* [Arc](Scenic.Primitive.Arc)
+* [Circle](Scenic.Primitive.Circle)
+* [Ellipse](Scenic.Primitive.Ellipse)
+* [Group](Scenic.Primitive.Group)
+* [Line](Scenic.Primitive.Line)
+* [Path](Scenic.Primitive.Path)
+* [Quad](Scenic.Primitive.Quad)
+* [Rectangle](Scenic.Primitive.Rectangle)
+* [RoundedRectangle](Scenic.Primitive.RoundedRectangle)
+* [Scene Ref](Scenic.Primitive.SceneRef)
+* [Sector](Scenic.Primitive.Sector)
+* [Text](Scenic.Primitive.Text)
+* [Triangle](Scenic.Primitive.Triangle)

guides/scene_structure.md renamed to guides/overview_scene.md

@@ -1,7 +1,6 @@
 # Structure of a Scene
 
-A `Scenic.Scene` is a `GenServer` process. They create the Graphs that get drawn
-to the screen and respond to user input and other events.
+A `Scenic.Scene` is a `GenServer` process which creates and manages a [Graph](overview_graph.html) that gets drawn to the screen. Scenes also respondss to user input and other events.
 
 Scenes can reference each other, creating a logical hierarchy that lives above
 the Graphs themselves. This allows scenes to be reusable, small, and simple. A

guides/welcome.md

@@ -14,7 +14,7 @@ If you are new to Scenic, then you should read the following list in order.
 
 * [General Overview](overview_general.html)
 * [Getting Started](getting_started.html)
-* [Structure of a Scene](scene_structure.html)
+* [Structure of a Scene](overview_scene.html)
 * [Contributing](contributing.html)
 * [Code of Conduct](code_of_conduct.html)
 

lib/mix/tasks/hash.ex

@@ -35,7 +35,7 @@ defmodule Mix.Tasks.Scenic.Hash do
       >> guides/overview_general.md -> "UNcd84guRIEBK5a0tWdp5MYmJpI"
       >> guides/overview_driver.md -> "zsTJ_xDQGrXLBtQk80hSUt-wZYE"
       >> guides/scene_lifecycle.md -> "jNcP7dPNXon0zEMtyCqL2z-A7FY"
-      >> guides/scene_structure.md -> "apxgZRkCBHZeNNzCMpxgQRytHLA"
+      >> guides/overview_scene.md -> "apxgZRkCBHZeNNzCMpxgQRytHLA"
       >> guides/getting_started.md -> "v1So-K14iPs_mGQZqr237TPah8I"
       >> guides/overview_viewport.md -> "3TpXIFxcwG54N2bb0O-86aznSS4"
       >> guides/mix_tasks.md -> "CWp9l8tDfHf5czjJqpbKtPqaqlc"

mix.exs

@@ -110,7 +110,7 @@ defmodule Scenic.Mixfile do
       "guides/overview_general.md",
       "guides/getting_started.md",
       "guides/getting_started_nerves.md",
-      "guides/scene_structure.md",
+      "guides/overview_scene.md",
       "guides/scene_lifecycle.md",
       "guides/overview_graph.md",
       "guides/overview_viewport.md",