[Gzz-commits] manuscripts/UMLLink article.rst

[Tuukka Hastrup]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Tuukka Hastrup <address@hidden> 03/02/12 02:51:41

Modified files:
        UMLLink        : article.rst 

Log message:
        went through Implementation

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

Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.5 manuscripts/UMLLink/article.rst:1.6
--- manuscripts/UMLLink/article.rst:1.5 Tue Feb 11 14:06:53 2003
+++ manuscripts/UMLLink/article.rst     Wed Feb 12 02:51:41 2003
@@ -1,8 +1,10 @@
 
====================================================================================
-A free software toolchain for bidirectional linking between UML diagrams and 
Javadoc
+A Free Software toolchain for bidirectional linking between UML diagrams and 
Javadoc
 
====================================================================================
 
-:Stamp: $Id: article.rst,v 1.5 2003/02/11 19:06:53 humppake Exp $
+Alternative title: "Bridging Javadoc to design documentation via UML diagrams"?
+
+:Stamp: $Id: article.rst,v 1.6 2003/02/12 07:51:41 tuukkah Exp $
 
 Points for HT people
 ====================
@@ -68,7 +70,8 @@
        all documents
      * result still browsable in WWW
  * tjl: "quick but elegant hack" - small, useful, free tool
- * UML is a *language* - allows concise expression in textual form
+ * UML is a *language* - allows concise expression
+       * in textual form with our description language
 
 navigation:
  * bidirectional
@@ -104,6 +107,7 @@
 * UML diagrams: distinct context for Java classes and packages and relevant 
   architectural documentation; spatial menu; also node (XXX multi-ended nexus
   links)
+       * generated by our UML tool from our UML diagram description language
 
 * Cross-reference by Javadoc: cheap cross-link
 * Cross-link from javadoc comments: simple hyperlink
@@ -111,53 +115,57 @@
   (poorly implemented as WWW)
 
 * Links in UML diagrams: context navigation links
+       * generated by our UML link tool without any extra information
 
 * (XXX Free Software vs. Open Source vs. Open Software vs. Open Project...)
 
+
 Implementation
 ==============
 
-Eventually, we found no Free Software [XXX] alternatives, which would
-have fulfilled our needs. Therefore we decide to proceed with our own
+Eventually, we found no Free Software [XXX] tools which would
+fulfill our needs. Therefore, we decided to proceed with our own
 implementation. There were several goals to be achieved. The tool had
 to:
  
-- be tidy and light weight
+- be tidy and light-weight
 
 - be built on existing Free Software tools
   and be a part of Free Software toolchain 
 
-- generate output easily editable by others (from the source)
+- support easy re-editing (from the source)
 
 - provide a plugin interface for different documentation tools
 
 
-Up to this article all steps beside the last one are implemented. The
-existing tools we selected on the base of our documentation tool are:
-Javadoc [XXX], Docutils [XXX], and our own language based UML diagram
-tool. The UML tools also uses several Free Software utilies to convert
-the lexical UML description into final PNG (*Portable Network
-Graphics*) diagram files. Such utilies are mpost [XXX] (*MetaPost*),
-pstopnm [XXX] (*PostScript to Portable anymap*), pnmscale [XXX]
-(*Portable anymap scaling utility*) and pnmtopng (*Portable anymap to
-Portable Network Graphics*). Besides Javadoc, all tools used are Free
+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 [XXX], Docutils [XXX], and our own UML diagram description
+tool. The UML tools also use several free utilies to convert
+the lexical UML description into final *Portable Network
+Graphics* (PNG) diagram files. Such utilies are *MetaPost* [XXX] (mpost), 
+which implements a language for picture drawing, and Netpbm image file 
+manipulation toolkit. Besides Javadoc, all tools used are Free
 Software. 
 
 
-??After the plugin interface is created the documentation
+??After the plugin interface is created, the documentation
 linking utility could also be used with other HTML documentation
 generators in addition to Javadoc. Though, so far, has Javadoc provided a good 
enough source code documentation for our purposes and we probably have no 
reasons to change it?
 
 it is also  
 
-
-Because Javadoc have provided good enough fully generated and up-to-dated 
detailed documentation for our use, we had no reason to abandon it.
+The javadoc format is the standard way to include documentation in Java 
+source code. Generating the WWW pages is not a complicated process, and at the
+moment GNU Classpath Tools is developing a Free Software implementation called 
+gjdoc. As Javadoc has provided good enough fully generated and up-to-date 
+detailed documentation for our use, we have had no reason to abandon it yet.
 
 On the 
 
 Although our UML language was already implemented before the linking
 tool, which finally created the bi-directional linking between
-documentations, we discuss shortly about why we ended to create a
+documentations, we discuss shortly how we arrived at creating a
 language instead of using a diagram drawing tool with direct
 manipulation GUI.
 
@@ -169,13 +177,14 @@
 - indentation for blocks
 - robust for erros
 - "natural" to write
-- "ASCII layout" (our UML-language is an exception, which is discussed later)
+- "ASCII layout" (our language for UML is an exception, which is discussed 
+  later)
 
-Why UML-language
+Why UML description language
 
  - Doxygen can generate useless diagrams from the code class hierarchy 
-   should describe somewhere why these are useles... 
-   uses proprietary GraphViz tool to create diagrams
+     * 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
@@ -208,8 +217,8 @@
     - 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 
+ - though, because we are coders, we would prefer UML description 
+   language over menus and dialogs when creating UML diagrams
 
    + we need a ref. of criticism of direct manipulation!
 
@@ -264,15 +273,16 @@
 
 - not strictly necessary; could have used another editor
 
-- minimum barrier to make a diagram (well, at first have to learn our 
UML-script)
+- minimum barrier to make a diagram (well, at first have to learn our 
+       description language)
 
 - direct manipulation when building / editing structure of diagrams clumsy
  
-     - users are programmers --> a simple programming language is better than 
d.m.
+     - users are programmers --> a language is better than d.m.
 
-      + elements are easy to create by script language
+      + elements are easily described
 
-      + graphical placing could need an GUI
+      + graphical placing would need an GUI
 
 - diagrams in the same reST source as the architecture document
 
@@ -283,4 +293,4 @@
        interactively editable.
 
 - Dia could be used instead of metapost, but
-  direct manipulation problem again
\ No newline at end of file
+  direct manipulation problem again