Simplify grid examples, start on grids documentation

README.md

@@ -1177,11 +1177,174 @@ A [partial mixin](#optimising-output-using-partial-mixins) to generate image-spe
 Grids
 -------
 
-The ClearLess grid system is a straightforward grid system that supports either floated columns or columns created using inline-block. It supports infinite levels of nested columns.
+The ClearLess grid system is a straightforward grid system that supports either floated columns or columns created using `display: inline-block;`. It supports infinite levels of nested columns.
 
-Gutters are applied using the margin-left property. The columns that represent the last in a row at any time need to have the `.end-column()` (for floated grids) or `.inline-end-column()` (for inline-block grids) applied to them to stop them dropping down.
+Gutters are applied using the margin-left property. The columns that represent the last in a row at any time need to have the `.end-column()` (for floated grids) or `.inline-end-column()` (for inline-block grids) applied to them to stop them dropping down (although there are also shortcuts for doing this in the column, inline-column and span mixins themselves). There are obviously other ways to address this 'last column gutter' issue - but we've opted for simplicity and to closest match how many people would code this when doing so in 'straight' css.
 
-*Full documentation coming soon...*
+Columns need to be wrapped in a parent element with the appropriate `.column-wrapper()` or `.inline-column-wrapper()` mixin applied to them.
+
+### .column-wrapper()
+
+Applied to the parent element of the grid columns for **floated grids**. This (by design) *does not* apply any float clearing to the columns - you will likely want to use the `.clearfix()` mixin (or `overflow:hidden;` or whatever you're perferred float clearing methid is!) to account for this.
+
+```css
+.column-wrapper();
+```
+
+```css
+/* Usage: */
+.example {
+	.column-wrapper();
+}
+/* Example output: */
+.example {
+	width: 100%;
+}
+```
+
+### .inline-column-wrapper()
+
+Applied to the parent element of the grid columns for **inline-block grids**.
+
+```css
+.inline-column-wrapper();
+```
+
+```css
+/* Usage: */
+.example {
+	.column-wrapper();
+}
+/* Example output: */
+.example {
+	width: 100%;
+}
+```
+
+### .column()
+
+When supplied with no arguments, this mixin just sets up the necessary shared styles to make an element into a **floated** column. The `.span()` mixin should then be used to apply widths and margins accordingly.
+
+When supplied with a column count, this mixin effectively combines both of the above steps into one - simpler but may not result in the most optimised CSS, depending on the situation.
+
+```css
+.column();
+```
+
+```css
+.column( <@span>[, <@parent-grid-units>[, <@end-column>]] );
+```
+
+* `@span`: Number of grid columns to span.
+* `@parent-grid-units`: (Optional) For nested grids, the number of columns the parent element spans needs to be added here. Defaults to the value of `@total-columns`
+* `@end-column`: (Optional) Set to `true` if this column is the last one in a row.
+
+```css
+.column( <@span>[, <@end-column>] );
+```
+
+* `@span`: (Optional) Number of grid columns to span.
+* `@end-column`: (Optional) Set to `true` if this column is the last one in a row.
+
+```css
+/* Usage: */
+.example {
+	.column();
+}
+.example2 {
+	.column(2);
+}
+.example3 {
+	.column(2,true);
+}
+/* Example output: */
+.example {
+	float: left;
+	margin-right: 1.5873015873015872%;
+}
+.example2 {
+    float: left;
+    width: 11.11111111111111%;
+    margin-right: 1.5873015873015872%;
+}
+.example3 {
+    float: left;
+    width: 11.11111111111111%;
+}
+```
+
+### .inline-column()
+
+When supplied with no arguments, this mixin just sets up the necessary shared styles to make an element into a **inline-block** column. The `.span()` mixin should then be used to apply widths and margins accordingly.
+
+When supplied with a column count, this mixin effectively combines both of the above steps into one - simpler but may not result in the most optimised CSS, depending on the situation.
+
+```css
+.inline-column();
+```
+
+```css
+.inline-column( <@span>[, <@parent-grid-units>[, <@end-column>]] );
+```
+
+* `@span`: Number of grid columns to span.
+* `@parent-grid-units`: (Optional) For nested grids, the number of columns the parent element spans needs to be added here. Defaults to the value of `@total-columns`
+* `@end-column`: (Optional) Set to `true` if this column is the last one in a row.
+
+```css
+.inline-column( <@span>[, <@end-column>] );
+```
+
+* `@span`: (Optional) Number of grid columns to span.
+* `@end-column`: (Optional) Set to `true` if this column is the last one in a row.
+
+```css
+/* Usage: */
+.example {
+	.inline-column();
+}
+.example2 {
+	.inline-column(2);
+}
+.example3 {
+	.inline-column(2,true);
+}
+/* Example output: */
+.example {
+	display: inline-block;
+	vertical-align: top;
+	letter-spacing: normal;
+	word-spacing: normal;
+	margin-right: 1.5873015873015872%;
+}
+.ie7 .example {
+	display: inline;
+	zoom: 1;
+}
+.example2 {
+	display: inline-block;
+	vertical-align: top;
+	letter-spacing: normal;
+	word-spacing: normal;
+	width: 11.11111111111111%;
+	margin-right: 1.5873015873015872%;
+}
+.ie7 .example2 {
+	display: inline;
+	zoom: 1;
+}
+.example3 {
+	display: inline-block;
+	vertical-align: top;
+	letter-spacing: normal;
+	word-spacing: normal;
+	width: 11.11111111111111%;
+}
+.ie7 .example3 {
+	display: inline;
+	zoom: 1;
+}
+```
 
 
 Some notes on usage and best practices

examples/css/example.css

@@ -230,6 +230,17 @@ table {
   border-spacing: 0;
 }
 /* ---- setup ---- */
+.test {
+  display: inline-block;
+  vertical-align: top;
+  letter-spacing: normal;
+  word-spacing: normal;
+  margin-right: 1.5873015873015872%;
+}
+.ie7 .test {
+  display: inline;
+  zoom: 1;
+}
 body {
   padding: 20px;
   background: #DDD;
@@ -268,10 +279,6 @@ h2 {
   position: relative;
   padding-left: 16px;
 }
-.ie7 .nav a {
-  display: inline;
-  zoom: 1;
-}
 .nav a:before {
   position: absolute;
   display: block;
@@ -301,124 +308,78 @@ h2 {
 /* Grids using floats */
 .floated .section {
   width: 100%;
-}
+  overflow: hidden;
-.floated .section:before,
-.floated .section:after {
-  content: "";
-  display: table;
-}
-.floated .section:after {
-  clear: both;
-}
-.ie6 .floated .section,
-.ie7 .floated .section {
-  zoom: 1;
 }
 .floated .segment {
-  display: inline;
   float: left;
   margin-right: 1.5873015873015872%;
-  display: inline;
-  float: left;
 }
 /* Grids using inline-block */
 .inline .section {
   letter-spacing: -0.31em;
-  *letter-spacing: normal;
   word-spacing: -0.43em;
 }
+.ie7 .inline .section {
+  *letter-spacing: normal;
+}
 .inline .segment {
   display: inline-block;
   vertical-align: top;
   letter-spacing: normal;
   word-spacing: normal;
   margin-right: 1.5873015873015872%;
-  display: inline-block;
-  vertical-align: top;
-  letter-spacing: normal;
-  word-spacing: normal;
 }
+.ie7 .inline .segment {
+  display: inline;
+  zoom: 1;
+}
+/* shared grid sizes */
 .section-1 .segment {
-  width: 100%;
+  width: 23.809523809523807%;
 }
-.section-2 .segment {
+.section-1 .quaternary {
-  display: inline-block;
-  vertical-align: top;
-  letter-spacing: normal;
-  word-spacing: normal;
-  width: 49.2063492063492%;
-  margin-right: 1.5873015873015872%;
-}
-.section-2 .secondary {
   margin-right: 0;
   float: right;
 }
-.section-3 .segment {
+.section-2 .primary {
-  width: 49.2063492063492%;
+  width: 61.904761904761905%;
 }
-.section-4 .segment {
+.section-2 .secondary {
-  width: 49.2063492063492%;
+  width: 36.507936507936506%;
+  margin-right: 0;
+  float: right;
 }
-/* media query example */
+.section-3 .primary {
-@media all and (max-width: 40em) {
+  width: 17.46031746031746%;
-  .section-3 .segment:nth-child(2n),
-  .section-4 .segment:nth-child(2n) {
-    margin-right: 0;
-    float: right;
-  }
 }
-@media all and (min-width: 40em) {
+.section-3 .secondary {
-  .section-1 .segment {
+  width: 23.809523809523807%;
-    width: 23.809523809523807%;
+}
-  }
+.section-3 .tertiary {
-  .section-1 .quaternary {
+  width: 36.507936507936506%;
-    margin-right: 0;
+}
-    float: right;
+.section-3 .quaternary {
-  }
+  width: 17.46031746031746%;
-  .section-2 .primary {
+  margin-right: 0;
-    width: 61.904761904761905%;
+  float: right;
-  }
+}
-  .section-2 .secondary {
+.section-4 .primary {
-    width: 36.507936507936506%;
+  width: 11.11111111111111%;
-    margin-right: 0;
+  padding-right: 6.349206349206349%;
-    float: right;
+}
-  }
+.section-4 .secondary {
-  .section-3 .segment:nth-child(4n) {
+  width: 11.11111111111111%;
-    margin-right: 0;
+  padding-left: 6.349206349206349%;
-    float: right;
+  margin-left: 6.349206349206349%;
-  }
+}
-  .section-3 .primary {
+.section-4 .tertiary {
-    width: 17.46031746031746%;
+  width: 17.46031746031746%;
-  }
+  margin-left: 6.349206349206349%;
-  .section-3 .secondary {
+}
-    width: 23.809523809523807%;
+.section-4 .quaternary {
-  }
+  width: 17.46031746031746%;
-  .section-3 .tertiary {
+  padding-left: 6.349206349206349%;
-    width: 36.507936507936506%;
+  margin-right: 6.349206349206349%;
-  }
-  .section-3 .quaternary {
-    width: 17.46031746031746%;
-    margin-right: 0;
-    float: right;
-  }
-  .section-4 .primary {
-    width: 11.11111111111111%;
-    padding-right: 6.349206349206349%;
-  }
-  .section-4 .secondary {
-    width: 11.11111111111111%;
-    padding-left: 6.349206349206349%;
-    margin-left: 6.349206349206349%;
-  }
-  .section-4 .tertiary {
-    width: 17.46031746031746%;
-    margin-left: 6.349206349206349%;
-  }
-  .section-4 .quaternary {
-    width: 17.46031746031746%;
-    padding-left: 6.349206349206349%;
-    margin-right: 6.349206349206349%;
-  }
 }
 /* Nested Grids */
 .section-parent .segment {
@@ -435,13 +396,11 @@ h2 {
   margin-right: 3.225806451612903%;
   background: #999;
 }
-.floated .section-nested .segment > .secondary,
+.floated .section-parent .quaternary {
-.floated .section-parent .segment:nth-child(4n) {
   margin-right: 0;
   float: right;
 }
-.inline .section-nested .segment > .secondary,
+.inline .section-parent .quaternary {
-.inline .section-parent .segment:nth-child(4n) {
   margin-right: 0;
 }
 /* Sprites & Icons */
@@ -450,10 +409,6 @@ h2 {
   position: relative;
   padding-right: 16px;
 }
-.ie7 .more {
-  display: inline;
-  zoom: 1;
-}
 .more:after {
   position: absolute;
   display: block;

examples/less/example.less

@@ -6,6 +6,7 @@
 @using-modernizr: false;
 @using-ieclasses: true;
 
+@total-columns: 16;
 @column-width: 60;
 @gutter-width: 20;
 
@@ -21,6 +22,10 @@
 
 /* ---- setup ---- */
 
+.test {
+	.inline-column();
+}
+
 body {
 	padding: 20px;
 	background: #DDD;
@@ -55,7 +60,7 @@ h2 {
 		padding: 0;
 	}
 	a {
-		.inline-block();
+		display: inline-block;
 		.prepend-sprite-icon(2, 1, 6px, 11px, 0, 4px);
 	}
 }
@@ -83,6 +88,7 @@ h2 {
 .floated {
 	.section {
 		.column-wrapper();
+		overflow: hidden;
 	}
 	.segment {
 		.column();
@@ -100,105 +106,63 @@ h2 {
 	}
 }
 
+/* shared grid sizes */
+
 .section-1 {
 	.segment {
-		.span(16,true);
+		.span(4);
+	}
+	.quaternary {
+		.end-column();
 	}
 }
 
 .section-2 {
-	.segment {
+	.primary {
-		.inline-column(8);
+		.span(10);
 	}
 	.secondary {
-		.end-column()
+		.span(6);
+		.end-column();
 	}
 }
 
 .section-3 {
-	.segment {
+	.primary {
-		.span(8);
+		.span(3);
 	}
-}
+	.secondary {
-
+		.span(4);
-.section-4 {
-	.segment {
-		.span(8);
 	}
-}
+	.tertiary {
-
+		.span(6);
-
+	}
-/* media query example */
+	.quaternary {
-
+		.span(3);
-@media all and ( max-width: @mobile-width ) {
-	.section-3 .segment:nth-child(2n),
-	.section-4 .segment:nth-child(2n) {
 		.end-column();
-	}	
+	}
 }
-
-@media all and ( min-width: @mobile-width ) {
 	
-	.section-1 {
+.section-4 {
-		.segment {
+	.primary {
-			.span(4);
+		.span(2);
-		}
+		.post-pad(1);
-		.quaternary {
-			.end-column();
-		}
 	}
-
+	.secondary {
-	.section-2 {
+		.span(2);
-		.primary {
+		.pre-pad(1);
-			.span(10);
+		.pre-push(1);
-		}
-		.secondary {
-			.span(6);
-			.end-column();
-		}
 	}
-
+	.tertiary {
-	.section-3 {
+		.span(3);
-		.segment:nth-child(4n) {
+		.pre-push(1);
-			.end-column();
-		}
-		.primary {
-			.span(3);
-		}
-		.secondary {
-			.span(4);
-		}
-		.tertiary {
-			.span(6);
-		}
-		.quaternary {
-			.span(3);
-			.end-column();
-		}
 	}
-	
-	.section-4 {
-		.primary {
-			.span(2);
-			.post-pad(1);
-		}
-		.secondary {
-			.span(2);
-			.pre-pad(1);
-			.pre-push(1);
-		}
-		.tertiary {
-			.span(3);
-			.pre-push(1);
-		}
 		
-		.quaternary {
+	.quaternary {
-			.span(3);
+		.span(3);
-			.pre-pad(1);
+		.pre-pad(1);
-			.post-push-end(1);
+		.post-push-end(1);
-		}
 	}
-	
 }
 
 /* Nested Grids */
@@ -214,32 +178,23 @@ h2 {
 	}
 }
 
-.section-nested {
+.section-nested .segment {
-	.segment {
+	.span(2,8);
-		.span(2,8);
+	background: #999;
-		background: #999;
-	}
 }
 
-.floated {
+.floated .section-parent .quaternary {
-	.section-nested .segment > .secondary,
+	.end-column();
-	.section-parent .segment:nth-child(4n) {
-		.end-column();
-	}
 }
 
-.inline {
+.inline .section-parent .quaternary {
-	.section-nested .segment > .secondary,
+	.inline-end-column();
-	.section-parent .segment:nth-child(4n) {
-		.inline-end-column();
-	}
 }
 
-
 /* Sprites & Icons */
 
 .more {
-	.inline-block();
+	display: inline-block;
 	.append-sprite-icon(2, 1, 6px, 11px, 0, 4px);
 }
 

mixins/grids.less

@@ -6,16 +6,74 @@
 @grid-width: (@column-width*@total-columns) + (@gutter-width*(@total-columns - 1));
 
 .column-wrapper() {
-	.clearfix();
 	width: 100%;
 }
 
-.inline-column-wrapper() {
+.inline-column-wrapper() when not (@using-ieclasses) {
     letter-spacing: -0.31em;
     *letter-spacing: normal;
     word-spacing: -0.43em;
 }
 
+.inline-column-wrapper() when (@using-ieclasses) {
+    letter-spacing: -0.31em;
+    word-spacing: -0.43em;
+	.ie7 & {
+		*letter-spacing: normal;
+	}
+}
+
+
+.column() {
+	float: left;
+	.column-gutter();
+}
+
+.column( @span ) when (@span = false) {
+	float: left;
+}
+
+.column( @span, @total-columns:@total-columns, @end-column:false ) when (isnumber(@span)) and (isnumber(@total-columns)) {
+	@showgutter: false;
+	.column(@showgutter);
+	.span( @span, @total-columns, @end-column );
+}
+
+.column( @span, @end-column ) when (isnumber(@span)) and not (isnumber(@end-column)) {
+	@showgutter: false;
+	.column(@showgutter);
+	.span( @span, @end-column );
+}
+
+
+.inline-column() {
+	.inline-block();
+	vertical-align: top;
+    letter-spacing: normal;
+    word-spacing: normal;
+	.column-gutter();
+}
+
+.inline-column( @span ) when (@span = false) {
+	.inline-block();
+	vertical-align: top;
+    letter-spacing: normal;
+    word-spacing: normal;
+}
+
+.inline-column( @span, @total-columns:@total-columns, @end-column:false ) when (isnumber(@span)) and (isnumber(@total-columns)) {
+	@showgutter: false;
+	.inline-column(@showgutter);
+	.span( @span, @total-columns, @end-column );
+}
+
+.inline-column( @span, @end-column ) when not (isnumber(@end-column)) {
+	@showgutter: false;
+	.inline-column(@showgutter);
+	.span( @span, @end-column );
+}
+
+
 .end-column() {
 	margin-right: 0;
 	float: right;
@@ -40,58 +98,6 @@
 }
 
 
-.column() {
-	display: inline;
-	float: left;
-	.column-gutter();
-}
-
-.column( @span:false ) when (@span = false) {
-	display: inline;
-	float: left;
-}
-
-.column( @span, @total-columns:@total-columns, @end-column:false ) when (isnumber(@span)) and (isnumber(@total-columns)) {
-	@showgutter: false;
-	.column(@showgutter);
-	.span( @span, @total-columns, @end-column );
-}
-
-.column( @span, @end-column ) when (isnumber(@span)) and not (isnumber(@end-column)) {
-	@showgutter: false;
-	.column(@showgutter);
-	.span( @span, @end-column );
-}
-
-
-.inline-column() {
-	display: inline-block;
-	vertical-align: top;
-    letter-spacing: normal;
-    word-spacing: normal;
-	.column-gutter();
-}
-
-.inline-column( @span:false ) when (@span = false) {
-	display: inline-block;
-	vertical-align: top;
-    letter-spacing: normal;
-    word-spacing: normal;
-}
-
-.inline-column( @span, @total-columns:@total-columns, @end-column:false ) when (isnumber(@span)) and (isnumber(@total-columns)) {
-	@showgutter: false;
-	.inline-column(@showgutter);
-	.span( @span, @total-columns, @end-column );
-}
-
-.inline-column( @span, @end-column ) when not (isnumber(@end-column)) {
-	@showgutter: false;
-	.inline-column(@showgutter);
-	.span( @span, @end-column );
-}
-
-
 .pre-pad( @span ) {
 	@calc-column-width: 100%*((((@gutter-width+@column-width)*@span)) / @grid-width);
 	padding-left: @calc-column-width;