forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <>
Subject Re: Docbook as forrest-plugin
Date Tue, 26 Oct 2004 18:25:25 GMT
Sean Wheller wrote:
> On Tuesday 26 October 2004 14:54, Ross Gardler wrote:
>>>In the case of Docbook, the transformation to PDF, RTF, PS is via XSL:FO.
>>>The stylesheets for fo are already in the Docbook distribution and FOP is
>>>already in Forrest. Again, use the FO from the Docbook stylesheets and
>>>pass it to FOP. For now we will assume that we are transforming a
>>>complete book. Later we will use functions already available in Docbook
>>>to transforms smaller granularity. Let's keep it simple for now.
>>But there is a real problem with this. If I have a site with Docbook
>>files and files will they both be formatted the same?
>>This is very, very important as it is one of the goals of Forrest to
>>have consistent output from various inputs. Just how configurable are
>>these stylesheets?
> Oooops, nope. I don't think the Docbook XSL's will work on the OO files.
> They are modular and configurable. You can overide and custom any template. 
> But I think the difference between OO and Docbook XML structure is a big one.

I didn't quite mean that OO files should be processed by the Docbook 
ones but that when they are processed they look the same.

However, do you now understand why we have the intermediate format? 
Recall my mail about having to create multiple stylesheets to support 
multiple input/output combinations. With the intermediate format there 
is only one for each input format and one for each output format.

>>>The other thing is to try use Saxon or Xalan, as this is forrest I think
>>>we need to use Xerces and Xalan. My custom stylesheets call to
>>>extensions, these extensions are also a part of the Docbook stylesheet
>>>distribution. I especially call fop.extensions. There is much that FOP
>>>does not handle, this extension helps to smooth life with a better output
>>>result and less errors during transforms. IOW, it's faster.
>>Hmmm.... I'm not entirely sure we would want to go this way. Extensions
>>cause a problem with tool independence, and I *think* Forrest wants to
>>be tool independent. If we have to go this way we will need to ask this
>>in another thread to ensure all devs see it.
> Can't see why. This is a "Docbook Plugin" for Forrest. It does not impact 
> directly on forrest. The extensions are java and proven to work with xerces, 
> xalan, and fop. All are Apache.

The more "extra" bits we include in the Docbook plugin the more like a 
completely separate application it becomes. Whilst I am willing to 
assist with creating a plugin that conforms to the way Forrest does it 
(and therefore will be easy to maintain). I am reticent to help create a 
plugin that will make it difficult for Forrest developers.

This coupled with the problem above (you cannot output consistent PDF 
documents with the skin I choose to use) means that, as I have always 
maintained, bypassing the intermediate format will be a mistake.

>>>We will then come back to the XInclude problem, but this time I have a
>>>solution. We will switch the Xerces XInclude mechanism ON and not rely on
>>>the Cocoon patchy implimentation thereof.
>>Does that actually work? If so please submit a patch, I don't think
>>there are any side-effects from this as long as it does not prevent
>>CInclude from working.
> Hey. It will work in the plugin. :-) The file sample I sent you is made from 5 
> first level xi:includes each with X number of subnested xi:includes. What 
> forrest gets from the Docbook plugin is what I sent you. So there is no need 
> for forrest to expand &entities; or xi:include. In PDF that is over 1400 A4 
> or Letter sized pages.

Hmmm... if there is a real problem with XIncludes it should be fixed in 
the core of Forrest not in a plugin.

>>>Let's get that far and then discuss
>>>POD, WIKI, DVI, TXT, etc
>>We have to know the route we are taking will produce a fully functional
>>plugin in the end. You are proposing bypassing much of the important
>>parts of Forrest in order to achieve what *you* need to achieve, but it
>>is important that we ensure it also achieves what other users want to
>>achieve. There are already users who use the existing Docbook
>>functionality, we cannot remove any existing functionality.
>>However, it is not all bad news. There is nothing to stop you working on
>>an another Docbook plugin. As long as you call it something different
>>from the one we have you can use your own and our existing users can use
>>I have every intention of helping you get this plugin working, but I
>>also have every intention of making sure it conforms to the way we do
>>things here. As you know we are not stuck in our ways, we are flexible
>>but any new solution needs to be better than the old, without those
>>intermediate formats we are just making more work for future developers
>>(see my mail and Dave B's mail in this thread about why we use an
>>intermediate format).
>>Since we (Forrest) are going to a subset of XHTML2, and you are starting
>>with XHTML1 the creation of our intermediate format in your plugin will
>>(eventually) be a fairly easy thing to do (see Dave B's comments in this
>>thread). I therefore propose that I create a Docbook plugin with the
>>existing functionality (renamed "docbook-subset"), and you work on a
>>brand new plugin called "docbook-full", in the docs we can make it clear
>>that the docbook-full plugin does not provide all output formats. Once
>>we have the XHTML1->intermediate format converters we can deprecate
>>docbook-subset and rename docbook-full to docbook.
> I don't think it is a problem. Either way. The current solution is stunted. As 
> I said before, it's a partial support for a standard. People can continue to 
> use this option, or they can move to the plug-in. In addition, I see no 
> reason why the Docbook Plug-in cannot be extended to include stylesheets for 
> other formats. At first I would add existing packages like docbook2latex, and 
> docbook2man.
> I think that once a docbook2pod is developed, it can be moved out to 
> where development thereof will be accelerated. The same for 
> any other format.

I think you are missing the point of Forrest. You are supposed to be 
able to put any input in and get out any *skinned* output. The idea of 
the skin is you change a single property and that is it. Skins can be 
maintained by Forrest or by individual projects.

We have agreed that we should be able to skin the XHTML output 
accordingly. However, have not, as yet, found a way of skinning the 
other output formats in a manner that is consistent with a projects 
chosen skin.

What you are proposing is that all skin developers create a special 
transformation for Docbook sources for *all* output formats forrest 
provides. The current system does not require, it requires one 
stylesheet for each output format.

I would be -1 on a final solution that removes all the benefits of the 
skinning system since this is one of the fundamental parts that makes 
Forrest what it is. However, as described above your proposal is a step 
towards what we need to do, as an intermediate step I am +1. You may not 
have the need in your own project, but I have it in mine. In true open 
source fashion, if you provide what you need, I will build on it to 
provide what I need.

> I *think*, I don't say for sure, you may find that the docbook community (a 
> large one) will put support behind it. I also *think* that the Docbook 
> plug-in will increase the usage of Forrest by other Open projects, in turn 
> increasing the number of developers who may contribute to the project.

I do not think the Docbook community will help users of Forrest write a 
series of translations for all the forrest skins that they use. It is 
not the role of the Docbook community.

By using the intermediate format of Forrest we don't need the Docbook 
community to provide that support, they stay focused on their XHTML 
stylesheets, we stay focused on maintaining out XHTML->intermediate 

Less work for the Docbook community, less work for Forrest community and 
more supported formats (anything you can get in XHTML will be supported 
by the XHTML->intermediate stylesheets).

> All in all, I think that the XHTML mech will also be good, as I see from other 
> messages.

I disagree and the fact that you cannot produce all the relevant output 
formats convinces me of the fact. However, this need not stop us moving 
forwards. As described above, if you create a plugin that does what 
*you* need it to do, others in the Forrest community will use that as a 
base to provide what they need it to do. So lets not argue the toss, 
lets get the first stage done and then ask the community to vote on its 
inclusion here.


View raw message