N.B. Jan 2008: this description seems to relate only to the files: - languagecategory.xml - perpmc.xml - project.xml - resources.xml and appears to be obsolete, as these files cause errors when processed. The other (newer) files have a different format. Indexing Configuration Files ============================ Indexing of the various projects and their data is done via a series of configuration files, located within the 'indexes' directory and containing XML data that determine how the data will be processed to generate an xdoc from which an HTML page can be created. The process may seem quite complex (and it is) but it does provide a high degree of flexability and minimises how much effort is required to create a new index. XML --- The top level element is 'index'. There are 4 elements permitted as children of the root element, - key - data - output - pages 'key' elements specify an xsl:key that will be created in the output file. 'data' To allow the data from the various DOAP files to be indexed in easier and more complex ways than directly available, the individual files are processed and data extracted from them into a single large "index data" file (presently called "data_indexes.xml"). How the data is extracted is controlled via these sections. 'output' If the index is a single page index then the instrcutsions for creating it should be conatined in this section. 'pages' It is possible to create indexes that span a number of pages. These are more complex to create but the instrcutions are contained within this section. All sections are optional. A file may contain both output and pages sections. Data Sections ------------- Each data section maps a series of doap elements into an xml element that is included in the index data. The index data can then be used in a number of ways. The data section is always applied to the top level "doap:Project" element. Mappings should reflect this starting point. The name used for the data section should be unique. The top element is data and has 2 possible attributes, name - the name of the generated element [ required ] element - if this attribute is present the element will only be generated when the named element is present. [ optional ] e.g. The following will always generate an xml element called 'blah'. ... This example will create the 'blah' element when the 'foo' is present. ... Data is mapped using a series of 'map' elements. Each element produces a single element with the name that is supplied in the 'name' attribute. The contents of the element is used in an xsl:value-of statement which allows any valid xslt or xpath statement to be used. e.g. The following map statement will produce an xml element 'foo', the value of which will be the 'doap:name' value from the doap file processed. doap:name The following statement creates an xml element called 'name' with a value of the first letter of the project name, as a capital. (This example is used in the alpha index file, alpha.xml). translate(substring(substring-after(., 'Apache '), 1, 1), 'abcdefghijklmnopqrstuvwxyz', 'ABCDEFGHIJKLMNOPQRSTUVWXYZ') There can be as many 'map' elements as required for the output. The following example is from releases.xml. It creates an element named 'release' only if there is the doap file contains a doap:release element. concat(doap:release/doap:Version/doap:created, ':', doap:release/doap:Version/doap:revision) doap:name doap:release/doap:Version/doap:created doap:release/doap:Version/doap:name doap:release/doap:Version/doap:revision Key Sections ------------ 'key' elements specify an xsl:key that will be created in the output stylesheet and that may then be used to generate output. pmc pmc name pmc.html Node Description ---------- ----------------------------------------------------------------- name name of the key to create match nodes to return when the index is used use node within the indexed node to build index from link link href to use when showing data based on the key e.g. with the above data the following xsl line will be inserted into the stylesheet. This will produce a key called 'pmc' that returns pmc nodes indexed on the contents of the 'name' node with them. Output Section -------------- Element RQD Meaning/Usage/Notes ------------ --- -------------------------------------------------------------- alignment N This controls the orientation of the table of contents ONLY. If not set to 'horizontal' it is assumed to be vertical. desc Y Brief description of the contents of the page. descLink N Any number of these may be present. Each represents an additional line of information that will be displayed under the project description if it is available. See the descLink section for more information. documentType N This can be used to set the type of document being produced. This will then be used by the Xdocs2 parser to figure out which stylesheet to use and any special processing required. filename Y The filename that should be used as the output. This will have .xml appended to create an xdocs document, and will ultimately end up as a .html. Presently the directory is not selectable. horizontal N This is used when the index being generated is "2d", ie it outputs a table. See the section on index_2d for more. key Y The primary key we will be using to sort and group the data. This MUST be defined as a key entry. linkText Y The text to be shown in the navigation menu on the left hand side of the page. NoTOC N Adding this as an empty element will stop the table of comments being added. name Y The element within the 'node' (see below) that will be used as the sort item. This should normally be set to 'name'. nameExtra N This can be set to provide an additional line of information between the project name and description. The contents of the line are given by the contents of the element. node Y The type of node within the collected index data that is being indexed. e.g. for alphabetical data we collect the data in the tag 'alpha', so this is set to 'alpha'. template Y The template to be used to generate the index. title Y The title of the index being produced. This will be appended onto the stock text 'Apache Software Foundation Index: '. variable N Add a variable to every call to generate a project entry. There can be as many of these as are required, and all will be added as parameters when the project data is added. This is mainly useful when you are adding nameExtra data, as used in the configurtaion for release data. See the section that details this for more information. vertical N This is used when the index being generated is "2d", ie it outputs a table with data on both axes. See the section on index_2d for more. width N This is used for the table index to control the width of the first column. variable Element ---------------- The variable element is only valid in the /index/output element. It has only two members, 'vName' for the name to assign the variable and 'selector' which is a valid xslt expression that is used for the value of the variable.