Convert Help sources from HTML to AsciiDoctor (#351)

The documentation for the Draw2D, GEF and Zest bundles has been
converted to AsciiDoctor. The corresponding HTML files are generated as
part of the incremental build.

Meaning that any changes to the adoc files inside the IDE will cause the
HTML files to be updated allowing us to immediately verify the new
output.

Note that this change also performs minor changes to the documentation,
such as fixing URLs and references to the JavaDoc, as well as fixing the
JavaDoc generation for Zest itself.

.gitignore

@@ -1,7 +1,6 @@
-/*/*/bin/
-/target
-/*/*/target
-/promotion/target
+**/bin/
+**/target/
+**/guide/*.html
 /gef-updates
 *~
 *.rej

org.eclipse.draw2d.doc.isv/.classpath

@@ -1,5 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <classpath>
+	<classpathentry kind="src" path="guide-src"/>
 	<classpathentry kind="con" path="org.eclipse.pde.core.requiredPlugins"/>
 	<classpathentry kind="con" path="org.eclipse.jdt.launching.JRE_CONTAINER"/>
 	<classpathentry kind="output" path="bin"/>

org.eclipse.draw2d.doc.isv/.project

@@ -5,7 +5,19 @@
 	<projects>
 	</projects>
 	<buildSpec>
+		<buildCommand>
+			<name>org.eclipse.jdt.core.javabuilder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
+		<buildCommand>
+			<name>org.eclipse.m2e.core.maven2Builder</name>
+			<arguments>
+			</arguments>
+		</buildCommand>
 	</buildSpec>
 	<natures>
+		<nature>org.eclipse.m2e.core.maven2Nature</nature>
+		<nature>org.eclipse.jdt.core.javanature</nature>
 	</natures>
 </projectDescription>

org.eclipse.draw2d.doc.isv/buildDoc.xml

@@ -46,19 +46,18 @@
 		<unzip src="${linkoffline-target}/org.eclipse.platform.doc.isv.jar" dest="${linkoffline-target}/org.eclipse.platform.doc.isv/" />	
 		<echo message="Done: ${linkoffline-target} contains unzipped offline link target." />
 
-		<property name="tmp.options.file" value="javadocOptions.tmp.txt" />
+		<property name="tmp.options.file" value="javadocOptions.txt" />
 		<echo message="Preparing temporary options file ${tmp.options.file}" />
-		<copy file="javadocOptions.txt" tofile="${tmp.options.file}" overwrite="true" />
-		<replaceregexp file="${basedir}/${tmp.options.file}" flags="g" match="(\r\n?|\n);" replace="${args.list.delimiter}" />
-		<replace file="${basedir}/${tmp.options.file}" token="@context@" value="${api.context.libs.classpath}" />
-		<replace file="${basedir}/${tmp.options.file}" token="@rt@" value="${bootclasspath}" />
-		<replace file="${basedir}/${tmp.options.file}" token="@args.list.delimiter@" value="${args.list.delimiter}" />
-		<replace file="${basedir}/${tmp.options.file}" token="@linkoffline-target@" value="${linkoffline-target}" />
+		<replaceregexp file="${project.build.directory}/${tmp.options.file}" flags="g" match="(\r\n?|\n);" replace="${args.list.delimiter}" />
+		<replace file="${project.build.directory}/${tmp.options.file}" token="@context@" value="${api.context.libs.classpath}" />
+		<replace file="${project.build.directory}/${tmp.options.file}" token="@rt@" value="${bootclasspath}" />
+		<replace file="${project.build.directory}/${tmp.options.file}" token="@args.list.delimiter@" value="${args.list.delimiter}" />
+		<replace file="${project.build.directory}/${tmp.options.file}" token="@linkoffline-target@" value="${linkoffline-target}" />
 		<echo message="Done." />
 
 		<echo message="Generating javadoc..." />
 		<exec dir="." executable="${javadoc}" output="doc.bin.log">
-			<arg line="@${basedir}/${tmp.options.file} -J-Xmx1000M" />
+			<arg line="@${project.build.directory}/${tmp.options.file} -J-Xmx1000M" />
 		</exec>
 		<echo message="Done." />
 	</target>

org.eclipse.draw2d.doc.isv/guide-src/connections.adoc

@@ -0,0 +1,89 @@
+= Connections and Routing
+
+== Connections and Routing
+
+Connections figures are used to display a line between two points. The
+link:../reference/api/org/eclipse/draw2d/Connection.html[`Connection`]
+interface extends `IFigure`. The provided `PolylineConnection` 
+implementation can be used in most cases. The source and target
+endpoints of a connection are each defined using a `ConnectionAnchor`.
+These endpoints, along with any other points on the connection, are set
+by the connection's `ConnectionRouter`. Usually every connection in a
+drawing has the same router instance. Connections with common endpoints
+can share anchor instances as well.
+
+=== Connection Usage
+
+Connections are created and added just like any other figure. Usually,
+connections should be displayed above other elements of a drawing using
+Layers. Unlike normal figures, you must not set the bounds of a
+connection. Instead, you must provide the source and target anchors and
+let the connection router calculate the connection's points.  The
+connection then determines its own bounding box.
+
+A connection has a simple router by default - one that can connect the
+source and target anchors. But additional routers are available and can
+be set on the connection. Some routers can handle constraints for the
+connection such as a list of bendpoints through which the connection
+passes. Note that when setting a routing constraint on a connection, you
+must first set the router which will use that constraint.
+
+A convenient way to share the router with all connections and to place
+connections above the drawing is to use a `ConnectionLayer`. The layer
+has a connection router property which it shares with every child that's
+a connection. You can update this property and easily change every
+connection's router at once.
+
+=== Routing and Anchors
+
+A connection always has a router and it must set at least two points on
+the connection: the source and target endpoints. By default, or when set
+to `null`, the connection's routing will be performed by an internal
+default router. The ends are placed with the help of anchors. An anchor
+is a fixed or calculated location, usually associated with some figure.
+For example, the ChopboxAnchor finds the point at which a line going to
+the reference point intersects a box, such as the bounds of a figure.
+The _reference point_ is either the anchor at the opposite end, or a
+bendpoint or some other point nearest to the anchor. Anchors notify the
+connection when their anchor points has changed.
+
+image:images/chopbox.gif[image] +
+_A ChopboxAnchor calculates the connection endpoint by finding the
+reference's intersection with a rectangle_
+
+The router calculates the endpoints and any other points in the middle
+of the connection. It then sets the points on the connection by calling
+link:../reference/api/org/eclipse/draw2d/Connection.html#setPoints(org.eclipse.draw2d.geometry.PointList)[`setPoints(PointList)`].
+The connection's existing point list can be reused to reduce garbage,
+but the points must be set on the connection anyway so that it knows
+about any changes made.
+
+=== Adding Decorations and Children to Connections
+
+Like most figures, PolylineConnection supports the addition of children.
+The children might be arrowheads or labels that decorate the connection.
+The placement of each type of decoration can vary, so a
+link:../reference/api/org/eclipse/draw2d/DelegatingLayout.html[`DelegatingLayout`]
+is used to delegate to each child's constraint object, a
+link:../reference/api/org/eclipse/draw2d/Locator.html[`Locator`].
+PolygonDecoration can be used to create render a rotatable shape at the
+end of a connection. The end of a connection can be labeled by adding a
+Label with a `ConnectionEndpointLocator`. A connection will extend its
+bounds beyond what would be required to paint just the polyline.
+
+image:images/decorations.gif[image] +
+_A connection with 2 child decorations_
+
+=== Connection Layout
+
+Connections extend the process of validation and layout to include
+routing. Since layout is the process of positioning children, routing
+must come first. This allows a child's locator to operate on the
+connection's newly-routed points.
+
+During the validation step, the connection must remember its old bounds
+and determine its new. It then must damage the appropriate regions on
+the update manager. The provided implementation does all of these things
+for you. It also requests revalidation according to certain events
+specific to connections, such as an anchor moving or the router
+changing.

org.eclipse.draw2d.doc.isv/guide-src/coordinates.adoc

@@ -0,0 +1,165 @@
+= Coordinate Systems
+
+== Coordinate Systems
+
+Draw2d provides a flexible coordinate with simple defaults. Different
+coordinate systems are required by certain optimizations and features
+provided by draw2d. A coordinate system is nothing more than an
+adjustment made to the Draw2d `Graphics` when painting children
+(coordinate systems have *no affect* on the way a figure paints itself).
+For example, it is possible to translate or zoom a Graphics. Both of
+these operations affect subsequent paint calls. To match what you see,
+operations like searching for a figure at a point must respect such
+coordinate changes.
+
+The default coordinate system is very simple, it is the same for every
+figure. So it doesn't matter if a figure is parented by another figure,
+you could compare the bounding boxes directly to each other. When the
+figures paint, they all paint in the same coordinates, and when hit
+testing is performed, the location is not modified when searching
+recursively through the children. This coordinate system is called
+_absolute_. If a figure uses absolute coordinates, when it moves, it
+must also translate its children by the same amount. "Absolute" may not
+be the best choice of words. "Inherited" is probably more accurate,
+since children are inheriting the parent's coordinate system, which
+could be anything.
+
+The opposite of absolute (or inherited) coordinates is _relative_ (also
+_local)_. In a relative coordinate system, the bounds of children are
+relative to the client area of their parent. The client area is the
+parent's bounds unless the parent has insets. When a figure with
+relative coordinates is moved, the children come along for free, without
+any changes to their bounds.
+
+=== Relative vs. Absolute
+
+The default coordinate system is absolute and is often left unchanged. A
+figure can easily change the coordinate system used for its children by
+overriding useLocalCoordinates(). The following table shows some
+possible reasons to choose either.
+
+[.custom]
+|===
+|*Task* |*Absolute Coordinates* |*Relative Coordinates*
+
+|Translate/move a figure |The figure and all of its children must be
+translated, which can be expensive in extreme cases. |Only the figure's
+bounds must be updated. The children move for free.
+
+|Hit-test / determine repaint regions |No adjustments are needed to
+coordinates. |Some simple math is used to adjust coordinates and
+rectangles to/from the coordinate system's origin.
+
+|Observe the figure's "location" on the Canvas |A FigureListener can be
+used if the entire parent chain is using absolute coordinates. But this
+guarantee is rare. |A FigureListener and CoordinateListener must be
+used. You must call translateToAsbolute on the figure being observed to
+get its canvas coordinates.
+
+|Determine the bounds of a parent based on the bounds of the children
+|Easy - after the children have been position, the parent can then
+figure out what its bounds should be. |Extremely hard, since updating
+the parent's bounds will cause the children to "move".
+|===
+
+=== Other Coordinate Systems
+
+Zooming and scrolling are done specially by the viewport and scalable
+layered pane figures provided with Draw2d. Scrolling a drawing is quite
+common, and it would be silly if doing this required updating the
+bounding rectangle of every figure in the drawing. As an optimization, a
+viewport can be constructed with _virtual_ scrolling, which is
+implemented by translating the coordinate system's origin.
+
+Zoom is done by scaling the coordinate system about the origin.
+
+=== Working with Absolute Coordinates
+
+The only types of locations which can be passed around and compared in a
+meaningful way are absolute. Here, "absolute" means the top-most parent
+(or root) figure's coordinate system. When Draw2d is used with SWT
+Canvas, an absolute location is the location on that Canvas. To get the
+location on the Display (i.e. the monitor), you would then have to use
+the utilities on SWT's Display to convert from a Control to the Display.
+
+To convert to and from absolute coordinates, utility methods are defined
+on IFigure. These methods will convert any object implementing the
+` Translatable` interface (historical note: zoom was not in the first
+draw2d release so translation was the only type of converting
+necessary).
+
+* link:../reference/api/org/eclipse/draw2d/IFigure.html#translateToAbsolute(org.eclipse.draw2d.geometry.Translatable)[*`translateToAbsolute(Translatable)`*] -
+converts from the receiver's coordinates to absolute coordinates.
+Note that the receiver's coordinate system is the system in which
+the receiver is placed, and *not* the coordinates in which it
+places its children.
+* link:../reference/api/org/eclipse/draw2d/IFigure.html#translateToRelative(org.eclipse.draw2d.geometry.Translatable)[*`translateToRelative(Translatable)`*] -
+converts from absolute coordinates to the receiver's coordinates.
+The above methods are implemented recursively by walking up the parent
+chain and performing the conversion for each parent. It's not easy to
+extend the behavior of a recursive method, so the actual conversions are
+factored out into separate methods.  These methods are also public and
+are called in some situations.
+* link:../reference/api/org/eclipse/draw2d/IFigure.html#translateToParent(org.eclipse.draw2d.geometry.Translatable)[*`translateToParent(Translatable)`*] -
+converts from the coordinate system defined by the receiver.  If the
+receiver uses absolute/inherited coordinates, no conversion is performed.
+* link:../reference/api/org/eclipse/draw2d/IFigure.html#translateFromParent(org.eclipse.draw2d.geometry.Translatable)[*`translateFromParent(Translatable)`*] -
+converts to the coordinate system defined by the receiver.
+
+==== Example: How to place a Shell on top of a Figure
+
+____
+Given a figure that is displayed on a Canvas, how do we popup a shell
+such that it is in exactly the same location on the screen?
+____
+
+==== Solution:
+
+____
+First, take the figure's location and convert it to the canvas. Note
+that the figure's bounds are returned by reference, so you need to
+create a copy to avoid modifying the original bounds. Next, create an
+SWT Rectangle and convert it to the display's coordinates:
+
+[source,java]
+----
+public void example1(Shell shell, Figure figure, Canvas canvas) {
+    org.eclipse.draw2d.geometry.Rectangle r;
+    org.eclipse.swt.graphics.Rectangle swtRect;
+
+    r = figure.getBounds().getCopy();
+    figure.translateToAbsolute(r);
+
+    swtRect = new org.eclipse.swt.graphics.Rectangle(r.x, r.y, r.width, r.height);
+    shell.setBounds(canvas.getDisplay().map(canvas, null, swtRect));
+}
+----
+____
+
+==== Example: How to Position a Connection using an Anchor
+
+____
+Given a ConnectionAnchor, what is the proper way to set the endpoint of
+a connection?
+____
+
+==== Solution:
+
+____
+A connection anchor is a helper object that returns a Point in absolute
+coordinates. The connection figure can be inside a figure such as a
+viewport or layer that has its own coordinate system. The following code
+makes the necessary conversion:
+
+[source,java]
+----
+public void example2(Connection connection, ConnectionAnchor sourceAnchor, Point reference) {
+    Point anchorpoint = sourceAnchor.getLocation(reference);
+    connection.translateToRelative(anchorpoint);
+
+    PointList list = connection.getPoints();
+    list.setPoint(anchorpoint, 0);
+    connection.setPoints(list);
+}
+----
+____

org.eclipse.draw2d.doc.isv/guide-src/guide.adoc

@@ -0,0 +1,15 @@
+= Draw2d Guide
+
+== Draw2d Programmer's Guide +
+org.eclipse.draw2d +
+
+* link:overview.html[Overview] - the big picture
+* link:painting.html[Painting] - details of the paint process and how
+nesting affects painting
+* link:layout.html[Layout] - preferred size, layout, validating figures
+* link:hittest.html[Hit Testing] - finding figures, correcting
+coordinates, modifying the space occupied by a figure
+* link:connections.html[Connections and Routing] - connections, anchors,
+decorations, and routing
+* link:coordinates.html[Coordinate Systems] - absolute and relative
+coordinates, working with absolute coordinates

org.eclipse.draw2d.doc.isv/guide-src/hittest.adoc

@@ -0,0 +1,36 @@
+= Hit Testing
+
+== Hit Testing
+
+There are several situations which require finding a figure for a mouse
+location. For example, determining which tooltip to display when the
+mouse pauses on top of a figure canvas. Another example is interactive
+graphical applications, which must interpret dragging one figure on top
+of another.
+
+There are four methods available on IFigure which perform hit testing,
+three of which are actually just convenience methods which call the
+fourth.
+
+* link:../reference/api/org/eclipse/draw2d/IFigure.html#findFigureAt(int,int)[*`findFigureAt(int x, int y)`*] -
+finds the top-most figure for the given x and y coordinate.
+* link:../reference/api/org/eclipse/draw2d/IFigure.html#findFigureAt(org.eclipse.draw2d.geometry.Point)[*`findFigureAt(Point p)`*] -
+similar to above, except takes a Point instead of an int.
+* link:../reference/api/org/eclipse/draw2d/IFigure.html#findFigureAtExcluding(int,int,java.util.Collection)[*`findFigureAtExcluding(int x, int y, Collection exclude)`*] -
+finds the top-most figure for the given coordinates that is not in the
+exclusion set or contained by a figure in the exclusion set. This is
+used for ignoring a figure being dragged, or for ignoring transparent
+layers or figures which are not involved in an interaction.
+* link:../reference/api/org/eclipse/draw2d/IFigure.html#findFigureAt(int,int,org.eclipse.draw2d.TreeSearch)[*`findFigureAt(int x, int y, TreeSearch)`*] -
+All of the above methods call this method. TreeSearch is a helper that
+is used to quickly prune branches which should not be searched, and to
+accept the final candidate figure.
+
+Hit testing must be done exactly the same way as painting. Clipping and
+coordinate changes must be duplicated in both. As an optimizations,
+branches of the figure composition tree are pruned by calling
+`containsPoint()`. If a figure does not contain the location, it returns
+NULL and does not search its children. By default, all figures are
+considered to be the rectangular region defined by their bounds,
+regardless of how or if they paint. This can be overridden as it is in
+Polyline, Ellipse, and other figures.