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

[Tuomas Lukka]

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

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

MetaPost produces postscript so including it in LaTeX should be easy.

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

If it only messes the .rst file up, including it with a string would be better.

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

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

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

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.

User-interface-wise, this is really important: we *NEED* to see where
we are.

Of course, if we assume a good browser, we could just put an overlay on the 
image, but ...


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

Depends on whether that can be made as simple. Could you make an example file?

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

A more specific goal. WML is about general programmability,
our little thingy is about achieving a very specific goal
in program documentation.

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

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

No, no, simply enhance the "node" of the diagram we are at.

The diagram would kind of be seen as a multi-ended link "nexus", 
seen always from one of its ends (the document it's included in), and
the link to that document within the diagram would be highlighted.

        Tuomas