forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <je...@apache.org>
Subject Re: docbook; user question
Date Wed, 08 Oct 2003 10:31:22 GMT
On Tue, Oct 07, 2003 at 03:00:06PM -0700, R Parker wrote:
> Hi,
> 
> First, I've installed and have a preliminary forrest
> based site running. Excellent solution. Thanks!
> 
> Disclaimer: there isn't a forrest-user list yet so I'm
> posting to your dev list. Sorry.
> 
> I've got a multiple part and chapter book marked up as
> docbook-xml. I'd like to put it into xdocs/jam and
> have it magically turn into my book. Here's book.xml:

Ah, did you actually call it 'book.xml'?  That is unfortunately a
reserved filename in Forrest.  Our old pre-site.xml menu system used
per-directory book.xml files.

> <?xml version="1.0" standalone="yes"?>
>     <!DOCTYPE book PUBLIC "-//Norman Walsh//DTD DocBk
> XML V4.1.2//EN"
>        
> "/usr/share/sgml/docbook/xml-dtd-4.1.2/docbookx.dtd" [
...
> </book>
> 
> Here's the error:
> validate-xdocs:
> /home/httpd/htdocs/forrest/src/documentation/content/xdocs/jam/accoustics.xml:1:26:
> Document root element "chapter", must match DOCTYPE
> root "null".
> /home/httpd/htdocs/forrest/src/documentation/content/xdocs/jam/accoustics.xml:1:26:
> Document is invalid: no grammar found.
> 
> Well that's to be expected because accoustics.xml by
> itself is not a valid xml file. The entire book is
> valid xml but documents like accoustics.xml are all
> linked into the above book.xml file which must be read
> before accoustics.xml--obviously I'm not a markup
> language expert just a writer so please tolerate my
> ignorance.

Well you've diagnosed the problem with accoustics.xml correctly.  The
easiest solution is to just turn off validation of subsections.  This can
be done with a pattern in forrest.properties:

http://xml.apache.org/forrest/validation.html

The included XML files will still be validated when the File Formerly
Known As book.xml is validated.


In general though, I have serious doubts over whether Forrest is a good
choice for rendering large amounts of Docbook.  Its native support is _very_
minimal.  For any serious usage, you'll need to download the proper
Docbook XSLTs and tell Forrest to use them:

http://xml.apache.org/forrest/faq.html#docbook

If your site is predominantly generated from Docbook, then Forrest
doesn't add much value.  IMO we should remove the docbook2document.xsl to
avoid misleading people such as yourself.


--Jeff

PS: I think it's 'acoustics', not 'accoustics'.

> Here's site.xml entry:
> <jam label="jam" href="jam/" tab="jam">
>     <index label="jam" href="jam.html"
> description="jam"/>
>   </jam>
> 
> And the tabs.xml entry:
> <tab id="jam" label="jam" dir="jam"
> indexfile="book.html"/>
> 
> I suspect anyone can read the above and immediately
> know what I'm trying to do and why it doesn't work and
> what needs to be done to achieve my objective.
> 
> BTW, I followed the sdocbook sample file and got a
> couple documents working and expect that I'm using
> tags that aren't defined in sdocbook. That's fine,
> I'll edit the book to comply and convert .png files to
> .jpg, etc.
> 
> ron
> 

Mime
View raw message