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

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/02/13 04:39:45

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

Log message:
        refs

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/gzigzag.bib.diff?tr1=1.23&tr2=1.24&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/gzz/manuscripts/UMLLink/article.rst.diff?tr1=1.12&tr2=1.13&r1=text&r2=text

Patches:
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.12 
manuscripts/UMLLink/article.rst:1.13
--- manuscripts/UMLLink/article.rst:1.12        Wed Feb 12 13:31:11 2003
+++ manuscripts/UMLLink/article.rst     Thu Feb 13 04:39:45 2003
@@ -5,7 +5,7 @@
 .. Alternative title: "Free Software toolchain for bidirectional 
    linking between UML diagrams and Javadoc"
 
-.. :Stamp: $Id: article.rst,v 1.12 2003/02/12 18:31:11 humppake Exp $
+.. :Stamp: $Id: article.rst,v 1.13 2003/02/13 09:39:45 humppake Exp $
 
 .. Points for HT people
    ====================
@@ -214,8 +214,7 @@
 
 - provide a plugin interface for different documentation tools
 
-
-Up to this article all steps except the last one are implemented. The
+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 [friendly95javadoc]_, Docutils [goodger02docutils]_, and
 our own UML diagram description tool. Further, the UML tool uses
@@ -229,69 +228,34 @@
 alternative or using them as parallel should be possible with only
 minor plugin programming.
 
-it is also  
-
-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 how we arrived at creating a
-language instead of using a diagram drawing tool with direct
-manipulation GUI.
-
-
-- flow diagram of the implementation
-
-reST's filosophy
-
-- indentation for blocks
-- robust for erros
-- "natural" to write
-- "ASCII layout" (our language for UML is an exception, which is discussed 
-  later)
-
-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
-
-
- - 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
+The javadoc format is the standard way to include documentation in
+Java source code [friendly95javadoc]_. Generating the WWW pages is not
+a complicated process, and at the moment GNU Classpath Tools
+[fsf02classpath]_ is developing a Free Software implementation called
+gjdoc. Also many other Javadoc like Free Software tools for exists -
+many of them supporting multiple programming languages including Java.
+
+.. 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.
+
+UML tool
+--------
+
+Our UML 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
+instead of using already existing free diagram drawing tool like Dia
+[larsson03dia]_, or CASE-tool like AgroUML [tigris03argouml]_.
+
+.. There exist also such Javadoc like tools, which generate some embedded
+   diagrams into documentation. Doxygen [heesch03doxygen]_ ,for example,
+   generates diagrams of class inheritance tree. Also proprietary
+   Rational Rose has could be
 
-    - Rational Soda is WYSIWYG, maybe this could be discussed under
-      it
+Though,as discussed earlier, we wanted to use human created diagrams
+in our design documentation.
 
  - though, because we are coders, we would prefer UML description 
    language over menus and dialogs when creating UML diagrams
@@ -347,6 +311,49 @@
      replacing already created object
 
 
+ - 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
+
+
+Docutils
+--------
+
+reST's filosophy
+
+- indentation for blocks
+- robust for erros
+- "natural" to write
+- "ASCII layout" (our language for UML is an exception, which is discussed 
+  later)
+
+  
+   [gentner-nielsen96anti-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
+
+
 - not strictly necessary; could have used another editor
 
 - minimum barrier to make a diagram (well, at first have to learn our 
@@ -359,6 +366,18 @@
       + elements are easily described
 
       + graphical placing would need an GUI
+
+
+- flow diagram of the implementation
+
+reST's filosophy
+
+- indentation for blocks
+- robust for erros
+- "natural" to write
+- "ASCII layout" (our language for UML is an exception, which is discussed 
+  later)
+
 
 - diagrams in the same reST source as the architecture document
 
Index: manuscripts/gzigzag.bib
diff -u manuscripts/gzigzag.bib:1.23 manuscripts/gzigzag.bib:1.24
--- manuscripts/gzigzag.bib:1.23        Wed Feb 12 13:13:52 2003
+++ manuscripts/gzigzag.bib     Thu Feb 13 04:39:45 2003
@@ -378,17 +378,20 @@
  publisher = {ACM Press},
  }
 
address@hidden gentner-nielsen-anti-mac,
-    author = "Don Gentner and Jakob Nielsen",
-    title = "The Anti-Mac interface",
-    journal = "Communications of the ACM",
-    volume = "39",
-    number = "8",
-    pages = "70--82",
-    year = "1996",
-    doi = "http://doi.acm.org/10.1145/232014.232032";
address@hidden,
+   author = {Don Gentner and Jakob Nielsen},
+   title = {The Anti-Mac interface},
+   journal = {Communications of the ACM},
+   volume = {39},
+   number = {8},
+   year = {1996},
+   issn = {0001-0782},
+   pages = {70--82},
+   doi = {http://doi.acm.org/10.1145/232014.232032},
+   publisher = {ACM Press},
 }
 
+
 @article{ shneiderman-direct-manipulation,
     title = "Hypertext: An introduction and survey",
     author = "Ben Shneiderman",
@@ -1647,21 +1650,51 @@
    year = {1989}
 }
 
address@hidden fsf02categories,
address@hidden,
   key =         {Free Software Foundation, Inc.},
   publisher =   {Free Software Foundation, Inc.},
   title =       {Categories of Free and Non-Free Software},
   year =        {2002},
   howpublished = {\url{http://www.fsf.org/philosophy/categories.html}},
-  url =         {http://www.fsf.org/philosophy/categories.html}
+}
+
address@hidden,
+  key =         {Free Software Foundation, Inc.},
+  publisher =   {Free Software Foundation, Inc.},
+  title =       {GNU Classpath-tools},
+  year =        {2002},
+  howpublished = {\url{http://www.gnu.org/software/cp-tools/}},
 }
 
 @Misc{goodger02docutils,
   author =      {David Goodger},
   title =       {An Introduction to reStructuredText},
-  howpublished = 
{\url{http://docutils.sourceforge.net/spec/rst/introduction.html}},
+  howpublished = {\url{http://docutils.sourceforge.net/spec/rst/}},
   year =        {2002},
 }
+
address@hidden,
+  author =      {Alexander Larsson, Cyrille Chépélov and Lars Clausen and Hans 
Breuer},
+  title =       {Dia - a drawing tool},
+  howpublished = {\url{http://www.lysator.liu.se/~alla/dia/}},
+  year =        {2003},
+}
+
address@hidden,
+  key =         {Tigris.org - Open Source Software Engineering},
+  publisher =   {Tigris.org - Open Source Software Engineering},
+  title =       {ArgoUML - A modelling tool for design using UML},
+  howpublished = {\url{http://argouml.tigris.org/}},
+  year =        {2002},
+}
+
address@hidden,
+  author =      {Dimitri van Heesch},
+  title =       {Doxygen - a documentation system},
+  howpublished = {\url{http://www.doxygen.org/}},
+  year =        {2003},
+}
+
 
 @comment misc(urn-working-group,
 @comment title = {IETF Uniform Resource Names Working Group},