Hey Everyone,
This email is an extended discussion about improving the current
"programmer's guide". I'm posting it to let you all know what I'll be
working on over the next while (few years). You will observe that, since
uDig sits at the top of the stack, this manual needs to explain all the
pieces---a lot of work. This is the description of an eventual goal.
Note, that the current guide is trying to serve two different audiences,
'SDK developers' wanting to make their own apps and 'uDig internal
developers' working on the uDig code base. It is critical to identify
and separate out those sections which are only targeted only at one of
these two audiences. It might eventually be necessary to split the
manual into two.
The recent post by Jacques to the list is very similar to my experience
in approaching uDig. In order to use uDig, there is a whole lot to learn
from coding theory, through Java 5.0, all the third party libraries and
Geotools, to Eclipse and uDig extension points. The code is either being
deprecated, if one uses releases, or unstable and changing underneath,
if one uses SVN checkouts. The work to set things up is large and the
explanations fragile (cookbooks are notoriously bad at telling you how
things can go wrong and what to do in that case). This all to say that
we have a long way to go before making it easy for programmers to go
from downloading software to tackling the problems which they face.
The situation cannot be resolved immediately. Instead, let's treat the
whole stack as if it were in a beta stage (e.g. pretend geotools is 0.2,
udig is at 0.1) and try to get things in shape for a future 'stable'
release.
On the doc infrastructure:
-------------------------
The current infrastructure for the docs allows anyone to edit them but
creates documents which are hard to read and requires an approach which
I find hard personally. The resolutions to the situation depend on the
uDig infrastructure.
Wiki is cool in allowing everyone to participate.
However, the docs made by wiki are hard to read.
* It's not clear if, or how, the "Programmer's Guide" could be
obtained as a PDF. Similarly, somewhere it says the guide is
available as an Eclipse plugin but how to get it in that form is
never stated.
* The formatting of confluence allows text to be as wide as the
browser window which makes for lines which are so long as to be
unreadable. Worse, the lines are formatted to be at least as
wide as the largest diagram on the page. Knuth (of TeX and "The
Art of Programming" fame) talks at length about the importance
of short lines for legibility.
* The docs right now cannot be read sequentially but must be read
by navigating from the "Outline" into each page and back. For
now, I personally open each page in a separate tab but this is
less than elegant. We could do a lot of work to fix this
situation by hand but that effort seems like a burden and might
break the eclipse version.
The docs are also hard to edit.
* One must be online to edit. This happens to be a real problem
for me in my current situation.
* The wiki markup is not particularly powerful. Not a critical
issue but worth noting. I wanted to center a line today and
there does not appear to be any way to do this.
There are potentially many solutions to this problem. Most software uses
docbook for the task and it is very powerful. Docbook is not perfect
however and I have no idea how it would integrate with a confluence web
site or with eclipse. I am *very* tempted to go back to LaTeX and
release the documents as PDF files but will work with wiki for the
immediate future.
Having Canonical Examples:
--------------------------
The uDig code base needs a series of plugins which serve as canonical
examples for SDK Programmers (ie. those making their own apps). These
would explicitly *not* be in the net.refractions.udig namespace to show
that these use uDig without being part of it. The namespace issue is one
of the fundamental problems with addressing 'SDK programmers' and 'uDig
internal programmers' in the same document. I would propose using the
org.virtual.'exampleGroup' namespace or something simlar.
Ideally, I hope to have the following plugins (some of these of course,
exist). The idea is that these plugins get the user past the simple
technical difficulties of programming uDig which everyone eventually
learns to the point where the user can tackle the problems which
actually interest the user in particular:
BASIC:
* A "hello uDig" plugin that adds a menu/toolbar button
and makes basic use of the catalog. This shows the user
(1) how to get code that runs from the GUI since the
user doesn't control execution flow, (2) how to interact
with the uDig Data model.
THIRD PARTY:
* Plugins using Java Advanced Imaging or I/O plugins.
* Plugins using JTS
* Plugins using Geotools---ideally, these would be
modified tutorials from the Geotools code base.
* Plugins using GeoAPI/GeoObjects/GeoWidgets.
uDig base:
* A catalog exploration plugin that fully explains the
layout of the 'Data model'.
* A plugin that builds a layer, adds it to the catalog,
and to a map.
* A plugin that reads a .csv file "lat, long, value".
* A plugin that makes a tool
* A plugin that performs an operation.
uDig GUI:
* A menu/button plugin
* A dialog plugin
* A wizard plugin
* A view plugin
* A perspective plugin
* A help plugin
* A help plugin which walks a user through a series of
proceedure.
PACKAGING:
* A "hello uDig" plugin which is packaged and deployed
unto a uDig installation.
* A "hello uDig" plugin and feature set, packaged and
deployed onto an update site.
* A branded update feature, that adds graphics into the
"about" dialog.
* An application that uses the uDig platform and *not* the
GUI if this is possible, say a command line tool for
counting features in a shapefile.
* An application that uses only parts of uDig, say a
shapefile viewer.
* A rebranded application.
* A rebranded application which is deployable with a JRE
onto the major OS platforms as its own unit.
* A rebranded application distributed as an 'updater'
binary and an 'update' website.
Note that this guide should *not* take on the role of introducing
eclipse, which is how the current document mostly reads. The eclipse
manuals have good examples of buttons/view/wizards and the like. This
should explain the particularities of uDig, for example what kind of
perspectives might make sense in the uDig system.
So far, I have managed to create only the first plugin (as well as
several Eclipse plugins), but I'll keep working at it.
Having a bundled SDK:
--------------------
(A long term vision for SDK programmers.)
uDig should aim to distribute a Software Developer's Kit. I'm not sure
it is possible/legal but it would be a nice thing to do when Geotools
and uDig eventually stabilize.
The SDK would be a single download with as much of the pieces integrated
as possible including:
* Java/JAI/J...I/O (probably not legal but maybe the free stack
will work by then).
* The eclipse IDE configured for uDig development
* The third party jars, api and source
* The uDig jars, api and source
* The programmer's manual
Alternatively, it might be possible to do this as a series of 'updates'
and simply release an eclipse RCP updater.
Since this would be a lot of work to prepare, it's not worth doing until
the core libraries are fairly stable.
A Working outline of:
---------------------
This is not complete but should give you all an idea of where I'm
heading.
The uDig Programmer's Guide:
----------------------------
PART I. INTRODUCTION
Overview:
--------
This chapter is to build up enthusiasm. Thank writers for
participating. Make writers feel important and want to keep
going.
Welcome:
* to uDig, free GIS with an eclipse and geotools flavour
* how to interact with the community - contact into lists/irc
(with caveat that informal help is volunteer)(perhaps the
companies would want to offer an avenue to negotiate paid help
to writers who want it.)
* Let's have fun programming!
The two faces of uDig
* uDig from the user perspective - a network app
* uDig from the developer's (plugin/SDK) perspective - a platform
What this doc is about
* Explain what the doc is trying to do, who it targets, how to
read it.
* Go immediately to ... for instant gratification.
The ground covered by the doc
* A cursory outline of the manual
* Expectations of readers in terms of programming/GIS/library
knowledge.
A word of caution
* Programming uDig is hard to start
* Eclipse is very powerful and therefore pretty complex
* Everything is unstable, and why (still developing the standards,
still inventing the api's, still coding the libs).
* Space is *hard* interplay of 2-D to 3-D, topology, trying to
model the universe
* Don't panic, ask for help early and often, be nice (also to
yourself), and have a long term vision.
About this Manual:
* Authors/Verision History
* How to get the doc in various formats
* License
The Design of uDig:
------------------
This chapter explains how uDig thinks of itself and how writers
are expected to build on what is there. It outlines the various
types of extensions possible from hacks, to plugins and full
branded product.
The uDig Platform:
* Architectural diagram: A real one w/ especially the interface
classes used to access each component. My current graphic is a
six tier model with uDig split into Platform (catalog/discovery)
and GUI.
* Details of the Architecture with reference to java packages,
interfaces and classes.
* The uDig 'Data' model. I suspect the Catalog is the root of all
geospatial data in uDig. This would explaining the catalog and
how to use it to obtain features and their attribute data.
* The uDig 'View' and Controller models. Eclipse based but would
complement the other side of the classic MVC split.
uDig Design Patterns:
* What design patterns are and why they are constantly mentioned.
* Where they are used fundamentally in uDig: Factories...
How to interact with uDig:
* (Hacks ->) Plugins -> Features -> Products
* The thread of control
The Science of Geospatial Data:
------------------------------
This chapter gives a brief overview of the OCG refrence model,
of geospatial data, Coordinate Reference Systems and so on. This
aims to get everyone using the same 'language' and points to
good references for developers running into issues.
The basics: Simple Features
* The OGC's reference model: Topic 0
Geog. Info Science:
* A minimum of info and a maximum of pointers.
Sources of computational algorithms:
* Other software: R, GRASS, ...
Third Party libraries:
---------------------
This chapter would work through each of the third party
libraries and their tutorials to explain the layout of these
libraries. The manual should also explain where and how the
libraries are used in uDig.
Java 5.0:
JTS:
Geotools:
Eclipse:
PostGIS:
PART II. GETTING STARTED
Best practices for development:
------------------------------
This chapter explains how to keep the development environment
clean so as to simplify one's life. The current "Guidelines and
Rules" seems internal to uDig development and some of this
should be pushed over to the "Project" doc. The info could be
modified into a section on how programers could conform with
uDig if they wanted to and why they should want to.
* Suggestions for best practices and their advantages.
* Rules for becoming a 'community' participant with a directory in
svn.
* Rules for contributing to uDig with pointer to the "project" doc
Assembling a development platform:
---------------------------------
This chapter explains how to get a java sdk, an eclipse PDE, and
the uDig source code. The quick start and other guides which
exist work well but need to gain the motive and consequences
behind every step since that's the info users need to do things
differently and recover from errors.
* The structure of a developer's platform
* Quick start - pulling together the docs which exist
Getting an Eclipse PDE Adding uDig
* A formal presentation - explains the utility of each piece.
Extending uDig through Plugins:
------------------------------
This chapter explains how uDig plugins work in particular. There
will have to be some overlap with explaining eclipse plugins but
that should be kept to a minimum.
Introdution to plugins:
* The centrality of plugins to uDig development: clean way to
extend
* How uDig plugins work:
use extension points in eclipseRCP, uDig, or other
plugins use API in java, geotools, eclipse, uDig provide
extension points provide API
* Plugin structure
Coarse structure: Detailed (Plugin Index)
How to use plugins with uDig
* Extension of Eclipse:
what these extension points do (UI) and links to docs
* Extension of uDig:
what these extension points do-(uDig+extension+points
+list)
A first plugin:
--------------
We've covered *way* too much ground before giving users the
instant gratification they deserve.
Cookbook version:
* "Hello uDig, how big is your catalog?"
Extended version:
* The reasons and consequences of the various steps.
PART III. MOVING ALONG PLUGIN BY PLUGIN
Tutorial plugins:
----------------
This chapter steps through the list given above to get users
familiar with the different kinds of plugins (simple, feature,
fragment, and application/platform) and how to discover and use
uDig extension points.
Use of uDig Extension points:
----------------------------
Ideally, there would be an example of the use of each extension
point in uDig based either on a tutorial or on explaining a
plugin in the existing code. This would explain, for example,
how to make a feature source that would read a simple csv file
or how to define new layer operations.
Apps of different kinds:
-----------------------
A chapter on the different kinds of apps one could build with
uDig, their architectural design, and problems encountered.
Power Plugins:
----------
This chapter explains how to do the powerful things like rip out
the Geotools default feature model in favour of a new version or
how uDig programming can lead to true anarchy or world
domination, depending on one's political persuasion.
Appendices/Index/License/Misc:
-----------------------------
All the stuff that hangs onto a big document.
That's all I have as an outline for now --- it's a grandiose and long
term plan, but since I need to learn these things, the doc is merely a
compendium of my notes.
ciao,
adrian
_______________________________________________
User-friendly Desktop Internet GIS (uDig)
http://udig.refractions.net
http://lists.refractions.net/mailman/listinfo/udig-devel
