On 1/4/06, Jörn Nettingsmeier <[EMAIL PROTECTED]> wrote: > [EMAIL PROTECTED] wrote: > > On 1/3/06, Bob Harner <[EMAIL PROTECTED]> wrote: > >> As for comments within files, it might be worthwhile to more carefully > >> consider how this is structured, rather than just putting plain text > >> inside of comment tags. It would be nice to have the internal > >> documentation in these files be extractable (someday) by a program, in > >> the same way that javadoc documentation is easily extractable from > >> java source code. See > >> http://www.codeproject.com/soap/xsltdocumentor.asp an example of such > >> a program for XSLT files in particular. Does anyone else have any > >> suggestions in this area? We will need a syntax for documenting xslt > >> and xmap files especially. > > > > You inspired me. > > http://solprovider.com/lenya/xsltdoc > > > > Is that a useful start? It does not expect any special tags, but we > > could parse comments to decide how or if to display them. Some of my > > test files have code commented out, and having the obsolete code in > > the documentation is annoying. > > sexy. ++votes. > > how about cloning javadoc's syntax and combining it with the categories > i proposed earlier (see > http://wiki.apache.org/lenya/CategoriesForFileDocumentation) ? > > i.e. an xmldoc comment could look like this: > <!--- > - @parsed_during page request > - @modification_by_admin mandatory > - > --> > > or maybe > <!--* @<category> <content> > * @<category> <content> > *--> > > ?
I agree with borrowing from Javadoc where useful and natural, but I'm inclined to prefer an XML-based syntax for the documentation within XML files, if possible. That might make it easier for XML-based tools like solprovider's to handle them. Also, I feel that internal documentation usually shouldn't say much about the context in which the file is used, since changes external to the file would then (and often do) make the documentation wrong. I wonder if the headings proposed at http://wiki.apache.org/lenya/CategoriesForFileDocumentation might go too far in that direction. Most of these XSL and XMAP files really just need a good clearly-written descriptive paragraph at the top describing *how* to use the file and *what happens* when you use it. That's the "public interface". Here's a proposal along those lines: 1) Add an xmlns:doc namespace line in the root element at the top of the file, like the last line of the following: <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"; xmlns:xhtml="http://www.w3.org/1999/xhtml"; xmlns:lenya="http://apache.org/cocoon/lenya/page-envelope/1.0"; xmlns:doc="http://apache.org/cocoon/lenya/xmldoc/1.0/"; > 2) Just below that element, add the header documentation, like this example (which would be for global-sitemap.xmap): <doc:head> This sitemap file handles all Lenya-specific requests to the application. It defines the pipeline for the top-level Lenya page (introduction), a list of available publications, lucene searching, the editors, and default error pages for all publications (which may be overridden per publication). External sitemap files are mounted for specific areas of the Lenya CMS pages such as navigation, admin, scheduler, and usecases. URI's should generally reach this file in original form (no prefix removed). NOTE: Most of the components used by this file and the sitemap files it mounts are expected to have been declared by the calling sitemap file. <doc:version>$Id: global-sitemap.xmap 165399 2005-04-30 10:13:23Z antonio $</doc:version> </doc:head> 3) A more extensive example might include more of the headings you suggest (such as <parsed-during> and <parsed-by>) within the doc:head element, to the degree that people find them helpful. 4) We should probably also use such XML tags deeper into the XSL & XMAP files where such text might be useful externally (in the same way that individual public methods within java source code are documented). For example, each XMAP file has a public interface that includes 1) the URI patterns matched and 2) the corresponding output (HTML page, XML stream, PDF file, etc). For example, the first pipeline in global-sitemap.xmap (Lenya 1.2.4) might look like this: <doc:pipeline> Show a list of all the publications for user to chose from. </doc:pipeline> <map:pipeline> <map:match pattern="publications.xml"> <map:generate type="directory" src="lenya/pubs"/> <map:transform src="lenya/xslt/util/xinclude.xsl"/> <map:transform type="xlink"> <map:parameter name="href" value="lenya/pubs/dummy.xml"/> </map:transform> <map:serialize type="xml"/> </map:match> </map:pipeline> Note that the documentation preceeds the pipeline, in javadoc fasion. The documentation display tool, such as solprovider's, could automatically pull out the match pattern string (publications.xml in the above example) when parsing xmap files, right? What do all of you think? Is this approach, using a new doc namespace, too heavy-handed? --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
