[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gzz-commits] manuscripts/UMLLink Makefile article.rst
From: |
Asko Soukka |
Subject: |
[Gzz-commits] manuscripts/UMLLink Makefile article.rst |
Date: |
Wed, 12 Feb 2003 12:30:21 -0500 |
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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Gzz-commits] manuscripts/UMLLink Makefile article.rst,
Asko Soukka <=