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
