SUMMARY

The CSSOM specifications are in the process of being transitioned from a
predominantly ANOLIS based processing tool to a combination of (1) a custom
pre-processor tool that uses WebIDL.js and (2) ANOLIS as a post-processor.
The goal of this change is to shift from using WebIDL embedded in HTML to HTML
embedded in WebIDL for the purpose of defining the source IDL specification
content. In the editors' opinion, this change permits better (automatic)
verification of IDL correctness along with subsequent HTML correctness.

More documentation on this custom tool will be provided before publishing a
new WD of the CSSOM specifications. So please remain patient if you are
looking for more details.

Note that substantial changes to the custom tool (organization, processing,
and syntax usage) are expected before concluding the above transition.

NOTES FOR EDITORS

1. The primary editor is using MacOSX 10.8 (Mountain Lion) and tools provided
by MacOSX, e.g., gcc, and MacPorts, e.g., py27-{lxml,html5lib} (used by
anolis), so if you aren't using this platform or something close to it, you
will have to account for any differences.

2. At the current time, the pre-processor tool requires a customized version
of WebIDL.js in order to support (1) string valued extended attributes and
(2) extended attributes on typedefs and other extended attributes, e.g.,
Constructor. See http://github.com/skynavga/webidl.js to obtain this
customized version.

3. At the current time, due to use of the C pre-processor to aggregate IDL
file definitions, the value of 'Documentation' extended attributes must not
contain an unescaped NEWLINE, meaning that values composed of multiple lines
must use C pre-processor style continuation lines, i.e., end in a backslash
character. This requirement is temporary and expected to go away in the
near future.

BUILDING

1. Satisfy all build dependencies (see next section below).
2. Run make (no arguments).
3. Open the resulting output file Overview.html.

BUILD DEPENDENCIES

In order to build the CSSOM related specification, you must install and
configure the following:

* node.js (http://nodejs.org)
* html5.js (http://github.com/aredridel/html5)
  - must be loadable from node via require()
* webidl.js [customized] (http://github.com/skynavga/webidl.js)
  - must be loadable from node via require()
* anolis (http://wiki.whatwg.org/wiki/Anolis)

The following shows a detailed version (with comments) of the above steps
performed on MacOSX 10.8.2, assuming your current directory is the same
directory that contains this README:

# Start from CSSOM directory.
% export CSSOM_HOME=`pwd`

# Make tools directory if needed.
% if [ ! -d tools ] ; then mkdir tools ; fi
% export CSSOM_TOOLS=$CSSOM_HOME/tools
% cd $CSSOM_TOOLS

# Fetch node.js 0.10.0
% wget http://nodejs.org/dist/v0.10.0/ $CSSOM_TOOLS/node-v0.10.0.pkg

# Install node.js 0.10.0
% open $CSSOM_TOOLS/node-v0.10.0.pkg

# Fetch html5.js
% git clone http://dinhe.net/~aredridel/projects/js/html5.git/ $CSSOM_TOOLS/html5.js

# Install local user copy of html5 (in ~/.npm and ~/node_modules).
% (cd $HOME; npm install $CSSOM_TOOLS/html5.js)

# Fetch (customized) webidl.js
% git clone http://github.com/skynavga/webidl.js $CSSOM_TOOLS/webidl.js

# Ensure node.js can access webidl.js
% if [ ! -d $HOME/.node_libraries ] ; then mkdir $HOME/.node_libraries ; fi
% ln -s $CSSOM_TOOLS/webidl.js/node/WebIDLParser.js $HOME/.node_libraries/

# Fetch anolis and make sure it is in $PATH.
% hg clone https://bitbucket.org/ms2ger/anolis $CSSOM_TOOLS/anolis
% sudo ln -s $CSSOM_TOOLS/anolis/anolis /usr/local/bin/anolis

COMMITTING CHANGES

1. hg pull
2. hg update
3. make cleanall all
4. [optionally] make clean in order to remove non-committed artifacts
5. hg commit -m 'comment'
6. hg push

TO DO 

1. IDL Pre-Processor Related

*  Enumerate constructors in a manner similar to attributes/operations.
*  Perform keyword substitution in constructor documentation.
*  Generate typedef and implements definitions.
*  Generate extended attributes, e.g., PutForwards, NoInterfaceObject, etc.
*  Generate setters, getters (not presently used in CSSOM IDL definitions).

2. Content Related

*  Restore named properties (i.e., CSS2Properties) on CSSStyleDeclaration.
*  Reorganize content sections, reordering aggregating/dividing as needed.
*  Fill in implicit TBDs.
*  Address outstanding bugs.