52 |
documentation embedded in the program code, such as Javadoc. |
documentation embedded in the program code, such as Javadoc. |
53 |
\end{abstract} |
\end{abstract} |
54 |
|
|
55 |
|
.. of documentation: design documents and javadoc program code |
56 |
|
documentation. |
57 |
|
\end{abstract} |
58 |
|
|
59 |
|
|
60 |
Introduction |
Introduction |
61 |
============ |
============ |
62 |
|
|
235 |
The implementation in Navidoc |
The implementation in Navidoc |
236 |
============================= |
============================= |
237 |
|
|
238 |
Navidoc is as a light-weight tool built on top of several existing |
.. think, this should be much clearer :) But how to say everything shortly... |
|
Free Software tools. |
|
239 |
|
|
240 |
.. The main existing components are Docutils [goodger02docutils]_, |
Navidoc, our implementation, is as a light-weight tool built on top of |
241 |
|
several existing Free Software tools. Its main purpose is to compile |
242 |
|
the design documentation and UML diagrams embedded within it. |
243 |
|
Navidoc uses several free utilies to convert each |
244 |
|
textual UML diagram description into a set of imagemaps --- one |
245 |
|
for each target document since the current document is highlighted |
246 |
|
in the images. These diagrams embedded into target documents, allow easy traverse |
247 |
|
through all the participant nodes and backlink to the startup page holding |
248 |
|
the original diagram. |
249 |
|
|
250 |
|
.. After compiling, it creates imagemaps for every UML diagram to link |
251 |
|
diagrams' elements to corresponding source code documentation |
252 |
|
pages. Linked diagrams will also be embedded into every target page to |
253 |
|
|
254 |
|
.. The main existing components are Docutils [goodger02docutils]_, |
255 |
|
|
256 |
.. we can only have very few references [fsf02categories]_ |
.. we can only have very few references [fsf02categories]_ |
257 |
|
|
258 |
- main parts: Docutils [goodger02docutils]_, lexical UML language |
.. - main parts: Docutils [goodger02docutils]_, lexical UML language |
|
|
|
|
Navidoc uses several free utilies to convert each |
|
|
textual UML diagram description into a set of imagemaps --- one |
|
|
for each target document since the current document is highlighted |
|
|
in the images. |
|
259 |
|
|
260 |
.. No space for this, I wager |
.. No space for this, I wager |
261 |
|
|
263 |
(mpost), which implements a language for picture drawing, and Netpbm |
(mpost), which implements a language for picture drawing, and Netpbm |
264 |
image file manipulation toolkit. |
image file manipulation toolkit. |
265 |
|
|
266 |
- why lexical UML language: |
.. - why lexical UML language: |
267 |
|
|
268 |
|
* no need for additional tools, when writing documentation |
269 |
|
|
270 |
* no need for additional tools, when writing documentation |
* describing is fast |
271 |
|
|
272 |
* describing is fast |
* setting layout may be more |
273 |
|
|
274 |
* setting layout may be more |
We've it found useful to create UML diagrams using textual syntax |
275 |
|
embedded within documentation page originals. In small softaware |
276 |
|
development groups, where programmers also write the documentation, |
277 |
|
the documentation tools shouldn't be gap to change the programming |
278 |
|
tool to document writing tools. Textual UML diagram description, of |
279 |
|
course, can be written with any text editor. Comparing with any direct |
280 |
|
manipulation drawing tool, textual description may feel abstract at |
281 |
|
first, but the when users are programmers it could be even more |
282 |
|
natural for them to describe things lexically. |
283 |
|
|
284 |
|
.. Also at least for a |
285 |
|
programmer, who are used to describe objects lexically, describing |
286 |
|
the UML diagrams lexically should keep the gap low for using |
287 |
|
also diagrams, when documenting the software project. |
288 |
|
|
289 |
.. Embedding diagrams into HTML |
.. Embedding diagrams into HTML |
290 |
============================ |
============================ |