Re: status of doc generation

[Nicola Ken Barozzi <ni...@apache.org>]

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)
---------------------------------------------------------------------

Re: status of doc generation

[Nicola Ken Barozzi <ni...@apache.org>]

Peter Donald wrote:
> On Sun, 4 Aug 2002 07:02, Nicola Ken Barozzi wrote:
> 
>>>* 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).
> 
> kool.

Yup, and is also a big help for us :-)

>>>* 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 don't want cocoon to crawl at all ;) 

Maybe I will delude you ;-) but Cocoon can generate using a file with a 
list of links basically since day one of the Cocoon CLI.
Nobody really liked it much though.

> I find it much easier to 
> include/exclude things explicitly using ant include/exclude. Then I can work 
> out exactly which pages will be transformed without worrying whether the 
> links to all pages a re present.

This can be done by making an html page that contains all the pages you 
want to generate as html links, or specify Cocoon not to crawl the links 
further with a CLI option.

Anyway, CLI was made not to stop on dead links but to warn and make a 
404 page instead, something that somehow has been broken or ages and 
that I'm gonna fix very soon.

>>>* 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?
> 
> Anakias project.xml file has the links that are relative to the base project 
> dir start with a "/" if that helps any.

BTW, there is a new Transformer that augments links:

     <map:transform type="augment">
       <map:parameter name="mount" value="samples/flow/"/>
     </map:transform>

Anyway, this is a task for libre, we need to get it right, guys!
Come on private Gump, get the toothbrush! ;-)

>>>* 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?
> 
> 
> Essentially theres a few tools that add something like
> 
> <!-- Created by Cocoon on 15'th Dec 1987 -->
> 
> on end of page. Not sure if cocoon does it or not. The problem with this is of 
> course that almost every page will be different if the site is regenerated 
> but many of the changed files would only have a different date if you know 
> what I mean.

Right.
Cocoon does it only if an option is set, and Forrest deosn't use it, so 
it should be all ok.

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


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>

Re: status of doc generation

[Nicola Ken Barozzi <ni...@apache.org>]

Peter Donald wrote:
> On Sun, 4 Aug 2002 07:02, Nicola Ken Barozzi wrote:
> 
>>>* 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).
> 
> kool.

Yup, and is also a big help for us :-)

>>>* 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 don't want cocoon to crawl at all ;) 

Maybe I will delude you ;-) but Cocoon can generate using a file with a 
list of links basically since day one of the Cocoon CLI.
Nobody really liked it much though.

> I find it much easier to 
> include/exclude things explicitly using ant include/exclude. Then I can work 
> out exactly which pages will be transformed without worrying whether the 
> links to all pages a re present.

This can be done by making an html page that contains all the pages you 
want to generate as html links, or specify Cocoon not to crawl the links 
further with a CLI option.

Anyway, CLI was made not to stop on dead links but to warn and make a 
404 page instead, something that somehow has been broken or ages and 
that I'm gonna fix very soon.

>>>* 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?
> 
> Anakias project.xml file has the links that are relative to the base project 
> dir start with a "/" if that helps any.

BTW, there is a new Transformer that augments links:

     <map:transform type="augment">
       <map:parameter name="mount" value="samples/flow/"/>
     </map:transform>

Anyway, this is a task for libre, we need to get it right, guys!
Come on private Gump, get the toothbrush! ;-)

>>>* 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?
> 
> 
> Essentially theres a few tools that add something like
> 
> <!-- Created by Cocoon on 15'th Dec 1987 -->
> 
> on end of page. Not sure if cocoon does it or not. The problem with this is of 
> course that almost every page will be different if the site is regenerated 
> but many of the changed files would only have a different date if you know 
> what I mean.

Right.
Cocoon does it only if an option is set, and Forrest deosn't use it, so 
it should be all ok.

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

Re: status of doc generation

[Peter Donald <pe...@apache.org>]

On Sun, 4 Aug 2002 07:02, Nicola Ken Barozzi wrote:
> > * 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).

kool.

> > * 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 don't want cocoon to crawl at all ;) I find it much easier to 
include/exclude things explicitly using ant include/exclude. Then I can work 
out exactly which pages will be transformed without worrying whether the 
links to all pages a re present.

> > * 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?

Anakias project.xml file has the links that are relative to the base project 
dir start with a "/" if that helps any.

> > * 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?

Essentially theres a few tools that add something like

<!-- Created by Cocoon on 15'th Dec 1987 -->

on end of page. Not sure if cocoon does it or not. The problem with this is of 
course that almost every page will be different if the site is regenerated 
but many of the changed files would only have a different date if you know 
what I mean.

-- 
Cheers,

Peter Donald
-----------------------------------------------
"Only two things are infinite, the universe and 
human stupidity, and I'm not sure about the 
former." -Albert Einstein 
----------------------------------------------- 


--
To unsubscribe, e-mail:   <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>