forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Levitt <>
Subject Re: DITA plugin
Date Thu, 31 Mar 2005 19:49:23 GMT
--- Ross Gardler <> wrote:
> Jeff Levitt wrote:
> > Hi all, 
> > 
> > I am new to this list.  I am a Derby contributor,
> and
> > I wanted to see if I could help out with Ross's
> Jira
> > issue:
> > 
> >
> :-)) That issue was created because I say a
> discussion that about Derby 
> needing DITA sources. I'm glad to see you here, we
> know Forrest but I 
> don't think anyone here knows DITA.
> > I created the DITA docs that Derby is using for
> > documentation, and since we use Forrest for our
> site,
> > it would be nice if we could throw our XML DITA
> files
> > into directories within our xdocs/ directory and
> get a
> > working site with html output in there using the
> > toolkit.
> > 
> > Basically, all the DITA toolkit does is use xsl
> > transforms with ant to build html or PDF (with
> FOP). 
> Forrest works by on a pipeline process. You start
> with an input format, 
> this gets transformed into our internal format which
> is then converted 
> to out output formats.
> We have this intermediate step so that we only need
> to maintain one set 
> of output XSL's.
> Right now our internal format is called XDoc,
> however we plan to move to 
> a subset of XHTML2 in the next release. XDoc is
> pretty much XHTML2 
> anyway at this stage.
> In order to have Forrest generate the "decorations"
> on a page 
> (navigation, logo's search box etc.) we need to
> convert your DITA 
> documents into our internal format.
> Since there is a toolkit that provides DITA->HTML
> and we have a 
> stylesheet that converts HTML->XDoc we would be best
> to go that route.
>  > There is a preprocessing step to fix related
> links and
>  > linking etc.
> This could be a concern, although we can do
> preprocessing too. Can you 
> explain a little more about what this preproccesing
> step is and what it 
> does.

>From the DITA Toolkit docs:

"A pre-process is done before the main transformation.
The input of Pre-process is dita files and the output
of Pre-process is also dita files. But the output is
in temp directory. Pre-process is the basic for the
main transformation, it handles several different
processing before the main transformation. Without
pre-process, dita topics and map can still be
transformed into different outputs, but the features
in pre-process such as resolving conref attribute are
not available."

So the dita files get transformed to new dita files in
a temp directory, and those are the dita files that
get processed by the rest of the xsl files into html,
pdf, etc.  The preprocess xsl files are located in
xsl/preprocess/ in the toolkit.  The ant build.xml
file is used to automatically call the preprocessing
and then the general processing using the correct xsl
files for each output.

>  > So in my research of Forrest, it seems I would
> have to
>  > follow this process to get a transform to work
> with
>  > DITA's xsl files:
>  >
>  >
> This is a way of overriding behaviour on a per-site
> basis. However, 
> since DITA is a format that other projects are
> likely to use we would be 
> better off cresting an input plugin. The process is
> very similar, but 
> there is an automated distribution and installation
> process for plugins.
> Plugins are not in 0.6, but the framework has been
> stable for a while 
> now, and will be in the imminent 0.7 release. You
> can see some users 
> docs for plugins at:
> Some developer background at
> and some docs on how to make a plugin at:
> > Is there anyone who would like to work on this
> with me
> > who might know a lot more about modifying the xmap
> > files to accept new xsl files?  I figure it might
> be
> > easier to share my DITA toolkit knowledge with
> someone
> > more familiar with Forrest, and together we can
> get
> > the right xsl files in the right places and allow
> for
> > preprocessing and full transform of the DITA
> source in
> > a Forrest site build.
> Lets go...
> First off, a few questions:
> - what stylesheets are used to create the HTML
> output at present
> - what are the processing steps to create HTML at
> present
> - can you make available some of the output of the
> existing process

The stylesheets for html are called in the
ditatargets.xml file (called by build.xml)...and ant
is something that is relatively new to me...However it
does call the general processing xsl file for html,
which is xsl/dita2html.xsl (which I believe also calls
the xhtml processing file, dita2xhtml.xsl because they
use similar templates).  That xsl file calls the rest
of the xsl files it needs, all located in
xsl/xslhtml/.  Before it gets to any of that, it uses
one or more of the preprocess xsl files.  I am
guessing this process makes duplicating it with
Forrest a mighty task...

I have included an html file created from this
process.  If you'd like the entire set of dita files
for derby, as well as instructions on building them,
go to:

Note that we are having some minor issues with our
build, so you may get some failures, but you should
get at least one book to work, providing you with html
output as well as the intermediate dita files in the
temp directory.
View raw message