You are viewing a plain text version of this content. The canonical link for it is here.
Posted to user@forrest.apache.org by David Crossley <cr...@apache.org> on 2005/08/02 12:21:54 UTC
simplified docbook plugin (Was: Forrest run works but forrest doesn't)
Phillip Evans wrote:
> >What do you mean by "edit styles"?
>
> Two things really. There are some aspects of the sdocbook conversion that
> don't seem to be handled well by sdocbook2document.xsl, but you are right, I
> don't know enough to make any beneficial changes there.> I really need a
> docbook2document.xsl in the longer term. I understand that there used to be
> one, but I can't seem to find it in the current release.
No there was not ever one. You can use the full docbook xsl
but that won't give you the Forrest navigation trimmings.
http://forrest.apache.org/faq.html#docbook
After we change Forrest to use XHTML2 at its core
(maybe next forrest version), then you would be able
to use the full docbook XSL to output XHTML, then Forrest
would apply the theming to that.
> By the way, forrest
> did not handle the sdocbook conversion until I moved
> 'sdocbook2document.xsl' to:
>
> \site\src\documentation\resources\stylesheets\sdocbook2document.xsl
>
> It would skin blank pages until I moved that file.
> Is this due to a configuration error on my part?
Sorry i don't understand what you mean.
Have you declared the simplifiedDocbook plugin
in your forrest.properties file?
> The other aspect is editing the css, and that is made interesting through
> the Firefox plugin as described in the howto's.
>
> >I suggest waiting until you understand a bit more before trying to write
> documentation for others.
>
> Yes, you are right, but sometimes a bit of naivety can uncover some of the
> assumptions that us mere footsloggers get stuck on. After several days of
> struggle since starting from scratch, with very little to show for it, I was
> very close to giving the exercise up as being beyond my grasp. But now, I'm
> very happy with a usable result that I can fine-tune.
Ask questions before you reach that stage.
David
> Anyway, thank you for your assistance
>
> Phil
>
Re: simplified docbook plugin
Posted by David Crossley <cr...@apache.org>.
Ross Gardler wrote:
> David Crossley wrote:
> >Ross Gardler wrote:
> >>David Crossley wrote:
> >>
> >>>Are you just talking about the stylesheet or the DTDs too?
> >>>The trouble with the DTDs is that they will make this
> >>>plugin, and our SVN trunk, very cumbersome. How many
> >>>versions of Full DocBook and Simplified DocBook will
> >>>we support?
>
> ...
>
> >The issue is more about efficiency. When the xml parser
> >encounters a document type declaration in an xml instance,
> >then it must resolve the DTD and everything that is thereby
> >referenced. So if you don't provide local copies, then there
> >are network trips on every parse.
> >
> >We could not provide them, and just give people
> >documentation about how to configure their own.
> >In fact we already have that.
> >
> >The trouble is that they don't. Then poor Forrest
> >would appear awfully slow to them.
>
> How about we enhance the plugin install mechanism to offer to download
> an additional package of DTD's. So the install process would be:
>
> - set forrest.properties
> - forrest
> - approve plugin licenses (to be done)
> - specify required DTD's
> - install selected DTD's
>
> This way we can tell users, "these DTD's are xMb, are you sure you want
> to install them? If you don't install them then Forrest will only work
> whilst you are online and will not perform as fast"
This is exactly the point that we arrived the last
time that we discussed this topic.
So i presume that we need to develop a "DTD package descriptor".
Some issues ...
* Sometimes DTDs are in a compressed archive,
complete with an "XML Catalog" which defines
each resource and maps it to a local relative URI.
* Sometimes there is a single DTD file.
* Sometimes a DTD refers to other pieces via
local references.
* Sometimes there is no "XML Catalog" provided,
so we will need a default one.
* How would Forrest automatically know that the
DTDs are needed? Perhaps we can have an Ant thing
to scan their project source tree and match document
type declarations with the installed XML Catalogs.
It is not my immediate itch to take on this job,
but i will certainly help where i can.
There is also a need for a similar download mechanism
for sets of XSL stylesheets.
For example, the Apache XML Commons website uses Forrest.
For the Resolver documentation, Forrest uses the
Forrest-supplied DocBook DTDs and the project sitemap has a
hard-coded URL to the local system-supplied Full DocBook XSLs.
David
Re: simplified docbook plugin
Posted by Ross Gardler <rg...@apache.org>.
David Crossley wrote:
> Ross Gardler wrote:
>
>>David Crossley wrote:
>>
>>>Are you just talking about the stylesheet or the DTDs too?
>>>The trouble with the DTDs is that they will make this
>>>plugin, and our SVN trunk, very cumbersome. How many
>>>versions of Full DocBook and Simplified DocBook will
>>>we support?
...
> The issue is more about efficiency. When the xml parser
> encounters a document type declaration in an xml instance,
> then it must resolve the DTD and everything that is thereby
> referenced. So if you don't provide local copies, then there
> are network trips on every parse.
>
> We could not provide them, and just give people
> documentation about how to configure their own.
> In fact we already have that.
>
> The trouble is that they don't. Then poor Forrest
> would appear awfully slow to them.
How about we enhance the plugin install mechanism to offer to download
an additional package of DTD's. So the install process would be:
- set forrest.properties
- forrest
- approve plugin licenses (to be done)
- specify required DTD's
- install selected DTD's
This way we can tell users, "these DTD's are xMb, are you sure you want
to install them? If you don't install them then Forrest will only work
whilst you are online and will not perform as fast"
Ross
Re: simplified docbook plugin
Posted by David Crossley <cr...@apache.org>.
Ross Gardler wrote:
> David Crossley wrote:
> >
> >Are you just talking about the stylesheet or the DTDs too?
> >The trouble with the DTDs is that they will make this
> >plugin, and our SVN trunk, very cumbersome. How many
> >versions of Full DocBook and Simplified DocBook will
> >we support?
>
> Good point, I wasn't thinking of the validation requirements. This
> requires a little more thought, I won't commit this change.
I wasn't worried so much about validation requirements.
Actually that should not be a concern of Forrest (though
certainly something we can help with).
The issue is more about efficiency. When the xml parser
encounters a document type declaration in an xml instance,
then it must resolve the DTD and everything that is thereby
referenced. So if you don't provide local copies, then there
are network trips on every parse.
We could not provide them, and just give people
documentation about how to configure their own.
In fact we already have that.
The trouble is that they don't. Then poor Forrest
would appear awfully slow to them.
> (I now remember we need to move the Docbook schema out of Core into the
> plugin now you fixed the catalog resolving for plugins).
Yeah, another job.
David
Re: simplified docbook plugin
Posted by Ross Gardler <rg...@apache.org>.
David Crossley wrote:
> Ross Gardler wrote:
>
>>David Crossley wrote:
>>
>>>Phillip Evans wrote:
>>
>>>>I suppose it is possible to modify input.xmap so that will accept
>>>>sdocbook-v1.1 as well?
>>>>
>>>>Where should that be done?
>>>
>>>You could alter the input.xmap in the
>>>FORREST_HOME/build/plugins/org.apache.forrest.plugin.input.simplifiedDocbook
>>>Search for the term "sdocbook-v1.0" (it occurs twice) and
>>>add similar handling for "sdocbook-v1.1".
>>>
>>>However, there is more to it than that. You also need
>>>to provide the DTDs for sdocbook-v1.1
>>>
>>>There is more information about this process at
>>>http://forrest.apache.org/docs_0_70/your-project.html#adding_new_content_type_2
>>>except that you are doing your changes in the plugin
>>>rather than in the core.
>>>
>>>You might also need to provide a different
>>>sdocbook2document.xsl stylesheet because i presume
>>>sdocbook 1.1 is different to sdocbook 1.0
>>
>>There are a couple of sdocbook releases that we don't currently support
>>(v1.1 and v4.1.2.5 - that later may be the same as the former as v1.1 is
>>not available from OASIS).
>>
>>Since we do not fully support even sdocbook v1.0 I propose adding these
>>new versions to the plugin along with a note in the docs that support is
>>not complete and issues should be raised on Jira to enable us to improve
>>support.
>>
>>That is, I do not plan to write a new stylesheet for this at this stage.
>>
>>Are people OK with me committing these changes (lazy consensus in
>>operation).
>
>
> Are you just talking about the stylesheet or the DTDs too?
> The trouble with the DTDs is that they will make this
> plugin, and our SVN trunk, very cumbersome. How many
> versions of Full DocBook and Simplified DocBook will
> we support?
Good point, I wasn't thinking of the validation requirements. This
requires a little more thought, I won't commit this change.
(I now remember we need to move the Docbook schema out of Core into the
plugin now you fixed the catalog resolving for plugins).
Ross
Re: simplified docbook plugin
Posted by David Crossley <cr...@apache.org>.
Ross Gardler wrote:
> David Crossley wrote:
> >Phillip Evans wrote:
>
> >>I suppose it is possible to modify input.xmap so that will accept
> >>sdocbook-v1.1 as well?
> >>
> >>Where should that be done?
> >
> >You could alter the input.xmap in the
> >FORREST_HOME/build/plugins/org.apache.forrest.plugin.input.simplifiedDocbook
> >Search for the term "sdocbook-v1.0" (it occurs twice) and
> >add similar handling for "sdocbook-v1.1".
> >
> >However, there is more to it than that. You also need
> >to provide the DTDs for sdocbook-v1.1
> >
> >There is more information about this process at
> >http://forrest.apache.org/docs_0_70/your-project.html#adding_new_content_type_2
> >except that you are doing your changes in the plugin
> >rather than in the core.
> >
> >You might also need to provide a different
> >sdocbook2document.xsl stylesheet because i presume
> >sdocbook 1.1 is different to sdocbook 1.0
>
> There are a couple of sdocbook releases that we don't currently support
> (v1.1 and v4.1.2.5 - that later may be the same as the former as v1.1 is
> not available from OASIS).
>
> Since we do not fully support even sdocbook v1.0 I propose adding these
> new versions to the plugin along with a note in the docs that support is
> not complete and issues should be raised on Jira to enable us to improve
> support.
>
> That is, I do not plan to write a new stylesheet for this at this stage.
>
> Are people OK with me committing these changes (lazy consensus in
> operation).
Are you just talking about the stylesheet or the DTDs too?
The trouble with the DTDs is that they will make this
plugin, and our SVN trunk, very cumbersome. How many
versions of Full DocBook and Simplified DocBook will
we support?
David
Re: simplified docbook plugin
Posted by Ross Gardler <rg...@apache.org>.
[moved from user list]
David Crossley wrote:
> Phillip Evans wrote:
>
...
>>I suppose it is possible to modify input.xmap so that will accept
>>sdocbook-v1.1 as well?
>>
>>Where should that be done?
>
>
> You could alter the input.xmap in the
> FORREST_HOME/build/plugins/org.apache.forrest.plugin.input.simplifiedDocbook
> Search for the term "sdocbook-v1.0" (it occurs twice) and
> add similar handling for "sdocbook-v1.1".
>
> However, there is more to it than that. You also need
> to provide the DTDs for sdocbook-v1.1
>
> There is more information about this process at
> http://forrest.apache.org/docs_0_70/your-project.html#adding_new_content_type_2
> except that you are doing your changes in the plugin
> rather than in the core.
>
> You might also need to provide a different
> sdocbook2document.xsl stylesheet because i presume
> sdocbook 1.1 is different to sdocbook 1.0
There are a couple of sdocbook releases that we don't currently support
(v1.1 and v4.1.2.5 - that later may be the same as the former as v1.1 is
not available from OASIS).
Since we do not fully support even sdocbook v1.0 I propose adding these
new versions to the plugin along with a note in the docs that support is
not complete and issues should be raised on Jira to enable us to improve
support.
That is, I do not plan to write a new stylesheet for this at this stage.
Are people OK with me committing these changes (lazy consensus in
operation).
Ross
Re: simplified docbook plugin
Posted by David Crossley <cr...@apache.org>.
Phillip Evans wrote:
>
> Thanks for your time on this. I have done as you outlined. After running
> forrest site in testSDocbook directory I again got the message in the
> console:
>
> BROKEN: C:\apachefriends\xampp\htdocs\apache-forrest-0.7\plugins\plugins.xml
> <The system cannot find the file specified>
>
> However all the plugins appeared to be retrieved and configured as you
> describe.
>
> I checked the distribution zip file for forrest and found that
> \apache-forrest-0.7\plugins\plugins.xml was present, so copied it to where
> it should have been in my installation. I re-ran forrest site without
> problems.
Youch. It might be better if you re-installed the forrest
distribution. Perhaps you have other things missing too.
> I then ran forrest run in:
> FORREST_HOME/build/plugins/org.apache.forrest.plugin.input.simplifiedDocbook
> without problems, and could view sdocbook.html and .pdf
Good.
> I then tried adding one of my own sdocbook documents, and again had the
> problem of no content. I checked out input.xmap, and found that it had a
> sourcetype of sdocbook-v1.0, whereas my documents are all sdocbook-v1.1
>
> I assigned sdocbook-v1.0 to a couple of my documents, and they worked fine.
As expected.
Before we go on, you should not be building a website inside
the FORREST_HOME/build/plugins/ area. That was just Ross asking
you to do a test to see if everything was working.
Create a new directory somewhere outside the
forrest distribution. cd to it and run 'forrest seed'
then add to forrest.properties to declare that you
want to use the simplifiedDocbook plugin.
> I suppose it is possible to modify input.xmap so that will accept
> sdocbook-v1.1 as well?
>
> Where should that be done?
You could alter the input.xmap in the
FORREST_HOME/build/plugins/org.apache.forrest.plugin.input.simplifiedDocbook
Search for the term "sdocbook-v1.0" (it occurs twice) and
add similar handling for "sdocbook-v1.1".
However, there is more to it than that. You also need
to provide the DTDs for sdocbook-v1.1
There is more information about this process at
http://forrest.apache.org/docs_0_70/your-project.html#adding_new_content_type_2
except that you are doing your changes in the plugin
rather than in the core.
You might also need to provide a different
sdocbook2document.xsl stylesheet because i presume
sdocbook 1.1 is different to sdocbook 1.0
David
RE: simplified docbook plugin (Was: Forrest run works but forrest doesn't)
Posted by Phillip Evans <pe...@wukwuk.com>.
> -----Original Message-----
> From: Ross Gardler [mailto:rgardler@apache.org]
> Sent: Wednesday, August 03, 2005 3:06 PM
> To: user@forrest.apache.org
> Subject: Re: simplified docbook plugin (Was: Forrest run
> works but forrest doesn't)
>
> Phillip Evans wrote:
>
>
> > Thanks for your time on this. I have done as you outlined. After
> > running forrest site in testSDocbook directory I again got
> the message
> > in the
> > console:
> >
> > BROKEN:
> > C:\apachefriends\xampp\htdocs\apache-forrest-0.7\plugins\plugins.xml
> > <The system cannot find the file specified>
> >
> > However all the plugins appeared to be retrieved and
> configured as you
> > describe.
>
> Yes the plugin download mechanism doesn't use a local copy of
> the file (neither does the docs build anymore, thanks to your
> report above).
>
> > I checked the distribution zip file for forrest and found that
> > \apache-forrest-0.7\plugins\plugins.xml was present, so
> copied it to
> > where it should have been in my installation. I re-ran forrest site
> > without problems.
>
> How can it have been present in the distribution but not in
> your installation? Is it safe for me to assume that this is a
> problem local to you rather than in the distribution.
Yes, safe to assume that. I have no explanation for it not being there in
the installation, but a local problem, yes.
> > I then ran forrest run in:
> >
> FORREST_HOME/build/plugins/org.apache.forrest.plugin.input.simplifiedD
> > ocbook without problems, and could view sdocbook.html and .pdf
> >
> > I then tried adding one of my own sdocbook documents, and again had
> > the problem of no content. I checked out input.xmap, and
> found that it
> > had a sourcetype of sdocbook-v1.0, whereas my documents are all
> > sdocbook-v1.1
> >
> > I assigned sdocbook-v1.0 to a couple of my documents, and
> they worked fine.
> >
> > I suppose it is possible to modify input.xmap so that will accept
> > sdocbook-v1.1 as well?
> >
> > Where should that be done?
>
> I've updated the plugin for version 4.1.2.5 of the plugin but
> there isn't a released 1.1 version that I can see (
> http://www.oasis-open.org/docbook/xml/simple/ ). What is the
> public identifier you are using?
I've been using a version from docbook.org which although it says it is
available at Oasis, actually isn't. It looks like I've mixed up the public
identifier in the following.
<!DOCTYPE article PUBLIC "-//OASIS//DTD Simplified DocBook XML V1.1//EN"
"http://docbook.org/xml/simple/1.1/sdocbook.dtd">
Perhaps I should revert to v1.0 for my documents?
>
> Once I know what we need to add I'll update the plugin. If
> you want to do this yourself (and supply a patch please) then
> take a look at input.xmap The supported DTD's are listed at
> the top of the file and you will need to add a matcher later
> in the file, it is pretty much a cut and past job.
>
Phil
Re: simplified docbook plugin (Was: Forrest run works but forrest
doesn't)
Posted by Ross Gardler <rg...@apache.org>.
Phillip Evans wrote:
It would really help if you make your replies inline as I am doing here.
If someone This keeps the context of our discussion so that I can
remember exactly what we are doing. I write many mails every day and I
have a short memory ;-)
It also helps make the archives much more readable, that is if a new
user has the same problem as you and comes to this mail in the archives
they will see a dialog that describes how to diagnose their problem
rather than a summary that you discovered the solution.
> Thanks for your time on this. I have done as you outlined. After running
> forrest site in testSDocbook directory I again got the message in the
> console:
>
> BROKEN: C:\apachefriends\xampp\htdocs\apache-forrest-0.7\plugins\plugins.xml
> <The system cannot find the file specified>
>
> However all the plugins appeared to be retrieved and configured as you
> describe.
Yes the plugin download mechanism doesn't use a local copy of the file
(neither does the docs build anymore, thanks to your report above).
> I checked the distribution zip file for forrest and found that
> \apache-forrest-0.7\plugins\plugins.xml was present, so copied it to where
> it should have been in my installation. I re-ran forrest site without
> problems.
How can it have been present in the distribution but not in your
installation? Is it safe for me to assume that this is a problem local
to you rather than in the distribution.
> I then ran forrest run in:
> FORREST_HOME/build/plugins/org.apache.forrest.plugin.input.simplifiedDocbook
> without problems, and could view sdocbook.html and .pdf
>
> I then tried adding one of my own sdocbook documents, and again had the
> problem of no content. I checked out input.xmap, and found that it had a
> sourcetype of sdocbook-v1.0, whereas my documents are all sdocbook-v1.1
>
> I assigned sdocbook-v1.0 to a couple of my documents, and they worked fine.
>
> I suppose it is possible to modify input.xmap so that will accept
> sdocbook-v1.1 as well?
>
> Where should that be done?
I've updated the plugin for version 4.1.2.5 of the plugin but there
isn't a released 1.1 version that I can see (
http://www.oasis-open.org/docbook/xml/simple/ ). What is the public
identifier you are using?
Once I know what we need to add I'll update the plugin. If you want to
do this yourself (and supply a patch please) then take a look at
input.xmap The supported DTD's are listed at the top of the file and you
will need to add a matcher later in the file, it is pretty much a cut
and past job.
> Might I suggest that on the initial plugins page on
> forrest.apache.org that a indication be placed above the download section
> that this is normally done automatically by forrest, rather than having to
> follow a link to a second page to find this out.
I've added a two sentence description on how to install plugins to the
page as you suggest, it will appear on the site next time we update.
> Still, I have learned heaps more than I would have if it had all gone
> smoothly, as it obviously does if done right. Next time, read the
> instructions, Phillip, read the instructions.
:-))
Ross
RE: simplified docbook plugin (Was: Forrest run works but forrest doesn't)
Posted by Phillip Evans <pe...@wukwuk.com>.
Ross,
Thanks for your time on this. I have done as you outlined. After running
forrest site in testSDocbook directory I again got the message in the
console:
BROKEN: C:\apachefriends\xampp\htdocs\apache-forrest-0.7\plugins\plugins.xml
<The system cannot find the file specified>
However all the plugins appeared to be retrieved and configured as you
describe.
I checked the distribution zip file for forrest and found that
\apache-forrest-0.7\plugins\plugins.xml was present, so copied it to where
it should have been in my installation. I re-ran forrest site without
problems.
I then ran forrest run in:
FORREST_HOME/build/plugins/org.apache.forrest.plugin.input.simplifiedDocbook
without problems, and could view sdocbook.html and .pdf
I then tried adding one of my own sdocbook documents, and again had the
problem of no content. I checked out input.xmap, and found that it had a
sourcetype of sdocbook-v1.0, whereas my documents are all sdocbook-v1.1
I assigned sdocbook-v1.0 to a couple of my documents, and they worked fine.
I suppose it is possible to modify input.xmap so that will accept
sdocbook-v1.1 as well?
Where should that be done?
It may have been that downloading the plugins manually meant that they were
not installed correctly. Might I suggest that on the initial plugins page on
forrest.apache.org that a indication be placed above the download section
that this is normally done automatically by forrest, rather than having to
follow a link to a second page to find this out.
Still, I have learned heaps more than I would have if it had all gone
smoothly, as it obviously does if done right. Next time, read the
instructions, Phillip, read the instructions.
Now to try out the testSDocbook site with some of my documents.
Thanks again, Ross.
I am using forrest-0.7
-----Original Message-----
From: Ross Gardler [mailto:rgardler@apache.org]
Sent: Wednesday, August 03, 2005 2:53 AM
To: user@forrest.apache.org
Subject: Re: simplified docbook plugin (Was: Forrest run works but forrest
doesn't)
Phillip Evans wrote:
> OK, here is the process I followed and the issues that I have found
> while getting forrest to work with sdocbook.
Once we have verified that this works (or debugged why it doesn't work)
we'll get your sdocbook files working in the new sample site we did.
Ross
Re: simplified docbook plugin (Was: Forrest run works but forrest
doesn't)
Posted by Ross Gardler <rg...@apache.org>.
Phillip Evans wrote:
> OK, here is the process I followed and the issues that I have found while
> getting forrest to work with sdocbook.
>
> I edited forrest.properties to include the sdocbook plugin and the Open
> Office plugin.
> I put a (validated) sdocbook file and an Open Office document into 'sample'
> directory of a freshly seeded site. (I also added some sdocbook files to a
> 'manuals' subdirectory of 'sample')
> I edited site.xml to give LH Navigation to these documents.
> I ran 'forrest' to build a static site. The build was unsuccessful due to
> some broken links.
> I downloaded plugin.xml from forrest.apache.org into the plugins directory
> as the build said that file was missing. (It took me a while to figure that
> out) I then got a successful build.
What build? the build of forrest or the build of your site? I've never
heard this one before.
There should be no need to download it manually, Forrest retrieves it
when necessary.
What version of Forrest are you using?
> The Open Office document converted OK,(except for images) but the sdocbook
> page had only the header and LH Navigation, no content. The build listing
> shows all plugins being available and mounts them.
>
> Following the documentation from "V5.2. How do I use DocBook as the xml
> documentation format?" as best as I was able with my limited knowledge, I
> made the following changes to sitemap.xmap in src/documentation/ :
...
> After which everything worked. I had presumed that just declaring the
> sdocbook plugin would do the trick. I needed to move sdocbook2document.xsl
> because of the <map:transform src= declaration I added above.
This is mixing two issues. That FAQ is about setting up separate
handling of docbook files. It has nothing to do with the sdocbook
plugin. You are correct in assuming that you just installing the
sdocbook plugin should work for you. I'd like to get to the bottom of
why it didn't work in your case, maybe you uncovered a bug:
You do not seem to have changed any core Forrest files so lets start again:
rm -RF FORREST_HOME/build/plugins
(this will remove all currently installed plugins)
rm the plugins.xml file you downloaded manually.
cd PROJECT_HOME
mkdir testSDocbook
cd testSDocbook
forrest seed
add org.apache.forrest.plugin.input.simplifiedDocbook to the
project.required.plugins property of forrest.properties file
forrest site
When forrest runs it should retrieve the sdocbook plugin from the
forrest site. If you get any errors such as the missing plugins.xml file
please post the relevant output from you the console in which you ran
the above command.
If you get no errors do this:
cd FORREST_HOME/build/plugins/org.apache.plugin.input.simplifiedDocbook
forrest run
http://localhost:8888/samples/sdocbook.html
This will load a page generated from a simplified docbook file in the
plugin docs.
I just did this with my Forrest install, this works just fine. However,
I am using SVN head so it would be great if you could test it with
whatever version of Forrest you are using.
Once we have verified that this works (or debugged why it doesn't work)
we'll get your sdocbook files working in the new sample site we did.
Ross
RE: simplified docbook plugin (Was: Forrest run works but forrest doesn't)
Posted by Phillip Evans <pe...@wukwuk.com>.
OK, here is the process I followed and the issues that I have found while
getting forrest to work with sdocbook.
I edited forrest.properties to include the sdocbook plugin and the Open
Office plugin.
I put a (validated) sdocbook file and an Open Office document into 'sample'
directory of a freshly seeded site. (I also added some sdocbook files to a
'manuals' subdirectory of 'sample')
I edited site.xml to give LH Navigation to these documents.
I ran 'forrest' to build a static site. The build was unsuccessful due to
some broken links.
I downloaded plugin.xml from forrest.apache.org into the plugins directory
as the build said that file was missing. (It took me a while to figure that
out) I then got a successful build.
The Open Office document converted OK,(except for images) but the sdocbook
page had only the header and LH Navigation, no content. The build listing
shows all plugins being available and mounts them.
Following the documentation from "V5.2. How do I use DocBook as the xml
documentation format?" as best as I was able with my limited knowledge, I
made the following changes to sitemap.xmap in src/documentation/ :
I added the following
--------------------------
<sourcetype name="sdocbook">
<document-declaration public-id="-//OASIS//DTD Simplified
DocBook XML V1.1//EN" />
</sourcetype>
--------------------------
After this existing section:
--------------------------
<map:when test="hello-v1.0">
<map:generate src="{project:content.xdocs}{../../1}.xml" />
<map:transform
src="{project:resources.stylesheets}/hello2document.xsl" />
<map:serialize type="xml-document"/>
</map:when>
--------------------------
I added this:
--------------------------
<map:when test="sdocbook">
<map:generate src="{project:content.xdocs}{../../1}.xml" />
<map:transform
src="{project:resources.stylesheets}/sdocbook2document.xsl" />
<map:serialize type="xml-document"/>
</map:when>
--------------------------
And I added this section:
--------------------------
<map:match pattern="**manuals/**.xml">
<map:generate src="{project:content.xdocs}{1}manuals/{2}.xml" />
<map:act type="sourcetype"
src="{project:content.xdocs}{1}manuals/{2}.xml">
<map:select type="parameter">
<map:parameter name="parameter-selector-test" value="{sourcetype}" />
<map:when test="sdocbook">
<map:transform
src="{project:resources.stylesheets}/sdocbook2document.xsl" />
</map:when>
</map:select>
</map:act>
<map:serialize type="xml"/>
</map:match>
--------------------------
After which everything worked. I had presumed that just declaring the
sdocbook plugin would do the trick. I needed to move sdocbook2document.xsl
because of the <map:transform src= declaration I added above.
Then I went back and commented out the bits I added, one at a time, and did
a fresh build each time. The match pattern section made no difference but
the sdocbook files were not built if either the source type or map generate
sections were left out. I presume the sdocbook plugin should modify this
file or override it somehow?
Perhaps my next exercise should be to do a reinstall of forrest and see if
this is repeatable. I would love to find out that there is an easier way.
Phil
Ps Just had a thought. I downloaded the plugins manually before modifying
forrest.properties, rather than letting forrest get them automatically when
needed. Perhaps that has affected the installation of the plugins?
-----Original Message-----
From: David Crossley [mailto:crossley@apache.org]
Sent: Tuesday, August 02, 2005 8:22 PM
To: user@forrest.apache.org
Subject: simplified docbook plugin (Was: Forrest run works but forrest
doesn't)
>
> It would skin blank pages until I moved that file.
> Is this due to a configuration error on my part?
Sorry i don't understand what you mean.
Have you declared the simplifiedDocbook plugin in your forrest.properties
file?
David
> Anyway, thank you for your assistance
>
> Phil
>