illustrations and license

Author: begriffs

LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2012 Joe Nelson.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -1,13 +1,13 @@
 ![Logo](css-ratiocinator/raw/master/illustration/githubheader.png "Logo")
 
 The CSS Ratiocinator automatically refactors your CSS and generates a
-new stylesheet for your site. It works by examining your site's live
-DOM in the browser and reverse engineering a new, more elegant, CSS
-definition that captures styles down to the pixel.
+new stylesheet for your site. It works by examining your site's live DOM
+in the browser and reverse engineering a new, more elegant definition
+that captures styles down to the pixel.
 
 It addresses the problem of old CSS whose styles accumulate and
 contradict each other. After a certain point all CSS seems to grow only
-by internal antagonism. The ratiocinator wipes the slate clean and
+by internal antagonism. The Ratiocinator wipes the slate clean and
 provides a harmonious new beginning.
 
 ## Usage
@@ -24,3 +24,33 @@ Runs best in [Google Chrome](//www.google.com/chrome).
 
 ## Mechanism
 
+The ratiocinator proceeds in two phases: assessment and consolidation.
+During assessment it determines which nodes will need which styles,
+accounting for browser defaults and cascade rules. The browser provides
+a full list of computed style for every node, and our first step is to
+prune redundencies from cascaded style in a depth-first process called
+"lifting." ![Lifting](css-ratiocinator/raw/master/illustration/lift.png "Lifting")
+
+The last step in assessment is stripping default styles. The final
+style needn't specify CSS defaults, so we remove them prior to the
+consolidation phase.
+
+Next comes consolidation, where we find shared pieces of style
+throughout the cleaned DOM tree and extract them to CSS declarations.
+
+![Consolidating](css-ratiocinator/raw/master/illustration/consolidate.png "Consolidating")
+
+In the diagram above, the ratiocinator will choose to output a
+declaration for the styles in red before those in blue. Although there
+are more blue items than red in element `aside.foo`, there are more red
+elements overall. The red has greater "volume." Hence the ratiocinator
+will extract styles for all elements with class `foo` first and then for
+`aside` elements second.
+
+## Contributing
+
+## License
+
+The CSS Ratiocinator is Copyright © 2012 Joe Nelson. It is free
+software, and may be redistributed under the terms specified in the
+LICENSE file.

illustration/consolidate.dot

@@ -0,0 +1,30 @@
+digraph G {
+  rankdir=LR
+  node [shape=record];
+
+  subgraph cluster_dom {
+    label="Consolidating";
+    color=lightgrey;
+    body  [label="body"];
+    div   [label=<
+      <table border="0">
+        <tr><td>div.foo</td></tr>
+        <tr><td><FONT color="red">color: black</FONT></td></tr>
+        <tr><td><FONT color="red">margin: 10px</FONT></td></tr>
+      </table>
+    >]
+    aside [label=<
+      <table border="0">
+        <tr><td>aside.foo</td></tr>
+        <tr><td><FONT color="red">color: black</FONT></td></tr>
+        <tr><td><FONT color="blue">background: #AAA</FONT></td></tr>
+        <tr><td><FONT color="blue">border: 1px solid black</FONT></td></tr>
+        <tr><td><FONT color="blue">border-radius: 5px</FONT></td></tr>
+        <tr><td><FONT color="red">margin: 10px</FONT></td></tr>
+      </table>
+    >]
+
+    body -> div;
+    body -> aside;
+  }
+}

illustration/consolidate.png

@@ -0,0 +1,32 @@
+digraph G {
+  rankdir=LR
+  node [shape=record];
+
+  subgraph cluster_after {
+    rank=2;
+    label="After";
+    color=lightgrey;
+    body_1 [label="body"];
+    div_1  [label="div | color: red"];
+    p_10   [label="p | font-weight: bold"];
+    p_11   [label="p"];
+
+    body_1 -> div_1;
+    div_1  -> p_10;
+    div_1  -> p_11;
+  }
+
+  subgraph cluster_before {
+    rank=1;
+    label="Before";
+    color=lightgrey;
+    body_0 [label="body"];
+    div_0  [label="div | color: red"];
+    p_00   [label="p | color: red | font-weight: bold"];
+    p_01   [label="p | color: red"];
+
+    body_0 -> div_0;
+    div_0  -> p_00;
+    div_0  -> p_01;
+  }
+}