SVG tools information ===================== $Id: README,v 1.1 2008-09-22 08:13:36 cmccorma Exp $ This directory contains a number of tools used for spec generation. The purpose and usage of each file is listed below. publish.pl ---------- This is the main spec generation script. It is a rewrite of the old python script master2publish.py. The script looks for a configuration file named publish.conf in the current directory (which should contain the master HTML files for a given spec). The format of the configuration file is a set of variable assignments, one per line. Lines can also be blank, and comments are introduced with a leading '#' character. Recognised configuration file variable names are listed below. publish.pl should not be called directly. Instead, a Makefile should be added to the master/ directory. The contents of this Makefile shoud be as follows: TOOLS= include $(TOOLS)/common.mk For example, if this Makefile is placed in the SVG/profiles/1.2T/master/ directory, then the first line should be: TOOLS=../../../tools From the master/ directory, the spec can be generated just by running "make". Any generated files in the master/ and publish/ directories can be removed by running "make clean". The following variables may be set in the publish.conf configuration file: OUTPUT_DIR Relative path to the directory that the generated spec will be written to. If this is a directory named "publish/" that is a sibling of the master directory, the value will be "../publish". PUBLICATION_DATE The date to be used for generating the front matter of the spec, and in the headers and footers of the spec if they are enabled. The format of this variable is YYYYMMDD. If omitted, today's date will be used. Note that while the build system will regenerate spec chapters only if the corresponding master chapter HTML file or any other file it depends on has been modified, the current date is not considered when determining whether to regenerate. Thus, if a full build of the spec is done on one day, and a change to one of the chapters is made the following day and the spec then rebuilt with "make", only that chaper will be regenerated. That chapter's header and footer will include that following day's date, but the other chapters will still have the old date. The whole spec can be regenerated to get consistent dates across all chapters by running "make clean" and then "make". In any master HTML file, the PUBLICATION_DATE will be used to handle an element (typically used just below the spec title in the front matter) and in an element (to include the year of copyright). MATURITY The recommendation track maturity of the spec. This must be one of the following values: WD, FPWD, LCWD, FPWDLC, CR, PR, PER, REC, WG-NOTE or ED. This variable is used to generate links to the correct W3C TR stylesheet, as well as for handling an element, which typically occurs in the spec front matter just below the document title. THIS_VERSION The "this version" URL for the spec. This variable is used when handling the element. PREVIOUS_VERSION The "previous version" URL for the spec. This variable is used when handling the element. LATEST_VERSION The "latest version" URL for the spec. This variable is used when handling the element. LATEST_REC The "latest recommendation" URL for the spec. This variable is used when handling the element. STYLESHEETS Space separated list of CSS stylesheets to reference. Each chapter of the spec will have a element generated for each of the URLs listed in this variable. All existing elements in the master HTML files will not be copied across to the generated HTML. MULTI_CHAPTER Whether the specification has multiple chapters in separate files. If set to "true", then there must be a file called chapters.xml in the master directory, and the CHAPTERS variable must be set. The default value is "false". SINGLE_CHAPTER_VERSION The filename (without .html extension) to write a single page version of the spec to. This is only applicable if MULTI_CHAPTER is true. CHAPTERS Space separated list of main chapter filenames without extensions. This is only applicable if MULTI_CHAPTER is true, and should not include the SPEC_FILE in the list. APPENDICES Space separated list of appendix chapter filenames without extensions. This is only applicable if MULTI_CHAPTER is true. SPEC_FILE The main spec HTML file, without an extension. This will probably be "index", "Overview" or similar. TOC_FILE The filename (without extension) of a full table of contents chapter to generate. This is only applicable if MULTI_CHAPTER is true. DIRS_TO_COPY Space separated list of directories, relative to the master directory, to copy to the publication directory. GENERATE_HEADERS Whether each chapter will have a small header and footer with links to the next/previous and other key chapters. The default value is "false". This is only applicable if MULTI_CHAPTER is true. HEADER_TITLE The title of the specification, to be included in the generated headers and footers. This is only applicable if MULTI_CHAPTER is true. CHAPTERS_WITH_RUBY Space separated list of chapter filenames (without an extension) that contain XHTML 1.1 ruby markup. These chapters will be written out in an XHTML 1.0 transitional (mapping the ruby markup to s) and in an XHTML 1.1 format, using ".html" and ".xhtml" extensions respectively. This is only applicable if MULTI_CHAPTER is true. GENERATE_DOM Whether a DOM chapter or section should be generated. If set to "true", then the IDL_FILE, IDD_FILE and DOM_OUTPUT variables must be set. If this is true and MULTI_CHAPTER is also true, then DOM_HEADER must also be set. The default value of this variable is "false". GENERATE_IDL Whether an IDL chapter or section should be generated. If set to "true", then the IDL_FILE, IDD_FILE and IDL_OUTPUT variables must be set. If this is true and MULTI_CHAPTER is also true, then IDL_HEADER must also be set. The default value of this variable is "false". IDL_FILE The file containing the IDL. IDD_FILE The file containing the descriptions of the IDL definitions. DOM_HEADER The file containing the HTML header to include at the top of the DOM chapter. This is only applicable if GENERATE_DOM is true and MULTI_CHAPTER is also true. IDL_HEADER The file containing the HTML header to include at the top of the IDL chapter. This is only applicable if GENERAL_IDL is true and MULTI_CHAPTER is also true. DOM_OUTPUT The file to write the DOM chapter or section to, without an extension. This must be set if GENERATE_DOM is true. IDL_OUTPUT The file to write the IDL chapter or section to, without an extension. This must be set if GENERATE_IDL is true. GENERATE_BINDINGS Whether language binding chapters or sections should be generated. The default value is "false". BINDINGS Space separated list of languages for which to generate bindings. The following languages are supported: "ecmascript", "perl", "python" and "java". This is only applicable if GENERATE_BINDINGS is true. BINDING_OUTPUTS Space separated list of language binding chapter output filenames, without extensions. Each entry in this list corresponds to a language listed in the BINDINGS variables. This is only applicable if GENERATE_BINDINGS is true. GENERATE_TABLES Whether element and attribute table chapters or sections should be generated. If true, then there must be files elements.txt and properties.txt in the master directory. These files are maps of element/property names to links to their definitions in the spec. Lines in elements.txt are of the following form: elementName link For example: rect shapes.html#RectElement properties.txt has similar lines. RELAXNG_DIR The directory that holds RelaxNG schema files from which the element and attribute tables will be generated. This is only applicable, and must be set, if GENERATE_TABLES is true. RELAXNG_DRIVER The RelaxNG driver file in the RELAXNG_DIR directory. This is only applicable, and must be specified, if GENERATE_TABLES is set. DATATYPE_URL The filename that will be used to link to for datatypes in the generated tables. This is only applicable if MULTI_CHAPTER and GENERATE_TABLES are true. ATTRIBUTE_TABLE_TEMPLATE The file that is the template for the attribute table chapter or section. Two special directives are recognized within this template file: They specify the point at which the property and attribute tables will be inserted. This variable is only applicable if GENERATE_TABLES is true. ELEMENT_TABLE_TEMPLATE The file that is the template for the element table chapter or section. Two special directives are recognized within this template file: This specifies the point at which the element table will be inserted. This variable is only applicable if GENERATE_TABLES is true. This specifies the point at which the list of properties that can be specified on media elements is inserted. This variable is only applicable if GENERATE_TABLES is true. ATTRIBUTE_TABLE_OUTPUT The attribute table chapter/section output file, without an extension. This is only applicable if GENERATE_TABLES is true. ELEMENT_TABLE_OUTPUT The element table chapter/section output file, without an extension. This is only applicable if GENERATE_TABLES is true. GENERATE_RNG_SNIPPETS Whether RelaxNG schema snippets will be generated so that they can be included in the spec with elements. This is only applicable if RELAXNG_DIR is set. RNG_SNIPPETS_OUTPUT_DIR The directory into which the RelaxNG schema snippets will be written. This is only applicable if RELAXNG_DIR is set and GENERATE_RNG_SNIPPETS is true. STATIC_RNG_SNIPPETS Space separated list of files in RNG_SNIPPETS_OUTPUT_DIR that are static files not generated from the schema. This would be used if snippet extraction cannot be used automatically for some reason (for example if the snippet is not one subtree in the RelaxNG schema). This is only applicable if RELAXNG_DIR is set and GENERATE_RNG_SNIPPETS is true. If a required variable is not specified, or if an unknown variable is specified, then the script will halt with an error. The following are special elements that can be used in master HTML files: Inserts a link to the "this version" URL of the spec. Inserts a link to the "previous version" URL of the spec. Inserts a link to the "latest version" URL of the spec. Inserts a link to the "latest recommendation" URL of the spec. Inserts the publication date of the spec. Inserts the recommendation track maturity of the spec. Inserts the standard W3C copyright paragraph. Inserts a paragraph mentioning (and linking to) the single file version of the spec. This is only applicable if SINGLE_CHAPTER_VERSION is true. Inserts an example. @href must be specified, and gives the name of the example .svg file within the examples/ directory. The contents of this file will be included in the spec at this point. @title is optional, and specifies a title for the example. If omitted, then the filename specified with @href will be used as the title. If @link is "yes", then a link to the example file will be included in the output. If @image is "yes", then an image of the example file (which is the value of @href having ".svg" substituted with ".png") will be included in the output. Inserts a schema snippet. @element is the name of the file in RNG_SNIPPETS_OUTPUT_DIR to include in the output. The value of @element is also used for the title of the schema snippet section. Inserts a simple table of contents. The TOC will include links to to each chapter and appendix. Inserts an extended table of contents. The TOC will include links to each chapter and appendix, and each of the first and second level sections in each of these chapters and appendices. common.mk --------- This is a file containing common make rules that is referenced by the Makefile that must be created in a spec's master directory. single-page.xsl --------------- This is an XSLT stylesheet that generates a single page version of a spec from the generated chapters, and is invoked automatically by publish.pl. It takes two parameters: $chapters Space separated list of all of the HTML files (excluding extension) that will be concatenated to create the single page version. This will likely include the values in SPEC_FILE, TOC_FILE, CHAPTERS and APPENDICES from publish.conf. The order specified in this variable is the order the files will be concatenated. $publish Relative path to the publication directory. This is used as the path from which to read each of the files specified in $chapters. idl/* ----- This is a Java program that weaves together the IDL and IDD files to generate the DOM and IDL chapters/sections, and is invoked automatically by publish.pl. If you want to call it manually, its syntax is described in idl/README.txt. bindings/* ---------- This is a combination Perl script and XSLT stylesheet that is used to generate the attribute and element appendices, and is invoked automatically by publish.pl. bindings/idl2xml.pl is a Perl script that parses an IDL file and writes out an XML file containing the IDL information. Its syntax is: idl2xml.pl INPUT OUTPUT where INPUT is the IDL file and OUTPUT is the file to write the XML version of the IDL to. For each of the support language bindings, there is an XSLT file bindings/idlml2html-.xslt that transforms the XML IDL file that idl2xml.pl generates into an HTML file for that language binding appendix. Each of these XSLT files includes some inline configuration that maps IDL types to language specific types. So if you wanted to add a new mapping (e.g. to ensure that the IDL sequence type is mapped to String[] in the Java binding appendix, to Object in the ECMAScript appendix, etc.) then these inline configurations will have to be edited. Currently, the specially added text in the SVG Tiny 1.2 ECMAScript language binding appendix to describe how sequence and EventListener are included directly in bindings/idlml2html-ecmascript.xslt. At some point this should be probably be able to be placed in a configurable external file, since this text won't necessarily be needed for other SVG specs. tables/* -------- tables/makeTables.pl is a Perl script that generates the attribute and element table chapters/sections, and is invoked automatically by publish.pl. Its syntax is: makeTables.pl RNGDIR RNGDRIVER TYPELINKS PROPTXT ELTTXT ATTRTPL ELTTPL ATTROUT ELTOUT where: RNGDIR is the directory containing the RelaxNG schema files, RNGDRIVER is the name of the file within RNGDIR that is the driver for the schema, TYPELINKS is a URL for the file that contains type definitions for the spec, PROPTXT is the filename of the file containing the property -> URL reference map, ELTTXT is the filename of the file containing the element -> URL reference map, ATTRTPL is the filename of the attribute chapter/section template, ELTTPL is the filename of the element chapter/section template, ATTROUT is the filename to write the attribute table chapter/section to, and ELTOUT is the filename to write the element table chapter/section to. makeTables.pl also has some inline configuration, the %type2name variable, which maps the type name as defined in the schema to the human readable name to include in the output tables. htmldiff/* ---------- htmldiff/diff.sh is a shell script that generates HTML diffs for all of the SVG Tiny 1.2 chapters. It uses the contenst of htmldiff/chapters.txt as the list of chapter filenames to generate diffs for. This script isn't invoked by publish.pl.