4 |
|
|
5 |
:Stamp: $Id$ |
:Stamp: $Id$ |
6 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
7 |
Points for HT people |
Points for HT people |
8 |
==================== |
==================== |
9 |
|
|
114 |
|
|
115 |
* (XXX Free Software vs. Open Source vs. Open Software vs. Open Project...) |
* (XXX Free Software vs. Open Source vs. Open Software vs. Open Project...) |
116 |
|
|
117 |
Introduction |
Implementation |
118 |
============ |
============== |
119 |
|
|
120 |
|
Eventually, we found no Free Software [XXX] alternatives, which would |
121 |
|
have fulfilled our needs. Therefore we decide to proceed with our own |
122 |
|
implementation. There were several goals to be achieved. The tool had |
123 |
|
to: |
124 |
|
|
125 |
|
- be tidy and light weight |
126 |
|
|
127 |
|
- be built on existing Free Software tools |
128 |
|
and be a part of Free Software toolchain |
129 |
|
|
130 |
|
- generate output easily editable by others (from the source) |
131 |
|
|
132 |
|
- provide a plugin interface for different documentation tools |
133 |
|
|
134 |
|
|
135 |
|
Up to this article all steps beside the last one are implemented. The |
136 |
|
existing tools we selected on the base of our documentation tool are: |
137 |
|
Javadoc [XXX], Docutils [XXX], and our own language based UML diagram |
138 |
|
tool. The UML tools also uses several Free Software utilies to convert |
139 |
|
the lexical UML description into final PNG (*Portable Network |
140 |
|
Graphics*) diagram files. Such utilies are mpost [XXX] (*MetaPost*), |
141 |
|
pstopnm [XXX] (*PostScript to Portable anymap*), pnmscale [XXX] |
142 |
|
(*Portable anymap scaling utility*) and pnmtopng (*Portable anymap to |
143 |
|
Portable Network Graphics*). Besides Javadoc, all tools used are Free |
144 |
|
Software. |
145 |
|
|
146 |
|
|
147 |
|
??After the plugin interface is created the documentation |
148 |
|
linking utility could also be used with other HTML documentation |
149 |
|
generators in addition to Javadoc. Though, so far, has Javadoc provided a good enough source code documentation for our purposes and we probably have no reasons to change it? |
150 |
|
|
151 |
|
it is also |
152 |
|
|
153 |
|
|
154 |
|
Because Javadoc have provided good enough fully generated and up-to-dated detailed documentation for our use, we had no reason to abandon it. |
155 |
|
|
156 |
|
On the |
157 |
|
|
158 |
|
Although our UML language was already implemented before the linking |
159 |
|
tool, which finally created the bi-directional linking between |
160 |
|
documentations, we discuss shortly about why we ended to create a |
161 |
|
language instead of using a diagram drawing tool with direct |
162 |
|
manipulation GUI. |
163 |
|
|
164 |
|
|
165 |
|
- flow diagram of the implementation |
166 |
|
|
167 |
|
reST's filosophy |
168 |
|
|
169 |
|
- indentation for blocks |
170 |
|
- robust for erros |
171 |
|
- "natural" to write |
172 |
|
- "ASCII layout" (our UML-language is an exception, which is discussed later) |
173 |
|
|
174 |
|
Why UML-language |
175 |
|
|
176 |
|
- Doxygen can generate useless diagrams from the code class hierarchy |
177 |
|
should describe somewhere why these are useles... |
178 |
|
uses proprietary GraphViz tool to create diagrams |
179 |
|
|
180 |
|
|
181 |
|
- How should we discuss WYSIWYG, WYSIAYG/WYSIATI for reST &c? Someone will |
182 |
|
surely ask about that, |
183 |
|
|
184 |
|
PARTIAL RESOLUTION: |
185 |
|
|
186 |
|
- proprietarity (really?) |
187 |
|
- versioning much worse |
188 |
|
(changes in rtf could probably be compared?) |
189 |
|
- users = programmers --> used to editing text and compiling, |
190 |
|
it's the most practical to use the same editor as for coding |
191 |
|
- lack of good, **extensible** tools |
192 |
|
|
193 |
|
|
194 |
|
[gentner-nielsen-anti-mac, p.75] collects arguments/argues |
195 |
|
generally against WYSIWYG. |
196 |
|
|
197 |
|
- a document has a rich semantic structure that is poorly |
198 |
|
captured by its appearance on a sceen or printed page |
199 |
|
- other text representations, such as SGML, distinct the semantic |
200 |
|
structure and rules for converting the text and semantics into |
201 |
|
printablepage |
202 |
|
- WYSIWYG assumes there is only one useful representation of the |
203 |
|
information: that of the final reports |
204 |
|
- WYSIWYG assumes people want paper-style reports (and we already |
205 |
|
live within information flood) |
206 |
|
- blind users exists |
207 |
|
|
208 |
|
- Rational Soda is WYSIWYG, maybe this could be discussed under |
209 |
|
it |
210 |
|
|
211 |
|
- though, because we are coders, we would prefer UML script |
212 |
|
language over menus and dialogs when creating UML objects |
213 |
|
|
214 |
|
+ we need a ref. of criticism of direct manipulation! |
215 |
|
|
216 |
|
- not necessarily improve performance, users must learn the meaning |
217 |
|
of the graphical components, graphic presentation could be |
218 |
|
misleading, graphical presentation could take excessive screen display |
219 |
|
space [Shneiderman-direct-manipulation, p. 64] |
220 |
|
|
221 |
|
probably only the first argument of performance is relevant |
222 |
|
anymore... though, creating the graphic presentation for problem |
223 |
|
could lead to using metaphors and those are often |
224 |
|
criticized (even by D. Norman :) |
225 |
|
|
226 |
|
- "The dark side of a direct manipulation interface is that |
227 |
|
you have to directly manipulate everything. Instead of an |
228 |
|
executive who gives high-level instructions, the user is |
229 |
|
reduced to an assembly line worker who must carry out the |
230 |
|
same task over and over." |
231 |
|
[gentner-nielsen-anti-mac, p.74] |
232 |
|
|
233 |
|
limits the precision of our actions to the precision |
234 |
|
achieved with eye-hand-mouse coordination (language and |
235 |
|
mathematics can be more precise) |
236 |
|
[gentner-nielsen-anti-mac, p.74] |
237 |
|
|
238 |
|
direct manipulation requires the user to be involved in |
239 |
|
every action, but sometimes the user may not know |
240 |
|
what to do |
241 |
|
[gentner-nielsen-anti-mac, p.74] |
242 |
|
|
243 |
|
"It's as if we have thrown away a million years of |
244 |
|
evolution, lost our facility with expressive language, |
245 |
|
and been reduced to pointing at objects in the immediate |
246 |
|
environment. -- We have lost all the power of language, and |
247 |
|
can no longer talk about objects that are not immidiately |
248 |
|
visible." |
249 |
|
[gentner-nielsen-anti-mac, p.74] |
250 |
|
|
251 |
|
- summaring: direct manipulation could be easy, if there is |
252 |
|
a natural graphic presentation for the problem. Even then |
253 |
|
it's not necesesserily the most efficient method. Also the |
254 |
|
practical point of using the same writing tool foor coding and |
255 |
|
documenting. |
256 |
|
|
257 |
|
+ Rose's problem with direct manipulation: a lot of windows, |
258 |
|
menus, dialogies etc... to get direct manipulateable graphic |
259 |
|
representation for everything |
260 |
|
|
261 |
|
+ though, directmanipulation is only relevant solution for |
262 |
|
replacing already created object |
263 |
|
|
264 |
|
|
265 |
|
- not strictly necessary; could have used another editor |
266 |
|
|
267 |
|
- minimum barrier to make a diagram (well, at first have to learn our UML-script) |
268 |
|
|
269 |
|
- direct manipulation when building / editing structure of diagrams clumsy |
270 |
|
|
271 |
|
- users are programmers --> a simple programming language is better than d.m. |
272 |
|
|
273 |
|
+ elements are easy to create by script language |
274 |
|
|
275 |
|
+ graphical placing could need an GUI |
276 |
|
|
277 |
|
- diagrams in the same reST source as the architecture document |
278 |
|
|
279 |
|
- separate UML structure from presentation, show structure in easily |
280 |
|
editable text |
281 |
|
|
282 |
UML (the Unified Modeling Language), founded mainly by Booch, Jacobson and |
- placement: currently metapost; looking at ways to make |
283 |
Rumbaugh during 1900s to ``XXX blah blah`` [#]_, has become the *de facto* -- |
interactively editable. |
284 |
|
|
285 |
|
- Dia could be used instead of metapost, but |
286 |
|
direct manipulation problem again |