xml-xmlbeans-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Turner <je...@apache.org>
Subject Re: XMLBeans website
Date Wed, 24 Sep 2003 11:07:07 GMT
On Tue, Sep 23, 2003 at 05:49:44PM -0700, David Remy wrote:
> Thanks Jeff.  Your post was very helpful.
> > 
> > Yes, most projects have the 'source' for their documentation 
> > (XML) in the
> > source tree, and then the actual rendered HTML/PDF 
> > documentation in the
> > separate 'xml-site' CVS module.
> > 
> I assume most projects have some documentation, like javadoc and/or
> user doc, in html format somewhere in their source tree like XMLBeans
> does.

The javadoc wouldn't be in the source tree, or required for generation of
the website.  Forrest can be told to ignore certain URLs:

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

This allows javadoc and website to be generated independently.

> I have created a separate top level directory (not committed
> yet) for the XMLBeans website.  Is it possible to have forrest
> copy/read the .html files from their home directory in the main source
> tree and copy them into a specific location in the src/../xdocs tree
> changing their name from .html to .ehtml and then cleaning up after?

There's nothing that does this currently.  Some projects (like Cocoon
[1]) have an Ant script which prepares a customised directory of docs for
Forrest to use, and then invoke Forrest:

<target name="docs" depends="...">
    <ant antfile="${forrest.home}/forrest.antproxy.xml" target="site"/>
</target>

It's a bit ugly though.  Adding pre/post-render hooks to Forrest would be
a useful feature.


Taking a broader perspective..

Practically, isn't this mostly a rebranding exercise?  Adopt Forrest so
the site fits in with the rest of xml.apache.org?  Without "committing"
to Forrest (rewriting all docs in XML), you won't get any benefits of
Forrest (PDFs and whatnot), but will still accrue the costs.

I would suggest looking at how the Ant project generates docs.  The Ant
site's skin would fit into xml.apache.org (see http://ant.apache.org).
The documentation format is HTML with a few custom tags, so you wouldn't
need to drastically alter the existing xmlbeans documentation.  It's also
a much simpler, faster system than Forrest, fine if your website is
simple.

Alternatively if you'd like to stick with Forrest, we're happy to work on
features xmlbeans needs (pre/post hooks to start with).


Cheers,

--Jeff

[1] http://cvs.apache.org/viewcvs.cgi/cocoon-2.1/src/targets/forrest-build.xml?rev=HEAD&content-type=text/vnd.viewcvs-markup

...
> 
> rem

- ---------------------------------------------------------------------
To unsubscribe, e-mail:   xmlbeans-dev-unsubscribe@xml.apache.org
For additional commands, e-mail: xmlbeans-dev-help@xml.apache.org
Apache XMLBeans Project -- URL: http://xml.apache.org/xmlbeans/


Mime
View raw message