Mercurial > drafts / file revision

 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.