cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d...@cocoon.apache.org
Subject [Cocoon Wiki] Updated: XfolioXmlDoc
Date Fri, 16 Jul 2004 11:12:10 GMT
   Date: 2004-07-16T04:12:09
   Editor: FredericGlorieux <frederic.glorieux@xfolio.org>
   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')]] ||
 
 

Mime
View raw message