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. |
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 |
|
|
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 |
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 |
|
|
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. |
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 |
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 |
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, |
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: * |
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 |
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 |
|
|