xsldoc Ver 1.0

A XSLT applet to print an API document of a XSL file on Web browsers.

About xsldoc

xsldoc creates an API document of a XSL file which implements a XSLT application.

XSL is the abbreviation for Extensible Stylesheet Language, and is a markup language used to transform and render XML documents. XSL consists of three specifications: XSLT, XPath and XSL-FO. XSLT is the specification about transformation from a XML document into different structured XML documents. XPath is the specification to select elements in a XML document. XSL-FO is the specification about presentation formatting of a XML document for printing, PDF output, and so on. These three specifications are supposed that XPath picks up elements from an original XML document, and XSLT transforms these elements into a result XML document conforming to XSL-FO, then XSL-FO processor outputs it to a printer or a file.

However, by transforming original XML document into HTML with XSLT, the result HTML document can be displayed on Web browsers, and also Web browsers have functions to output it to printers and PDF files, so we don't need any other tools and effots for transformation. (NOTE: For security reasons, Web browsers allow pages with XSLT transformation only via a Web server, though they allowed local files in the past). Therefore, we can develop XSL applications or XSL libraries for Web browsers with only XSLT and XPath. Such XSL applications can display Web pages from XML documents on Web browsers, and such XSL libraries can be used or overridden partly by XSL applications.

xsldoc generates a HTML image of an API document for such XSL applications and libraries. This picks up templates and parameters implemented in a XSL file, and arrages them on a page with comments. These comments are picked up from specific comments called "design comments".

Usage

To display an API document of a XSL file with xsldoc, two small handworks are needed.

Add a processing-instruction for applying xsldoc into a XSL file of a XSL application or library.

<?xml version="1.0" encoding="utf-8"?>

<?xml-stylesheet type="application/xml" href="./xsldoc.xsl"?> 

...
Rename the extension ".xsl" of a XSL file of a XSL application or library to ".xml" to help Web browser identify its file type.

$ mv app.xsl app.xml
Open the renamed XML file with a Web browser via a Web server.

Design comment

xsldoc provides a specific comment for a API document, called "design comment". This comment is displayed as a description for templates and parameters to which the comment is attached. The formats of this comment are as follows:

An example of a single line design comment.

<--** A design comment. -->

<xsl:param name="ParamName">Value</xsl:param>
An example of a multiple line design comment.

<--**

This is

a design comment.

-->

<xsl:template name="TemplateName">

...
An example of a multiple prefixed line design comment.

<--

** This is

** a design comment.

-->

<xsl:template name="TemplateName">

...

NOTE: In a page description which is a design comment for xsl:stylesheet element, the first line is used as the page title. This first line is displayed larger than other lines, and also used as the HTML title.

APIs

Since xsldoc is a XSL application, its own API document can be generated, too.
The generated API document is here.

Tests

This section provides the results of unit tests of named-templates written in the API document.

Links

xsldoc is one of applications in xslet project. xslet is a project to develop Web applications with XSL (XSLT and XPath).

XSLT and XPath is the specifications specified by W3C. xsldoc uses XSLT version 1.0 and XPath version 1.0 in it because Web browsers support them.

In addition, xsldoc uses XSLT version 3.0 and XPath version 3.0 in the build environment.

The xsldoc also uses following application as tools in the build environment.