[docbook-apps] Creating a GUI to configure DocBook FO XSL [was Re: [docbook-apps] XSL FO parameter admonition.properties (and more!)]

[Steve Whitlatch <swhitlat at getnet dot net>]

> Sorry if this come too late to help. I haven't checked the list in a while.

No problem. It's funny though, I was 1/2 through your post when I thought 
"hey, he's talking about stuff related to what I'm doing."

> If I understand your question correctly, you are interested in the DocBook
> stylesheet parameters, rather than the FO properties (or maybe it's both).
> I've been fooling around with a similar stylesheet customization application
> off and on. You may find the techniques I used work for you. Both process
> the existing DocBook XSL files at start up to avoid hardwiring anything that
> might change.

I'm writing a GUI in Java that allows a user to create a DocBook XSL 
customization layer for FO. With some changes, most of the code can later be 
used to do the same thing to create an HTML customization layer. And, 
depending on the state of DITA XSL, with the correct changes it may be useful 
there too. 

The problem I wrote about in the previous post was mostly just a worry at that 
time. But now it is becoming a bit more real. Most of the structure of the 
program is complete. I am now down to the details of creating panels in a 
tabbed pane, one tab for each group of parameters. Now I must decide what 
user input is allowable and create the widgets and actions in each group's 
tab. It's easy enough to create an XSL file containing all the defaults 
(taken from param.xml), but I was worried, and still am somewhat, that in 
some cases the input I allow the GUI to produce will break the XSL, and also 
that I will not provide all the legal options to the user. 

Some FO parameters are easy. For example: 
<xsl:param name="admon.graphics" select="0"></xsl:param>

The user can skip the parameter completely, or select zero or one. Then the 
program builds a string and writes it to the XSL file. 

Other parameters are more complicated. This is the kind of thing that worries 
me still just a bit:
**************
 admonition.title.properties â To set the style for admonitions titles.
<xsl:attribute-set name="admonition.title.properties">
  <xsl:attribute name="font-size">14pt</xsl:attribute>
  <xsl:attribute name="font-weight">bold</xsl:attribute>
  <xsl:attribute name="hyphenate">false</xsl:attribute>
  <xsl:attribute name="keep-with-next.within-column">always</xsl:attribute>
</xsl:attribute-set>
**************

When dealing with a property set, I need to know all the legal attributes and 
what I can legally feed to them from the GUI. The suggestion I will follow is 
to consult the XSL-FO specification for a list. 

I think there are about 200 named parameters in param.xml, but many are 
property sets, so that means more GUI stuff is needed.

> One option is to use SAX to process all of the .xml files located in params
> directory and construct a parameter set from what you find. This has the
> advantage of allowing you to grab <refpurpose> and/or Â<refsect1> content to
> use as a tooltip in the UI. 

I think that tooltip help is a good idea, and I planned for that; however, I 
do not have plans for an automated process by which necessary information is 
extracted from any DocBook XSL distribution files. That's beyond me. 
Improvements can be made, but I want to at least complete something that 
works. I'm just using what I know now. 

> The problem (which you seem to have found), is 
> that you won't necessarily get all of the parameters that are actually
> present in the stylesheets. It does provide a useful base set of parameters
> that can be used as a drag source when constructing a customization
> stylesheet.

How much will I miss if I just include everything from param.xml? 

The normal groups are Admonitions, Callouts, etc. But I also have another 
group I call "From the Wild." I hope to include in that group slick little 
valuable XSL bits, the kind of stuff some of us search the archives for. And 
of course, I'll eventually learn enough XSL to invent whatever is necessary. 
Then I'll include that too.

> The other option is to use an XSL processor (I've used Xalan), then walk the
> resulting Stylesheet object to get the parameters and their values. This
> method hands you every parameter defined in the root stylesheet, plus those
> from any included/imported stylesheets. Constructing the parameter set this
> way has the advantage of only showing those parameters that are actually
> present (and presumably used by a template).

All I do is hard-code a bunch of strings into a String array. Like this:

*********************
String[] param0 = 
	{
		"0",
		"<!-- If true (non-zero), admonitions are presented in an alternate style 
\nthat uses a graphic. Default graphics are provided in the distribution. 
-->",
		"<xsl:param name=\"admon.graphics\" select=\"",
		"0",
		"\"></xsl:param>"
	};
	defaultsMap.put("Admonitions admon.graphics", param0);
**********************

defaults.Map is a TreeMap. It eventually becomes a serialized object. 

When fully populated, it contains all the info needed from param.xml. The 
first string in the string array is just a flag  indicating whether the 
parameter should be written out to the XSL file. The second string is the 
help text for a tooltip. The third and fifth strings are the text of the 
parameter. The fourth string is targetted to be the input from the GUI. When 
the program starts, the entire TreeMap is read into memory. The user creates 
a "project," including necessary filenames, and eventually the program writes 
out an XSL file and uses it as part of a string of options to an xslt 
processor.

The hard part to writing this GUI is the part I am doing now, creating the 
parameter groups' widgets. I expect there will be more than 500 and perhaps 
as many as 1000 different widgets that offer choices, accept input, or 
something (checkboxes, textfields, popups, popdowns, etc.).  

> In my case, the parameters and their values are displayed in a table widget
> so that they can be easily sorted and edited. ÂI plunk the individual
> stylesheets in a tree widget to show the nesting. Selecting a stylesheet
> node filters the table to show only the parameters from that particular
> stylesheet.

Sounds like you know more about doing this kind of thing than I do. 

> As far as constraining the 'allowed' values, I think you're going to have to
> rely on the documentation. Since it mostly consists of passing strings into
> the stylesheets, just about anything is allowed, but only some values will
> make sense. It depends on what the template is trying to do with the value
> it receives. HTH.

I think I should check the input from the user and reject invalid input. It's 
more work, but I should do it. While I determine what the GUI should 
allow/reject, if I'm uncertain, I'll ask here. Or maybe if you don't mind, 
I'll ask you directly. When I have something that I think works, I expect 
others will find some bugs and errors. 

I understand that my approach with populating the TreeMap is not the best. 
Each time param.xml changes, the Java source code file that produces the  
TreeMap would need to be updated. Right now, that's a manual process. Perhaps 
the TreeMap can be created from a file that gets created from some automated 
XSL process. It would be inconsistent with the GUI, but would still save some 
time and effort. 

I like using the TreeMap because it easily resides in memory and provides very 
quick access to all the needed info from param.xml. The input to the XSL file 
that comes from the "From the Wild" group cannot reside in the TreeMap. I'm 
not sure where to put it. Maybe I'll just make another TreeMap.

I think it will be several months before I have something useful.  

enough, 

Steve Whitlatch
swhitlat@getnet.net

To unsubscribe from this list, send a post to docbook-apps-unsubscribe@lists.oasis-open.org, or visit http://www.oasis-open.org/mlmanage/.