On Tue, 9 Jan 2001, Catherine Letondal wrote:

Hi,

I have a question about documentation mechanisms in XOtcl. I would like to use introspection for documenting my application, but not for generating HTML files. As far as I have understood:

• metadata is deprecated (http://media.wu-wien.ac.at/doc/tutorial.html#meta-data)

right. The metadata were not very powerful and as runtime constructs they have always used performance & memory. The @ syntax is more powerful ...

• @ object is a kind of /dev/null which has to be redefined somehow

right. But at the moment we haven't build a generic runtime structure for the running program, but we will have that very soon ... the planned steps are: - fix the problems Kristoffer has identified - extract a generic structure for runtime representation of metadata - what now is xodoc will become the static file analyser building that structure - another component builds that structure during execution and allows you to access/change it(*) - makeDoc.xotcl will contain the HTML documentation tool based on static analysation

You are probably interested in (*) ... we hope to get at the xoDoc issues during the next 1-2 weeks (but we have to fix the diverse gdbm (mainly of the windows port) problems first ... we're currently adding another persistence store implementation ... that is really free & that we hope to run/install on Win and on Unix well).

For the time being at least the syntax of @ (as described on this mailing list before) should be quite stable.

• xodoc does this but for HTML documentation

So my question is: how do I use or not use @ for generating some kind of metadata, i.e data which can be found (and changed by the user if needed) during the application?

@ is intended to be extensibly interpretable. It uses a quite simple syntax so its easy to build interpretations that parses the attached Tcl lists. The following lines from xoDoc are a general way to do it:

Class XODocCmd -parameter { {xoDocObj ""} } XODocCmd instproc unknown args { [self] instvar xoDocObj if {[llength $args] > 1} { switch [lindex $args 1] { proc - instproc { return [eval $xoDocObj handleMethod $args] } default { switch [lindex $args 0] { @File { return [$xoDocObj handleFile [lindex $args 1]] } default { return [eval $xoDocObj handleObj $args] } } } } } puts stderr "Unknown documentation: '$args'" } XODocCmd @

you just have to put your application specific tags and interpretation method into the switches ...

It is easy that every application can define its own behavior for interpreting different kinds of metadata (and you can extend it with new application specific tags). @ is just intended as a common place for metadata/documentation inside of a program, that can be turned on and off during execution.

All what XOTcl should provide is a common framework for documenting XOTcl. Your application may document quite different things with @.

Eg. instead of just having the @File token, you can add new @XXX token ... and the argument lists are just extensible key/value pairs

Why is metadata deprecated?

We believe that @ can express everything you can express with metadata, but with @ you can choose yourself if you want to use it or not (metadata is a built-in language feature and can not be turned off). Since @ is more powerful, we hope to get the core language smaller & easier comprehensible, by only using @ ...

For now we hope that not too many people were using metadata at all ... later it might get much more difficult to "clean up" such problematic parts of language. We think "metadata" as it was, was not a very intutive & elegant & general solution. I hope you haven't have a large program part written with "metadata" ;) ... but the conversion to @ is not very problematic ...

Regards,

Uwe