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

[Asko Soukka]

Fri, 13 Dec 2002, Tuomas Lukka wrote:
> 1) parse .rst -> HTML, extract UML diagrams
> 2) add UML diagrams into the parsed html

Ok. I didn't know that <object> is do badly supported and browsers can't
auto-resize it correctly.

> They should definitely not go into the same directory as the independent umls:
> it's best not to put generated and "real" data into the same place.

Ok. Since javadoc is fully generated we could put png-files there (in
javadoc-dirs), but even RSTs and generated HTMLs are in the same
directories we don't want more generated data there...

We could have one directory for all documl-generated files, but then
<img>-paths may look like "../../../../umltmp/foo-context.png".

Tuukkah and vegai had already some discussion about naming or placing
generated stuff so, that tehy could be easily handled in .cvsignres...
should ask also about their opinions.

> >   - if there is content for a new diagram, but the name specified by
> >     argument is already used, the directive will refer the diagram
> >     that already exists and outputs error about name conflict
> Hmm... I think I'd prefer to have UML and UMLREF to make the distinction
> absolutely clear.

Ok. But after the new diagram defined in UML-directive is created, it will
be linked into the generated HTML-dokument like any other diagram is
linked using UMLREF-directive.

Now I wonder, how should the original context of
some diagram be marked as Benja suggested?

> I don't like the overriding business: having the same name twice should
> be a fatal error.

But unique names are ok?

> >   - documl.py is called from the root of gzz, as parameters it will
> >     get all the rst-files (filenames with paths) to convert, or
> >     alternatively all the directories to search RSTs for (recursively?)
> I think recursive search would be good.

This should probably work both ways. Single files will be added to queue
as their are, but directories cause recursive search. Of course Multiples
should be trimmed off.

> >     + write <object>-tag into the document tree, <object> tag
> >       will refer to a HTML-file in some specified directory,
> >       the file could be named e.g. rstname-diagramname.html
> And in the second pass, undo the <object> tag?

Rethinking this:
- in the first pass we can add correct image-element and an empty
  imagemap-element into the document tree of parsed RST
- in the second pass we search the empty imagemap-tag according to its
  name (or id in XHTML) and create the imagemap within it

> > Some open questions for this approach:
> >  - unambiquous naming for the output files
> just pick a long enough random string.

I don't like the idea of fully random filenames.
Maybe diagramname-randomstring.png, but no more :)

> >  - how should implicitly added diagrams (for bidirectional links)
> >    be placed in RST's? Should the umltool add one <object> referrence
> >    into the beginning of all RST's it handles?
> That, and allow the user to affect its location by including a ".. UMLBACK"
> directive somewhere.

Ok. UMLBACK could write a comment (e.g. "<!-- UMLBACK -->" in HTML) into
the document tree, if that's possible.

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