[Gzz-commits] manuscripts ./gzigzag.bib UMLLink/umllink.rst

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/01/28 09:21:39

Modified files:
        .              : gzigzag.bib 
        UMLLink        : umllink.rst 

Log message:
        small progress

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/gzigzag.bib.diff?tr1=1.11&tr2=1.12&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/umllink.rst.diff?tr1=1.49&tr2=1.50&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/umllink.rst
diff -u manuscripts/UMLLink/umllink.rst:1.49 
manuscripts/UMLLink/umllink.rst:1.50
--- manuscripts/UMLLink/umllink.rst:1.49        Mon Jan 27 09:19:38 2003
+++ manuscripts/UMLLink/umllink.rst     Tue Jan 28 09:21:39 2003
@@ -2,7 +2,7 @@
 A free software toolchain for bidirectional linking between UML diagrams and 
Javadoc
 
====================================================================================
 
-:Stamp: $Id: umllink.rst,v 1.49 2003/01/27 14:19:38 humppake Exp $
+:Stamp: $Id: umllink.rst,v 1.50 2003/01/28 14:21:39 humppake Exp $
 
 Issues
 ======
@@ -17,35 +17,6 @@
     should be more general, and we should point out that
     this situation is probably not uncommon.
 
-- 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-nielsen-anti-mac, p.75] collects arguments/argues
-  generally against WYSIWYG.
- 
-    - 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
-
 - why even outdated but well simplified diagram
   is better than too detailed, automaticly up-to dated 
   and reverse engineered diagram.
@@ -65,34 +36,55 @@
     of cross-hierarchical links and browsin along them still unkown.
     When generating sourcecode, the documentation could be embedded into 
     source as comments. Some user comment didn't like Rose's way of
-    adding extra comments into generated code 
<http://c2.com/cgi/wiki?RationalRose>
+    adding extra comments into generated code 
+    <http://c2.com/cgi/wiki?RationalRose>
 
 Introduction
 ============
 
-UML, the blah, has recently become blah blah
+UML (the Unified Modeling Language), found mainly by Booch, Jacobson and
+Rumbaugh during 1900s to XXX blah blah [#]_, has become *de facto* 
+industry-standard language for specifying, visualizing, constructing, 
+and documenting the products in software  engineering. Recently, various 
+approaches have been developed towards unifying software architecture 
+design and code. Whether the source code is generated from the UML-based 
+architectural model [#]_ or the documentation is reverse engineered from 
+the code [#]_. Nowadays UML seem to be taken in CASE tools even almost 
+as a visual language, though it's not primarly designed to be a 
+programming language. [#]_.
+
+.. [#] XXX booch-jacobson-rumbaugh-uml-user-guide? 
+
+.. [#] harrison-barton-raghavachari00uml-to-java
+
+.. [#] pierce-tilley02connecting-documentation-rose
+
+.. [#] booch-jacobson-rumbaugh-uml-user-guide p.15
+       booch-jacobson-rumbaugh-uml-reference-manual p.4
+
+Against the trend of unifying the architectural documentation and code
+using UML, we tend still to define the details in the source code and 
+use UML only for planning and document our software architecture in more 
+general level. We keep UML as a common language for intercommunication 
+within our software developer team and within project's all stakeholders.
+In this purpose we prefer more well abstracted and comprehensible
+human drawn diagrams than exact spesifications matching source code to 
+every detail.
 
-UML book [booch-jacobson-rumbaugh-uml-used-guide, p.24]:: 
+[#]_:: 
 
     "You draw diagrams to visualize a system from different
     perspectives, so a diagram is a projection into a system.
     For all but the most trivial systems, a diagram represents an elided
-    view of the elements that make up a system."
+    view of the elements that make up a system." 
 
-Recently, various approaches have been developed towards
-unifying software architecture design and code (REFS)
+.. [#] booch-jacobson-rumbaugh-uml-user-guide, p.24
 
- * they seem to end up generating either the documentation
-   from the code or the code from the documentation 
-   (antont's note about duplication of data problem)
-
-   [harrison-barton-raghavachari00java-to-uml]
-   [pierce-tilley02connecting-documentation-rose]
-   
-In this article, we present the tools we developed
-for using UML diagrams as multiple-ended hyperlinks
-between the architectural documents and javadoc generated
-java source documentation.
+Altough, even if the architectural documentation won't fully match with 
+details of current implementation, we feel important to enable fast
+transitions between them. In this article, we present the tools we 
+developed for using UML diagrams as multiple-ended hyperlinks between the
+architectural documents and javadoc generated java source documentation.
 
 Background
 ==========
@@ -146,6 +138,27 @@
       decentralized working places - is especially vulnerable to 
       intercommunication problems
 
+Javadoc
+-------
+
+Javadoc  [#]_ is a hypertext documentation tool developed by Sun 
+Microsystems and delivered with Sun's Java distribution packages [#]_. 
+Javadoc generates detailed and well crosslinked documentation analyzing
+classes and including also comments from java source packages. Besides
+crosslinking, Javadoc creates indexes and archical trees as navigational
+aids for finding individual classes.
+
+.. [#] http://java.sun.com/j2se/javadoc/
+
+.. [#] Java is a trademark of Sun Microsystems
+
+Sun's distribution of Javadoc tools is proprietary, but there exists
+also free software (licensed unde GPL) alternatives like doc++ [#]_, 
+which can create documentation also from sources of other languages 
+(e.g. C++).
+
+.. [#] http://docpp.sourceforge.net/
+
 UML
 ---
 
@@ -168,6 +181,36 @@
  - co-operating with Rational Soda, Soda is WYSIWYG
    [pierce-tilley02connecting-documentation-rose]
 
+ - 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-nielsen-anti-mac, p.75] collects arguments/argues
+   generally against WYSIWYG.
+ 
+    - 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
+
  - though, because we are coders, we would prefer UML script 
    language over menus and dialogs when creating UML objects 
 
@@ -223,19 +266,31 @@
 
  - proprietary
 
-Dia (drawing, generating code templates)
+Dia  (drawing, generating code templates)
 
+ - Dia [#]_ a free software (licensed under GPL) diagram creating program 
+   with direct manipulation user interface.
  - more a drawing than a design tool
  - could be used instead of metapost, but
    direct manipulation problem again
- - open source 
+
+.. [#] http://www.lysator.liu.se/~alla/dia/
 
 Doxygen
 
+ - Doxygen [#]_ is an another Javadoc-like documentation tool, which
+   generates hypertext documentation from source code of good variety
+   of different languges. An intresting feature in Doxygen is that
+   it generates and embeds UML diagrams representing software's 
+   class and inheritance hierarchies into class documentation. Also
+   the currently viewed class is higlighted in diagrams. Doxygen
+   also creates shrinkable treeview for class hierarchy.
+
  - can generate useless diagrams from the code class hierarchy
  - should describe somewhere why these are useles... 
- - uses non open source graphviz
+ - uses proprietary GraphViz tool to create diagrams
 
+.. [#] http://www.doxygen.org/
 
 MetaPhor, hypertext in soft. devel? [metaphor]
 
@@ -255,15 +310,6 @@
 combines all the good parts we need from previous tools without
 reformin dramatically our workin culture.)
 
-Javadoc
--------
-
-Javadoc, the hypertext documentation tool that comes with
-Java (trademark of Sun Microsystems, Javadoc is distributed only
-as part of Java, non-free), is ...
-
-doc++ a free software alternative for javadoc
-
 Setting of problem
 ==================
 
@@ -621,6 +667,8 @@
   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
 
 - Currently, we only link UML classifiers to Java classes and other documents. 
Methods 
   could also be linked, especially in interaction diagrams.
Index: manuscripts/gzigzag.bib
diff -u manuscripts/gzigzag.bib:1.11 manuscripts/gzigzag.bib:1.12
--- manuscripts/gzigzag.bib:1.11        Mon Jan 27 09:19:38 2003
+++ manuscripts/gzigzag.bib     Tue Jan 28 09:21:39 2003
@@ -2730,7 +2730,7 @@
     publisher = {Reading, MA: Addison-Wesley},
 }
 
address@hidden,
address@hidden,
   author = {William Harrison , Charles Barton , Mukund Raghavachari},
   title = {Mapping UML designs to Java},
   booktitle = {ACM SIGPLAN Notices},