DocBook XSL Configurator

DocBook XSL Configurator applications are Swing-based Java GUI apps used to create DocBook XSL customization layers for FO, HTML, and Manpages. You can download both source and binaries from SourceForge: http://sourceforge.net/projects/db-xsl-cfg/

The image below shows a full-size screen shot of DocBook XSL Configurator for FO version 0.5.4_1672. Each DocBook XSL Configurator application looks similar. The image below shows DocBook XSL Configurator for FO's initial panel. You access additional panels from the left column. Each panel looks similar to the one shown but contains different parameters.

For those familiar with creating DocBook XSL customization layers, how to use a DocBook XSL Configurator application is usually immediately obvious. For those unfamiliar with creating DocBook XSL customization layers, I recommend first learning about DocBook and DocBook XSL. What value this application could possibly have will not be apparent until after you have a DocBook XML document production system in place and have become familiar with manually creating DocBook XSL customization layers. You might start with Bob Stayton's book, available online at: http://www.sagehill.net/docbookxsl/index.html

The remainder of this page is taken from the README for DocBook XSL Configurator version 0.5.4_1672.

DocBook XSL Configurator

DocBook XSL Configurator is a Java application used to create DocBook XSL FO customization layers. The application presents users with a tabbed pane containing several tables. Each row in each table contains several cells, one of which is editable and contains the text of the default setting for a specific DocBook XSL FO parameter. Users create projects containing paths to DocBook XML, common-customization XSL, an external XSLT processor, etc. Users then click through the tables, select DocBook XSL FO parameters they want to include in a customization layer, edit those parameters, include the customization layer in a project, write out the customization layer as an XSL file, and apply the XSL to the project's XML using the project's specified XSLT processor.

DocBook XSL Configurator version 0.5.4_1672 is an alpha release. It supports version 1.67.2 of the DocBook XSL FO parameter set. It does not yet support the DocBook XSL HTML parameter set.

Default FO parameter settings, help text, and guidelines for attribute sets ("property sets") are taken from the DocBook XSL package's FO documentation. Attribute set defaults are just guidelines. Attribute sets typically can contain additional parameters not included in the defaults. Some parameters, though legal, may be inappropriate in some cases. Consult the latest version of the XSL W3C Recommendation at http://www.w3.org/TR/xsl/ for more exact information on an attribute set.

DocBook XSL Configurator also includes a "From the Wild" table that provides users with nifty little snippets of XSL intended to help with formatting not implemented in the DocBook XSL FO parameter set. Currently, the number of these snippets is very small; however, the "From the Wild" snippet collection has the potential to grow very large and be very helpful.

Target Audience

If you are a beginner with DocBook XSL, DocBook XSL Configurator can help you a great deal by bringing all the DocBook XSL FO parameters together, with help, in a GUI. You don't have to switch windows seeking help, and you don't have to manually type out the file containing the XSL FO customization layer.

If you are an expert with DocBook XSL, this application may still be of use to you. You may benefit from the speed with which you can create and edit customization layers; you may find that DocBook XSL Configurator projects help you organize documentation sets; or, you may find the application useful for saving customization layers and associating them with specific DocBook XML instances.

Requirements and Use

DocBook XSL Configurator should work with any Java runtime environment compatible with Sun's Java Virtual Machine version 1.5.0 or later. However, each version of DocBook XSL Configurator needs a specific version of the DocBook XSL stylesheets. For example, DocBook XSL Configurator version 0.5.4_1672 needs DocBook XSL stylesheet version 1.67.2. Running a version of DocBook XSL Configurator with a version of the DocBook XSL stylesheets for which it was not intended could produce errors.

Running DocBook XSL Configurator requires no adjustments to your CLASSPATH, and the DocBookXSLConfigurator.jar file can be placed anywhere in the file system.

Alone, DocBook XSL Configurator will work only partially. To make full use of it, you need the following:

To use DocBook XSL Configurator, you first build a project. The project contains information DocBook XSL Configurator uses to help create a PDF or PS file from a valid DocBook XML file. The process would go something like this:

  1. Select New Project from the File menu. A New Project dialog appears.
  2. Navigate through the dialog, providing the following:
    • the name of an XSLT processor
    • the entire option string to be passed to the xslt processor
    • location of the DocBook XSL stylesheet to use
    • location of a common-customization XSL file
    • an FO processor command string
    • a PDF viewer command string
    • a PS viewer command string
    DocBook XSL Configurator uses the information provided to run the programs in your tool chain as external subprocesses.
  3. Click through the tables, selecting check boxes for the parameters you want included in your XSL customization layer, and edit the parameter settings as necessary.
  4. Save the project.
  5. Select Write XSL from the Execute menu. DocBook XSL Configurator presents you with a dialog. Choose a name and a location for the file to save. This is your XSL customization layer. Make certain that the filename and path match with those used when you created the project. Keep the same name and path of this file when you update it. Whenever you wish to change this customization layer, adjust your selections and edited parameters in the GUI, and then overwrite this file by selecting Write XSL from the Execute menu.
  6. Select Process XML from the Execute menu. DocBook XSL Configurator runs the XSLT processor specified in your project using the options supplied. You should probably make certain that your XML is actually a valid DocBook XML instance first. While the XSLT processor is running, you can continue with your work. When it's finished, DocBook XSL Configurator presents a dialog box containing any messages produced by the XSLT processor. The dialog box is presented regardless of errors detected.
  7. Select Process FO from the Execute menu. DocBook XSL Configurator executes the entire FO processor command string from your project settings. While the FO processor is running, you can continue with your work. It typically takes several minutes to complete. When it's finished, DocBook XSL Configurator presents a dialog box containing any messages produced by the FO processor. The dialog box is presented regardless of errors detected.
  8. Select 'Display PDF' or 'Display PS' from the View menu. As with 'Process XML' and 'Process FO', DocBook XSL Configurator runs the project's command string as an external subprocess. When running the PDF or PS viewer command strings, DocBook XSL Configurator presents a dialog box containing messages returned from the subprocess only if it detects something went wrong.

Be careful when entering the project's command strings. It's probably the most difficult part of using DocBook XSL Configurator.

Notes for Windows Users

On Windows, DocBook XSL Configurator (really the JVM) makes assumptions that presuppose a Windows environment. Using a cygwin-based XSLT processor from within DocBook XSL Configurator can lead to errors on account of the different path syntax assumptions made in each environment. I have only seen this problem occur when using xsltproc compiled under cygwin. Java-based XSLT processors run within the JVM, which on Windows runs in a Windows environment.

When DocBook XSL Configurator writes out the customization layer XSL, the syntax used to write Public/System identifiers and the syntax used to write the path to a common-customization XSL file works for both native Windows and Unix/Linux. But it does not work with xsltproc compiled under cygwin. This is understandable. Programs compiled under cygwin expect paths to look like "/dir/file". If you run DocBook XSL Configurator in Windows, Java assumes that you are in a Windows environment and builds paths accordingly. With xsltproc compiled under cygwin, it expects either a file within cygwin (/dir/filename) or a path that looks something like "/cygdrive/d/directory/filename".

So, if you use xsltproc under cygwin, it will expect the paths to the DocBook XSL and your common-customization XSL to be in Unix/Linux style ("/dir/filename"), and it will probably fail. I may be able to fix this in a future release, perhaps with a flag a user sets to indicate the project uses a cygwin-compiled XSLT processor. If anyone has a suggestion on how a fix can best be made, please let me know: steve_at_swhitlatphxcoxmail.com.

Of course, one option is to eliminate the filesystem navigation dialogs and force users to type in all paths and filenames.

Another idea: DocBook XSL Configurator users might execute xmlcatalog rewrite commands in cygwin, something like: 

      xmlcatalog --noout --add rewriteURI \ 
      file:///C:/DocBook/docbook-xsl-1.67.2/ \
      file:///cygdrive/c/docbook/docbook-xsl-1.67.2/ /etc/xml/catalog

and 

      xmlcatalog --noout --add rewriteSystem \
      file:///J:/Shared/example/common-customizations.xsl \
      file:///cygdrive/j/Shared/example/common-customizations.xsl \
      /etc/xml/catalog

First, you need to have XML Catalogs working under cygwin. Second, to make the fix semi-permanent, you would need to keep your common-customization XSL file always in the same location. The intention of the above two commands would be to cause xsltproc to substitute the second URI for the first whenever it sees it. I spent only a few minutes on this idea. In theory, it seems it should work. In practice, it did not work for me.

When processing XML or FO files, the Java runtime may request access to your local net or the Internet. The Java runtime does that on my Windows 2000 system (using J2EE). DocBook XSL Configurator does not attempt to access your LAN or the Internet. However, processing an XML file or an FO file with a Java based processor may result in a pop-up from your firewall requesting access to your LAN or the Internet. Even libxml2 programs will request access to the Internet if you are not using the --nonet option. Subsequently, processing from within DocBook XSL Configurator may fail because a program cannot reach the Internet. Or DocBook XSL Configurator may not start, failing silently because java.exe has been denied access to your LAN or the Internet. It depends on how you have configured your firewall.

On my Windows 2000 system with ZoneAlarm, I give java.exe permission to access the local network or the Internet, but no other permissions. Still, ZoneAlarm occasionally denies java.exe access to anything and makes me re-authorize it. The point is that if your firewall silently confines java.exe, or another program you execute from within DocBook XSL Configurator, processing or even DocBook XSL Configurator itself may fail.

Normally, resolving entity references is done using XML Catalogs. On cygwin or Unix/Linux, XML Catalogs are often configured for you by the distribution or one of the packages you install. The native Windows libxml2 package from http://www.zlatkovic.com/libxml.en.html uses the XML_CATALOG_FILES and SGML_CATALOG_FILES environment variables to locate catalog files. With native Windows libxml2, you need to configure XML Catalogs yourself.

The XML Catalog solution I am using on native Windows is to set an XML_CATALOG_FILES environment variable that points to "C:\etc\xml\catalog". In that file, I use the "file:///dir/filename" syntax to point to DTDs and other resources just like I would in Unix/Linux.

If you are interested in the problem of XML Catalogs on Windows, an archive of a discussion of the subject involving several of the main developers can be accessed starting at http://mail.gnome.org/archives/xslt/2002-March/msg00027.html.

Many people have XML Catalogs working with Saxon. To add XML Catalog support to Saxon, you can try the instructions at http://www.kosek.cz/xml/saxon/.

Or, try the material from Bob Stayton's excellent book http://www.sagehill.net/docbookxsl/UseCatalog.html.

To get Windows XML Catalogs working on cygwin, Michael Smith provides a few tips at http://sources.redhat.com/ml/docbook-apps/2004-q3/msg00432.html.

Native Windows Example Commands

In the following examples, the backslash at the end of a line means that the text of the command is continued on the next line. You should not include the backslashes as part of a similar command you would actually use.

Notes for Linux/Unix Users

On Linux and and other Unix systems, if you start DocBook XSL Configurator from the command line you may see the following in your terminal: 

      Warning: Cannot convert string "MetaCtrlInsert" to type VirtualBinding

It's harmless. You can ignore it, or you can make it go away by issuing the following command: 

      xprop -root -remove _MOTIF_DEFAULT_BINDINGS

Use man xprop for further information.

Hope to Do