Writing docs... Where shall I put that?

[Pier Fumagalli <pi...@betaversion.org>]

I need to write some docs for the HttpProxyGenerator, and was wondering on
where I shall put those files...

As Stefano is remodeling the build system, would it be better to have it in
src/blocks/proxy/doc or in src/documentation/... ????

I tend to believe that it might be better to have the documentation bundled
together with the block, but then the build system for the webapp should
change as well...

Hints?

    Pier


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org

Re: Writing docs... Where shall I put that?

[Niclas Hedhman <ni...@hedhman.org>]

On Wednesday 19 February 2003 02:24, Pier Fumagalli wrote:
> I need to write some docs for the HttpProxyGenerator, and was wondering on
> where I shall put those files...
>
> As Stefano is remodeling the build system, would it be better to have it in
> src/blocks/proxy/doc or in src/documentation/... ????
>
> I tend to believe that it might be better to have the documentation bundled
> together with the block, but then the build system for the webapp should
> change as well...

Doesn't the Block spec need to include how the Block Doc should be structured?

All blocks will not be part of the main documentation, yet must be as easily 
available to the Cocoon users as the main documentation.
Documentation for non-available blocks should not show up.

Niclas

---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org

Re: Writing docs... Where shall I put that?

[Stefano Mazzocchi <st...@apache.org>]

Pier Fumagalli wrote:
> I need to write some docs for the HttpProxyGenerator, and was wondering on
> where I shall put those files...
> 
> As Stefano is remodeling the build system, would it be better to have it in
> src/blocks/proxy/doc or in src/documentation/... ????
> 
> I tend to believe that it might be better to have the documentation bundled
> together with the block, but then the build system for the webapp should
> change as well...
> 
> Hints?

I think it would be wise to have the block documentation associated with 
the block. That would make the documentation modular to fit the new 
module-oriented paradigm we are heading to.

But I would suggest to do this *after* I have the basic new build system 
up and running, so for now, place it in the main documentation.

-- 
Stefano Mazzocchi                               <st...@apache.org>
    Pluralitas non est ponenda sine necessitate [William of Ockham]
--------------------------------------------------------------------



---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org

Re: Writing docs... Where shall I put that?

[Diana Shannon <sh...@apache.org>]

On Tuesday, February 18, 2003, at 01:24  PM, Pier Fumagalli wrote:

> As Stefano is remodeling the build system, would it be better to have 
> it in
> src/blocks/proxy/doc or in src/documentation/... ????

I'd say src/documentation for now, in spite of its imperfections... 
Otherwise, the doc won't be published on the web. Also, users may not 
know to look for it in its block.

> I tend to believe that it might be better to have the documentation 
> bundled
> together with the block, but then the build system for the webapp should
> change as well...

I agree with you, but we can always refactor (move docs, etc.) down the 
road when better documentation build options become available/finalized.

Diana


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org