Re: Re: obvious extension of o-xml to all forms of programming, and need for import facility from existing code

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


On Thu, 8 May 2003, Yves Moisan wrote:

> One thing that could be worth thinking about when talking about bringing in
> functional specs is literate modelling (Jim Arlow). It would be nice if
> textual/diagrammatic artifacts like literate modelling documents (outputted
> in XMI ?) could serve as a basis for functional spec definition, which could
> then be turned into o:XML code and to user manuals by XSLT (?) and finally
> used as a validating artifact for test cases.  XP user stories could be
> embedded into literate modelling documents and therefore be linked more
> closely to code than if they were mere text documents held separately.

Yves, these are all great ideas, and very achievable too.
Inline documentation can be done in almost any way you want by simply
extending the core language. Say that you want to add comments as
attributes, eg:
<o:type name="foo" comment="the foo type that does bar">
  <o:function name="foo" comment="the foo constructor">
    <o:param name="arg" comment="..."/>
etc
or in element content:
<o:type name="foo">
  <o:documentation>
    <para>some <ulink url="http://www.docbook.org">DocBook</ulink> fragment</para>
  </o:documentation>
...

Any elements or comments appearing within o:XML declarations will simply
be ignored by the interpretor, but can be harvested by a documentation
generator stylesheet. This stylesheet could also be designed to take into
account any xlinked external artifacts such as diagrams or images.

This doesn't however take into account the Literate Programming
requirement of reordering. If you want the code to appear as fragments in
the documentation rather than vice versa, maybe an approach like this
would work: DBLP: DocBook-based Literate Programming
http://www.west-point.org/users/usma1978/36200/LitProg/SGMLWEB/index.htm

> I guess there could be a way of specifying the granularity at which one
> wants to "manage" one's code (not every helper function or class would show
> in UML diagrams ...) so that only some of the o:XML code could be
> specifically tied to textual/diagrammatic artifacts such as literate
> modelling documents.  Maybe a tool like xMLP could fit in well with such a
> scheme ?

I had a quick look at xmLP, but didn't get very far with the docs
available. Looks like it could be a good way to 'write programs into the
documentation'.

While anyone can document their programs almost any way they want, I'd
still like to incorporate some basic commenting/documentation mechanisms
in the core language as soon as possible. Would be nice to have an xslt
that generates cross-linked and indexed documentation automatically.

If anyone has suggestions for how contextual docs should look in o:XML let
me know.

cheers,


/m

Martin Klang
http://www.o-xml.org - the object-oriented XML programming language
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org

iD8DBQE+u6QDU02Ml0598n4RAhWAAKCKRYjQKtj0OSISh4avr6lkyLJIXACdF5bV
iTUZyqrJ+PsNojgNtgqwrrU=
=RqSM
-----END PGP SIGNATURE-----