DTD Complication

[Maria Jones <jo...@bellsouth.net>]

I have done a new installation of forrest from CVS. I have previous 
documentation using various other dtds namely Oasis, SuSE, and KDE. The 
configuration of forrest validates good for the Oasis doc's however both KDE 
and SuSE are having issues.

Here's my take:
Oasis is using the included docbookx.dtd as configured. By default --- very 
nice!

I have included the SuSE dtd in the catalog.xcat file as instructed. Thus:

....

<public publicId="-//SuSE//DTD DocBook XML V4.2-Based Subset 0.1//EN"
        uri="susedtd/0.2.3/susex.dtd"/>
<public publicId="-//SuSE//DTD DocBook XML V4.2-Based Variant 0.1//EN"
        uri="susedtd/0.2.3/susex.dtd"/>

<public publicId="-//SuSE//ENTITIES DocBook HTML Additional General Entities 
V4.2//EN"
        uri="susedtd/0.2.3/susex.dbgenent-html.mod"/>
<public publicId="-//SuSE//ENTITIES DocBook LATEX Additional General Entities 
V4.2//EN"
        uri="susedtd/0.2.3/susex.dbgenent-latex.mod"/>
<public publicId="-//SuSE//ENTITIES DocBook Additional General Entities 
V4.2//EN"
        uri="susedtd/0.2.3/susex.dbgenent.mod"/>
<public publicId="-//SuSE//ENTITIES DocBook International Entities V4.2//EN"
        uri="susedtd/0.2.3/susex.i10n.mod"/> 
....

I have placed the dtd and modules into the 
${forrest_root}/src/core/context/resources/schema/ directory. And the 
appropriate files are located in the sub-directories as specified. 

If i open up my test xml file in kate, and validate against the local dtd; all 
seems good to go. I've tried it with using the original dtd's from my root 
( /usr/share/xml/docbook/custom/susedtd/0.2.3/schema/dtd/susex.dtd ), and/or 
the forrest copy 
( ${forrest_root}/src/core/context/resources/schema/susedtd/0.2.3/susex.dtd ) 
---- shouldn't matter but both validate ok when specified.

File DOCTYPE is as follows:

....
<!DOCTYPE book PUBLIC "-//SuSE//DTD DocBook XML V4.2-Based Variant 0.1//EN" 
"/usr/share/xml/docbook/custom/susedtd/0.2.3/schema/dtd/susex.dtd" []>
....

So i included my test file in site.xml. As such:

....
<susex label="SuSE Docbook" href="test-susex.html" description="SuSE 
example" />
....

Enter my website root of test site. Now i run 'forrest validate' ---- BUILD 
SUCCESSFUL. Then  i run 'forrest' ---- BUILD SUCCESSFUL again.

So i navigate to my "new" page and voila! No content? What am i missing?

Thanks for your time.

Re: DTD Complication

[David Crossley <cr...@apache.org>]

Maria Jones wrote:
> David Crossley wrote:
> > Maria Jones wrote:
> > > I have done a new installation of forrest from CVS.
> >
> > I hope that you are aware that Forrest does not use CVS
> > anymore. If you are using CVS, then you are using very
> > old sources. http://forrest.apache.org/faq.html#cvs
> <snip>
> 
> My bad! Wrong choice of words --- i have pulled using Subversion. Oops!

Good.

> > The way that you have configured this will still work,
> > but is not advisable. You should not mess with the Forrest
> > source itself. You say "as advised", but i do not think
> > that our documentation says to add to Forrest's internal
> > catalog.
> >
> > You can provide a dedicated catalog.xcat for your project.
> > See below.
> >
> > The current head version of SVN has even better ways to
> > configure your local DTDs.
> 
> I reviewed the documentation and it does not state to uncomment the varaible 
> in forrest.properties. Thus i assumed, that it should be added to the 
> internal catalog. It is implied now that i look at it, but doesn't jump out 
> at the new user. Might need to review the docs.

No need to un-comment the variables unless you need to change them.
They are the defaults.

> > You need to follow the document "Using Forrest" your-project.html
> > It describes the steps to deal with a new document type.
> > It sounds like you have not added a "sitemap" to your project
> > which is needed to detect your new document type.
> 
> Also, review the following text from 
> http://forrest.apache.org/docs/your-project.html#sitemap.xmap:
> 
> <snip>
> If your site defines its own sitemap, it must perform all the operations of 
> the Forrest default. To get started, simply copy the Forrest sitemaps from 
> xml-forrest/src/resources/conf/*.xmap into your src/documentation directory 
> (or wherever ${project.sitemap-dir} points to).
> </snip>
> 
> This references a directory structure that does not exist. Rather, it should 
> reference ${xml-forrest}/src/core/context/*.xmap. Or at least that i got out 
> of it. :)

Correct. Ah, you have caught us toward the end of a re-organisation
and the docs need to catch up.

> BTW, i need not change anything in sitemap.xmap, but i did make the neccessary 
> stylesheet declarations in forrest.xmap which is sourced from sitemap.xmap. 
> Just as you had expected --- this was my problem.

Glad that you have found it. BTW you do not need to copy all
sitemaps, just the particular ones that you need to change.

> And believe it or not, this did the job. Great work David!!!!

We believe it.

> > By the way, do not expect Forrest to deal with all possible
> > DocBook elements, especially extensions.
> > See http://forrest.apache.org/faq.html#docbook
> >
> > I hope that helps. If not then keep asking questions.
> 
> My sole purpose is to build a repository for Linux Documentation. But more 
> user friendly. I own the Linux-Howtos.com domain. I currently have a database 
> of well over 13,000 Linux documentation source. Generating almost 8 GB's of 
> mirrored local documentation sources. I would like to eventually build a XML 
> database of it all; but that is WAY down the road. And i decided to change my 
> CMS to XML-based --- given Forrest is well known, and OS community oriented 
> ---- it was my first choice. 

Welcome, we need to evolve with use cases such as yours.

You do not need to have xml docs to work with Forrest, as long
as they have some structure.

> Anyways, i have documented my failures and/or successes throughout the 
> process; if you would like to utilize them for documentation review and/or 
> development i can forward it later.I intend to contribute my findings to the 
> community as i develop the site further.

Oh please do. We always need help with docs, especially from
user experience. Do what i did when started with opensource,
and still do. As you read the Forrest docs via your local
'forrest run', edit the xml source when you spot a problem.
Run 'build patch' and add it to our Jira Issue tracker.
Its a great way to learn Forrest and immediately contribute.

Sure send us your notes too.

--David


> Great product -- and good work! Thanks very much! ;)

Re: DTD Complication

[Maria Jones <jo...@bellsouth.net>]

On Thursday 17 June 2004 21:00, David Crossley wrote:
> Maria Jones wrote:
> > I have done a new installation of forrest from CVS.
>
> I hope that you are aware that Forrest does not use CVS
> anymore. If you are using CVS, then you are using very
> old sources. http://forrest.apache.org/faq.html#cvs
<snip>

My bad! Wrong choice of words --- i have pulled using Subversion. Oops!

>
> The way that you have configured this will still work,
> but is not advisable. You should not mess with the Forrest
> source itself. You say "as advised", but i do not think
> that our documentation says to add to Forrest's internal
> catalog.
>
> You can provide a dedicated catalog.xcat for your project.
> See below.
>
> The current head version of SVN has even better ways to
> configure your local DTDs.

I reviewed the documentation and it does not state to uncomment the varaible 
in forrest.properties. Thus i assumed, that it should be added to the 
internal catalog. It is implied now that i look at it, but doesn't jump out 
at the new user. Might need to review the docs.

>
> You need to follow the document "Using Forrest" your-project.html
> It describes the steps to deal with a new document type.
> It sounds like you have not added a "sitemap" to your project
> which is needed to detect your new document type.
>

Also, review the following text from 
http://forrest.apache.org/docs/your-project.html#sitemap.xmap:

<snip>
If your site defines its own sitemap, it must perform all the operations of 
the Forrest default. To get started, simply copy the Forrest sitemaps from 
xml-forrest/src/resources/conf/*.xmap into your src/documentation directory 
(or wherever ${project.sitemap-dir} points to).
</snip>

This references a directory structure that does not exist. Rather, it should 
reference ${xml-forrest}/src/core/context/*.xmap. Or at least that i got out 
of it. :)

BTW, i need not change anything in sitemap.xmap, but i did make the neccessary 
stylesheet declarations in forrest.xmap which is sourced from sitemap.xmap. 
Just as you had expected --- this was my problem. And believe it or not, this 
did the job. Great work David!!!!

> By the way, do not expect Forrest to deal with all possible
> DocBook elements, especially extensions.
> See http://forrest.apache.org/faq.html#docbook
>
> I hope that helps. If not then keep asking questions.

My sole purpose is to build a repository for Linux Documentation. But more 
user friendly. I own the Linux-Howtos.com domain. I currently have a database 
of well over 13,000 Linux documentation source. Generating almost 8 GB's of 
mirrored local documentation sources. I would like to eventually build a XML 
database of it all; but that is WAY down the road. And i decided to change my 
CMS to XML-based --- given Forrest is well known, and OS community oriented 
---- it was my first choice. 

Anyways, i have documented my failures and/or successes throughout the 
process; if you would like to utilize them for documentation review and/or 
development i can forward it later.I intend to contribute my findings to the 
community as i develop the site further.

Great product -- and good work! Thanks very much! ;)

Re: DTD Complication

[David Crossley <cr...@apache.org>]

Maria Jones wrote:
> I have done a new installation of forrest from CVS.

I hope that you are aware that Forrest does not use CVS
anymore. If you are using CVS, then you are using very
old sources. http://forrest.apache.org/faq.html#cvs

More below.

> I have previous 
> documentation using various other dtds namely Oasis, SuSE, and KDE. The 
> configuration of forrest validates good for the Oasis doc's however both KDE 
> and SuSE are having issues.
>
> Here's my take:
> Oasis is using the included docbookx.dtd as configured. By default --- very 
> nice!
> 
> I have included the SuSE dtd in the catalog.xcat file as instructed. Thus:
> 
> ....
> 
> <public publicId="-//SuSE//DTD DocBook XML V4.2-Based Subset 0.1//EN"
>         uri="susedtd/0.2.3/susex.dtd"/>
> <public publicId="-//SuSE//DTD DocBook XML V4.2-Based Variant 0.1//EN"
>         uri="susedtd/0.2.3/susex.dtd"/>
> 
> <public publicId="-//SuSE//ENTITIES DocBook HTML Additional General Entities 
> V4.2//EN"
>         uri="susedtd/0.2.3/susex.dbgenent-html.mod"/>
> <public publicId="-//SuSE//ENTITIES DocBook LATEX Additional General Entities 
> V4.2//EN"
>         uri="susedtd/0.2.3/susex.dbgenent-latex.mod"/>
> <public publicId="-//SuSE//ENTITIES DocBook Additional General Entities 
> V4.2//EN"
>         uri="susedtd/0.2.3/susex.dbgenent.mod"/>
> <public publicId="-//SuSE//ENTITIES DocBook International Entities V4.2//EN"
>         uri="susedtd/0.2.3/susex.i10n.mod"/> 
> ....
> 
> I have placed the dtd and modules into the 
> ${forrest_root}/src/core/context/resources/schema/ directory. And the 
> appropriate files are located in the sub-directories as specified. 
> 
> If i open up my test xml file in kate, and validate against the local dtd; all 
> seems good to go. I've tried it with using the original dtd's from my root 
> ( /usr/share/xml/docbook/custom/susedtd/0.2.3/schema/dtd/susex.dtd ), and/or 
> the forrest copy 
> ( ${forrest_root}/src/core/context/resources/schema/susedtd/0.2.3/susex.dtd ) 
> ---- shouldn't matter but both validate ok when specified.

The way that you have configured this will still work,
but is not advisable. You should not mess with the Forrest
source itself. You say "as advised", but i do not think
that our documentation says to add to Forrest's internal
catalog.

You can provide a dedicated catalog.xcat for your project. 
See below.

The current head version of SVN has even better ways to
configure your local DTDs.

> File DOCTYPE is as follows:
> ....
> <!DOCTYPE book PUBLIC "-//SuSE//DTD DocBook XML V4.2-Based Variant 0.1//EN" 
> "/usr/share/xml/docbook/custom/susedtd/0.2.3/schema/dtd/susex.dtd" []>
> ....
> 
> So i included my test file in site.xml. As such:
> 
> ....
> <susex label="SuSE Docbook" href="test-susex.html" description="SuSE 
> example" />
> ....
> 
> Enter my website root of test site. Now i run 'forrest validate' ---- BUILD 
> SUCCESSFUL. Then  i run 'forrest' ---- BUILD SUCCESSFUL again.

The DTD configuration and validation is obviously
working then.

> So i navigate to my "new" page and voila! No content? What am i missing?

You need to follow the document "Using Forrest" your-project.html
It describes the steps to deal with a new document type.
It sounds like you have not added a "sitemap" to your project
which is needed to detect your new document type.

By the way, do not expect Forrest to deal with all possible
DocBook elements, especially extensions.
See http://forrest.apache.org/faq.html#docbook

I hope that helps. If not then keep asking questions.

--David