/[gzz]/manuscripts/UMLLink/article.rst
ViewVC logotype

Diff of /manuscripts/UMLLink/article.rst

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.4 by tuukkah, Tue Feb 11 16:31:11 2003 UTC revision 1.5 by humppake, Tue Feb 11 19:06:53 2003 UTC
# Line 4  A free software toolchain for bidirectio Line 4  A free software toolchain for bidirectio
4    
5  :Stamp: $Id$  :Stamp: $Id$
6    
   
   
   
   
7  Points for HT people  Points for HT people
8  ====================  ====================
9    
# Line 118  Conceptual model (for HT people!) Line 114  Conceptual model (for HT people!)
114    
115  * (XXX Free Software vs. Open Source vs. Open Software vs. Open Project...)  * (XXX Free Software vs. Open Source vs. Open Software vs. Open Project...)
116    
117  Introduction  Implementation
118  ============  ==============
119    
120    Eventually, we found no Free Software [XXX] alternatives, which would
121    have fulfilled our needs. Therefore we decide to proceed with our own
122    implementation. There were several goals to be achieved. The tool had
123    to:
124    
125    - be tidy and light weight
126    
127    - be built on existing Free Software tools
128      and be a part of Free Software toolchain
129    
130    - generate output easily editable by others (from the source)
131    
132    - provide a plugin interface for different documentation tools
133    
134    
135    Up to this article all steps beside the last one are implemented. The
136    existing tools we selected on the base of our documentation tool are:
137    Javadoc [XXX], Docutils [XXX], and our own language based UML diagram
138    tool. The UML tools also uses several Free Software utilies to convert
139    the lexical UML description into final PNG (*Portable Network
140    Graphics*) diagram files. Such utilies are mpost [XXX] (*MetaPost*),
141    pstopnm [XXX] (*PostScript to Portable anymap*), pnmscale [XXX]
142    (*Portable anymap scaling utility*) and pnmtopng (*Portable anymap to
143    Portable Network Graphics*). Besides Javadoc, all tools used are Free
144    Software.
145    
146    
147    ??After the plugin interface is created the documentation
148    linking utility could also be used with other HTML documentation
149    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?
150    
151    it is also  
152    
153    
154    Because Javadoc have provided good enough fully generated and up-to-dated detailed documentation for our use, we had no reason to abandon it.
155    
156    On the
157    
158    Although our UML language was already implemented before the linking
159    tool, which finally created the bi-directional linking between
160    documentations, we discuss shortly about why we ended to create a
161    language instead of using a diagram drawing tool with direct
162    manipulation GUI.
163    
164    
165    - flow diagram of the implementation
166    
167    reST's filosophy
168    
169    - indentation for blocks
170    - robust for erros
171    - "natural" to write
172    - "ASCII layout" (our UML-language is an exception, which is discussed later)
173    
174    Why UML-language
175    
176     - Doxygen can generate useless diagrams from the code class hierarchy
177       should describe somewhere why these are useles...
178       uses proprietary GraphViz tool to create diagrams
179    
180    
181     - How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will
182       surely ask about that,
183    
184        PARTIAL RESOLUTION:
185    
186            - proprietarity (really?)
187            - versioning much worse
188              (changes in rtf could probably be compared?)
189            - users = programmers --> used to editing text and compiling,
190              it's the most practical to use the same editor as for coding
191            - lack of good, **extensible** tools
192    
193      
194       [gentner-nielsen-anti-mac, p.75] collects arguments/argues
195       generally against WYSIWYG.
196    
197        - a document has a rich semantic structure that is poorly
198          captured by its appearance on a sceen or printed page
199        - other text representations, such as SGML, distinct the semantic
200          structure and rules for converting the text and semantics into
201          printablepage
202        - WYSIWYG assumes there is only one useful representation of the
203          information: that of the final reports
204        - WYSIWYG assumes people want paper-style reports (and we already
205          live within information flood)
206        - blind users exists
207    
208        - Rational Soda is WYSIWYG, maybe this could be discussed under
209          it
210    
211     - though, because we are coders, we would prefer UML script
212       language over menus and dialogs when creating UML objects
213    
214       + we need a ref. of criticism of direct manipulation!
215    
216         - not necessarily improve performance, users must learn the meaning
217           of the graphical components, graphic presentation could be
218           misleading, graphical presentation could take excessive screen display
219           space [Shneiderman-direct-manipulation, p. 64]
220    
221           probably only the first argument of performance is relevant
222           anymore... though, creating the graphic presentation for problem
223           could lead to using metaphors and those are often
224           criticized (even by D. Norman :)
225          
226         - "The dark side of a direct manipulation interface is that
227           you have to directly manipulate everything. Instead of an
228           executive who gives high-level instructions, the user is
229           reduced to an assembly line worker who must carry out the
230           same task over and over."
231           [gentner-nielsen-anti-mac, p.74]  
232    
233           limits the precision of our actions to the precision
234           achieved  with eye-hand-mouse coordination (language and
235           mathematics can be more precise)
236           [gentner-nielsen-anti-mac, p.74]  
237    
238           direct manipulation requires the user to be involved in
239           every action, but sometimes the user may not know
240           what to do
241           [gentner-nielsen-anti-mac, p.74]  
242    
243           "It's as if we have thrown away a million years of
244           evolution, lost our facility with expressive language,
245           and been reduced to pointing at objects in the immediate
246           environment. -- We have lost all the power of language, and
247           can no longer talk about objects that are not immidiately
248           visible."    
249           [gentner-nielsen-anti-mac, p.74]  
250    
251         - summaring: direct manipulation could be easy, if there is
252           a natural graphic presentation for the problem. Even then
253           it's not necesesserily the most efficient method. Also the
254           practical point of using the same writing tool foor coding and
255           documenting.
256    
257       + Rose's problem with direct manipulation: a lot of windows,
258         menus, dialogies etc... to get direct manipulateable graphic
259         representation for everything
260    
261       + though, directmanipulation is only relevant solution for
262         replacing already created object
263    
264    
265    - not strictly necessary; could have used another editor
266    
267    - minimum barrier to make a diagram (well, at first have to learn our UML-script)
268    
269    - direct manipulation when building / editing structure of diagrams clumsy
270    
271         - users are programmers --> a simple programming language is better than d.m.
272    
273          + elements are easy to create by script language
274    
275          + graphical placing could need an GUI
276    
277    - diagrams in the same reST source as the architecture document
278    
279    - separate UML structure from presentation, show structure in easily
280      editable text
281    
282  UML (the Unified Modeling Language), founded mainly by Booch, Jacobson and       - placement: currently metapost; looking at ways to make
283  Rumbaugh during 1900s to ``XXX blah blah`` [#]_, has become the *de facto* --         interactively editable.
284    
285    - Dia could be used instead of metapost, but
286      direct manipulation problem again

Legend:
Removed from v.1.4  
changed lines
  Added in v.1.5

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26