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 12:31:51 GMT
Dave Brondsema wrote:
> 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.

I agree with you 100%, but I am exploring the alternatives with Sean as 
he is very sure that we don't need to in the Docbook plugin (I think we 
know better from the time we have been working on Forrest, but lets see 
- new eyes bring new ideas). In the meantime, I don't know Docbook and 
its generated XHTML so in exploring this with Sean I am gaining an 
understanding of what can be done with Docbook. My ultimate goal is to 
generate our intermediate format as a subset of XHTML2.

We may go with bypassing the intermediate in the short term (only for 
Docbook) so that we don't lose Sean as a developer on the Docbook 
plugin. If I/we fail to convince him of the need for the intermediate 
(or if he convinces us otherwise) then we will still have a working 
Docbook plugin, which has to be a good thing. (Sean - now you know my 
real motivation ;-)

Now, lets see if we can convince Sean:

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

Yes. Do you think that building the Docbook plugin so that it produces 
XHTML is a good first step to do this. Having Seans site as a test site 
for Docbook integration and our move to XHTML would be great. From what 
I ca see it is a reasonably large site, almost exclusively in Docbook - 
written by many others (possible different markup techniques).

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

Yes, I agree with this. I will extract the existing Docbook 
functionality into a plugin as soon as I can (probably this week). We 
will shortly have SVN restructured, at that point we can release a 
version of the Docbook plugin for 0.6 and work on the next iteration in SVN.

(actually it may be worth considering a new release, we have quite a few 
reasonably important bug fixes in 0.6 and the plugin functionality is 
pretty significant, perhaps a 0.6.1 is on the cards)

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

Yes, I am just taking Sean down this route now (see other mail).

> Current:
> html --\                           /-> html
> docbook--\                      /----> pod
> jspwiki   ------> document-v12 ------> pdf
> document-v12--/
> openoffice--/
> XHTML (iteration 1):
> html --\                                     /-> html
> docbook--\                                /----> pod
> jspwiki   -----> document-v12 --> xhtml2 ------> pdf
> document-v12--/
> openoffice--/
> Then we format by format, start going directly to xhtml2:
> html --\                                     /-> html
> docbook---------------------------\       /----> pod
> jspwiki   -----> document-v12 --> xhtml2 ------> pdf
> document-v12--/
> openoffice--/
> Eventually we get:
> html --\                    /-> html
> doc---------\            /----> pod
> jspwiki   -----> xhtml2 ------> pdf
> document-v12--/
> openoffice--/
> 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.

Seems like a plan, I'll copy this to the relevant issue for safe 
keeping. But I'd like to propose another line in this process:

Docbook -> XHTML1 -> XHTML2 (subset) -> output format

This is what I am hoping we can do with Seans work. As Sean the way we 
currently do it (subset of Docbook -> Document1.2 -> output) does not 
work and is demanding a great deal of duplicated effort with the Docbook 
stylesheets. Whereas doing it this way will give us support of any 
XHTML1 document. In addition from Seans site we will get a very good 
test site for this transformation (it is large with many authors).



View raw message