[Gzz-commits] manuscripts/UMLLink short-paper.rst

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/05/21 14:58:34

Modified files:
        UMLLink        : short-paper.rst 

Log message:
        textual UML

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/short-paper.rst.diff?tr1=1.25&tr2=1.26&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/short-paper.rst
diff -u manuscripts/UMLLink/short-paper.rst:1.25 
manuscripts/UMLLink/short-paper.rst:1.26
--- manuscripts/UMLLink/short-paper.rst:1.25    Wed May 21 14:41:51 2003
+++ manuscripts/UMLLink/short-paper.rst Wed May 21 14:58:34 2003
@@ -2,7 +2,7 @@
 Bridging Javadoc and design documentation via UML diagram image maps
 ====================================================================
 
-.. $Id: short-paper.rst,v 1.25 2003/05/21 18:41:51 tjl Exp $
+.. $Id: short-paper.rst,v 1.26 2003/05/21 18:58:34 humppake Exp $
 
 .. short paper == 2 pages, deadline the end of May
 
@@ -52,6 +52,11 @@
     documentation embedded in the program code, such as Javadoc. 
     \end{abstract}
 
+..  of documentation: design documents and javadoc program code
+    documentation.  
+    \end{abstract}
+
+
 Introduction
 ============
 
@@ -230,20 +235,27 @@
 The implementation in Navidoc
 =============================
 
-Navidoc is as a light-weight tool built on top of several existing
-Free Software tools. 
+.. think, this should be much clearer :) But how to say everything shortly...
 
-..  The main existing components are Docutils [goodger02docutils]_,
+Navidoc, our implementation, is as a light-weight tool built on top of
+several existing Free Software tools. Its main purpose is to compile
+the design documentation and UML diagrams embedded within it. 
+Navidoc uses several free utilies to convert each
+textual UML diagram description into a set of imagemaps --- one
+for each target document since the current document is highlighted
+in the images. These diagrams embedded into target documents, allow easy 
traverse
+through all the participant nodes and backlink to the startup page holding
+the original diagram.
+
+.. After compiling, it creates imagemaps for every UML diagram to link
+   diagrams' elements to corresponding source code documentation
+   pages. Linked diagrams will also be embedded into every target page to
 
+.. The main existing components are Docutils [goodger02docutils]_,
 
 ..  we can only have very few references [fsf02categories]_ 
 
-- main parts: Docutils [goodger02docutils]_, lexical UML language
-
-Navidoc uses several free utilies to convert each
-textual UML diagram description into a set of imagemaps --- one
-for each target document since the current document is highlighted
-in the images.
+.. - main parts: Docutils [goodger02docutils]_, lexical UML language
 
 ..  No space for this, I wager
 
@@ -251,13 +263,28 @@
     (mpost), which implements a language for picture drawing, and Netpbm
     image file manipulation toolkit. 
 
-- why lexical UML language:
+.. - why lexical UML language:
+
+    * no need for additional tools, when writing documentation
 
-  * no need for additional tools, when writing documentation
+    * describing is fast
 
-  * describing is fast
+    * setting layout may be more 
 
-  * setting layout may be more 
+We've it found useful to create UML diagrams using textual syntax
+embedded within documentation page originals. In small softaware
+development groups, where programmers also write the documentation,
+the documentation tools shouldn't be gap to change the programming
+tool to document writing tools. Textual UML diagram description, of
+course, can be written with any text editor. Comparing with any direct
+manipulation drawing tool, textual description may feel abstract at
+first, but the when users are programmers it could be even more
+natural for them to describe things lexically.
+
+.. Also at least for a
+   programmer, who are used to describe objects lexically, describing
+   the UML diagrams lexically should keep the gap low for using
+   also diagrams, when documenting the software project.
 
 .. Embedding diagrams into HTML
    ============================