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

[Asko Soukka]

CVSROOT:        /cvsroot/gzz
Module name:    manuscripts
Changes by:     Asko Soukka <address@hidden>    03/02/12 12:30:21

Modified files:
        UMLLink        : Makefile article.rst 

Log message:
        references

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

Patches:
Index: manuscripts/UMLLink/Makefile
diff -u manuscripts/UMLLink/Makefile:1.5 manuscripts/UMLLink/Makefile:1.6
--- manuscripts/UMLLink/Makefile:1.5    Wed Feb 12 06:17:49 2003
+++ manuscripts/UMLLink/Makefile        Wed Feb 12 12:30:21 2003
@@ -9,18 +9,18 @@
 clean:
        rm -f *.gen.* *.~*
 
-#%.gen.pdf: %.gen.ps
-#      ps2pdf $*.gen.ps $*.gen.pdf
+%.gen.pdf: %.gen.ps
+       ps2pdf $*.gen.ps $*.gen.pdf
 
-%.gen.pdf: %.gen.latex
-       pdflatex $*.gen.latex
+#%.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
+       BIBINPUTS=..:$$BIBINPUTS bibtex $*.gen
+       latex $*.gen.latex
 
 %.gen.ps: %.gen.dvi
        dvips $*.gen.dvi -o $*.gen.ps
Index: manuscripts/UMLLink/article.rst
diff -u manuscripts/UMLLink/article.rst:1.9 manuscripts/UMLLink/article.rst:1.10
--- manuscripts/UMLLink/article.rst:1.9 Wed Feb 12 09:46:39 2003
+++ manuscripts/UMLLink/article.rst     Wed Feb 12 12:30:21 2003
@@ -4,7 +4,7 @@
 
 Alternative title: "Bridging Javadoc to design documentation via UML diagrams"?
 
-:Stamp: $Id: article.rst,v 1.9 2003/02/12 14:46:39 tuukkah Exp $
+:Stamp: $Id: article.rst,v 1.10 2003/02/12 17:30:21 humppake Exp $
 
 Points for HT people
 ====================
@@ -107,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
@@ -123,39 +124,32 @@
 Diagrams
 ========
 
-
-
 Introduction
 ============
 
-Software projects manage a large base of evolving documentation, which is 
-inter-related on many levels. Design documentation gives architectural views 
-on more general level, while the program code source files give all the minute 
-details on how the computer should act and contain embedded documentation for 
-human-readability. Although these two parts of documentation are 
-semantically dependent, in practice they are often linked scarcely -- if at 
-all.
-
-The Unified Modeling Language (UML) is the standard way to XXX visually 
-describe software constructs in diagrams _[#]. It was originally developed 
-for descriptions 
-on an abstract level (many constructs cannot be directly expressed in 
-any programming language) _[#], but current trend is to use it also on the 
-concrete 
-level, as to fully unify the architectural documentation and program code: the 
-program code might be generated from highly detailed diagrams _[#], or exact 
-diagrams be produced from the source code _[#].
-
-
-.. [#] ``XXX`` booch-jacobson-rumbaugh-uml-user-guide? 
-
-.. [#] booch-jacobson-rumbaugh-uml-user-guide p.15
-       booch-jacobson-rumbaugh-uml-reference-manual p.4
-
-.. [#] harrison-barton-raghavachari00uml-to-java
-
-.. [#] pierce-tilley02connecting-documentation-rose
+Software projects manage a large base of evolving documentation, which
+is inter-related on many levels. Design documentation gives
+architectural views on more general level, while the program code
+source files give all the minute details on how the computer should
+act and contain embedded documentation for human-readability. Although
+these two parts of documentation are semantically dependent, in
+practice they are often linked scarcely -- if at all.
+
+The Unified Modeling Language (UML) is the standard way to visually
+describe software constructs in diagrams
+[booch-jacobson-rumbaugh98uml-user-guide]_. It was originally
+developed for descriptions on an abstract level (many constructs
+cannot be directly expressed in any programming language)
+[booch-jacobson-rumbaugh98uml-user-guide]_, but current trend is to
+use it also on the concrete level, as to fully unify the architectural
+documentation and program code: the program code might be generated
+from highly detailed diagrams
+[harrison-barton-raghavachari00uml-to-java]_, or exact diagrams be
+produced from the source code
+[pierce-tilley02connecting-documentation-rose]_.
 
+.. uml user guide p.XXX
+.. uml user guide p.12
 
 Against this trend, we still use UML only to plan and document our software 
 architecture on general level. UML functions as a common language for 
@@ -164,46 +158,51 @@
 human-drawn diagrams to exact illustrations matching source code to 
 every detail: 
 
-    "You draw diagrams to visualize a system from different
-    perspectives, so a diagram is a projection into a system.
-    For all but the most trivial systems, a diagram represents an elided
-    view of the elements that make up a system." [#]_
-
-:   (could other stakeholders be identified and described to some extent
-    somewhere? it might be interesting to think also towards users/customers,
-    who in some methods (ways of using XP) control use cases themselves)
-
-:   UML is easier to read than write. Also, non-programmers often don't have
-    the insight needed to directly take part in designing (even in use cases)?
-
-.. [#] booch-jacobson-rumbaugh-uml-user-guide, p.24
-
-
-In this article, we present a navigational aid which connects the two distinct
-areas of documentation, and its fairly easy implementation which 
-supplements the toolchain of other Free Software [] we use. The other 
-documentation tools can already generate web pages, and the tool injects the 
-added linking to those HTML files. The tool automatically generates the 
-linking deduced from readily available UML diagram descriptions in our 
-documentation. This means the tool is deployable without further authoring. 
-
-It turns out that in addition to working as multi-ended links, the diagrams 
-each generate a new navigational context within the target nodes. We found
-this useful because the Javadoc tool, which we use for program code 
-documentation, does not promote un-hierarchical coherence.
+   "You draw diagrams to visualize a system from different
+   perspectives, so a diagram is a projection into a system.
+   For all but the most trivial systems, a diagram represents an elided
+   view of the elements that make up a system."
+   [booch-jacobson-rumbaugh98uml-user-guide]_ 
+
+.. from uml user guide p.24
+
+.. (could other stakeholders be identified and described to some
+   extent somewhere? it might be interesting to think also towards
+   users/customers, who in some methods (ways of using XP) control
+   use cases themselves)
+
+.. UML is easier to read than write. Also, non-programmers often
+   don't have the insight needed to directly take part in designing
+   (even in use cases)?
+
+In this article, we present a navigational aid which connects the two
+distinct areas of documentation, and its fairly easy implementation
+which supplements the toolchain of other Free Software
+[fsf02categories]_ we use. The other documentation tools can already
+generate web pages, and the tool injects the added linking to those
+HTML files. The tool automatically generates the linking deduced from
+readily available UML diagram descriptions in our documentation. This
+means the tool is deployable without further authoring.
+
+It turns out that in addition to working as multi-ended links, the
+diagrams each generate a new navigational context within the target
+nodes. We found this useful because the Javadoc tool, which we use for
+program code documentation, does not promote un-hierarchical
+coherence.
 
-: Javadoc has plenty of unhierarchical links, but they are not meaningful, 
-  they don't give the documentation any structure.
+..  Javadoc has plenty of unhierarchical links, but they are not meaningful, 
+    they don't give the documentation any structure.
 
-: XXX move last chapter away from Introduction?
+..  XXX move last chapter away from Introduction?
 
 Implementation
 ==============
 
-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:
+Eventually, we found no Free Software [fsf02categories]_ tools which
+would fulfill our needs. Therefore, we decided to proceed with our own
+implementation. In addition to the previously discussed goals of the
+documentation as whole, there were also several implementation related
+goals to be achieved. The tool had to:
  
 - be tidy and light-weight
 
@@ -217,14 +216,13 @@
 
 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
+Javadoc [friendly95javadoc]_, Docutils [XXX], and our own UML diagram 
description
 tool. Further, the UML tool uses several free utilies to convert
 each 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
 linking utility could also be used with other HTML documentation