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

[Tuomas Lukka]

On Fri, Dec 13, 2002 at 12:45:34PM +0200, Asko Soukka wrote:
> Fri, 13 Dec 2002, B. Fallenstein wrote:
> > here. It makes sense to me if that's the same document containing the
> > source...
> > For diagrams that do not have a single 'master' location, putting them
> > in a separate file seems more appropriate, so that should be possible, too.
> 
> Ok. What think as the main problem is, that before generating any
> of the diagrams we should know all the rsts where hose diagrams are used.
> I except, that we don't want to parse all of the rsts twice or parse them
> all into memory at the same time. I don't know currently any way how to
> build final imagemaps into docutils document tree while converting rst
> (excepting that we can't parse the rsts twice).

Possible solution:

1) parse .rst -> HTML, extract UML diagrams
2) add UML diagrams into the parsed html

> I don't somehow like this current <object> approach, but for me it seems
> to be still the most reasonable way:

I don't think it is: some browsers don't like it (e.g. konqueror).
Also, in mozilla, the UI is horrible (scrolling viewport inside scrolling 
viewport).

We *want* it to be physically included.

> - We have specified a directory for all independent UMLs. UMLs there will
>   be defined as they are already, two files for one diagram (.uml and .mp)
>   and the prefix of filename is the unique name of the diagram.
> 
> - We could have an another directory for all the generated data, or use
>   the directory of "independent UML's". I'm also wondering should we store
>   the final output (png, html) into that directory or into directories
>   where they are used (peg-directories, javadoc-directories...)

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.


> - For RSTs we have an UML-directive:
> 
> .. UML: unique_name
>    :option: value
> 
>    .uml code
>    ---
>    .mp code

Yes.

>   - the directive has one argument, which specifies an
>     unique name for a new diagram, or name of the referred diagram
>   - if there is no content section, the directive will refer to
>     the diagram specified by its argument
>   - 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.

> What do you think about the naming of diagrams? Should there be some
> kind of namespaces? Although, they'll make this more complicated.
> 
> - My vision, how documl-tool could finally work:
>   - 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.

>   - input the names of all of the independent UMLs (I'd suggest that
>     names of the independent UML's overrides the ones in RSTs)
>     + also the data of UML diagrams could loaded in memory
>       already here

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

>   - convert RST's and always when UML-directive occurs:
>     + store referrences for UML-diagrams
>     + store UML data, if its new
>     + 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?

>   - only after all the RSTs have been converted, can generating
>     the diagrams be started: creating focus+context-versions (if not
>     disabled in UML-directive), saving output-files, generating
>     imagemaps...

> Some open questions for this approach:
>  - unambiquous naming for the output files

just pick a long enough random string.

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

> (this could need
>    creating empty html-files if no diagrams are added implicitly into
>    some RST)

Not if using the multi-pass approach.

        Tuomas