This is the mail archive of the docbook-apps@lists.oasis-open.org mailing list .


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[docbook-apps] Announce: DocBook XSL Configurator


Several months back, I had some discussion on this list about creating a Java 
GUI that would allow users a mostly point-and-click interface to creating 
customization layers for use with the DocBook XSL stylesheets. Well, I wrote 
the application and here it is. 

Announcing the first public release of DocBook XSL Configurator! Actualy two 
releases, one for version 1.65.1 of the DocBook XSL stylesheets and one for 
version 1.66.1. 

They are available for download from Sourceforge:
http://sourceforge.net/projects/db-xsl-cfg

DocBook XSL Configurator versions 0.5.2_1651 and version 0.5.3_1661 are alpha, 
since they have not been widely tested, but I know of no bugs and consider 
the software fully operational.

You can get a good idea of what DocBook XSL Configurator is and what it does 
from the following:

*******************************************
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.3_1661 is an alpha release.
	It supports version 1.66.1 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. 

	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.4.2 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.3_1661 needs DocBook 
	XSL stylesheet version 1.66.1. 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. 

	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 parameters and edit them as you like. Then, 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.

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

	- a valid DocBook XML instance. If you are new to DocBook XML, 
	  you should begin with Norman Walsh and Leonard Muellner's book, 
	  DocBook: The Definitive Guide, available online at: 
http://www.oasis-open.org/docbook/documentation/reference/html/docbook.html

	- the DocBook XML DTD package installed. You can download it from:
	  http://www.oasis-open.org/docbook/xml/

	- the DocBook XSL package installed. You can download it from:
	  http://sourceforge.net/project/showfiles.php?group_id=21935

	- some understanding of how the DocBook XSL package works with 
	  DocBook XML. Bob Stayton's book, DocBook XSL: The Complete 
	  Guide, available online at:
	  http://www.sagehill.net/docbookxsl/index.html, 
	  is probably the best resources available for learning 
	  DocBook XSL. 

	- an XSLT engine installed. DocBook XSL Configurator will work 
	  with any XSLT engine. I use xsltproc, which is part of the 
	  libxml2 package. You can download the libxml2 package from
	  http://xmlsoft.org/
	  You can download precompiled libxml2 binaries for Windows at:
	  http://www.zlatkovic.com/libxml.en.html 

	- an FO processor installed

	- PDF and PostScript viewers installed
**********************************************

The project GPLed and open to additional developers. I'm currently the only 
developer. Send any bug reports to swhitlat@getnet.net.

Enjoy!

Steve Whitlatch
swhiltat@getnet.net



 


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]