forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Sean Wheller <>
Subject Re: Docbook as forrest-plugin
Date Tue, 26 Oct 2004 19:31:16 GMT
On Tuesday 26 October 2004 20:25, Ross Gardler wrote:
> 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.

Well, technically you make anything look the same its XML/XSL.

> 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.

Well. Speaking personally, I am more in favor of having a system that works 
100% than having to suffice with a system that works 20% - 70%, depending on 
the source formats.

I understand why people want "intermediate format," but this is not a true 
solution. It's a work around to get something working. Forrest is now past 
0.6 and needs to "grow-up." Sorry if that sounds bad, but I mean it with good 
intentions. The best route is XHTML. That mean XHTML1 for now.

Forrest tries to take lots of responsability upon itself. While this is 
admirable, it does not always result in the best and most flexible solution. 
I think that the future for Forrest is good if the project can read in 
standard formats.

The number of formats is endless.  Already, the number of stylesheets 
supporting conversion to another format are growing in number. They don't all 
implement a full support for the target format. In addition, Forrest must 
develop them while the sources of these formats are always changing. That's 
an impossible task.

IMHO it is better to harness the power the community (I mean other projects) 
than to do it ourselves. We just need to define the format we accept, as 
yourself and others have said, this means HTML or XHTML (1,2). I am in favor 
of the later and I have no doubt that the Docbook community will develop 
stylesheets for XHTML2.0 and the will when the "Longhorn Help System" is 

I don't believe the power of forrest is in transformation to all formats. I 
think it is in providing a publishing system that can accept input from the 
numerous source formats out their and make it accessible. 

The power of transformation and level of presentation/complexity in projects 
such as DITA, TEI and Docbook is stronger than anything we could do by 
ourselves. Why not harness that power?

BTW, there's the next two plugins for Forrest DITA and TEI.

> >>>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.

It makes it easier. Docbook is already an application to itself. It will only 
grow stronger. As I said above, the benefit is there.

> 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.

Perhaps. But customization of the look and feel is not a problem. We just need 
to decide on a standard look. In XHTML it's CSS that does the work. In PDF 
etc. its the xsl:fo. Once we have custom layers we can enjoy the power of 
packaged transformations and focus on making them look the same.

> >>>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.

The problem is bigger than you may think. Fixing the current system while 
their is the intention to move to XHTML is just useless as we will build it 
and then throw it out in a short time. I would prefer to develop something 
that has a longer shelf life.

> >>>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
> >>ours.
> >>
> >>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.

Ahhh.... but what level of support. The level of execution currently available 
is 2/5 that of what it should be to be considered professional enough for 
commercial consumption.

> 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.

It is possible. Anything is possible. Yet, if it was easy, everyone would be 
doing it. If we do it then that would really make forrest outstanding. Don't 
get me wrong. I think forrest is good. It could be great, that is why I am 
I am looking into the other formats. I will return on this subject soon.

> 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.

Not quite. Am am proposing that forrest expect to receive input in a standard 
format that can be consistently skinned as per the project wishes. This 
extends to include all presentation type formats that forrest may provide 
access to.

The difference between our thinking is that I don't believe the current 
transformation system is:
a) strong enough to support complex requirements.
b) easy to manage as requirements and standards change (thinking XSLT 2.0)
c) an efficient use of development time.
> 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.

Great!!! Hopefully you can contribute it back.

> > 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
> stylesheets.
> 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).

Yes, but you can't get POD, DVI, PS etc in XHTML.

> > 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. 

This is not a fact. We have not proven this. Those pipelines are powerful 
things. We just need to join the pipes in the best manner.

> 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.

My thinking exactly. 
> Ross

Thanks for your help on this.
Sean Wheller
Technical Author

View raw message