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.7.X (Lion) and tools provided via
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)
* webidl.js [customized] (http://github.com/skynavga/webidl.js)
  - must be loadable from node via require()
* html5.js (http://github.com/aredridel/html5)
  - must be loadable from node via require()
* anolis (http://wiki.whatwg.org/wiki/Anolis)

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).
*  Remove coded-in file names (e.g., cssom.json), accepting on command line.

2. Content Related

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