/[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.34 by humppake, Fri Feb 14 23:08:52 2003 UTC revision 1.35 by humppake, Sat Feb 15 09:00:54 2003 UTC
# Line 204  We limit the enhancement to web pages ge Line 204  We limit the enhancement to web pages ge
204  process, which makes the task of our software easier than that of other web  process, which makes the task of our software easier than that of other web
205  augmentation tools [weinreich00-linkvis]_.  augmentation tools [weinreich00-linkvis]_.
206    
207  The current implementation is a part of and in use at our Free Software  The current implementation is a part of and in use at our Free
208  project [gzz]_, where it generates the publicly web-browsable  Software project [gzz]_, where it generates the publicly web-browsable
209  hypertext [gzz_doc_himalia]_ of project's documentation, as a part of the toolchain.  hypertext [gzz_doc_himalia]_ of project's documentation, as a part of
210    the toolchain.
211    
212  ..  Javadoc has plenty of unhierarchical links, but they are not meaningful,  ..  Javadoc has plenty of unhierarchical links, but they are not meaningful,
213      they don't give the documentation any structure.      they don't give the documentation any structure.
# Line 379  useful to be able to see if any design d Line 380  useful to be able to see if any design d
380  We believe that the architecture document will be read more, after  We believe that the architecture document will be read more, after
381  it's easily reachable from relevant parts of Javadoc. This is the  it's easily reachable from relevant parts of Javadoc. This is the
382  starting point for the Free Software toolchain we developed in this  starting point for the Free Software toolchain we developed in this
383  article: a toolchain for for bidirectional linking between design  article: a toolchain for bidirectional linking between design
384  documentation and Javadoc, using UML diagrams as multi-ended nexus  documentation and Javadoc, using UML diagrams as multi-ended nexus
385  links.  links.
386    
387  Design  Design
388  ======  ======
389    
390    .. some references to the screenshots here?
391    
392  XXX Hypertext blaablaa something...  XXX Hypertext blaablaa something...
393  -----------------------------------  -----------------------------------
394    
# Line 417  spatial navigation menus. Line 420  spatial navigation menus.
420  XXX linking UML diagrams  XXX linking UML diagrams
421  ------------------------  ------------------------
422    
423    .. could the table be replaces? removed?
424    
425  Looking closer, we can divide our UML diagrams into three classes:  Looking closer, we can divide our UML diagrams into three classes:
426  conceptual diagrams, specification diagrams and implementation  conceptual diagrams, specification diagrams and implementation
427  diagrams. Different diagram types can be linked within the  diagrams. Different diagram types can be linked within the
# Line 443  design documentation and to javadoc as f Line 448  design documentation and to javadoc as f
448  | implement it          |                       |                    |  | implement it          |                       |                    |
449  +-----------------------+-----------------------+--------------------+  +-----------------------+-----------------------+--------------------+
450    
451  The UML diagrams enable navigation in various purposes. Applying Trigg's  The UML diagrams enable navigation in various purposes. Applying
452  taxonomy of different link types [trigg83link-taxonomy]_, we could identify several semantic meanings  Trigg's taxonomy of different link types [trigg83link-taxonomy]_, we
453  of the links, shown in Fig. [ref-diagramlinks]_. Links from the diagram to  could identify several semantic meanings of the links, shown in
454  documentation pages are expressed in HTML imagemaps, and bi-directionality is  Fig. [ref-diagramlinks]_. Links from the diagram to documentation
455  ensured by injection of HTML IMG tags to all referred pages. As web browsers  pages are expressed in HTML imagemaps, and bi-directionality is
456  generally embed the IMG-linked diagram to the documentation nodes, the diagram  creates spatial links between all the referred pages. Further, each  ensured by injection of HTML IMG tags to all referred pages. As web
457  documentation node creates spatial links between all the diagrams it refers to,  browsers generally embed the IMG-linked diagram to the documentation
458  allowing the reader to see which alternate spatial views are available for the  nodes, the diagram creates spatial links between all the referred
459  current node.  pages. Further, each documentation node creates spatial links between
460    all the diagrams it refers to, allowing the reader to see which
461    alternate spatial views are available for the current node.
462    
463  .. figure:: umldoc-linking.gen.eps  .. figure:: umldoc-linking.gen.eps
464     :width: 16.9cm     :width: 15cm
465     :alternative: *     :alternative: *
466     :label: diagramlinks     :label: diagramlinks
467    
# Line 464  current node. Line 471  current node.
471  Documentation reader's point of view  Documentation reader's point of view
472  ---------------------------------------  ---------------------------------------
473    
474    .. at least here we should also refer to the screenshots
475    
476  Before reaching the current state, our documentation evolved through  Before reaching the current state, our documentation evolved through
477  several distinct steps, which will be viewed first from the reader's  several distinct steps, which will be viewed first from the reader's
478  and then from the developer's point of view.  and then from the developer's point of view.
# Line 563  goals to be achieved. The tool had to: Line 572  goals to be achieved. The tool had to:
572    
573  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
574  existing tools we selected as the basis for our documentation tool  existing tools we selected as the basis for our documentation tool
575  are: Javadoc, Docutils [goodger02docutils]_, and  are: Javadoc, Docutils [goodger02docutils]_, and our own UML diagram
576  our own UML diagram description tool. Further, the UML tool uses  description tool. Further, the UML tool uses several free utilies to
577  several free utilies to convert each lexical UML description into  convert each lexical UML diagram description into final *Portable
578  final *Portable Network Graphics* (PNG) diagram files. Such utilies  Network Graphics* (PNG) diagram files. Such utilies are *MetaPost*
579  are *MetaPost* [hobby89metapost]_ (mpost), which implements a language  [hobby89metapost]_ (mpost), which implements a language for picture
580  for picture drawing, and Netpbm image file manipulation  drawing, and Netpbm image file manipulation toolkit. Besides Javadoc,
581  toolkit. Besides Javadoc, all tools used are Free Software. The  all tools used are Free Software. The current linking tool is
582  current linking utility is implemented to support Javadoc, but after  implemented to support Javadoc, but after the plugin interface is
583  the plugin interface is ready, switching Javadoc to any free  ready, switching Javadoc to any free alternative or using them as
584  alternative or using them as parallel should be possible with only  parallel should be possible with only minor plugin programming.
 minor plugin programming.  
585    
586  The javadoc format is the standard way to include documentation in  The javadoc format is the standard way to include documentation in
587  Java source code [friendly95javadoc]_. Generating the WWW pages is not  Java source code [friendly95javadoc]_. Generating the WWW pages is not
# Line 589  many of them supporting multiple program Line 597  many of them supporting multiple program
597  UML tool  UML tool
598  --------  --------
599    
600  Our UML description tool was already implemented before the  Our UML diagram description tool was already implemented before the
601  documentation linking tool, which finally enabled the bi-directional  documentation linking tool, which finally enabled the bi-directional
602  linking between distinctdocumentations. In the following we discuss  linking between distinctdocumentations. In the following we discuss
603  shortly, how we ended up to use this our own lexical UML language  shortly, how we ended up to use this our own lexical UML language
# Line 617  customs. Because in small softaware deve Line 625  customs. Because in small softaware deve
625  write the documentation, the documentation tools shouldn't be gap to  write the documentation, the documentation tools shouldn't be gap to
626  change the programming tool to document writing tools. Even better  change the programming tool to document writing tools. Even better
627  would be that the programming tool could be used as documentation  would be that the programming tool could be used as documentation
628  tool. Lexical UML description for our UML drawing tool, of course, can  tool. Lexical UML diagram description for our UML drawing tool, of course, can
629  be written with any text editor. At least for a programmer, who are  be written with any text editor. At least for a programmer, who are
630  used to describe objects lexically, describing also the UML diagrams  used to describe objects lexically, describing also the UML diagrams
631  could be even more efficient than using direct manipulation drawing  lexically could be even more efficient than using distinct direct
632  tool.  manipulation drawing tool.
633    
634         "It's as if we have thrown away a million years of         "It's as if we have thrown away a million years of
635         evolution, lost our facility with expressive language,         evolution, lost our facility with expressive language,
# Line 646  quite challanging for a direct manipulat Line 654  quite challanging for a direct manipulat
654  these alternatives as easily available as they could be just typed  these alternatives as easily available as they could be just typed
655  when using lexical description.  when using lexical description.
656    
657    In our UML tool the describtion of UML diagram is divided in two: into
658    a description of all the elements in diagram [ref-umltoolumlsource]_
659    and description their graphical layout [ref-umltoolmpsource]_. The
660    final diagram file [ref-umltoolexample]_ is compiled
661    [ref-umltoolconvert]_ from the element and layout descriptions. The
662    description of existing elements is easily done using our UML tools'
663    lexical description language and the description is readable even
664    without compiling the graphical diagram. The graphical layout is more
665    difficult to express lexically without exceptional spatial
666    imagination. Usually the intended results need several compilation
667    trials. We admit that after all elements for a diagram are selected
668    using lexical description, the graphical placing for them could be
669    done much easier by direct manipulation.
670    
671  .. figure:: umltool-example-uml.gen.eps  .. figure:: umltool-example-uml.gen.eps
672     :label: umltoolumlsource     :label: umltoolumlsource
673     :width: 4.5cm     :width: 4.5cm
674    
675     Example of UML tool object description.       Example of UML tool element description.  
   
 In our UML tool the describtion of UML diagram is divided in two: into  
 a description of all the elements in diagram [ref-umltoolumlsource]_  
 and description their graphical layout [ref-umltoolmpsource]_. We  
 argue that for a programmer used to Describing existing objects for  
 diagram is easily done using our UML tools's lexical description  
 language, but the graphical placing of objects is a bit more  
 complicated, although, not impossible. We admit that after objects for  
 the diagram are selected, the graphical placing for them could be done  
 easiest by using direct manipulation.  
   
676    
677  .. figure:: umltool-example-mp.gen.eps  .. figure:: umltool-example-mp.gen.eps
678     :alternative: *     :alternative: *
# Line 670  easiest by using direct manipulation. Line 681  easiest by using direct manipulation.
681    
682     Example of UML tool layout description.       Example of UML tool layout description.  
683    
684    .. figure:: umltool-convert-process.gen.eps
685       :label: umltoolconvert
686       :width: 4.5cm
687    
688       The process of compiling UML diagram using our UML tool.
689    
690  .. UML:: umltool-example  .. UML:: umltool-example
691          :label: umltoolexample          :label: umltoolexample
692          :caption: Example of UML tool output.          :caption: Example of UML tool diagram output.
693          :width: 8.45cm          :width: 8.45cm
694    
695          bigpackage Example          bigpackage Example
# Line 713  easiest by using direct manipulation. Line 730  easiest by using direct manipulation.
730  Docutils  Docutils
731  --------  --------
732    
733  reST's filosophy  As a natural continuum for UML tool we started to use reStructuredText
734    (reST) plaintext syntax with Docutils parsering system
735    [goodger02docutils]_ for writing our design documentation. The UML
736    tool already shared some of the main goals of reST syntax
737    [goodger02docutils]_: it was readable also raw form, the most common
738    elements had very simple markup, it was writable with any text editor
739    and the UML markup was highly extensible (by enlarging the
740    preprocessor and MetaPost UML macro libary
741    [ref-umltoolconvert]_). ReST syntax itself is extensible easily by
742    inventing new directives and adding parsers for them into
743    Docutils. The extensibility of reST syntax and Docutils parsing system
744    made it possible to write embedded markup of our umltool into design
745    documentation. That way a lexical description of UML diagram is also
746    easily reachable and editable when updating the documentation
747    including the diagram description.
748    
749    Even reST syntax is somehow WYSIWYG (what-you-see-is-what-you-get).
750    Gentner and Nielsen [gentner-nielsen96anti-mac-onpage-75]_ argue that
751    a document has a rich semantic structure that is poorly captured by
752    its appearance on a sceen or printed page, which many WYSIWYG tools
753    assumes to be the only one useful representation of the
754    information. WYSIWYG seem to assume that people want always
755    paper-style reports to be read from top to bottom, when we already
756    live within an information flood, where the overloaded reader should
757    be allowed to affect the final representation of document
758    [gentner-nielsen96anti-mac-onpage-75]_. ReST and Docutils parser won't
759    make such assumptions, but tehy clearly distincts the semantic
760    structure and rules for converting the text and semantics into
761    printable page. ReST syntax has umambiguous rules to parse document
762    into structural form and after parsing it could be written into
763    multiple output formats [goodger02docutils]_.
764    
765    Linking tool
766    ------------
767    
768    Using reST syntax for design documentation, lexical description for
769    UML diagrams and extensible Docutils parser for generating the final
770    representation, we was allowed to embed also UML diagram description
771    within the design documentation reST sources. When converting the reST
772    document into final representation, our custom directive for Docutils
773    passed the embedded UML diagram description to our UML tool and added
774    a reference to the compiled diagram into Docutils' document tree
775    structure. This was a promising base to build our linking tool on.
776    
777    In the current implementation we have two docutils directives to use
778    for embedding UML diagrams into reST based design documentation. The
779    first one is used to describe a new UML diagram, the second is used to
780    refer to an already existing diagram. The correct reference is done
781    simply by diagram name, so it could be spoken about UML diagram
782    namespace, where all diagrams are distincted by unique naming.
783    
784    To enable linking elements in UML diagram a "jlink" command after each
785    linkable element is added into lexical UML diagram description
786    [ref-umltoolumlsourcelinked]_. If "jlink" has no attributes it is
787    linked to Javadoc page of the package or class determined from the
788    element's name. Otherwise element is linked into file determined by
789    the attribute following "jlink".
790    
791    The documentation [gzz_doc_himalia]_ is created in two distinct
792    phases. In the first phase [ref-umldocflow]_ all reST sources are
793    parsed and compiled into HTML and lexical UML diagram descriptions are
794    extracted into temporary storage [ref-umldocreferflow]_. Also the
795    paths for reST documents explicitly referring particular diagrams are
796    stored with that diagram source [ref-umldocreferflow]_. In the second
797    phase all compiled reST documents are processed again:
798    
799     - Focused versions of UML diagram with list of all explicitly
800       referring reST documents are created and embedded into compiled
801       documentation pages.
802    
803  - indentation for blocks   - Image maps targeting all linked elements appearing in UML diagrams
804  - robust for erros     are generated and embedded into compiled documentation pages.
 - "natural" to write  
 - "ASCII layout" (our language for UML is an exception, which is discussed  
   later)  
   
 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-nielsen96anti-mac, p.75] collects arguments/argues  
    generally against WYSIWYG.  
805    
806      - a document has a rich semantic structure that is poorly   - Finally focused versions of UML diagrams are created and implicitly
807        captured by its appearance on a sceen or printed page     embedded into targets of all linked elements appearing in
808      - other text representations, such as SGML, distinct the semantic     UML diagrams.
809        structure and rules for converting the text and semantics into  
810        printablepage  .. figure:: umltool-example-uml-linked.gen.eps
811      - WYSIWYG assumes there is only one useful representation of the     :label: umltoolumlsourcelinked
812        information: that of the final reports     :width: 4.5cm
     - 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  
813    
814       Example of UML tool element description with link
815       information for linking tool.  
816    
817  - not strictly necessary; could have used another editor  .. figure:: umldoc-flow.gen.eps
818       :label: umldocflow
819    
820  - minimum barrier to make a diagram (well, at first have to learn our     The two distinct phases of generating Javadoc and design
821          description language)     documentation bridged via UML diagrams.
822      
823    
824  - direct manipulation when building / editing structure of diagrams clumsy  .. figure:: umldoc-refer-flow.gen.eps
825       :label: umldocreferflow
826       - users are programmers --> a language is better than d.m.  
827       Compiling reST sources and extracting embedded UML diagram
828       descriptions into temporary storage.
829    
830    Practical use
831    =============
832    
833    The tool is currently in everyday use in the Gzz project ...
834    
835    - n classes, n diagrams, n pages architecture documentation, and works
836    
837    screenshots
838    
839        + elements are easily described  Acknowledgments
840    ===============
841    
842        + graphical placing would need an GUI  antont
843    
844    Conclusion
845    ==========
846    
847    - summaryy what have we done so far
848    
849    - UMLTOOL: diagram elements need easier placing (but still not automatic)
850    
851      - direct maniplation
852    
853  - flow diagram of the implementation    - we can still continue using our UML language for description
854        of diagram elements
855    
856  reST's filosophy  - LINKTOOL:
857    
858  - indentation for blocks    - Currently, we only link UML classifiers to Java classes and other
859  - robust for erros      documents. Methods
860  - "natural" to write      could also be linked, especially in interaction diagrams.
 - "ASCII layout" (our language for UML is an exception, which is discussed  
   later)  
861    
862      - plugin interface to enable other documentation tools than javadoc
863    
864  - diagrams in the same reST source as the design document  - standalone (from our CVS, still a lot of depends for the
865      existing Free Software) distribution package
866    
867  - separate UML structure from presentation, show structure in easily  - metapost's erros are fuzzy, when using scripting language for
868    editable text    drawing diagrams, we need clearer errors
869    
870       - placement: currently metapost; looking at ways to make    - it's possible that we change metapost for something else
        interactively editable.  
871    
872  - Dia could be used instead of metapost, but    - getting rid of problem with fuzzy error messages and slow
873    direct manipulation problem again      compiling process
874    
875      - However, less power: with mp, can draw arbitrary stuff on the diagrams
876        is well; this is sometimes useful, but sometimes not desirable.
877    
878    - all in all, this is temporary system: using web pages for the
879      presentation/UI layer of a hypertext system is useful and standard
880      but very limiting. The system we are using these tools to develop is
881      intended for better user interfaces to similar ...
882    
883      + antont's note about duplication of data problem
884    
885  .. bibliography:: gzigzag  .. bibliography:: gzigzag
886    

Legend:
Removed from v.1.34  
changed lines
  Added in v.1.35

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