Merge branch 'rel-v2.0.0' into gh-pages

tag: v2.0.0

.gitignore

@@ -25,7 +25,9 @@ build/Release
 # Commenting this out is preferred by some people, see
 # https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git-
 node_modules
-bower_components
 
 # Users Environment Variables
 .lock-wscript
+
+# Compiled source files
+out/

README.md

@@ -3,61 +3,162 @@ A default stylesheet with a set of tools that make designing with vertical rhyth
 
 Pronounced "Cross Meter".
 
-## Installation
+## Installation and Usage
 
-    $ bower install xmeter
+This package is really a two-in-one. First, it is a set of tools (functions,
+fallbacks, modules, etc.) that make your life easier when working on a site's
+existing stylesheet or starting a brand new one. Secondly, it provides a base
+stylesheet, a starting point, for developing a new site. It is geared towards
+sites (or sections of sites) that are more static and typographically inclined
+and not so dynamic like “web apps.”
+Read the [About](#about) section for more info.
 
-## Usage
+There are two ways you can use this package. One option is if you’re
+**developing** your own front-end package (such as a CSS library or site-wide
+stylesheet) that *uses* this package as a dependency, and the other option is
+if you’re **deploying** a project (such as a website or blog) that *mentions*
+(i.e., references) this stylesheet.
+
+This package uses **normalize.css** as a dependency.
+If you’re *developing* a package, then it is automatically installed,
+but if you’re *deploying* a project, you have to install it manually (via `bower`, etc.).
+
+**Important:** `xmeter.css` does *not* `@import normalize.css`
+(*this may change in the future—stay tuned for updates*).
+In order for it to work properly on your page,
+you *must* link **normalize.css** in your CSS / HTML *before* linking this stylesheet.
+
+### Development
+
+(The First Option)
+
+To install:
+
+    $ npm install xmeter
+
+#### Using the Tools
+
+Take a look in the `src/` folder. In here you will find a set of tools, starting
+with `_tool`, from which to pick and choose to use for your package. Note that
+the contents of each file are wrapped with the id selector `#XMETER {}` to keep
+it encapsulated. Think of `#XMETER` as one huge object whose properties are
+the mixins. Or think of it as a namespace. Whatever.
+
+If you want to use a particular tool in your stylesheet, you will have to
+`@import (reference)` that tool, and then invoke it with `#XMETER`. For example,
+if you plan to use the `.font-size-block()` mixin in your Less, you must include
+
+```less
+@import (reference) url('/node_modules/xmeter/src/_tool.module.fontsize.less');
+```
+
+at the top of your stylesheet. Then when you want to “call” the mixin, do
+
+```less
+.my-selector {
+  #XMETER .font-size-block(2.0; 1.5);
+}
+```
+
+To use the xmeter variables,
+
+```less
+@import (reference) url('/node_modules/xmeter/src/_settings.less');
+
+.my-selector {
+  #XMETER .VARS();
+  margin-bottom: @xmeter_vru;
+}
+```
+
+#### Using the Base
+
+Also in the `src/` folder are a set of files starting with `_base`. These files,
+unlike tools, provide actual styles for actual elements. Also unlike tools, these
+stylesheets are *not* meant to be cherrypicked. They are compiled separately<sup>&lowast;</sup> and
+concatenated together in the main file `xmeter.css`. If you’re developing a
+stylesheet that you want built off of xmeter, include
+
+```less
+@import url('/node_modules/xmeter/node_modules/normalize.css/normalize.css');
+@import url('/node_modules/xmeter/xmeter.css');
+```
+
+at the top of  your file. Notice that **normalize.css** must be imported separately,
+and before **xmeter**.
+
+This package also comes installed with a [test page](./test.html)
+that links to the main stylesheet.
+
+*<sup>&lowast;</sup>The reason the stylesheets are compiled separately is to increase
+encapsulation. They still have access to global variables (such as `#XMETER`),
+but now local variables and mixins can be defined within the file without
+affecting other files.*
+
+### Deployment
+
+(The Second Option)
+
+This option is for you if you don’t wanna develop with **xmeter**, you just
+wanna use it on your site. It’s a great starting point that “normalizes”
+unclassed HTML elements before any specific classes and styles get added on.
+
+See the [test page](./test.html) for a preview.
+
+To install:
+
+    $ bower install https://github.com/chharvey/xmeter.git
+    $ bower install normalize.css
+
+To reference this stylesheet on your own site:
 
-This package depends on **normalize.css**. It is listed under the package dependencies,
-so there is no need to install it separately. However this stylesheet does *not*
-`@import normalize.css` (*this may change in the future*). In order for it
-to work properly, you *must* link **normalize.css** in your HTML *before* linking this stylesheet.
-Use the following `link` elements
-in the HTML head:
 ```html
-<link rel="stylesheet" href="path/to/bower_components/normalize.css/normalize.css"/>
-<link rel="stylesheet" href="path/to/bower_components/xmeter/xmeter.css"/>
+<link rel="stylesheet" href="/bower_components/normalize.css/normalize.css"/>
+<link rel="stylesheet" href="/bower_components/xmeter/xmeter.css"/>
 ```
-If for some reason you do not have these stylesheets installed locally, you may fetch them off the
-web as you would from a CDN (though this is not recommended).
+
+If for some reason you do not have these stylesheets installed locally, you may
+fetch them off the web as you would from a CDN (though this is not recommended).
+
 ```html
 <link rel="stylesheet" href="https://necolas.github.io/normalize.css/latest/normalize.css"/>
 <link rel="stylesheet" href="https://chharvey.github.io/xmeter/xmeter.css"/>
 ```
-To use this stylesheet in your own Less project, import (reference) it:
-```css
-@import (reference) url('path/to/bower_components/xmeter/src/xmeter.less');
-```
-This allows you access to all the mixins and selectors, so you can build on top of them.
 
 ## About
 
 This stylesheet rides on top of **normalize.css** developed by
 [Nicolas Gallagher](http://necolas.github.io/normalize.css/).
 
-While **normalize.css** addresses discrepancies between different browsers' rendering of HTML
-elements, providing only the very basic and necessary styles, **xmeter.css** adds additional
-styles for a more streamlined look and a vertical rhythm system. (For more information on
-vertical rhythm, see these articles in
+While **normalize.css** addresses discrepancies between different browsers’
+rendering of HTML elements, providing only the very basic and necessary styles,
+**xmeter.css** adds additional tools and styles for a more streamlined look and a
+vertical rhythm system. (For more information on vertical rhythm, see these articles in
 [24ways](http://24ways.org/2006/compose-to-a-vertical-rhythm/) and
 [Smashing Magazine](http://www.smashingmagazine.com/2011/03/14/technical-web-typography-guidelines-and-techniques/#tt-rhythm).)
 
 Features of this stylesheet include the following. See the test page (`./test.html`)
 for a demo.
 
 - Vertical rhythm &mdash; every line on the page is exactly the same height
-  (dubbed a "vertical rhythm unit" or "vru") regardless of font size, and typographical
-  elements (headings, paragraphs, figures, blockquotes, lists, tables, etc.) are separated
-  by integer multiples of that height.
-- Font-size for `html` is set to `100%` to accommodate for user agent settings. All other
-  font-sizes are relative (either `rem`s or `em`s, no pixels or inches).
+  (dubbed a "vertical rhythm unit" or "vru") regardless of font size, and
+  typographical elements (headings, paragraphs, figures, blockquotes, lists,
+  tables, etc.) are separated by integer multiples of that height.
+- Font-size for `html` is set to `100%` to accommodate for user agent settings.
+  All other font-sizes are relative (either `rem`s or `em`s, no pixels or inches).
 - All line-height values are unitless.
-- Units for font-size, margin, and padding on block elements are in `rem`s rather than `em`s,
-  thus the size of an element's font remains the same regardless of where that element is placed
-  (style does not depend on location).
-- **However:** `em`s are used on text-level elements, so that these elements scale accordingly
-  when nested inside elements with a larger font size (style *does* depend on location).
-- Line-height for all inline (text-level) elements is 0. This allows the vertical rhythm to
-  remain unaffected.
+- Units for font-size, margin, and padding on block elements are in `rem`s
+  rather than `em`s, thus the size of an element's font remains the same
+  regardless of where that element is placed (style does not depend on location).
+- **However:** `em`s are used on text-level elements, so that these elements
+  scale accordingly when nested inside elements with a larger font size
+  (style *does* depend on location).
+- Line-height for all inline (text-level) elements is 0. This allows the
+  vertical rhythm to remain unaffected.
 - Minor, albeit prettier, style changes to some text-level elements from the browser default.
+- Fallback tools for browser discrepancies on CSS3 properties.
+- `.sprite()` mixin makes it easy to work with background image sprites.
+
+## Changelog
+
+It’s on [Github](https://github.com/chharvey/xmeter/releases).

lessc-each.js

@@ -0,0 +1,70 @@
+
+// This module takes a groups of files, filters out the non-less files,
+// then compiles all the less files into their css counterparts.
+//
+// Run `node  lessc-each.js  <dir1>  <dir2>` to activate.
+// @param `<dir1>` - the directory of files to compile
+// @param `<dir2>` - the directory for output files to go
+//
+// Issues:
+//
+// 1. This program converts the file contents into a string and uses `less.render()`
+//    on that string, so the urls inside the less file, which are relative to the
+//    file contents, will not get parsed correctly.
+//    One temporary workaround would be to run `node lessc-each.js <dir1> <dir2>`
+//    from inside `<dir1>`, but then make `<dir2>` relative to `<dir1>`.
+//
+//    Example: Running
+//
+//        $ node  lessc-each.js  ./src/  ./out/
+//
+//    from inside `/` (main repo directory).
+//    In the contents of `./src/_base.generic.less`, there is an `@import url('_settings.less');`,
+//    which is meant to import the `_settings.less` file inside `./src/`.
+//    When `less.render()` parses the string, it’s going to look for `./_settings.less`
+//    inside the current directory, and won’t find it (because it’s in `./src/`).
+//    So to work around this, you might run
+//
+//        $ cd  ./src/
+//        $ node  lessc-each.js  ./  ../out/
+//
+//    This method has not been tested, nor am I going to spend much time testing it
+//    as it is merely a HACK and not an actual fix of the problem.
+
+
+var
+    fs = require('fs')
+  , path = require('path')
+  , less = require('less')
+
+
+fs.readdir(process.argv[2], function (err, files) {
+  if (err) return console.error('There was an error: ', err)
+
+  var less_files = files.filter(function (el) {
+
+    var ext = path.parse(el).ext
+    var name = path.parse(el).name
+    return (ext === '.less') && (name.slice(0,5) === '_base')
+  })
+
+  less_files.forEach(function (el) {
+    var less_fullpath = path.normalize(process.argv[2] + '/' + el)
+    var css_fullpath  = path.normalize(process.argv[3] + '/' + el.slice(0, el.length-5) + '.css')
+
+    fs.readFile(less_fullpath, 'utf8', function (err, data) {
+      if (err) return console.error('There was an error: ', err)
+      less.render(data, function (error, output) {
+        if (error) {
+          console.error('FATAL! ' + less_fullpath + ' does NOT compile due to:' + '\n    ' + error.message)
+          console.log('Continuing to next file...')
+        } else {
+          fs.writeFile(css_fullpath, output.css, function (err, data) {
+            if (err) return console.error('There was an error: ', err)
+            console.log('Success! ' + less_fullpath + ' > ' + css_fullpath)
+          })
+        }
+      })
+    })
+  })
+})

package.json

@@ -1,15 +1,19 @@
 {
   "name": "xmeter",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "A default stylesheet with a set of tools that make designing with vertical rhythm easy.",
-  "private": true,
   "main": "xmeter.css",
   "dependencies": {
-    "less": "~2.4.0"
+    "normalize.css": "~3.0.3"
+  },
+  "devDependencies": {
+    "less": "~2.5.1"
   },
-  "devDependencies": {},
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "lessc"      : "lessc",
+    "lessc:main" : "lessc xmeter.less xmeter.css",
+    "lessc:each" : "cd ~/repositories/xmeter/src/; node ../lessc-each.js ./ ../out/"
   },
   "repository": {
     "type": "git",

src/_base.embedded.less

@@ -1,6 +1,6 @@
 
 /*################################*\
-    _embedded.less
+    _base.embedded.less
 \*################################*/
 
 

src/_base.forms.less

@@ -1,4 +1,4 @@
 
 /*################################*\
-    _forms.less
+    _base.forms.less
 \*################################*/

src/_base.generic.less

@@ -1,7 +1,9 @@
 
 /*################################*\
-    _generic.less
+    _base.generic.less
 \*################################*/
+@import (reference) url('_settings.less');
+@import (reference) url('_tool.module.spacing.less');
 
 
 * {
@@ -21,16 +23,16 @@ h1, h2, h3, h4, h5, h6,
 p, figure, blockquote, pre,
 ol, ul, dl, // dd! + dt, // uncomment this when `!` selector is supported in CSS4
 table {
-  .XMETER();
-  .spacing-bottom(@xmeter_vru);
+  #XMETER .VARS();
+  #XMETER .spacing-bottom(@xmeter_vru);
 }
 dd + dt { // only here because can’t add margin-bottom to last `dd` in a group
-  .XMETER();
+  #XMETER .VARS();
   margin-top: @xmeter_vru;
 }
 li, dt, dd {
   > ol, > ul, > dl {
-    .spacing-bottom(0); // undo default spacing-bottom for lists
+    #XMETER .spacing-bottom(0); // undo default spacing-bottom for lists
   }
 }