Author: desruisseaux
Date: Mon Oct 1 03:59:18 2012
New Revision: 1392195
URL: http://svn.apache.org/viewvc?rev=1392195&view=rev
Log:
Added a "Developing Apache SIS" page, and minor opportunist documentation fixes.
Added:
sis/trunk/src/site/apt/develop.apt (with props)
Modified:
sis/trunk/sis-build-helper/src/main/java/org/apache/sis/internal/taglet/Module.java
sis/trunk/sis-build-helper/src/site/apt/index.apt (props changed)
sis/trunk/sis-utility/src/site/apt/index.apt (props changed)
sis/trunk/src/site/apt/download.apt (props changed)
sis/trunk/src/site/apt/index.apt (contents, props changed)
sis/trunk/src/site/site.xml
Modified:
sis/trunk/sis-build-helper/src/main/java/org/apache/sis/internal/taglet/Module.java
URL:
http://svn.apache.org/viewvc/sis/trunk/sis-build-helper/src/main/java/org/apache/sis/internal/taglet/Module.java?rev=1392195&r1=1392194&r2=1392195&view=diff
==============================================================================
---
sis/trunk/sis-build-helper/src/main/java/org/apache/sis/internal/taglet/Module.java
(original)
+++
sis/trunk/sis-build-helper/src/main/java/org/apache/sis/internal/taglet/Module.java
Mon Oct 1 03:59:18 2012
@@ -114,7 +114,7 @@ public final class Module implements Tag
}
/**
- * Returns {@code false} since <code>@module</code> can not be used in
constructor
+ * Returns {@code false} since <code>@module</code> can not be used in
constructor.
*
* @return Always {@code false}.
*/
Propchange: sis/trunk/sis-build-helper/src/site/apt/index.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: sis/trunk/sis-build-helper/src/site/apt/index.apt
------------------------------------------------------------------------------
svn:mime-type = text/plain
Propchange: sis/trunk/sis-utility/src/site/apt/index.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: sis/trunk/sis-utility/src/site/apt/index.apt
------------------------------------------------------------------------------
svn:mime-type = text/plain
Added: sis/trunk/src/site/apt/develop.apt
URL:
http://svn.apache.org/viewvc/sis/trunk/src/site/apt/develop.apt?rev=1392195&view=auto
==============================================================================
--- sis/trunk/src/site/apt/develop.apt (added)
+++ sis/trunk/src/site/apt/develop.apt Mon Oct 1 03:59:18 2012
@@ -0,0 +1,144 @@
+ ------------------------------
+ Developing
+ ------------------------------
+
+
+Opening Apache SIS in an IDE
+
+ While the primarily SIS build system is Maven, the project provides some IDE
configuration files
+ for developers convenience. Before opening the project in an IDE, the source
code needs to be
+ downloaded from the {{{./source-repository.html}source repository}} and the
project built at
+ least once using Maven:
+
++---------------------------------------------------------+
+svn checkout http://svn.apache.org/repos/asf/sis/trunk sis
+cd sis
+mvn install
++---------------------------------------------------------+
+
+
+* NetBeans
+
+ NetBeans can open Maven projects natively. This is the recommended approach
for casual working
+ in a small amount of SIS modules. For extensive work on Apache SIS or for
work impacting many
+ modules, it may be more convenient and faster to open Apache SIS as a
NetBeans project.
+ Such pre-configured NetBeans project is available in the
<<<ide-project/NetBeans>>> directory.
+ This project will fetch dependencies directly from the <<<.m2/repository>>>
local directory,
+ and will refer to the resources <<<*.utf>>> files compiled by Maven in the
<<<sis-*/target>>>
+ directories. Consequently it is important to run <<<mvn\ install>>> before
opening the project
+ and after any change in the project dependencies or in the resources.
+
+ Users can customize their project configuration by editing the
<<<ide-project/NetBeans/nbproject/private/config.properties>>>
+ file. The <<<private>>> directory is excluded by the versioning system, so
it okay to put
+ user-specific information there. For example in order to overwrite the
default location of
+ the local Maven repository and to define a system property at execution
time, one can use:
+
++----------------------------------------------+
+maven.repository = /path/to/my/local/repository
+run.jvmargs = -DmyProperty=myValue
++----------------------------------------------+
+
+
+
+Developing Apache SIS
+
+ Improving and extending SIS requires extensive knowledge of geographic
information science,
+ object oriented programming, the Java language, and of the library itself.
Contributors should
+ expect that they will need to learn a great deal before being able to become
productive.
+ However, the effort required to become productive should improve the
contributor's understanding
+ and knowledge of geographic information systems, of geodetic and geographic
science, and of
+ effective computer programming.
+
+ This document is expected to evolve as the SIS project develops its own mode
of operation.
+
+
+
+* Background Knowledge
+
+ All contributors arrive to the project with different knowledge bases, some
with scientific
+ backgrounds, some with a background in computer science, and others with
geographic backgrounds
+ or even no training in geographic information science at all. By sharing the
richness of our
+ individual backgrounds we have acquired a list of subjects which we consider
critical to fully
+ understanding the SIS project. New contributors are highly encouraged to
explore these
+ areas if they have no or little knowledge of them.
+
+
+** Geographic Information Systems and Science
+
+ While a background in the field is not required, it nonetheless proves
exceedingly useful along
+ the way. GIS has developed its own language and has particular concerns
which return frequently.
+ Issues of spatial representation, data size, spatial scale, information
workflows and other topics
+ arise frequently and are worth understanding.
+
+ A good general introduction to the field is the book <Geographic Information
Systems and Science>
+ by Paul A. Longley, Michael F. Goodchild, David J. Maguire and David W.
Rhind published in its
+ second edition by John Wiley and Sons Ltd. in 2004.
+
+
+
+** The ISO/OGC Geospatial Model
+
+ SIS builds on the standards developed through a collaboration between the
International
+ Organization for Standardization\ (ISO) and the Open Geospatial Consortium\
(OGC).
+ Contributors to SIS should have at least a basic understanding of the model
developed in the
+ ISO\ 19000 series of specifications, starting with the Abstract model and
working through the
+ <Feature> model. While the ISO specifications are sold, the OGC releases its
own, essentially
+ identical versions of standards which have evolved from the collaboration.
The OGC specifications
+ are available for the {{{http://www.opengeospatial.org/standards}OGC
standards and specification}}
+ page.
+
+ As time progresses, we hope to develop documentation material to introduce
the ISO\ 19000
+ specification series.
+
+
+** Object-Oriented Programming in Java
+
+ SIS is a library designed to be used by other programmers. To play this role
effectively,
+ SIS must consider the various ways that users can reuse Java code: not only
through object
+ instantiation and method calls but also through inheritance. SIS pays
special attention to
+ accessibility constraints ensuring that only the classes and methods which
are offered for
+ use are publicly accessible and that these methods are fully and correctly
documented in javadoc.
+
+ Contributors are highly recommended to read the book <Effective Java> by
Joshua Block, published
+ in its second edition by Addison-Wesley in 2008. The book explains the
importance of certain
+ elements in the Java language and discusses subtleties of the language and
its use.
+ Most importantly, the book reveals the full scope a programmer must consider
when developing a
+ code library.
+
+
+** Mathematical Background
+
+ SIS frequently deals with complex calculations using relatively simple
mathematics of
+ trigonometry and matrix algebra. The coordinate operations of the
Referencing modules involve
+ trigonometric transformations on a flattened ellipsoid of rotation, the
image transformations in
+ the Coverage modules and in the Rendering system involve extensive use of
Affine transforms, and
+ the Analytic modules often use their own mathematical operations. These
mathematics cannot be
+ simplified â they reflect the richness of the world around us.
+
+ Affine transformations are not particularly complex but critically important
both to the
+ geo-referencing operations of the Referencing modules and to the image
transformations of the
+ Coverage modules. Affines transform coordinates through translation,
scaling, rotations, and
+ shear, though this latter component is used infrequently in the library.
Mathematically,
+ affine transformations are usually applied as a matrix operation applied to
a coordinate vector.
+ There are numerous introductions to affine transformations available on the
World Wide Web since
+ the concept is central to all graphics programming.
+
+
+
+* The GeoAPI Interfaces
+
+ SIS is build partially as an implementation of the GeoAPI interfaces. GeoAPI
defines a set
+ of objects offering particular methods thereby providing an interpretation
of the ISO/OGC
+ standards in the Java language. GeoAPI therefore defines the core of the
model implemented
+ by Apache SIS.
+
+ GeoAPI can most easily be learned by exploring the
+ {{{http://www.geoapi.org/snapshot/javadoc/index.html}GeoAPI Javadoc}}.
+
+
+
+* The SIS library modules
+
+ Contributors should gain a basic understanding of the core library including
the separation into
+ modules, the functionality available in the base module, and the functioning
of the modules of
+ interest.
Propchange: sis/trunk/src/site/apt/develop.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: sis/trunk/src/site/apt/develop.apt
------------------------------------------------------------------------------
svn:mime-type = text/plain
Propchange: sis/trunk/src/site/apt/download.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: sis/trunk/src/site/apt/download.apt
------------------------------------------------------------------------------
svn:mime-type = text/plain
Modified: sis/trunk/src/site/apt/index.apt
URL:
http://svn.apache.org/viewvc/sis/trunk/src/site/apt/index.apt?rev=1392195&r1=1392194&r2=1392195&view=diff
==============================================================================
--- sis/trunk/src/site/apt/index.apt (original)
+++ sis/trunk/src/site/apt/index.apt Mon Oct 1 03:59:18 2012
@@ -24,6 +24,8 @@ The Apache SIS⢠library
*
{{{http://builds.apache.org/job/sis-trunk/site/apidocs/index.html}Aggregated
Javadoc}}
+ * {{{./develop.html}Developing Apache SIS}}
+
* {{{./code-patterns.html}Recommended code patterns}}
* Developer Guide (English - translation to be provided later)
({{{./book/fr.xhtml}Français}})
Propchange: sis/trunk/src/site/apt/index.apt
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: sis/trunk/src/site/apt/index.apt
------------------------------------------------------------------------------
svn:mime-type = text/plain
Modified: sis/trunk/src/site/site.xml
URL:
http://svn.apache.org/viewvc/sis/trunk/src/site/site.xml?rev=1392195&r1=1392194&r2=1392195&view=diff
==============================================================================
--- sis/trunk/src/site/site.xml (original)
+++ sis/trunk/src/site/site.xml Mon Oct 1 03:59:18 2012
@@ -33,11 +33,11 @@
<!-- Links to appears just below the right banner -->
<!-- ==================================================== -->
<links>
+ <item name="Apache" href="http://www.apache.org"/>
<item name="Open Geospatial Consortium (OGC)"
href="http://www.opengeospatial.org"/>
<item name="GeoAPI" href="http://www.geoapi.org"/>
<item name="Javadoc"
href="http://builds.apache.org/job/sis-trunk/site/apidocs/index.html"/>
<!-- Absolute URL in order to point to the aggregated Javadoc instead
than module Javadoc. -->
- <item name="Apache" href="http://www.apache.org"/>
</links>
<!-- ==================================================== -->
