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 (Was: Forrest run works but forrest doesn't)
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:[EMAIL PROTECTED]
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
RE: simplified docbook plugin (Was: Forrest run works but forrest doesn't)
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:[EMAIL PROTECTED] 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)
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)
-Original Message- From: Ross Gardler [mailto:[EMAIL PROTECTED] 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
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
