Bob Harner wrote:
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.
true. it makes a lot of sense to use xml syntax. but then we should also
use more xml-friendly semantics - a little later, you write:
> <doc:pipeline>
> Show a list of all the publications for user to chose from.
> </doc:pipeline>
> <map:pipeline>
<snip>
> Note that the documentation preceeds the pipeline, in javadoc fasion.
hmm. in xml, the most natural way of associating some property (such as
the <doc:x/> tags) is by nesting, not preceeding. plus the tag name
"pipeline" is not so nice. how about this:
<map:pipeline>
<doc:head>This is a pipeline</doc:head>
<doc:parsed_by>...</doc:parsed_by>
...
</map:pipeline>
not quite so nice for humans used to javadoc, but a lot more robust wrt
stylesheet transformations and automatic editing of the files.
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 thought about this, too. the reason i'm advocating such excessive
commenting (especially about the context) is that it reflects my way of
learning lenya. i browse file after file, and then a flow chart starts
to form in my mind. but from my recent discussion with andreas, it has
occurred to me that this might not be the best approach for everyone.
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".
sure, feel free to purge the wiki page a little. the categories in their
current state resulted from a quick brain-storming to get the ball
rolling...
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/"; >
nice.
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>
ok for per-file docs, but as i said before, for per-element docs i'd
rather use nesting.
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.
that's probably the best test :)
What do all of you think? Is this approach, using a new doc
namespace, too heavy-handed?
i like it.
but i must confess i have not looked very closely into solprovider's
solution or the xmldoc resource someone posted recently.. will do that soon.
--
"Open source takes the bullshit out of software."
- Charles Ferguson on TechnologyReview.com
--
Jörn Nettingsmeier, EDV-Administrator
Institut für Politikwissenschaft
Universität Duisburg-Essen, Standort Duisburg
Mail: [EMAIL PROTECTED], Telefon: 0203/379-2736
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
