UML tool (was: Re: [Gzz] Asko 2002-12-04/05 (OvalBgVob))

[B. Fallenstein]

Hi Asko,

Asko Soukka wrote:
>  - Finally, Tuomas asked my interest for enhanching current documl tool
>    and trying to write an article about it:

I'd be interested in collaborating on this, if you want to. The current 
state of the uml tool bugs me, but not quite enough to really work up 
the initiative and rework it-- if I have to do it alone...

>    + at first architecture htmls should be replaced with rst's, for
>      reST this needs our own UML-directives.

Yes. That's very imporant for this to work sensibly.

An interesting issue here is how to make it work so that the reST can be 
written into LaTeX also with the UML diagrams included-- this would be 
*very* useful for me, I think.

One other issue is whether to include the metapost code in the UML 
directives, too-- I am for it.

>    + at the beginning of UML-diagram should be a link list for all reST
>      (architecture and peg) pages where diagram is included

Hmm, you mean in the HTML right before the UML diagram? Or embedded into 
the image? (The latter is bloat... but I gather you mean the former...)

>    + the diagram should be included in every documenet where it links to

The problem with this and the former is, of course, that it is dependent 
on our doc architecture (pegs, javadoc, etc.). We'd need a plugin 
interface and provide customization for our doc structure through that 
interface.

>    + finally the diagram should be 'personalized' for document where
>      its included (explicitly or implicitly by this script)
>      + the current document should be focused by coloring (and maybe
>        later with zooming) in included diagrams, here this gets
>        interesting :)

Hm, I'm not 100% convinced: this means a lot of data bloat on the output 
side... maybe optional or some such?

>    I would be interested enough, if I'm allowed to extract a fully GZZ's
>    cvs independent tool from this.

Yes, it should be independent of Gzz. Sure.

>    Since everything is LGPL, this
>    shouldn't be a problem - needs only a little more time. What this needs
>    is at least some kind of config and listing all dependencies (javadoc,
>    (docxx,) metapost, docutils). Probably uml.py and uml-helper.mp should
>    be also documented little more :)

Also, refactored to be cleaner.

I at once thought about changing the syntax to use YAML-- would that 
make sense to you?

>    My motive is that I could easily
>    use these tools also with other projects than gzz afterwards. And if it
>    gets good enough, probably someone elso wants also...

;-)

>    What would be the targets of the paper?
>     - using several doc tools serially together for synergy

Reference: WML. But I don't like WML-- too tangled. Hmm. Is this 
different? How?

>     - embedding architectural diagrams (also within the
>       documentation of single components to show their using contexts)

Yes. An important point here is to embed architectural diagrams in a way 
that isn't too disruptive of context-- I'd like to write a peg and 
include a diagram whose source code is readable when reading the rst in 
source.

>     - bidirectional linking within documentation (also within
>       documentation created using different tools

Yes...

>     - focus+context in diagrams
>     (- how all this should come naturally in GZZ ;)

Actually, I don't understand that point.

Are you saying you want to move the current diagram item to the center 
also, showing only the directly connected classes around it? This seems 
to be a very different paradigm from the current uml tool...

-b.