No registered users in community xowiki
in last 10 minutes
in last 10 minutes
[Xotcl] Re: [Xotcl] using _at_, metadata, ... without xodoc
From: Uwe Zdun <uzdun_at_k2.informatik.uni-essen.de>
Date: Tue, 9 Jan 2001 23:00:34 +0100 (CET)
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 _at_ syntax is more powerful ...
> - _at_ 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 _at_ (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 _at_ for generating some kind of
> metadata, i.e data which can be found (and changed by the user if needed) during
> the application?
_at_ 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] {
_at_File {
return [$xoDocObj handleFile [lindex $args 1]]
}
default {
return [eval $xoDocObj handleObj $args]
}
}
}
}
}
puts stderr "Unknown documentation: '$args'"
}
XODocCmd _at_
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). _at_ 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 _at_.
Eg. instead of just having the _at_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 _at_ can express everything you can express with
metadata, but with _at_ 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
_at_ is more powerful, we hope to get the core language smaller & easier
comprehensible, by only using _at_ ...
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 _at_
is not very problematic ...
Regards,
Uwe
Date: Tue, 9 Jan 2001 23:00:34 +0100 (CET)
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 _at_ syntax is more powerful ...
> - _at_ 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 _at_ (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 _at_ for generating some kind of
> metadata, i.e data which can be found (and changed by the user if needed) during
> the application?
_at_ 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] {
_at_File {
return [$xoDocObj handleFile [lindex $args 1]]
}
default {
return [eval $xoDocObj handleObj $args]
}
}
}
}
}
puts stderr "Unknown documentation: '$args'"
}
XODocCmd _at_
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). _at_ 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 _at_.
Eg. instead of just having the _at_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 _at_ can express everything you can express with
metadata, but with _at_ 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
_at_ is more powerful, we hope to get the core language smaller & easier
comprehensible, by only using _at_ ...
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 _at_
is not very problematic ...
Regards,
Uwe