Date: 2004-07-16T04:12:09 Editor: FredericGlorieux <[EMAIL PROTECTED]> Wiki: Cocoon Wiki Page: XfolioXmlDoc URL: http://wiki.apache.org/cocoon/XfolioXmlDoc
no comment Change Log: ------------------------------------------------------------------------------ @@ -1,82 +1,97 @@ -''' 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 +---- +FredericGlorieux [[MailTo(frederic DOT glorieux AT xfolio DOT org)]] (c) 2003, 2004 + +(c) 2003, 2004 [http://xfolio.org xfolio.org], [http://www.ajlsm.com AJLSM], [http://www.strabon.org Strabon] , [http://www.eumedis.net Eumedis]. Licence : [http://www.apache.org/licenses/LICENSE-2.0 Apache]. +---- + +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 +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 ? +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 +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. An XSL template could be : ---------------- +{{{ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + += WHAT = -''' Little abstract: This is a cocoon sitemap [http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html] -... -'''------ + += WHO = 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. += HOW = + +How to use + += WHY = + +More on logic + += CHANGES = -= Changes = * 2004-07-14:[#SM] I'm alive = TODO = So much... -{{{ -<?xml version="1.0" encoding="UTF-8"?> -<!-- -''' +--> +<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"/> + +}}} + +'''with this effect''' +--------------- + += WHAT = + Little abstract: This is a cocoon sitemap [http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html] -... -'''------ + += WHO = 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. += HOW = + +How to use + += WHY = + +More on logic + += CHANGES = -= 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 = @@ -86,12 +101,10 @@ = See Also = -[[FullSearch()]] -[[PageList(docbook)]] -[[PageList(javadoc)]] -[[PageList(xfolio)]] -[[PageList(forrest)]] -[[PageList(chaperon)]] +|| '''about documentation''' || +|| [[PageList(docs|doco)]] || +|| '''cited by''' || with the authors || +|| [[FullSearch()]] || [[FullSearch('FredericGlorieux')]] ||
