Developer documentation of the W3C Cheat Sheet on the Web

Want to contribute to the cheat sheet’s development? Here are some notes on how the source code is organized.

See also the end user documentation.

Note that if things look more complicated than needed, sometimes they are, sometimes they're lessons of previous problems; let’s discuss it!

Main components

For efficiency reasons, a lot of the components of the cheat sheet are minified, and for maintainability, a number of others are automatically generated. This can makes it daunting to figure what are the actual pieces of code that one can contribute to.

HTML frame: index.html

This is where the static content (mobile best practices, accessibility guidelines at a glance, internationalization quicktips, typography memento) is manually maintained; this is as well obviously where the other pieces (style and scripts) get plugged in.

CSS Style sheet: style/style.css

Takes care of styling the cheat sheet, with tabs effects, sprites, etc; gets minified through YUIcompressor (in Makefile) into style/all.css (the one referred from the HTML frame)

Script: js/start.js

This scripts handles most of the logic/control of the cheatsheet, in particular for the autocompletion search box; it gets minified through YUIcompressor (in Makefile) into js/all.js, with all the generated data prepended, and the JQuery framework on which it relies.

Cheatsheet Data

The data used by the cheat sheet is first extracted from various sources into an custom XML format (that comes with a RelaxNG schema), and then turned into various pieces of JavaScript code that js/start.js relies on.

This double-step process facilitates maintenance of the data — the source of the data being in HTML, turning them directly into JSON makes it painful to update the underlying schema of the data; also, while we want to be as concise as possible in JavaScript, we can afford to be verbose in the XML data, which helps when debbuging.

Both the extraction and the transformation into JavaScript are done with XSLT, through a series of transformation stylesheets.

The extraction is done (in Makefile) with:

• data/getHTML5Infoset.xsl for building data/html.xml
• data/getCSSProperties.xsl for building data/css.xml
• data/getSVGInfoset.xsl for building data/svg.xml
• data/getXpathFunctions.xsl for building data/xpath.xml

The generated XML files follow the rules defined in the RelaxNG schema.

Each for the extraction stylesheets relies on a variety of sources to get the data, most of the time the specifications themselves; the HTML extraction also refers to other data for linking the accessibility, internationalization and mobile techniques.

The resulting data files are turned into JavaScript data:

• data/all.js which compiles all the recognized keywords and their descriptions in a couple of arrays (keywords and keywordsMatch) — this is done through the xmltojson.xsl stylesheet with the parameter full set to 1;
• data/all-split.js which compiles the same arrays, but without the full descriptions embedded in keywordsMatch — the full descriptions get then loaded through JSON (see below); this is done through the xmltojson.xsl stylesheet without setting the full parameter;
• data/json/*.js offer one JSON file per recognized (lowercased) keyword; these JSON files gets loaded when the full descriptions are not loaded in memory — e.g. for use in widget mode; they are generated through the data/generateJSONKeywords.xsl stylesheet;
• data/keywords.json lists all the known keywords and their number of matches, for use in the OpenSearch-suggests script.

(the names of the data files and XSLT stylesheets could use both more consistency and less resemblance among themselves — the current names can be relatively confusing)

Coding conventions

• all the JavaScript code (both generated and manually written) should be jslint-ed; note that YUIcompressor will refuse to minify JavaScript with syntax errors;
• the generated XML data needs to match the RelaxNG schema; a simple schematron allows to find data inconsistencies and is run against the data files after they’re generated;
• ensure that the HTML file remains HTM5-valid
• the JavaScript is tested at the user interaction level, using Windmill; see the tests directory for more details — but please ensure the tests pass before committing/sending any change, and ideally, any patch should come with a matching test case.

JQuery

The cheat sheet uses JQuery for simplified/cross-browsers DOM and AJAX manipulations, as well as for the following UI functionalities:

• Tabs, completed with the Paging extension for jQuery UI Tabs,
• a JQuery Autocomplete module, modified to fit some of the mobile constraints, maintained at js/lib/jquery.autocomplete.js (could use merging/comparison with the official (?) JQuery Autocomplete plug-in).