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

[Tuomas Lukka]

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

Yes, the focusing is a major reason for wanting them there. The UML diagram
would function as a "multi-ended nexus link".

> > > >   + 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?

Probably. Just make them python classes.

> > > 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?

Google it. Yet another markup language. What XML should have been ;) ;)

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

Yes, I believe the point is that this makes it one step more difficult and
less enticing to make a diagram.

> > > >    - 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 :)

Absolutely. Basically, it would be an open method somewhere: get focused image 
of this diagram.

        Tuomas