Re: simplified docbook plugin

[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

[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

[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

[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

[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

[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

[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