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

[Asko Soukka]

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

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

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

- For RSTs we have an UML-directive:

.. UML: unique_name
   :option: value

   .uml code
   ---
   .mp code

  - 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
  - content section is divided into .uml part and .mp part by some
    specified mark like a line of "-"s

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?)
  - 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
  - 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
  - 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
 - 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? (this could need
   creating empty html-files if no diagrams are added implicitly into
   some RST)

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