[Xotcl] Re: [Xotcl] using @, metadata, ... without xodoc

[Uwe Zdun]

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