[Cocoon Wiki] New: XfolioXmlDoc

[do...@cocoon.apache.org]

   Date: 2004-07-14T06:12:15
   Editor: FredericGlorieux <fr...@xfolio.org>
   Wiki: Cocoon Wiki
   Page: XfolioXmlDoc
   URL: http://wiki.apache.org/cocoon/XfolioXmlDoc

   p

New Page:

'''
We know how useful are javadocs. Cocoon users are also important
XML code producers (*.xmap, *.xsl, *.xsp ...). Problem is, there is not yet a standard way
to comment such code. Is a kind of "xmldoc" possible ?
'''----
FredericGlorieux [[MailTo(frederic DOT glorieux AT xfolio DOT org)]] (c) 2003, 2004 xfolio.org, ajlsm.com, strabon.org
[http://www.gnu.org/copyleft/gpl.html GPL]

After create and maintain different Cocoon Apps, with different people, I definitely wait for the best 
solution to document XML code files. Think especially about XSL, where you can find very clever and tricky 
XPath expression, so that it is quite impossible to understand them 3 months after (Imagine I have in more
than one place things like {{{<!-- It works, but can't remember how -->}}}.

Docbook Project have probably the longest experience of a big XSL project to administrate, with so much users that
the pack had to be documented in a full book. I spent time to understand their logic, interesting. A namespace
in XSL is devoted to documentation. But this can't be a generic solution for all kind of XML code files. Have you ever 
try to mix contents in {{{*.xmap <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"/>}}} ?

The best is then probably to keep it simple, and use what is done for : {{{<!-- the comments -->}}}. So, inside, only text,
no tags. By the way, isn't it the kind of syntax of this Wiki ? 
Instead of the every time licence declaration, the first comment could be a complete Wiki page describing the file ? Perhaps some knows,
but Cocoon is also able to parse such things (forrest, chaperon). So it's perhaps possible to begin a simple light XML Code Documentation 
System, so for each files wwe can get some thing like

---------------

'''
Little abstract:
This is a cocoon sitemap [http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html]
...
'''------

Copyright 1999-2004 The Apache Software Foundation
[http://www.apache.org/licenses/LICENSE-2.0 Apache Licence]

= Authors =
 * [[Anchor(SM)]]StefanoMazzocchi [[MailTo(stephano AT apache DOT org)]]

= Logic =
Explain the main concepts.

= Changes =
 * 2004-07-14:[#SM]  I'm alive

= TODO =

So much...

{{{
<?xml version="1.0" encoding="UTF-8"?>
<!--
'''
Little abstract:
This is a cocoon sitemap [http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html]
...
'''------

Copyright 1999-2004 The Apache Software Foundation
[http://www.apache.org/licenses/LICENSE-2.0 Apache Licence]

= Authors =
 * [[Anchor(SM)]]StefanoMazzocchi [[MailTo(stephano AT apache DOT org)]]

= Logic =
Explain the main concepts.

= Changes =
 * 2004-07-14:[#SM]  I'm alive

= TODO =

So much...

-->
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"/>

}}}

'''An idea for your templates ?''' 

= References =

 * [http://java.sun.com/j2se/1.5.0/docs/guide/javadoc/ Javadoc]
 * [http://docbook.org/ Docbook]
 * [http://docbook.sourceforge.net/projects/xsl/ Docbook xsl]

= See Also =

[[FullSearch()]]
[[PageList(docbook)]]
[[PageList(javadoc)]]
[[PageList(xfolio)]]
[[PageList(forrest)]]
[[PageList(chaperon)]]