forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dave Brondsema <>
Subject Re: Docbook as forrest-plugin
Date Tue, 26 Oct 2004 00:57:07 GMT
Ross Gardler wrote:
> Sean Wheller wrote:
>> On Monday 25 October 2004 16:53, Ross Gardler wrote:
>>> So, Sean, can you provide a simple sample output from a typical Docbook
>>> tranformed into XHTML using the stylesheets. This will help me
>>> understand if the problems I envision are really there or not
>>> (unrecognised CSS styles that the skins must be extended in order to
>>> handle).
>> Sent in message off-list.
> Wow, that was a huge example, glad you sent it off list.
> I've glanced through and, as expected, it is pretty good code. There are 
> only a couple of things that would get in the way of our skinning and 
> they are trivial, in the vast majority of cases they will not cause a 
> problem (if ever), e.g.:
> <ul type="disc" compact="compact">
> <table border="0" width="100%" cellspacing="0" cellpadding="0"
>                                     class="blockquote" summary="Block 
> quote">
> <td width="80%" valign="top">
> <td align="left">S20acct</td>
> So, what needs to be done is the plugin needs to be able to add CSS 
> classes into a skin. If there are no name clashes between current 
> forrest skins and the Docbook XSLT generated code then I have a 
> suggestion, however, I have not considered the issue 
>  in this response, as I'm 
> still getting my head around it, but others, more familiar with that 
> issue may want to speak up, nor am I particular familiar with the way 
> XSL is used to generate the skins at present - so please consider this a 
> set of random thoughts to elicit comments.
> We cannot use the  <extra-css> element of skinconf.xml as this would 
> require the plugin to modify a file in the project. Besides we would 
> still want the skinconf.xml to override the formatting provided by the 
> skin.
> The options I see are:
> 1) plugins only output Forrests intermediate format
> 2) style definitions can be embedded in the body-html document
> 3) plugins can provide an extension.css for each skin it supports
> 4) skins can provide an extension.css for each plugin it supports
> 5) a combination of 3 and 4
> Option 1 is what we have been doing successfully until now. However, as 
> Sean points out it is forcing us to duplicate some work done by other 
> projects (in this case Docbook to XHTML stylesheets, same is true of 
> Open documents)
> Option 2 is the hack solution I have in the 
> plugin, it is not a pretty solution, but it does work.
> Option 3 and 4 both have the effect of splitting the skin definition 
> across multiple locations. In the case of option 3 it is the plugin that 
> takes responsibility for ensuring skins are supported, in option 4 it is 
> the skin that is responsible for supporting the plugin.
> Option 5 allows the maximum flexibility but also the maximum confusion 
> (what takes priority skin or plugin?)
> Regardless of which option is taken, skinconf.xml settings should 
> override the default settings (not possible with option 2).
> Ross

I think the best way is to generate the intermediate format.  This, of 
course, won't be too hard when our intermediate format is a subset of 
xhtml2, because lots of existing stylesheets output xhtml.  There will 
always be some "massaging" of the xml (probably classes and ids, etc) 
that the plugin will have to do after using the standard docbook->xhtml 
The intermediate format is still the Forrest Document, however.  We 
don't want to spend too much time on something that we know will be 
obsolete, but the future isn't here yet so we do need some solution. 
The first iteration of the docbook plugin should work just like forrest 
does now.  After that works fine, we can try new approaches to the 
stylesheets we use.

Remember, too, that we could have output plugins that transform from the 
intermediate format to a new final output format (txt, pod, man, etc). 
That's why one common intermediate format works best.

html --\                           /-> html
docbook--\                      /----> pod
jspwiki   ------> document-v12 ------> pdf

XHTML (iteration 1):
html --\                                     /-> html
docbook--\                                /----> pod
jspwiki   -----> document-v12 --> xhtml2 ------> pdf

Then we format by format, start going directly to xhtml2:
html --\                                     /-> html
docbook---------------------------\       /----> pod
jspwiki   -----> document-v12 --> xhtml2 ------> pdf

Eventually we get:
html --\                    /-> html
doc---------\            /----> pod
jspwiki   -----> xhtml2 ------> pdf

Skinconfig variables get used in all arrows after the intermediate 
format.  To be more accurate in the diagram, the html output format 
should probably be split in to one for each skin available.

Dave Brondsema : : programming : student org : personal

View raw message