1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
START HERE
<style>
div.box {
background-color: #DDDDDD;
padding: 15px;
border: dashed 3px orange;
margin-left: 100px;
margin-right: 100px;
margin-top: 20px;
font-size: x-large;
}
</style>
<div class="box">
<span class="mono" style="font-size: xx-large; font-weight: bold;">
Out of date
</span>
<p>
These documents were mostly written in 2006, before java-gnome 4.0 became a
reality. Two years on most of these decisions have been implemented. This
tree will therefore soon be replaced by documents defining the current design
and architecture.
</p>
</div>
This directory documents the evolution and design of the re-engineered (4.0)
java-gnome bindings.
Organization of this directory
------------------------------
The design documents are loosely organized according to the following scheme:
1. Background material:
* [The Great Owen Thread and other necessary homework](1a-Homework.html)
* [Java Native Interface](1b-AllAboutJNI.html)
2. Governing assumptions (our objective as a project, who our audience is, and
what constraints we impose on ourselves as we go about our business):
* [Objective and Audience](2a-ObjectiveAndAudience.html)
* [Design Constraints](2b-DesignConstraints.html)
3. Miscellaneous organizational decisions:
* [Package Names](3a-PackageNames.html)
* [Version Numbering](3b-VersionNumbers.html)
4. Discussion of public APIs:
* [TreeView, TreeModel](4a-TreeViewAndTreeModel.html)
* [GObject properties](4b-ObjectProperties.html)
5. Architecture:
* [Internal Architecture](5a-Architecture.html)
These numbers correspond to those used to organize the original threads on the
java-gnome-hackers mailing list. All of these documents started life as emails
written by Andrew Cowie, so they tend to be written in the first person. That
will no doubt fade over time as these documents evolve into canonical
references.
About the format of our documentation
-------------------------------------
These documents are all text files! They are, however, _**lightly**_ marked up
with the syntax of John Gruber's "[Markdown][markdown]" so that they also
present nicely as web pages. See [`doc/style/MARKUP`](../style/MARKUP.html)
for details.
As conventions, we:
* put the title of the document by itself on the first line of the file (the
script that renders these to HTML on our website picks this up as `<TITLE>`
and top banner `<H1>` heading for the document),
* note, _in italics_, the date of the last significant modification at the
bottom of the file, and
* put a `vim` "modeline" on the last line of the document enforcing
the word-wrap width (actually, it ends up on the third last line, in the
copyright statement footer. Same same).
Contribute!
-----------
This documentation are distributed with java-gnome and are maintained
alongside (in!) the source code. As such they are living documents and will
likely evolve over time as new design decisions are taken. If you care to see
the history behind certain decisions, check the mailing list archives and the
version history of the files in this directory.
If there is a change you would like to make, check out a copy of the source
code and send a patch using `bzr bundle`.
Remember, if you want to hack on java-gnome itself, extend it or use it for
new and miraculous things, you're best off doing so alongside the community.
Certainly join our mailing lists, but most of all hang with us online, at
`#java-gnome` on `irc.gimp.org`.
About this directory's name
---------------------------
Incidentally, this directory was named at [foss.in][] 2006 by several
students gathered around after Andrew Cowie gave a talk about the java-gnome
4.0 prototype. When asked what they thought a directory containing all the
background, instructions, architecture, and other answers to anything you'd
want to know should be called, Srichand Pendyala replied:
> "Why don't you call it 42?"
Awesome! Alas, "42" is a bit of an inside joke, and given our goal of
approachability for newcomers, `doc/42/` wouldn't really be obvious as the
location of the design documentation.
So `doc/design/` it is, but such enthusiasm is to be rewarded: I promised him
that his idea would live on in our documentation. Cheers Srichand!
AfC
_Last modified 7 Dec 06_
[markdown]: http://daringfireball.net/projects/markdown/basics
[foss.in]: http://foos.in/2006/
<!--
Copyright © 2006 Operational Dynamics Consulting, Pty Ltd
As project documentation, this file forms an integral part of the source
code of the library it accompanies, and thus is made available to you by its
authors as open source software: you can redistribute it and/or modify it
under the terms of the GNU General Public License version 2 ("GPL") as
published by the Free Software Foundation.
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GPL for more details.
You should have received a copy of the GPL along with this program. If not,
see http://www.gnu.org/licenses/. The authors of this program may be
contacted through http://java-gnome.sourceforge.net/.
vim: set textwidth=78 nowrap:
-->
|
