forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <nicola...@apache.org>
Subject Re: status of doc generation
Date Sat, 03 Aug 2002 21:02:54 GMT

Peter Donald wrote:
>
> I'll reiterate what I want again. 

Thank you, it will help me focus better on real needs.
I'm CCing this to Forrest-dev too.

> * Simple task to call so I can have different pipelines (changes vs normal 
> document vs faqs) work.

We are discussing on how to make the user enhance the system using 
mounted pipelines.
Given that Forrest already has enhanced FAQ, TODO, CHANGES DTDs, for the 
moment it should be enough, and we can always discuss and insert new 
DTDs in Forrest quite quickly, given that they are general enough (which 
  is generally the case).

> * I want to be able to include/exclude files based on ant includes/ecludes

Since Cocoon crawles the docs, IMHO it basically means that you want 
Cocoon not to proceed crawling on certain url patterns... can be done, 
but could you please tell me the use, it's not clear to me.

> * I want only the files that have been changed to be updated

Definately. I'm working on it.

> * I want zero copying about

Forrest CVS now doesn't need copying anymore.

> * I want 15 second build time max

ie fast... once you have non-updated files not recreating, incremental 
builds will be much faster than that.

> * I want to be able to have all the links in menu to be relative to base of 
> site, not base of page they are in. SO I can put docs in bdg/foo.xml and has 
> all links work gracefully

This is more an implementation request than a feature request...
as per feature, IMHO it boils down to the fact that in nested books we 
do ../../..etc to reference parent books, which IMNSHO really sucks...

Any suggestion from Forresters? This is a tipical URI-space problem, 
suggestions?

> * I want no dates or build specific data to be stored in generated docs 
> (because causes pain when updating online docs).

Sorry, I don't get this. Could you elaborate more?
Anyway, Forrest will update the site for you, so it shouldn't be a 
problem...

> * I want nice output. Similar to ...
> [cocoon] Generating doc: foo.html
> [cocoon] Generating doc: bdg/foo.html
> [cocoon] Error Generating doc: bar.html (<a> on line 15 must be terminated 
> with a </>)

As per your request I put it in, but Berin got angry over it being to 
verbose... *shrugs* just add --verbose and it should be more informative 
now.

> One thing that I have not said before but I would like to have is the 
> following. I would like to be able to add in a construct like
> 
> <code-link class="org.apache.avalon.framework.Version">the Version</code-link>

> or <code-link class="org.apache.avalon.framework.Version"/> (which defaults 
> to using short classname as text for link). This would then link to the 
> appropriate uri for class javadoc. I would like it to work in a way similar 
> to javadoc links. So you can have multiple api base dirs (ie phoenix docs 
> could link to framework code).

This is a very cool thing, and interrelated with the URI problem above.

If we tell the system that the javadocs are at a certain URI, we don't 
even need special semantics.

The real problem is, how can we tell Forrest to play well with other 
tools and integrate the URI space?
Let's start with Javadocs, once that is done we can integrate all sorts 
of stuff like unit tests an metrics.

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------


Mime
View raw message