cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Reinhard Poetz <reinh...@apache.org>
Subject Re: [proposal] Cocoon documentation system
Date Mon, 17 Jan 2005 10:09:13 GMT
Nicola Ken Barozzi wrote:
> Reinhard Poetz wrote:
> 
>>
>> At http://wiki.apache.org/cocoon/CocoonDocumentationSystem I propose 
>> the architecture of a new extensible documentation system. 
> 
> 
> I am *strongly* in favor of plain html

I know :-)

> as a source, as Forrest renders 
> it nicely; the Incubator website is now all using html as a source format.

After some thinking I propose supporting both formats. I think the HTML format 
is not necessary after the web appolication has gone online, but until we reach 
this point, HTML is very useful.
(We can make Forrest fail, if there is the content in both formats available.)

> Also, I don't see the need for a separate metadata file, which would 
> duplicate stuff that is in SVN and in the source file.

It's not only about author and date. It's also about status, target audience and 
keywords. I'm in favor of having this information explicit marked up in useful 
XML. This simplifies the publishing process (guarantee a consistent layout) and 
in the future queryable.

> Comment file handling can be added as a Forrest plugin; I prefer it 
> separate because in fact it *is* separate. Maybe putting the comments in 
> a doc.comments directory, with each a separate html file would be nice.

In my sample repository I used a custom sitemap which does the aggreagation. 
Pretty simple. See 
http://svn.apache.org/repos/asf/cocoon/whiteboard/doc-repos/2.2/src/documentation/sitemap.xmap

> I added my comments to the Wiki BTW.

Thanks. Find my answers in the Wiki too.

-- 
Reinhard

Mime
View raw message