[Gzz-commits] manuscripts/UMLLink article.rst umldoc-flow.dia...

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/02/15 04:00:55

Modified files:
        UMLLink        : article.rst umldoc-flow.dia 
                         umltool-convert-process.dia 
                         umltool-example-mp.dia 
                         umltool-example-uml-linked.dia 

Log message:
        implementation

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/article.rst.diff?tr1=1.34&tr2=1.35&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/umldoc-flow.dia.diff?tr1=1.3&tr2=1.4&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/umltool-convert-process.dia.diff?tr1=1.2&tr2=1.3&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/umltool-example-mp.dia.diff?tr1=1.2&tr2=1.3&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/umltool-example-uml-linked.dia.diff?tr1=1.2&tr2=1.3&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.34 
manuscripts/UMLLink/article.rst:1.35
--- manuscripts/UMLLink/article.rst:1.34        Fri Feb 14 18:08:52 2003
+++ manuscripts/UMLLink/article.rst     Sat Feb 15 04:00:54 2003
@@ -9,7 +9,7 @@
 .. Alternative title: "Free Software toolchain for bidirectional 
    linking between UML diagrams and Javadoc"
 
-.. :Stamp: $Id: article.rst,v 1.34 2003/02/14 23:08:52 humppake Exp $
+.. :Stamp: $Id: article.rst,v 1.35 2003/02/15 09:00:54 humppake Exp $
 
 .. Points for HT people
    ====================
@@ -204,9 +204,10 @@
 process, which makes the task of our software easier than that of other web 
 augmentation tools [weinreich00-linkvis]_. 
 
-The current implementation is a part of and in use at our Free Software 
-project [gzz]_, where it generates the publicly web-browsable 
-hypertext [gzz_doc_himalia]_ of project's documentation, as a part of the 
toolchain.
+The current implementation is a part of and in use at our Free
+Software project [gzz]_, where it generates the publicly web-browsable
+hypertext [gzz_doc_himalia]_ of project's documentation, as a part of
+the toolchain.
 
 ..  Javadoc has plenty of unhierarchical links, but they are not meaningful, 
     they don't give the documentation any structure.
@@ -379,13 +380,15 @@
 We believe that the architecture document will be read more, after
 it's easily reachable from relevant parts of Javadoc. This is the
 starting point for the Free Software toolchain we developed in this
-article: a toolchain for for bidirectional linking between design
+article: a toolchain for bidirectional linking between design
 documentation and Javadoc, using UML diagrams as multi-ended nexus
 links.
 
 Design
 ======
 
+.. some references to the screenshots here?
+
 XXX Hypertext blaablaa something...
 -----------------------------------
 
@@ -417,6 +420,8 @@
 XXX linking UML diagrams
 ------------------------
 
+.. could the table be replaces? removed?
+
 Looking closer, we can divide our UML diagrams into three classes:
 conceptual diagrams, specification diagrams and implementation
 diagrams. Different diagram types can be linked within the
@@ -443,18 +448,20 @@
 | implement it          |                       |                    |
 +-----------------------+-----------------------+--------------------+
 
-The UML diagrams enable navigation in various purposes. Applying Trigg's 
-taxonomy of different link types [trigg83link-taxonomy]_, we could identify 
several semantic meanings 
-of the links, shown in Fig. [ref-diagramlinks]_. Links from the diagram to 
-documentation pages are expressed in HTML imagemaps, and bi-directionality is 
-ensured by injection of HTML IMG tags to all referred pages. As web browsers 
-generally embed the IMG-linked diagram to the documentation nodes, the diagram 
 creates spatial links between all the referred pages. Further, each 
-documentation node creates spatial links between all the diagrams it refers to,
-allowing the reader to see which alternate spatial views are available for the 
-current node.
+The UML diagrams enable navigation in various purposes. Applying
+Trigg's taxonomy of different link types [trigg83link-taxonomy]_, we
+could identify several semantic meanings of the links, shown in
+Fig. [ref-diagramlinks]_. Links from the diagram to documentation
+pages are expressed in HTML imagemaps, and bi-directionality is
+ensured by injection of HTML IMG tags to all referred pages. As web
+browsers generally embed the IMG-linked diagram to the documentation
+nodes, the diagram creates spatial links between all the referred
+pages. Further, each documentation node creates spatial links between
+all the diagrams it refers to, allowing the reader to see which
+alternate spatial views are available for the current node.
 
 .. figure:: umldoc-linking.gen.eps
-   :width: 16.9cm
+   :width: 15cm
    :alternative: *
    :label: diagramlinks
 
@@ -464,6 +471,8 @@
 Documentation reader's point of view
 ---------------------------------------
 
+.. at least here we should also refer to the screenshots
+
 Before reaching the current state, our documentation evolved through
 several distinct steps, which will be viewed first from the reader's
 and then from the developer's point of view.
@@ -563,17 +572,16 @@
 
 Up to this article, all steps except the last one are implemented. The
 existing tools we selected as the basis for our documentation tool
-are: Javadoc, Docutils [goodger02docutils]_, and
-our own UML diagram description tool. Further, the UML tool uses
-several free utilies to convert each lexical UML description into
-final *Portable Network Graphics* (PNG) diagram files. Such utilies
-are *MetaPost* [hobby89metapost]_ (mpost), which implements a language
-for picture drawing, and Netpbm image file manipulation
-toolkit. Besides Javadoc, all tools used are Free Software. The
-current linking utility is implemented to support Javadoc, but after
-the plugin interface is ready, switching Javadoc to any free
-alternative or using them as parallel should be possible with only
-minor plugin programming.
+are: Javadoc, Docutils [goodger02docutils]_, and our own UML diagram
+description tool. Further, the UML tool uses several free utilies to
+convert each lexical UML diagram description into final *Portable
+Network Graphics* (PNG) diagram files. Such utilies are *MetaPost*
+[hobby89metapost]_ (mpost), which implements a language for picture
+drawing, and Netpbm image file manipulation toolkit. Besides Javadoc,
+all tools used are Free Software. The current linking tool is
+implemented to support Javadoc, but after the plugin interface is
+ready, switching Javadoc to any free alternative or using them as
+parallel should be possible with only minor plugin programming.
 
 The javadoc format is the standard way to include documentation in
 Java source code [friendly95javadoc]_. Generating the WWW pages is not
@@ -589,7 +597,7 @@
 UML tool
 --------
 
-Our UML description tool was already implemented before the
+Our UML diagram description tool was already implemented before the
 documentation linking tool, which finally enabled the bi-directional
 linking between distinctdocumentations. In the following we discuss
 shortly, how we ended up to use this our own lexical UML language
@@ -617,11 +625,11 @@
 write the documentation, the documentation tools shouldn't be gap to
 change the programming tool to document writing tools. Even better
 would be that the programming tool could be used as documentation
-tool. Lexical UML description for our UML drawing tool, of course, can
+tool. Lexical UML diagram description for our UML drawing tool, of course, can
 be written with any text editor. At least for a programmer, who are
 used to describe objects lexically, describing also the UML diagrams
-could be even more efficient than using direct manipulation drawing
-tool.
+lexically could be even more efficient than using distinct direct
+manipulation drawing tool.
 
        "It's as if we have thrown away a million years of 
        evolution, lost our facility with expressive language,
@@ -646,22 +654,25 @@
 these alternatives as easily available as they could be just typed
 when using lexical description.
 
+In our UML tool the describtion of UML diagram is divided in two: into
+a description of all the elements in diagram [ref-umltoolumlsource]_
+and description their graphical layout [ref-umltoolmpsource]_. The
+final diagram file [ref-umltoolexample]_ is compiled
+[ref-umltoolconvert]_ from the element and layout descriptions. The
+description of existing elements is easily done using our UML tools'
+lexical description language and the description is readable even
+without compiling the graphical diagram. The graphical layout is more
+difficult to express lexically without exceptional spatial
+imagination. Usually the intended results need several compilation
+trials. We admit that after all elements for a diagram are selected
+using lexical description, the graphical placing for them could be
+done much easier by direct manipulation.
+
 .. figure:: umltool-example-uml.gen.eps
    :label: umltoolumlsource
    :width: 4.5cm 
 
-   Example of UML tool object description.  
-
-In our UML tool the describtion of UML diagram is divided in two: into
-a description of all the elements in diagram [ref-umltoolumlsource]_
-and description their graphical layout [ref-umltoolmpsource]_. We
-argue that for a programmer used to Describing existing objects for
-diagram is easily done using our UML tools's lexical description
-language, but the graphical placing of objects is a bit more
-complicated, although, not impossible. We admit that after objects for
-the diagram are selected, the graphical placing for them could be done
-easiest by using direct manipulation.
-
+   Example of UML tool element description.  
 
 .. figure:: umltool-example-mp.gen.eps
    :alternative: *
@@ -670,9 +681,15 @@
 
    Example of UML tool layout description.  
 
+.. figure:: umltool-convert-process.gen.eps
+   :label: umltoolconvert
+   :width: 4.5cm 
+
+   The process of compiling UML diagram using our UML tool.
+
 .. UML:: umltool-example
        :label: umltoolexample
-       :caption: Example of UML tool output.
+       :caption: Example of UML tool diagram output.
        :width: 8.45cm 
 
        bigpackage Example
@@ -713,84 +730,157 @@
 Docutils
 --------
 
-reST's filosophy
+As a natural continuum for UML tool we started to use reStructuredText
+(reST) plaintext syntax with Docutils parsering system
+[goodger02docutils]_ for writing our design documentation. The UML
+tool already shared some of the main goals of reST syntax
+[goodger02docutils]_: it was readable also raw form, the most common
+elements had very simple markup, it was writable with any text editor
+and the UML markup was highly extensible (by enlarging the
+preprocessor and MetaPost UML macro libary
+[ref-umltoolconvert]_). ReST syntax itself is extensible easily by
+inventing new directives and adding parsers for them into
+Docutils. The extensibility of reST syntax and Docutils parsing system
+made it possible to write embedded markup of our umltool into design
+documentation. That way a lexical description of UML diagram is also
+easily reachable and editable when updating the documentation
+including the diagram description.
+
+Even reST syntax is somehow WYSIWYG (what-you-see-is-what-you-get).
+Gentner and Nielsen [gentner-nielsen96anti-mac-onpage-75]_ argue that
+a document has a rich semantic structure that is poorly captured by
+its appearance on a sceen or printed page, which many WYSIWYG tools
+assumes to be the only one useful representation of the
+information. WYSIWYG seem to assume that people want always
+paper-style reports to be read from top to bottom, when we already
+live within an information flood, where the overloaded reader should
+be allowed to affect the final representation of document
+[gentner-nielsen96anti-mac-onpage-75]_. ReST and Docutils parser won't
+make such assumptions, but tehy clearly distincts the semantic
+structure and rules for converting the text and semantics into
+printable page. ReST syntax has umambiguous rules to parse document
+into structural form and after parsing it could be written into
+multiple output formats [goodger02docutils]_.
+
+Linking tool
+------------
+
+Using reST syntax for design documentation, lexical description for
+UML diagrams and extensible Docutils parser for generating the final
+representation, we was allowed to embed also UML diagram description
+within the design documentation reST sources. When converting the reST
+document into final representation, our custom directive for Docutils
+passed the embedded UML diagram description to our UML tool and added
+a reference to the compiled diagram into Docutils' document tree
+structure. This was a promising base to build our linking tool on.
+
+In the current implementation we have two docutils directives to use
+for embedding UML diagrams into reST based design documentation. The
+first one is used to describe a new UML diagram, the second is used to
+refer to an already existing diagram. The correct reference is done
+simply by diagram name, so it could be spoken about UML diagram
+namespace, where all diagrams are distincted by unique naming.
+
+To enable linking elements in UML diagram a "jlink" command after each
+linkable element is added into lexical UML diagram description
+[ref-umltoolumlsourcelinked]_. If "jlink" has no attributes it is
+linked to Javadoc page of the package or class determined from the
+element's name. Otherwise element is linked into file determined by
+the attribute following "jlink".
+
+The documentation [gzz_doc_himalia]_ is created in two distinct
+phases. In the first phase [ref-umldocflow]_ all reST sources are
+parsed and compiled into HTML and lexical UML diagram descriptions are
+extracted into temporary storage [ref-umldocreferflow]_. Also the
+paths for reST documents explicitly referring particular diagrams are
+stored with that diagram source [ref-umldocreferflow]_. In the second
+phase all compiled reST documents are processed again:
+
+ - Focused versions of UML diagram with list of all explicitly 
+   referring reST documents are created and embedded into compiled
+   documentation pages.
 
-- indentation for blocks
-- robust for erros
-- "natural" to write
-- "ASCII layout" (our language for UML is an exception, which is discussed 
-  later)
-
-can generate useless diagrams from the code class hierarchy 
-
-     * should describe somewhere why these are useles... 
-     * uses proprietary GraphViz tool to create diagrams
-
- - How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will
-   surely ask about that,
-
-    PARTIAL RESOLUTION: 
-
-       - proprietarity (really?)
-       - versioning much worse 
-          (changes in rtf could probably be compared?)
-       - users = programmers --> used to editing text and compiling,
-          it's the most practical to use the same editor as for coding
-       - lack of good, **extensible** tools
-  
-   [gentner-nielsen96anti-mac, p.75] collects arguments/argues
-   generally against WYSIWYG.
+ - Image maps targeting all linked elements appearing in UML diagrams 
+   are generated and embedded into compiled documentation pages.
  
-    - a document has a rich semantic structure that is poorly
-      captured by its appearance on a sceen or printed page
-    - other text representations, such as SGML, distinct the semantic
-      structure and rules for converting the text and semantics into
-      printablepage
-    - WYSIWYG assumes there is only one useful representation of the
-      information: that of the final reports
-    - WYSIWYG assumes people want paper-style reports (and we already
-      live within information flood)
-    - blind users exists
-
-    - Rational Soda is WYSIWYG, maybe this could be discussed under
-      it
+ - Finally focused versions of UML diagrams are created and implicitly
+   embedded into targets of all linked elements appearing in
+   UML diagrams.
+
+.. figure:: umltool-example-uml-linked.gen.eps
+   :label: umltoolumlsourcelinked
+   :width: 4.5cm 
 
+   Example of UML tool element description with link
+   information for linking tool.  
 
-- not strictly necessary; could have used another editor
+.. figure:: umldoc-flow.gen.eps
+   :label: umldocflow
 
-- minimum barrier to make a diagram (well, at first have to learn our 
-       description language)
+   The two distinct phases of generating Javadoc and design
+   documentation bridged via UML diagrams.
+   
 
-- direct manipulation when building / editing structure of diagrams clumsy
- 
-     - users are programmers --> a language is better than d.m.
+.. figure:: umldoc-refer-flow.gen.eps
+   :label: umldocreferflow
+
+   Compiling reST sources and extracting embedded UML diagram
+   descriptions into temporary storage.
+
+Practical use
+=============
+
+The tool is currently in everyday use in the Gzz project ...
+
+- n classes, n diagrams, n pages architecture documentation, and works
+
+screenshots
 
-      + elements are easily described
+Acknowledgments
+===============
 
-      + graphical placing would need an GUI
+antont
 
+Conclusion
+==========
+
+- summaryy what have we done so far
+
+- UMLTOOL: diagram elements need easier placing (but still not automatic)
+
+  - direct maniplation
 
-- flow diagram of the implementation
+  - we can still continue using our UML language for description
+    of diagram elements
 
-reST's filosophy
+- LINKTOOL:
 
-- indentation for blocks
-- robust for erros
-- "natural" to write
-- "ASCII layout" (our language for UML is an exception, which is discussed 
-  later)
+  - Currently, we only link UML classifiers to Java classes and other
+    documents. Methods
+    could also be linked, especially in interaction diagrams.
 
+  - plugin interface to enable other documentation tools than javadoc
 
-- diagrams in the same reST source as the design document
+- standalone (from our CVS, still a lot of depends for the 
+  existing Free Software) distribution package
 
-- separate UML structure from presentation, show structure in easily
-  editable text
+- metapost's erros are fuzzy, when using scripting language for
+  drawing diagrams, we need clearer errors
 
-     - placement: currently metapost; looking at ways to make 
-       interactively editable.
+  - it's possible that we change metapost for something else
 
-- Dia could be used instead of metapost, but
-  direct manipulation problem again
+  - getting rid of problem with fuzzy error messages and slow
+    compiling process
 
+  - However, less power: with mp, can draw arbitrary stuff on the diagrams
+    is well; this is sometimes useful, but sometimes not desirable.
+
+- all in all, this is temporary system: using web pages for the 
+  presentation/UI layer of a hypertext system is useful and standard 
+  but very limiting. The system we are using these tools to develop is 
+  intended for better user interfaces to similar ...
+
+  + antont's note about duplication of data problem
 
 .. bibliography:: gzigzag
+
Index: manuscripts/UMLLink/umldoc-flow.dia
Index: manuscripts/UMLLink/umltool-convert-process.dia
Index: manuscripts/UMLLink/umltool-example-mp.dia
Index: manuscripts/UMLLink/umltool-example-uml-linked.dia