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

[Asko Soukka]

Fri, 6 Dec 2002, Tuomas Lukka wrote:
> Benja Fallenstein wrote:
> > 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.
> Absolutely.

Great :)

> > One other issue is whether to include the metapost code in the UML
> > directives, too-- I am for it.
>
> There needs to be an easy way to refer to it, but other than that it's
> possible, especially if the code stays even marginally human-readable.

AFAIK, we should be able to refer do the same UML from different reSTs
(currently architectural and PEG). Probably we also want to create
diagrams outside reST. I am not for this, but maybe it could be made
optional?

> > >   + 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...)
> Either, they should be small and inconspicuous.

I would like to embed them inside the diagram for consistency.
According to Tuomas' drawing (gzz/doc/metacode/Uml_inclusion.jpg) these
links can also be focused and IMHO the way of focusing should be
consistent with other parts of the diagram.

> > >   + 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.
> Yes.

What information do we need? The directory where files are and some
information where should we placed <img/> and <imagemap/> withing the
files. And how do we match the classes and filenames when making jlinks?
With javadoc it is easy: matching directories for packages and filenames
for classes, but what about cxxdoc and others(?)?. Should this be
somehow generalized for the plugin 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

See Tuomas' drawing (gzz/doc/metacode/Uml_inclusion.jpg) for
focus+context with coloring.

> > >       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?
> Possibly. On the other hand, it's not *that* much: each diagram would be
> only 4-10 times; disk space is cheap. Especially since the diagrams
> are usually pretty small in output.

Since everything are generated and thus temporary I won't think this as
a problem. Well... the time needed for generating "personalized" images
could be problem for someone. This could be made optional, but AFAIK this
is one of the most interesting parts of this :) I would like to make this
easily enhanceable.

> > I at once thought about changing the syntax to use YAML-- would that
> > make sense to you?
> Depends on whether that can be made as simple. Could you make an example file?

YAML?

> > >    - 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.
> Yes.

An alternative for embedding the UML source inside the reST source would
be adding link to the UML source. It could be placed below the image,
when handling UML-directives. So, link for the UML source would exists
only in rsts (or actually in the htmls generated from them).

> > >    - 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...
> No, no, simply enhance the "node" of the diagram we are at.

The different color as in Tuomas' example, would well be good
enough. Still, I would like to leave this open for enhancements :)

-- 
Asko Soukka     | Taitoniekantie 9 A 603 | address@hidden
+358-40-8235947 | FIN-40740 JYVÄSKYLÄ    | http://www.iki.fi/asko.soukka/