[Gzz-commits] manuscripts/UMLLink Makefile article.rst SKETCH...

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/02/11 14:06:53

Modified files:
        UMLLink        : Makefile article.rst 
Added files:
        UMLLink        : SKETCH 
Removed files:
        UMLLink        : article-sketch.rst 

Log message:
        implementation goals

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

Patches:
Index: manuscripts/UMLLink/Makefile
diff -u manuscripts/UMLLink/Makefile:1.3 manuscripts/UMLLink/Makefile:1.4
--- manuscripts/UMLLink/Makefile:1.3    Tue Feb 11 11:42:09 2003
+++ manuscripts/UMLLink/Makefile        Tue Feb 11 14:06:53 2003
@@ -1,13 +1,32 @@
-RST_TARGETS=$(shell for file in *.rst; do echo $${file%.rst}.gen.html; done)
 DIA_TARGETS=$(shell for file in *.dia; do echo $${file%.dia}.gen.png; done)
+RST_TARGETS=$(shell for file in *.rst; do echo $${file%.rst}.gen.pdf; done)
 
-all: $(RST_TARGETS) $(DIA_TARGETS)
+all: $(DIA_TARGETS) $(RST_TARGETS)
 
 showtargets:
-       echo $(RST_TARGETS) $(DIA_TARGETS)
+       echo$(DIA_TARGETS) $(RST_TARGETS) 
 
 clean:
-       rm -f *.gen.*
+       rm -f *.gen.* *.~*
+
+%.gen.pdf: %.gen.ps
+       ps2pdf $*.gen.ps $*.gen.pdf
+
+#%.gen.pdf: %.gen.latex
+#      pdflatex $*.gen.latex
+#      BIBINPUTS=..:$$BIBINPUTS bibtex $*.gen
+#      pdflatex $*.gen.latex
+
+%.gen.dvi: %.gen.latex
+       latex $*.gen.latex
+       BIBINPUTS=..:$$BIBINPUTS bibtex $*.gen
+       latex $*.gen.latex
+
+%.gen.ps: %.gen.dvi
+       dvips $*.gen.div -o $*.gen.ps
+
+%.gen.latex: %.rst
+       $(MAKE) -C ../../gzz rst RST="../manuscripts/UMLLink/$*.rst"
 
 %.gen.html: %.rst
        $(MAKE) -C ../../gzz rst RST="../manuscripts/UMLLink/$*.rst"
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.4 manuscripts/UMLLink/article.rst:1.5
--- manuscripts/UMLLink/article.rst:1.4 Tue Feb 11 11:31:11 2003
+++ manuscripts/UMLLink/article.rst     Tue Feb 11 14:06:53 2003
@@ -2,11 +2,7 @@
 A free software toolchain for bidirectional linking between UML diagrams and 
Javadoc
 
====================================================================================
 
-:Stamp: $Id: article.rst,v 1.4 2003/02/11 16:31:11 tuukkah Exp $
-
-
-
-
+:Stamp: $Id: article.rst,v 1.5 2003/02/11 19:06:53 humppake Exp $
 
 Points for HT people
 ====================
@@ -118,9 +114,173 @@
 
 * (XXX Free Software vs. Open Source vs. Open Software vs. Open Project...)
 
-Introduction
-============
+Implementation
+==============
+
+Eventually, we found no Free Software [XXX] alternatives, which would
+have fulfilled our needs. Therefore we decide to proceed with our own
+implementation. There were several goals to be achieved. The tool had
+to:
+ 
+- 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)
+
+- 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
+Software. 
+
+
+??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.
+
+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
+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 UML-language is an exception, which is discussed later)
+
+Why UML-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
+
+    - 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 
+
+   + we need a ref. of criticism of direct manipulation!
+
+     - not necessarily improve performance, users must learn the meaning
+       of the graphical components, graphic presentation could be 
+       misleading, graphical presentation could take excessive screen display
+       space [Shneiderman-direct-manipulation, p. 64]
+
+       probably only the first argument of performance is relevant
+       anymore... though, creating the graphic presentation for problem
+       could lead to using metaphors and those are often
+       criticized (even by D. Norman :)
+      
+     - "The dark side of a direct manipulation interface is that
+       you have to directly manipulate everything. Instead of an
+       executive who gives high-level instructions, the user is 
+       reduced to an assembly line worker who must carry out the
+       same task over and over."
+       [gentner-nielsen-anti-mac, p.74]  
+
+       limits the precision of our actions to the precision
+       achieved  with eye-hand-mouse coordination (language and 
+       mathematics can be more precise)
+       [gentner-nielsen-anti-mac, p.74]  
+
+       direct manipulation requires the user to be involved in
+       every action, but sometimes the user may not know
+       what to do
+       [gentner-nielsen-anti-mac, p.74]  
+
+       "It's as if we have thrown away a million years of 
+       evolution, lost our facility with expressive language,
+       and been reduced to pointing at objects in the immediate
+       environment. -- We have lost all the power of language, and
+       can no longer talk about objects that are not immidiately
+       visible."    
+       [gentner-nielsen-anti-mac, p.74]  
+
+     - summaring: direct manipulation could be easy, if there is
+       a natural graphic presentation for the problem. Even then 
+       it's not necesesserily the most efficient method. Also the
+       practical point of using the same writing tool foor coding and 
+       documenting.
+
+   + Rose's problem with direct manipulation: a lot of windows, 
+     menus, dialogies etc... to get direct manipulateable graphic
+     representation for everything
+
+   + though, directmanipulation is only relevant solution for
+     replacing already created object
+
+
+- not strictly necessary; could have used another editor
+
+- minimum barrier to make a diagram (well, at first have to learn our 
UML-script)
+
+- direct manipulation when building / editing structure of diagrams clumsy
+ 
+     - users are programmers --> a simple programming language is better than 
d.m.
+
+      + elements are easy to create by script language
+
+      + graphical placing could need an GUI
+
+- diagrams in the same reST source as the architecture document
+
+- separate UML structure from presentation, show structure in easily
+  editable text
 
-UML (the Unified Modeling Language), founded mainly by Booch, Jacobson and
-Rumbaugh during 1900s to ``XXX blah blah`` [#]_, has become the *de facto* --
+     - placement: currently metapost; looking at ways to make 
+       interactively editable.
 
+- Dia could be used instead of metapost, but
+  direct manipulation problem again
\ No newline at end of file