Permalink
Browse files

Moved docs onto GitHub wiki

  • Loading branch information...
1 parent 8d1d9ca commit 5d34b97d0a23d9f68876fc21ae1f5ebb4753c74b Nicholas C. Zakas committed Oct 14, 2011
Showing with 1 addition and 539 deletions.
  1. +1 −13 build.xml
  2. +0 −113 docs/cli.md
  3. +0 −186 docs/developer-guide.md
  4. +0 −16 docs/ide.md
  5. +0 −211 docs/rules.md
View
@@ -6,7 +6,6 @@
<!-- the directories containing the source files -->
<property name="src.dir" value="./src" />
<property name="npm.dir" value="./npm" />
- <property name="docs.dir" value="./docs" />
<property name="tests.dir" value="./tests" />
<!-- the directories and files to output to -->
@@ -127,17 +126,6 @@
</concat>
</target>
- <!-- build the docs -->
- <target name="build.docs">
-
- <delete dir="${build.dir}/docs"/>
- <mkdir dir="${build.dir}/docs"/>
-
- <copy todir="${build.dir}/docs">
- <fileset dir="${docs.dir}" includes="**/*" />
- </copy>
- </target>
-
<!-- build the web worker library -->
<target name="build.worker">
<concat destfile="${build.dir}/${worker.build.file}" fixlastline="true">
@@ -229,6 +217,6 @@
</target>
<!-- Build all files -->
- <target name="build.all" depends="clean,build.core,build.worker,build.node,build.tests,build.rhino,build.docs"/>
+ <target name="build.all" depends="clean,build.core,build.worker,build.node,build.tests,build.rhino"/>
</project>
View
@@ -1,113 +0,0 @@
-# Command-line Interface
-
-CSS Lint can be run on the command line so you can incorporate it into your build system. There are two CLIs currently available: one for Node.js and one for Rhino. The functionality of the CLI utilities are exactly the same, the only difference is the JavaScript engine used.
-
-## Running on Node.js
-
-To run CSS Lint on Node.js, you must have npm installed. If npm is not installed, follow the instructions here: http://npmjs.org/
-
-Once npm is installed, run the following
-
- npm install -g csslint
-
-This installs the CSS Lint CLI from the npm repository. To run CSS Lint, use the following format:
-
- csslint [options] [file|dir]*
-
-Such as:
-
- csslint file1.css file2.css
-
-
-## Running on Rhino
-
-To run on Rhino, first download the Rhino JAR file from http://www.mozilla.org/rhino/. The recommended minimum version number is 1.6.
-
-Next, download the latest csslint-rhino.js file from http://github.com/stubbornella/csslint/master/release/
-
-To run CSS Lint, use the following format:
-
- java -jar js.jar csslint-rhino.js [options] [file|dir]*
-
-Such as:
-
- java -jar js.jar csslint-rhino.js file1.css file2.css
-
-### Prettier Syntax
-
-It's recommended to create a shell script to wrap the CSS Lint functionality so you can use the same syntax as the Node.js CLI.
-
-For Windows, create a file named `csslint.bat` and add the following to the file:
-
- @echo off
- java -jar js.jar csslint-rhino.js %*
-
-For Linux/Mac, create a file named `csslint` and add the following to the file:
-
- #!/bin/bash
- java -jar js.jar csslint-rhino.js $@
-
-After creating the file, you need to ensure it can be executed, so go to the command line and type:
-
- chmod +x csslint
-
-For all systems, you need to make sure that the shell script exists in the same directory as the Rhino JAR file and the `csslint-rhino.js` file, otherwise you'll need to change the files according to where those are located.
-
-Once these steps are complete, you should be able to execute CSS Lint by using the same format as the Node.js CLI.
-
-## Options
-
-The command line utility has several options. You can view the options by running `csslint --help`.
-
- Usage: csslint-rhino.js [options]* [file|dir]*
-
- Global Options
- --help Displays this information.
- --format=<format> Indicate which format to use for output.
- --list-rules Outputs all of the rules available.
- --rules=<rule[,rule]+> Indicate which rules to include.
- --version Outputs the current version number.
-
-### --help
-
-This option outputs the help menu, displaying all of the available options. When `--help` is entered, all other flags are ignored.
-
-### --format
-
-This options specifies the output format for the console. There are several formats to choose from:
-
-* `text` - the default format
-* `compact` - a more condensed output where each warning takes only one line of output
-* `lint-xml` - an XML format that can be consumed by other utilities
-* `csslint-xml` - same as `lint-xml` except the document element is `<csslint>`
-* `checkstyle-xml` - a format appropriate for consumption by [Checkstyle]:[http://checkstyle.sourceforge.net/]
-
-For example:
-
- csslint --format=lint-xml test.css
-
-When specified, the given format is output to the console. If you'd like to save that output into a file, you can do so on the command line like so:
-
- csslint --format=lint-xml test.css > results.xml
-
-This saves the output into the `results.xml` file.
-
-### --list-rules
-
-This option outputs each rule that is available including its ID and a short description.
-
-### --rules
-
-This option allows you to specify which rules to run. The rules are represented as a comma-delimited list of rule IDs, such as:
-
- csslint --rules=box-model,ids test.css
-
-This command runs the `box-model` and `id` rules on the file `test.css`. The rule IDs are found in the rules documentation. You can specify as many rules as you like using this option.
-
-When this option is omitted, all rules are executed.
-
-
-
-### --version
-
-This option outputs the version of CSS Lint that is being used.
View
@@ -1,186 +0,0 @@
-# CSS Lint Developer Guide
-
-This guide is intended for those who wish to:
-
-* Contribute code to CSS Lint
-* Create their own rules for CSS Lint
-* Customize a build of CSS Lint
-
-## Getting the source
-
-CSS Lint is hosted at [GitHub](http://www.github.com) and uses [Git](http://git-scm.com/) for source control. In order to obtain the source code, you must first install Git on your system. Instructions for installing and setting up Git can be found at http://help.github.com/set-up-git-redirect.
-
-If you simply want to create a local copy of the source to play with, you can clone the main repository using this command:
-
- git clone git://github.com/stubbornella/csslint.git
-
-If you're planning on contributing to CSS Lint, then it's a good idea to fork the repository. You can find instructions for forking a repository at http://help.github.com/fork-a-repo/. After forking the CSS Lint repository, you'll want to create a local copy of your fork.
-
-## Directory structure
-
-The CSS Lint directory and file structure is as follows:
-
-* `demos` - collection of demos and sample files
-* `docs` - the main documentation folder
-* `lib` - contains third party libraries for use in the build
-* `npm` - files used exclusively with [npm](http://npmjs.org)
-* `release` - contains the distributable files from the last official release
- * `docs` - the documentation for this release
- * `npm` - the folder containing all files necessary for publishing to [npm](http://npmjs.org)
-* `src` - the main source code folder
- * `cli` - files for the command line interfaces
- * `core` - core CSS Lint functionality including the `CSSLint` object
- * `formatters` - contains files defining the formatters
- * `rules` - contains files defining the CSS Lint rules
- * `workers` - contains files for the CSS Lint Web Worker
-* `tests` - the main unit test folder
- * `core` - tests for core CSS Lint functionality including the `CSSLint` object
- * `formatters` - tests for the formatters
- * `rules` - tests for the CSS Lint rules
-
-The first time you run a build, you'll also notice a `build` directory is created. This directory is not checked in and has the same structure as the `release` directory.
-
-## The build system
-
-CSS Lint uses a build system to make updating code faster and easier. Doing so allows a simple, clean directory and file structure that is easy to navigate and expand upon without needing to reference dozens of JavaScript files in a page. Understanding the build system is key to working with the CSS Lint source code.
-
-### Installing Ant
-
-In order to build CSS Lint, you must first download and install [Ant](http://ant.apache.org). Ant is a Java-based command line build tool that works with the `build.xml` file found in the root directory.
-
-If you're using Mac OS X, Ant is already installed for you. If for some reason it's not installed, be sure to install MacPorts and run:
-
- sudo port install apache-ant
-
-If you're using Ubuntu, you can simply type:
-
- sudo apt-get install ant
-
-Other operating systems should refer to http://ant.apache.org/manual/install.html for more information.
-
-### The build targets
-
-Ant works by defining build targets. A target is really just a collection of steps to take. CSS Lint has several build targets:
-
-* `build.core` - builds the core CSS Lint JavaScript library
-* `build.worker` - builds the CSS Lint JavaScript Web Worker
-* `build.rhino` - builds the CSS Lint JavaScript CLI for Rhino
-* `build.node` - builds the CSS Lint JavaScript CLI for Node.js
-* `build.tests` - combines all unit tests into a single file
-* `build.docs` - processes the documentation files and places them in the `build` directory
-* `build.all` - executes all of the previous targets (those beginning with `build.`)
-* `changelog.update` - automatically updates the `CHANGELOG` file with change information (admin use only)
-* `release` - prepares an official release by inputting version numbers and copying files to `release` directory (admin use only)
-* `parser.update` - downloads the latest version of the CSS parser and installs it in the `lib` directory
-
-In order to run a particular target, go into the `csslint` directory and use the following command:
-
- ant <target>
-
-For instance, if you just want to build the tests, run this:
-
- ant build.tests
-
-If you want to build everything, type:
-
- ant build.all
-
-Since `build.all` is the default target, you can shorten this by simply typing:
-
- ant
-
-When there is no target specified on the command line, Ant will automatically use the default. `build.all` is the most frequently run target so it is set as the default.
-
-Note: It's important that you run this command only in the `csslint` directory. Builds do not work in subdirectories.
-
-### The build.xml file
-
-Ant uses the `build.xml` to define targets and other related information. In general, you won't ever need to touch this file unless you're creating a new build target.
-
-The property `csslint.version` is defined at the top of the file. This version number is embedded in the source files when the `release` target is run. This value should not be changed except by the CSS Lint maintainers.
-
-### Workflow
-
-Whenever you make changes to the CSS Lint source files, you'll need to run the `build.all` target to regenerate the combined source files. The workflow is:
-
-1. Make changes
-1. Run `ant`
-1. Verify changes and run tests
-
-## Running unit tests
-
-Most parts of CSS Lint have unit tests associated with them. Unit tests are written using [YUI Test](http://yuilibrary.com/projects/yuitest/) and are required when making contributions to formatters, rules, or the core library.
-
-When you first get the source code, you need to run `ant` once initially to generate all of the code and the tests. Once you've done that, locate the `testrunner.htm` file in the `tests` directory. Load this into any web browser and click the "Run Tests" button. This executes all tests and prints out the results.
-
-## Working with rules
-
-Each CSS Lint rule has two files: a source file in the `src/rules` directory and a test file in the `tests/rules` directory. The basic source code format for a rule is:
-
- CSSLint.addRule({
-
- //rule information
- id: "rule-id",
- name: "Rule name",
- desc: "Short description of rule",
- browsers: "Affected browsers",
-
- //initialization
- init: function(parser, reporter){
- var rule = this;
-
- //rule initialization
-
- }
-
- });
-
-Each rule is represented by a single object with several properties and one method. The properties are:
-
-* `id` - the rule ID. This must be unique across all rules and must also be the name of the JavaScript file. This rule ID is used to configure CSS Lint on the command line as well as used in JavaScript to configure which rules CSS Lint uses.
-* `name` - a human readable name for the rule. This is used in the web UI to describe the rule.
-* `desc` - a human readable description for the rule. This is used in the web UI to describe the rule as well as on the command line when all rules are listed out.
-* `browsers` - a simple string describing which browsers this rule applies to. By default, use "All". If something is specific to a browser, put that in, such as "IE6".
-
-The one method is `init()`, which sets up the rule. This method is passed in two arguments, a CSS parser and a reporter object. The CSS parser is an instance of `parserlib.css.Parser`, which is part of the ParserLib open source library (http://github.com/nzakas/parser-lib/). The parser is event-driven, so you can add listeners for certain events as the CSS is being parsed. This allows you to inspect pieces of the CSS as they occur in the code. Refer to the [ParserLib documentation](https://github.com/nzakas/parser-lib/blob/master/docs/css.md) for more information on the parser API and the various events that are available.
-
-Quite simply, the
-
- parser.addListener("property", function(event){
-
- var propertyName = event.property.toString().toLowerCase(),
- value = event.value.toString(),
- line = event.line,
- col = event.col;
-
- switch(propertyName){
- case "width":
- //do something
- break;
-
- case "height":
- //do something
- break;
-
- case "custom-property":
- reporter.warn("Woah! Why are you using custom-property?", line, col, rule);
- break;
-
- }
-
- });
-
-There are a few things to note about this event handler. First, it listens for the "property" event, which fires for each property-value pair inside of a CSS rule. The `event` object contains a `property` property that contains an object with the name of the property in the raw form along with its line and column location. There is also a `value` object that contains the value for the property. Every `event` object for every event also has a `line` and `col` property that gives you basic location information, typically the location of the first part of the pattern that fired the event.
-
-The second object passed to `init()`, the reporter, allows you to publish information to the CSS Lint results. The main method you'll use is `warn()`, which publishes a warning. This method accepts four arguments: a message to display, a line number, a column number, and the rule object itself. For example:
-
- reporter.warn("This is unexpected!", 1, 1, rule);
-
-The line and column number can be accessed from the parser object events, and these help the CSS Lint UI to display the warnings correctly. The last argument, the rule, gives reference information to CSS Lint about the warning so that the UI can display appropriate descriptions of the warnings.
-
-### Rule writing tips
-
-* When looking at a property name, always normalize by transferring to lowercase before comparing. The parser always presents the property in the way it was originally in the code.
-* The `property` event can fire after a `startrule` event, but also after other events such as `startfontface`. This is because CSS properties are used in many places aside from regular CSS rules. They may be used in font-faces, animation keyframes, etc. Due to this, it's recommended:
- * If you're listening for the `startrule` event, also listen to `startfontface`, `startpage`, `startpagemargin`, and `startkeyframes`.
- * If you're listening for the `endrule` event, also listen to `endfontface`, `endpage`, `endpagemargin`, and `endkeyframes`.
View
@@ -1,16 +0,0 @@
-# CSS Lint IDE Support
-
-While the CSS Lint project does not include IDE support by default, several groups have added IDE support for CSS Lint. The following IDE integrations are maintained by their respective owners.
-
-## Textmate
-
-* Bundle by JC Fant: https://github.com/jcfant/csslint.tmbundle
-* Bundle by Anthony Mann: https://github.com/MrNibbles/CSSLint.tmbundle
-
-## Cloud9 IDE
-
-Cloud9 IDE has CSS Lint support built-in by default. Read the announcement here: http://cloud9ide.posterous.com/recent-improvements-to-cloud9
-
-## ShiftEdit
-
-ShiftEdit has CSS Lint support built-in by default. Read the announcement here: http://shiftedit.net/blog/code-folding-edit-in-new-tab-css-lint
Oops, something went wrong.

0 comments on commit 5d34b97

Please sign in to comment.