842 |
============= |
============= |
843 |
|
|
844 |
The UML and linking tools are currently in everyday use in the Gzz |
The UML and linking tools are currently in everyday use in the Gzz |
845 |
project [gzz]_. For now, the projects covers about 380 Java classes |
project [gzz]_. For now, the documentation covers about 380 Java classes |
846 |
and over 80 pages of design documentation have been written |
and over 80 pages of design documentation exist [gzz_doc_himalia]_. |
847 |
[gzz_doc_himalia]_. There are only about 30 different human drawn UML |
We have only about 30 human-drawn UML |
848 |
diagrams embedded within the design documentation pages, but the |
diagrams embedded within the design documentation pages, but the |
849 |
amount of them is continuosly growing. For all those diagrams the |
amount of them is continuously growing. For all those diagrams, the |
850 |
linking tool generates more than 150 different differently focused |
linking tool generates more than 150 separate differently focused |
851 |
versions and by simply calculation the linking tool has embedded a |
versions, and by simple calculation the linking tool has embedded |
852 |
single diagram implicitly on an avarage into four distinct design |
each diagram implicitly on average into four distinct design |
853 |
documentation or Javadoc pages. The UML tool description language |
documentation or Javadoc pages. The UML tool description language |
854 |
covers currently 26 different diagram itemtypes and its being extended |
covers currently 26 different types of diagram items and is extended |
855 |
always when necessary. |
regularily as necessary. |
856 |
|
|
857 |
.. figure:: umldoc-screenshot.gen.eps |
.. figure:: umldoc-screenshot.gen.eps |
858 |
:environment: figure* |
:environment: figure* |
867 |
========== |
========== |
868 |
|
|
869 |
In this article we have discussed the hypertextualization of |
In this article we have discussed the hypertextualization of |
870 |
our software project's documentation. |
documentation in our software project. |
871 |
Using |
Using |
872 |
existing free software tools |
existing Free Software tools |
873 |
and a little new glue code we have made UML diagrams into |
and a little new glue code we have made UML diagrams into |
874 |
contextual menus for switching between the architectural design |
contextual menus for switching between the architectural design |
875 |
documentation and the detailed Javadoc documentation. |
documentation and the detailed Javadoc documentation. |
880 |
The software automatically creates multidirectional links |
The software automatically creates multidirectional links |
881 |
based on simple directives in the UML diagram source code in our documentation. |
based on simple directives in the UML diagram source code in our documentation. |
882 |
Only web pages generated during the documentation build |
Only web pages generated during the documentation build |
883 |
process are affected, which makes the task of our software easier than that of other web |
process are affected, which makes the task of our software easier than that of |
884 |
augmentation tools [weinreich00-linkvis]_. |
some other web augmentation tools [weinreich00-linkvis]_. |
885 |
|
|
886 |
Earlier concept-based navigation and map-based navigation have added |
Earlier concept-based navigation and map-based navigation have added |
887 |
horizontal links on top of hierarchical hypertext [brusilovsky02-mapnav]_. |
horizontal links on top of hierarchical hypertext [brusilovsky02-mapnav]_. |
899 |
documents. |
documents. |
900 |
Methods (and fields) should also be linked, especially in interaction diagrams, as well |
Methods (and fields) should also be linked, especially in interaction diagrams, as well |
901 |
as associations, whenever there is a suitable object in the code documentation. |
as associations, whenever there is a suitable object in the code documentation. |
902 |
|
The plugin interface for using other documentation tools also needs |
903 |
|
to be firmed up. |
904 |
|
|
905 |
The layout of the diagram is also currently |
The layout of the diagram is also currently |
906 |
more difficult than it should be. |
more difficult than it should be. |
907 |
While the creation of the diagram structure is easier using |
While the creation of the diagram structure is easier using |
908 |
written text than direct manipulation, |
written text than direct manipulation, |
909 |
the layout of the resulting structure would benefit from a click-and-drag interface. |
the layout of the resulting structure would benefit from a click-and-drag interface. |
910 |
However, this approach will also lose some expressive power: |
However, this approach would also lose some expressive power: |
911 |
in metapost the user is now allowed to draw anything on the diagram. |
in MetaPost layout the user is now allowed to draw anything on the diagram. |
912 |
It is possible that this can be solved by another stage after metapost, |
This can possibly be solved by another stage after metapost, |
913 |
where the locations of the nodes could be interactively defined into |
where the locations of the nodes could be interactively defined into |
914 |
metapost variables. |
MetaPost variables. |
915 |
On the other hand, there are also arguments against metapost: |
On the other hand, there are also arguments against MetaPost: |
916 |
the error messages receive on erroneous input to the UML tool |
the error messages received on erroneous input to the UML tool |
917 |
are difficult to decipher due to the translation layer between. |
are difficult to decipher due to the translation layer between. |
918 |
This might also speed up the compiling process. |
Abandoning MetaPost might also speed up the compiling process. |
|
|
|
|
The plugin interface for using other documentation tools also needs |
|
|
to be firmed up. |
|
919 |
|
|
920 |
Once some of these issues are resolved, we are planning |
Once some of these issues are resolved, we are planning |
921 |
to release the glue code as a standalone free software package; |
to release the glue code as a standalone Free Software package. |
922 |
until then, the code is still publicly accessible at our CVS version |
|
923 |
control server as part of the larger project [gzz]_ (note to referees: |
Finally, we'd like to point out that this tool could benefit from a less |
924 |
the project will likely be renamed by the final version). |
limited presentation layer than currently supported by web browsers. Ideally, |
925 |
|
hypertext browsers would directly support navigation maps in their |
926 |
Finally, we'd like to point out that this tool |
user interface, stabilizing the map positions during browsing. |
927 |
is only intended as a temporary system: using web pages for the |
|
|
presentation/UI layer of a hypertext system is useful and standard |
|
|
but also very limiting from a UI perspective. |
|
|
The system we are using this UML tool to develop is |
|
|
intended for better user interfaces to similar structures. |
|
928 |
|
|
929 |
Acknowledgments |
Acknowledgments |
930 |
=============== |
=============== |