/[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.12 by humppake, Wed Feb 12 18:31:11 2003 UTC revision 1.13 by humppake, Thu Feb 13 09:39:45 2003 UTC
# Line 214  goals to be achieved. The tool had to: Line 214  goals to be achieved. The tool had to:
214    
215  - provide a plugin interface for different documentation tools  - provide a plugin interface for different documentation tools
216    
217    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  
218  existing tools we selected as the basis for our documentation tool  existing tools we selected as the basis for our documentation tool
219  are: Javadoc [friendly95javadoc]_, Docutils [goodger02docutils]_, and  are: Javadoc [friendly95javadoc]_, Docutils [goodger02docutils]_, and
220  our own UML diagram description tool. Further, the UML tool uses  our own UML diagram description tool. Further, the UML tool uses
# Line 229  the plugin interface is ready, switching Line 228  the plugin interface is ready, switching
228  alternative or using them as parallel should be possible with only  alternative or using them as parallel should be possible with only
229  minor plugin programming.  minor plugin programming.
230    
231  it is also    The javadoc format is the standard way to include documentation in
232    Java source code [friendly95javadoc]_. Generating the WWW pages is not
233  The javadoc format is the standard way to include documentation in Java  a complicated process, and at the moment GNU Classpath Tools
234  source code. Generating the WWW pages is not a complicated process, and at the  [fsf02classpath]_ is developing a Free Software implementation called
235  moment GNU Classpath Tools is developing a Free Software implementation called  gjdoc. Also many other Javadoc like Free Software tools for exists -
236  gjdoc. As Javadoc has provided good enough fully generated and up-to-date  many of them supporting multiple programming languages including Java.
237  detailed documentation for our use, we have had no reason to abandon it yet.  
238    .. As Javadoc has
239  On the     provided good enough fully generated and up-to-date detailed
240       documentation for our use, we have had no reason to abandon it yet.
241  Although our UML language was already implemented before the linking  
242  tool, which finally created the bi-directional linking between  UML tool
243  documentations, we discuss shortly how we arrived at creating a  --------
244  language instead of using a diagram drawing tool with direct  
245  manipulation GUI.  Our UML description tool was already implemented before the
246    documentation linking tool, which finally enabled the bi-directional
247    linking between distinctdocumentations. In the following we discuss
248  - flow diagram of the implementation  shortly, how we ended up to use this our own lexical UML language
249    instead of using already existing free diagram drawing tool like Dia
250  reST's filosophy  [larsson03dia]_, or CASE-tool like AgroUML [tigris03argouml]_.
251    
252  - indentation for blocks  .. There exist also such Javadoc like tools, which generate some embedded
253  - robust for erros     diagrams into documentation. Doxygen [heesch03doxygen]_ ,for example,
254  - "natural" to write     generates diagrams of class inheritance tree. Also proprietary
255  - "ASCII layout" (our language for UML is an exception, which is discussed     Rational Rose has could be
   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  
256    
257      - Rational Soda is WYSIWYG, maybe this could be discussed under  Though,as discussed earlier, we wanted to use human created diagrams
258        it  in our design documentation.
259    
260   - though, because we are coders, we would prefer UML description   - though, because we are coders, we would prefer UML description
261     language over menus and dialogs when creating UML diagrams     language over menus and dialogs when creating UML diagrams
# Line 347  Why UML description language Line 311  Why UML description language
311       replacing already created object       replacing already created object
312    
313    
314     - How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will
315       surely ask about that,
316    
317        PARTIAL RESOLUTION:
318    
319            - proprietarity (really?)
320            - versioning much worse
321              (changes in rtf could probably be compared?)
322            - users = programmers --> used to editing text and compiling,
323              it's the most practical to use the same editor as for coding
324            - lack of good, **extensible** tools
325    
326    
327    Docutils
328    --------
329    
330    reST's filosophy
331    
332    - indentation for blocks
333    - robust for erros
334    - "natural" to write
335    - "ASCII layout" (our language for UML is an exception, which is discussed
336      later)
337    
338      
339       [gentner-nielsen96anti-mac, p.75] collects arguments/argues
340       generally against WYSIWYG.
341    
342        - a document has a rich semantic structure that is poorly
343          captured by its appearance on a sceen or printed page
344        - other text representations, such as SGML, distinct the semantic
345          structure and rules for converting the text and semantics into
346          printablepage
347        - WYSIWYG assumes there is only one useful representation of the
348          information: that of the final reports
349        - WYSIWYG assumes people want paper-style reports (and we already
350          live within information flood)
351        - blind users exists
352    
353        - Rational Soda is WYSIWYG, maybe this could be discussed under
354          it
355    
356    
357  - not strictly necessary; could have used another editor  - not strictly necessary; could have used another editor
358    
359  - minimum barrier to make a diagram (well, at first have to learn our  - minimum barrier to make a diagram (well, at first have to learn our
# Line 360  Why UML description language Line 367  Why UML description language
367    
368        + graphical placing would need an GUI        + graphical placing would need an GUI
369    
370    
371    - flow diagram of the implementation
372    
373    reST's filosophy
374    
375    - indentation for blocks
376    - robust for erros
377    - "natural" to write
378    - "ASCII layout" (our language for UML is an exception, which is discussed
379      later)
380    
381    
382  - diagrams in the same reST source as the architecture document  - diagrams in the same reST source as the architecture document
383    
384  - separate UML structure from presentation, show structure in easily  - separate UML structure from presentation, show structure in easily

Legend:
Removed from v.1.12  
changed lines
  Added in v.1.13

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