[Gzz-commits] manuscripts/UMLLink article.rst

[Tuomas J. Lukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Tuomas J. Lukka <address@hidden>        03/02/15 04:56:51

Modified files:
        UMLLink        : article.rst 

Log message:
        steps

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/article.rst.diff?tr1=1.41&tr2=1.42&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.41 
manuscripts/UMLLink/article.rst:1.42
--- manuscripts/UMLLink/article.rst:1.41        Sat Feb 15 04:43:14 2003
+++ manuscripts/UMLLink/article.rst     Sat Feb 15 04:56:51 2003
@@ -9,7 +9,7 @@
 .. Alternative title: "Free Software toolchain for bidirectional 
    linking between UML diagrams and Javadoc"
 
-.. :Stamp: $Id: article.rst,v 1.41 2003/02/15 09:43:14 tjl Exp $
+.. :Stamp: $Id: article.rst,v 1.42 2003/02/15 09:56:51 tjl Exp $
 
 .. Points for HT people
    ====================
@@ -482,48 +482,44 @@
 
 **Step 0; The beginning.** In the beginning we had a distinct design
 documentation with UML diagrams and Javadoc generated from the
-sourcecode. This is probably the most common case. The both pieces
-of documentation could comprehensive and well navigable by their own,
-but their information is hard to combine, because there is no
+sourcecode --- probably the most common case. Both 
+could be comprehensive and well navigable by their own,
+their information is difficult for the reader to combine 
+because there is no
 crosslinking between them.
 
 .. Advantage over paper: NONE
 
-**Step 1; Automatizing cross-indexing.** After the first step links
-from design documentation's UML diagrams are created into relevant
-Javadoc class documentation. Javadoc is finally reachable from design
-documentation simply by clicking the relevant class or package within
-embedded UML diagrams. Though, after moving to the Javadoc the context
-in design documentation would be immidiately lost. Also there is no
-links from Javadoc to design documentation.
+**Step 1; UML to Javadoc links.** Now there are imagemap links
+from the UML diagrams in the design documentation to the relevant
+Javadoc pages. 
+However, after moving to Javadoc the context
+in design documentation is lost, and 
+there are no links from Javadoc to design documentation.
 
 .. Advantage over paper: MARGINAL: automatize cross-indexing
 
-**Step 2; UML diagram context of a particular class may be seen and
-traversing between them is possible.** After the second step UML
-diagrams are implicitly embedded into Javadoc and embedded UML
-diagrams' objects also work as multi-end nexus links. We have diagrams
-working as menus between the objects that appear in diagrams.  Though,
-even though a single diagram could be used to traverse between all the
-documentation pages referred to in the diagram, the initiating design
-document is unreachable from the diagram itself.
+**Step 2; Relevant UML diagrams embedded in Javadoc.** 
+The UML
+diagrams are now embedded into the Javadoc pages they refer
+to, and they function as imagemaps also on the Javadoc pages.
+The diagrams function as menus between the objects that appear in diagrams.  
+While this step provides more context for the actual classes,
+the design documentation relevant to a given javadoc page
+is still unreachable.
 
 .. Advantage over paper: SOME: see the UML diagram contexts of a class,
    traverse them
 
-**Step 3; Multi-end nexus links easily traversable and structure of
-documentation can be understood.** Finally backlinks to the
-originating design documentation are added. It's possible to "step
-back" from class documentation back to design documentation. After
-backlinks to the design documentation are added, a single diagram
-links to all design documents and Javadoc pages where it is explicitly
-or implicitly included. Even though the design documents were not in
-roles in the original UML diagrams, they are included in the final
-image on top of the diagram. Putting all these into one graphical
-image makes the all links look a consistent whole - like a spatial
-menu. In the image, the element that represents the current document
-page is also focused and the objective of focus+contex menu is
-achieved.
+**Step 3; From Javadoc through a UML diagram to a design document.** 
+Even though the design documents were not included
+in the original UML diagrams, they are included in the final
+image on top of the diagram. Including **all** the contexts where
+the diagram appears as links 
+in the graphical
+image creates a consistent whole - a spatial focus+context menu. 
+The element that represents the current hypertext node
+is emphasized (colored and also circled) for clarity.  
 
 Because the original location on the diagrams is easily reachable from
 its every implicit occurerrence in Javadoc or in design documentation,