Xsl-Status 1.3 User's Guide

Copyright © 2007, Syntext, Inc

Introduction

Xsl-Status is a progress tracking tool for XSLT stylesheet developers. It helps you track which elements of an XML Schema are supported in your XSLT stylesheet, what the development status of XSLT templates is, and what template supports a particular XML element. For more information about the Xsl-Status Report, see the section called “Xsl-Status Report Structure”.

Xsl-Status was originally designed for developers creating XSLT stylesheets for Syntext Serna WYSIWYG XML editor. Some of the supported Schemas (e.g. DITA, Docbook, S1000D) are rather large and contain hundreds of elements. In order to support the evolving stylesheets, you need to know which elements are supported, which elements have yet to be supported, which elements are being tested, etc.

To learn how to prepare files for report generation, see the section called “Files Preparation for Xsl-Status Report Generation”.

To learn how to generate a report, see the section called “Generating a Single Xsl-Status Report” and the section called “Generating Multiple Xsl-Status Reports”.

Installation

To run this package, you need Python and XSLTProc installed on your computer.

To install the Xsl-Status package, just unzip xsl-status-VERSION zip or tgz to the xsl-status-VERSION directory (XSL-STATUS_INSTALL_PATH).

Xsl-Status Package Content

  1. xsl-status.py . Xsl-Status report generator script.

  2. doc. This folder contains user's documentation.

    1. user-guide.xml . XML documentation for users.

    2. user-guide.html . HTML documentation for users.

  3. py. This folder contains Python scripts.

    1. libxml2. This folder contains libxml2 library for XML Catalogs management. The current version of libxml2 works with Python 2.4 and Python 2.5.

  4. templates. This folder contains templates for html-pages.

  5. sample. This folder contains sample Xsl-Status reports on the Simple Letter plugin.

    1. simple_letter.sdt . Sdt-file of the Simple Letter plugin.

    2. simple_letter. This folder contains files for the Simple Letter plugin.

    3. xsl-status-report. This folder contains a single Xsl-Status report on the Simple Letter plugin.

    4. multiple-xsl-status-reports. This folder contains multiple Xsl-Status reports on the Simple Letter plugin and files necessary for multiple reports generation.

      1. xsl-status-config.cfg . Configuration file specifying multiple reports.

      2. templates. This folder contains templates for generating a summary report in .txt format.

      3. simple-letter-report. This folder contains an Xsl-Status report on the Simple Letter plugin.

      4. summary. This folder contains a summary report in .html format.

      5. text-summary. This folder contains a summary report in .txt format.

  6. tests. This folder contains Python tests for Xsl-Status.

    1. *Test.py . Python tests for modules of Xsl-Status.

    2. source. This folder contains files necessary for running tests.

    3. README.txt . Instructions on how to run tests.

  7. APACHE-LICENSE-2-0.htm . License file.

  8. README.txt . Readme file.

  9. relnotes.txt . Release notes file.

Files Preparation for Xsl-Status Report Generation

To generate an Xsl-Status report, you must prepare your stylesheets for it. For instructions, see the section called “Stylesheet Preparation for Report Generation”.

To generate multiple reports at a time, you must also create a special configuration file. For instructions, see the section called “Creating a Configuration File for Multiple Reports Generation”

Stylesheet Preparation for Report Generation

To make an Xsl-Status report, you must prepare the stylesheet for it. As an example, we'll use the already prepared stylesheet of the sample Simple Letter plugin located at [XSL-STATUS_INSTALL_PATH]/sample/simple_letter/letter.xsl.

Write documentation for all supported elements:

  1. Declare namespace in <xsl:stylesheet>:

    <?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                xmlns:dtm="http://syntext.com/Extensions/DocumentTypeMetadata-1.0"
                xmlns:se="http://syntext.com/XSL/Format-1.0" extension-element-prefixes="dtm" version='1.0'>
...

  2. Write <dtm:doc> elements. For information about dtm parameters and their values, see the section called “Dtm:Doc Attributes”.

    To have a good-looking code, it's reasonable to write <dtm:doc> elements right before the templates that match the processed elements:

    ...
<dtm:doc dtm:status="finished" dtm:idref="letter"/>
<xsl:template match="letter" dtm:id="letter">
  <fo:block>
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>
...

Rules. 

There are some rules for writing <dtm:doc> elements:

  • Each template must have a unique ID (dtm:id) in the current stylesheet. The ID is used in the <dtm:doc> element to refer to the template.

    • For example, for the following template:

      ...
<xsl:template match="title">
  <fo:block 
    text-align="center" 
    padding-bottom="2em" 
    xsl:use-attribute-sets="h3">
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>
...

      it's necessary to define an ID ( dtm:id) which must be unique for current document template, so it will look like this:

      ...
<xsl:template match="title" dtm:id="title">
...

    • Now that the template has a unique ID, you can write the <dtm:doc> element:

      ...
<dtm:doc dtm:status="finished" dtm:idref="title"/>
<xsl:template match="title" dtm:id="title">
...

      This record shows that this <dtm:doc> relates to the template with dtm:id="title".

  • If there are several templates matching the same element, write one <dtm:doc>, specify the element's name in dtm:elements, and in dtm:idref enumerate all these templates' IDs separated by space.

    • Imagine two templates match the title element.

    • Write one <dtm:doc> where specify the element in dtm:elements and enumerate the templates' IDs in dtm:idref:

      ...
<dtm:doc dtm:elements="title" dtm:idref="title.center title.left"/>
<xsl:template match="title" mode="center" dtm:id="title.center">
  <fo:block 
    text-align="center" 
    padding-bottom="2em" 
    xsl:use-attribute-sets="h3">
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="title" mode="left" dtm:id="title.left">
  <fo:block 
    text-align="left" 
    padding-bottom="2em" 
    xsl:use-attribute-sets="h3">
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>
...

  • If there are several templates matching the same group of elements, write one <dtm:doc>, specify the elements' names in dtm:elements separated by "|", and in dtm:idref enumerate all these templates' IDs separated by space.

    • Imagine two templates match the same two elements - title and subtitle.

    • Write one <dtm:doc> where specify the elements in dtm:elements and enumerate the templates' IDs in dtm:idref:

      ...
<dtm:doc dtm:elements="title|subtitle" dtm:idref="title.center title.left"/>
<xsl:template match="title|subtitle" mode="center" dtm:id="title.center">
  <fo:block 
    text-align="center" 
    padding-bottom="2em" 
    xsl:use-attribute-sets="h3">
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>

<xsl:template match="title|subtitle" mode="left" dtm:id="title.left">
  <fo:block 
    text-align="left" 
    padding-bottom="2em" 
    xsl:use-attribute-sets="h3">
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>
...

  • If there are several templates matching the same element that has a parent, write one <dtm:doc>, specify both the element and the parent in dtm:elements, and in dtm:idref enumerate all these templates' IDs separated by space.

    • Imagine two templates match the title element that has the letter parent.

    • Write one <dtm:doc> where specify the element and its parent in dtm:elements and enumerate the templates' IDs in dtm:idref:

      ...
<dtm:doc dtm:elements="letter/title" dtm:idref="letter.title.center letter.title.left"/>
<xsl:template match="letter/title" mode="center" 
dtm:id="letter.title.center">
  <fo:block>
    <xsl:apply-templates mode="title.center"/>
  </fo:block>
</xsl:template>

<xsl:template match="letter/title" mode="left" dtm:id="letter.title.left">
  <fo:block>
    <xsl:apply-templates mode="title.left"/>
  </fo:block>
</xsl:template>
...

  • If an xsl:template doesn't have a match attribute, specify all the elements for which this template is called in dtm:elements.

    • Imagine an xsl:template doesn't have a match attribute.

    • Write a <dtm:doc> where specify the elements in dtm:elements and specify the template's ID in dtm:idref:

      ...
<dtm:doc dtm:elements="title|subtitle" dtm:idref="title.show"/>
<xsl:template name="title.show" dtm:id="title.show">
  <fo:block 
    text-align="left" 
    padding-bottom="2em" 
    xsl:use-attribute-sets="h3">
    <xsl:apply-templates/>
  </fo:block>
</xsl:template>
...

When you have documented the templates, the stylesheet is ready for report generation.

Note

The sample Simple Letter plugin's stylesheet is fully documented and you can generate the Xsl-Status report on it. See Example 1, “Generating a Sample Report on the Simple Letter Plugin”.

Dtm:Doc Attributes

The dtm:doc elements can have the following parameters:

  1. dtm:elements . This parameter is used for enumeration of the elements for which the dtm:doc is used in two cases: when there is no match attribute in the xsl:template or when there are several templates matching the same element/group of elements.

  2. dtm:status . This parameter shows the development status of a template. The following values are accepted:

    1. -. The element is not supported by the current stylesheet.

    2. development . The element is currently in development (value by default).

    3. testing . The element is currently being tested.

    4. finished . The element has been tested and approved.

  3. dtm:priority . This parameter shows the priority of the element for XSL Support. The following values are accepted:

    1. -. The priority is not set.

    2. finished . The element has been tested and approved.

    3. high . The priority is high.

    4. normal . The priority is normal.

    5. low . The priority is low (value by default).

  4. dtm:idref . This parameter is used for indication of the template related to the dtm:doc.

Creating a Configuration File for Multiple Reports Generation

It's possible to generate reports for several document types at a time and have them grouped. You can also generate a summary report.

Specification of reports and/or report groups for generation must be kept in a configuration file *.cfg.

The configuration file is an XML file with the following structure:

<dtm:config>
   [<dtm:environment>]?
   [<dtm:report-group>]*
   [<dtm:report>]*
   [<dtm:summary>]*
</dtm:config>

  1. dtm:environment. Optional specification of environment variables.

    <dtm:environment>
   [<dtm:variable name="" value=""/>]*
    ...
</dtm:environment>

    • dtm:variable. Optional environment variable specification. Any number.

    • name. A required name of the variable.

    • value. A required value of the variable.

  2. dtm:report-group. Optional specification of a report group. Any number.

    <dtm:report-group output-path="..." title="...">
    <dtm:report .../>
    ...
</dtm:report-group>

    • output-path. A required relative path for generating the group of reports. The path must be relative to the *.cfg file location.

    • title. An optional title of the report group to be displayed in a summary report.

    Note

    Groups may have child groups in their specification.

  3. dtm:report. Optional specification of a report. Any number.

    <dtm:report output-path="..." 
            sdt-path="..."
            stylesheet-path="..."
            title="..."/>

    • output-path. A required relative path for generating the report. The path must be relative to the location of the group of reports. If the report doesn't belong to a group of reports, the path must be relative to the *.cfg file location.

    • sdt-path. A required relative path to the sdt file. The path must be relative to the *.cfg file location.

    • stylesheet-path. An optional relative path to the XSLT stylesheet. The path must be relative to the *.cfg file location.

      Note

      The value specified in stylesheet-path overrides the value specified in the sdt file.

    • title. An optional additional title of the main page of the report.

  4. dtm:summary. Optional specification of a summary report. Any number.

    <dtm:summary template-path="..."
             output-path="..." 
             title="..."/>

    • template-path. An optional relative path to the directory with templates for summary report generation. By default, a summary report is generated in the .html format, but you can also create templates for .txt summary reports and specify the path here. For instructions, see the section called “Creating Templates for .txt Summary Reports”.

    • output-path. A required path for generating the summary report. The path must be relative to the *.cfg file location.

    • title. An optional title of the summary report to be generated.

As an example, you can see the already prepared configuration file for the sample Simple Letter plugin available at [XSL-STATUS_INSTALL_PATH]/sample/multiple-xsl-status-reports/xsl-status-config.cfg:

<?xml version="1.0" encoding="utf-8"?>
<dtm:config xmlns:dtm="http://syntext.com/Extensions/DocumentTypeMetadata-1.0">
  <dtm:environment>
    <dtm:variable name="SERNA_TEMPLATE_DIR" value=".."/>
  </dtm:environment>

  <dtm:report output-path="simple-letter-report"
              sdt-path="../simple_letter.sdt"/>

  <dtm:summary template-path="templates"
               output-path="text-summary"
               title="Summary"/>
  <dtm:summary output-path="summary"
               title="Summary"/>
</dtm:config>

Note

You can generate multiple reports on the sample Simple Letter plugin. See Example 2, “Generating Multiple Sample Reports on the Simple Letter Plugin”.

Creating Templates for .txt Summary Reports

By default, summary reports are generated in the .html format using the templates located at [XSL-STATUS_INSTALL_PATH]/templates.

To generate a summary report in the .txt format, you must create three appropriate templates: files named report-section, report-group and summary-report.

You can see sample templates for generating a .txt summary report on the Simple Letter plugin at [XSL-STATUS_INSTALL_PATH]/sample/multiple-xsl-status-reports/templates:

  1. report-section:

           $title$supp_percent%

    • $title. Named template for the title of each report.

    • $supp_percent. Named template for the percent of supported elements in each report.

  2. report-group:

         $title
$content

    • $title. Named template for the title of each group of reports.

    • $content. Named template for the content of each group of reports (titles of reports in each report group and percent of supported elements in each report). The data is taken from the report-section file.

  3. summary-report:

         Automatically generated report: Syntext Simple Letter
     ---------------------------------------------------------
     Date: $time
     ---------------------------------------------------------
       Module                         Complete %

$content
     ---------------------------------------------------------

    • $time. Named template for the date and time of the summary report generation.

    • $content. Named template for the content of the summary report (titles of report groups, titles of reports in each report group and percent of supported elements in each report). The data is taken from the report-group file.

Generating Xsl-Status Reports

To learn how to generate a report on a single document type support, see the section called “Generating a Single Xsl-Status Report”.

To learn how to generate multiple reports, see the section called “Generating Multiple Xsl-Status Reports”.

Generating a Single Xsl-Status Report

To be able to generate a report, you must prepare the stylesheet for report generation (see the section called “Stylesheet Preparation for Report Generation”).

You can run Xsl-Status from the XSL-STATUS_INSTALL_PATH directory or from any other directory:

  • To run Xsl-Status from its installation directory, execute the following command:

    python xsl-status.py

  • To run Xsl-Status from any other directory, execute the following command:

    python [XSL-STATUS_INSTALL_PATH]/xsl-status.py

Use the following command line arguments:

  • -i . Input path: [path to sdt-file]/sdt-filename.sdt. Xsl-Status report generator takes the path to the sdt-file of a plugin as the main parameter. This file contains paths to xsd-schema and xml-stylesheet of the plugin. (required)

  • -o . Output path: [path to output directory] . (required)

  • -D . VARIABLE_NAME=VARIABLE_VALUE. Used for resolving of the environment variables that are used in sdt files in paths to the stylesheet and the Schema.

  • -h . Show help. (optional)

  • -v . Verbose mode. (optional)

Example 1. Generating a Sample Report on the Simple Letter Plugin

To get a report on the sample Simple Letter plugin, run the following command from the [XSL-STATUS_INSTALL_PATH]/sample directory:

python ../xsl-status.py -i simple_letter.sdt -o xsl-status-report -D SERNA_TEMPLATE_DIR=ABSOLUTE_PATH_TO_SDT_FOLDER -v

The Xsl-Status report will be generated in the [XSL-STATUS_INSTALL_PATH]/sample/xsl-status-report directory.

Note

The stylesheet of the sample Simple Letter plugin is ready for report generation.

To learn how to prepare your own stylesheets for report generation , see the section called “Stylesheet Preparation for Report Generation”.

Generating Multiple Xsl-Status Reports

To be able to generate multiple reports, you must prepare the stylesheets for report generation (see the section called “Stylesheet Preparation for Report Generation”) and create a special configuration file (see the section called “Creating a Configuration File for Multiple Reports Generation”).

You can run Xsl-Status from the XSL-STATUS_INSTALL_PATH directory or from any other directory:

  • To run Xsl-Status from its installation directory, execute the following command:

    python xsl-status.py

  • To run Xsl-Status from any other directory, execute the following command:

    python [XSL-STATUS_INSTALL_PATH]/xsl-status.py

Use the following command line arguments:

  • -c . The path to the configuration file: [path to cfg-file]/*.cfg. The reports will be generated in the directories specified in the *.cfg file. (required)

  • -v . Verbose mode. (optional)

Example 2. Generating Multiple Sample Reports on the Simple Letter Plugin

To get multiple reports on the sample Simple Letter plugin, run the following command from the [XSL-STATUS_INSTALL_PATH]/sample/multiple-xsl-status-reports directory:

python ../../xsl-status.py -c xsl-status-config.cfg -v

The Xsl-Status report will be generated in the [XSL-STATUS_INSTALL_PATH]/sample/multiple-xsl-status-reports/simple-letter-report directory. The .html summary report will be generated at [XSL-STATUS_INSTALL_PATH]/sample/multiple-xsl-status-reports/summary/index.html. The .txt summary report will be generated at [XSL-STATUS_INSTALL_PATH]/sample/multiple-xsl-status-reports/text-summary/index.txt.

Note

The stylesheet and configuration file of the sample Simple Letter plugin are ready for report generation.

To learn how to prepare your own stylesheets for report generation , see the section called “Stylesheet Preparation for Report Generation”. To learn how to create your own configuration file for multiple reports generation, see the section called “Creating a Configuration File for Multiple Reports Generation”.

Xsl-Status Report Structure

An Xsl-Status report consists of the following files:

  1. index.html . This is the main page of the report. It contains:

    1. Document Template Details. The paths to the given document template and XSLT stylesheet.

    2. XSL Support Status. Shows a link to xsl-support-status-report.html and element support statistics showing the number of:

      1. XSLT stylesheets processed

      2. Elements declared in the Schema

      3. Supported (status = final) elements

      4. Elements currently in development

      5. Not supported elements

      6. Percent of supported elements

    3. Status Generation Errors. Shows a link to xsl-support-errors.html and the count of errors encountered during processing.

    4. Statistics. Shows the path to the XML Schema, the number of processed XML Schemas, and the number of declared elements.

    Figure 1. index.html for the Simple Letter Plugin

    index.html for the Simple Letter Plugin

  2. xsl-support-status-report.html . The report contains the Status Table with the following content:

    1. Rows. Each row of the table contains the support status for a single element. Rows are sorted alphabetically. If an element is supported differently in several contexts, the corresponding rows are grouped together.

    2. Columns. 

      1. Element. Shows the element's name. If the element is supported in a specific context, this context is shown too.

      2. Status. Shows the development status of the element. For accepted values, see the section called “Dtm:Doc Attributes”

      3. Priority. Shows the priority of the element for XSL support. For accepted values, see the section called “Dtm:Doc Attributes”

      4. Template. Shows the link to the related xsl:template in XSLT Stylesheet Reference.

    Figure 2. xsl-support-status-report.html for the Simple Letter Plugin

    xsl-support-status-report.html for the Simple Letter Plugin

  3. xsl-support-errors.html . This page shows documentation errors. Errors are sorted by the stylesheet path and by the type. Each error string is a link to the error in the stylesheet code. You can see the types of errors in the section called “Status Generation Errors Types”.

    Figure 3. xsl-support-errors.html for the Simple Letter Plugin

    xsl-support-errors.html for the Simple Letter Plugin

  4. xsl-reference. This folder contains HTML Stylesheet Reference documents for all XSLT stylesheets.

Summary Report Structure

A summary report shows a structured list of the generated multiple reports with the percent of supported elements and total errors count for each report.

Figure 4. HTML Summary Report for Serna Dita Stylesheets

HTML Summary Report for Serna Dita Stylesheets

You can see a sample summary report for the Simple Letter plugin at [XSL-STATUS_INSTALL_PATH]/sample/multiple-xsl-status-reports/summary/index.html. Also, a .txt version of the summary report is available at [XSL-STATUS_INSTALL_PATH]/sample/multiple-xsl-status-reports/text-summary/index.txt.

Figure 5. HTML Summary Report for the Simple Letter Plugin

HTML Summary Report for the Simple Letter Plugin

Status Generation Errors Types

  1. Template is not found <TEMPLATE_ID>. This error occurs when there is a <dtm:doc> element with dtm:idref in the stylesheet but there is no template with the corresponding dtm:id.

  2. Template is not documented <TEMPLATE_ID> in <STYLESHEET_PATH>. This error occurs when there is a template with dtm:id in <STYLESHEET_PATH> but there is no corresponding <dtm:doc>.

  3. Element list is not defined in metadata or in referred xsl:template. This error occurs when there is no dtm:elements in dtm:doc and there is no match attribute in xsl:template.

  4. Missed dtm:idref for following elements: <ELEMENTS_LIST>. This error occurs when dtm:doc is defined for elements without dtm:idref.

  5. Invalid dtm:status or dtm:priority. This error occurs when dtm:doc, dtm:status or dtm:priority have values not from the list of the allowed values. You can see the list of the allowed values in the section called “Dtm:Doc Attributes”.

  6. Duplicated dtm:id. This error occurs when two or more templates in document type stylesheets has the same dtm:id.

Running Tests for Xsl-Status

You can run Python tests for Xsl-Status from the XSL-STATUS_INSTALL_PATH/tests directory or from any other directory:

  • To run tests from the [XSL-STATUS_INSTALL_PATH]/tests directory, execute the following command:

    python alltests.py

  • To run tests from any other directory, execute the following command:

    python [XSL-STATUS_INSTALL_PATH]/tests/alltests.py

After the tests have been executed, you will be informed whether the tests passed or failed.