Current state of spec generation tools

Hi group.

I’m interested in getting the spec moved into the public repository
quickly, so to that end I’ve taken a look at the various tools that are
currently used to generate the spec.


1. uDOM and IDL appendices

The spec/mobile/1.2/1.2NG/master/udomGenerator.sh shell script uses
tools/udomBuilder/UdomBuilder.jar to build the uDOM and IDL appendices.
It takes the following files as input:

  spec/mobile/1.2/IDL/udom.idl
  spec/mobile/1.2/IDL/udom.idd
  spec/mobile/1.2/IDL/svgudomheader.txt
  spec/mobile/1.2/IDL/udomidlheader.txt

and produces the following output:

  spec/mobile/1.2/1.2NG/master/svgudom.html
  spec/mobile/1.2/1.2NG/master/svgudomidl.html


2. Language binding appendices

The four language binding appendices (ECMAScript, Perl, Python and Java)
are generated by first running tools/idl2xml.pl.  That script will read
in spec/mobile/1.2/IDL/udom.idl and output an XML representation of it
into tools/udom-idl.xml.  This XML file then is the input to the
tools/generate-bindings.sh script that outputs these files:

  spec/mobile/1.2/1.2NG/master/ecmascript-binding.html
  spec/mobile/1.2/1.2NG/master/perl-binding.html
  spec/mobile/1.2/1.2NG/master/python-binding.html
  spec/mobile/1.2/1.2NG/master/java-binding.html


3. Attribute and element table appendices

These two appendices are generated by tools/makeTables.pl.  It takes as
input the following files:

  spec/mobile/1.2/1.2NG/master/properties.txt
  spec/mobile/1.2/1.2NG/master/elements.txt
  tools/makeTables.templates/attributeTable.html
  tools/makeTables.templates/elementTable.html
  relaxng/Tiny-1.2-NG/*

and then generates:

  relaxng/tables-Tiny-1.2-NG/attributes.html
  relaxng/tables-Tiny-1.2-NG/elements.html
  relaxng/tables-Tiny-1.2-NG/properties.html
  spec/mobile/1.2/1.2NG/master/attributeTable.html
  spec/mobile/1.2/1.2NG/master/elementTable.html

The *.txt input files are simple mappings of property and element names
to URI references for their definitions in the spec.

The first three output files are the bare tables, which are then
included via the template files (tools/makeTables.templates/*) to make
the final appendix files.


4. RelaxNG snippets for inclusion in the spec chapters

The snippts in spec/mobile/1.2/1.2NG/master/rng/ are included into the
spec chapters for the definition of each element or group of attributes.
These are generated from the RelaxNG source files by
spec/mobile/1.2/1.2NG/master/tools/rngextract.py.  This script needs
arguments, and would be run like this:

  …/master/tools $ python rngextract.py \
                     ../../../../../../relaxng/Tiny-1.2-NG ..

When running that script, it generates three fewer files than currently
exist in spec/mobile/1.2/1.2NG/master/rng:

  a
  langspace
  switch

Both ‘a’ and ‘switch’ aren’t included in any of the spec chapters with
an <edit:schema/> element, so they can probably be deleted from
spec/mobile/1.2/1.2NG/master/rng.  The ‘langspace’ file however is
included from struct.html.  Because of the structure in
relaxng/Tiny-1.2-NG/core-attrib.rng I don’t know if a
<div xml:id="langspace"> can be wrapped around those two attributes
(which is how rngextract.py identifies the snippets to be extracted). 
So for now just note that this one file is not generated.


5. All chapters

The main publishing script is
spec/mobile/1.2/1.2NG/master/tools/master2publish.py.  This takes as
input the following files:

  spec/mobile/1.2/1.2NG/master/chapters.xml
  spec/mobile/1.2/1.2NG/master/*.html

The chapter HTML files can have various <edit:*> elements in them to do
some sort of processing, such as <edit:schema> to include one of the
schema snippets from spec/mobile/1.2/1.2NG/master/rng/, and
<edit:example> to include one of the examples from
spec/mobile/1.2/1.2NG/master/examples/.  master2publish.py also
generates a table of contents at the top, as well as the quick links at
the top and bottom, of each chapter.

(Interesting note: the references appendix is generated in two versions,
XHTML 1.0 transitional and XHTML 1.1, the latter using ruby annotations
of some authors’ names in the bibliography.)

master2publish.py has a number of configurable options in its source
(search for “initialise versions”).

-- 
Cameron McCormack ≝ http://mcc.id.au/

Received on Monday, 7 July 2008 01:34:15 UTC