(use eggdoc htmlprag sxml-tools)

(define (pull-aquaterm-demo-code-in)
  `(pre ,(with-input-from-file "amb-demo.scm" read-string)))

(define doc
  `((eggdoc:begin
     (name "aquaterm")
     (description (p "Bindings to the C API for AquaTerm"))
     (author (url "http://www.chust.org/" "Thomas Chust"))
     (history
      (version "1.0.0" "Initial release"))
     
     (usage)
     (download "aquaterm.egg")
     
     (documentation
      (p "This documentation page is acutally a rewrite of the documentation for the Objective C AQTAdapter class. The C API this binding is relying on is not documented in its own right.")
      (p "For in-depth information on the functionality of the routines and general information you should consult the " (url "http://aquaterm.sourceforge.net/" "original AquaTerm documentation") " as well as this manual.")
      (p "Please not that the whole AquaTerm library is using the unit pt for its plot coordinates and sizes unless stated otherwise.")

      (subsection
       "Initializing and Deinitializing the Library"
       (group
	(procedure
	 "(aqt:init) => <boolean>"
	 (p "Initializes the library and return whether it was successful. You should call this routine before using any of the other functions."))
	(procedure
	 "(aqt:terminate) => <void>"
	 (p "Deinitializes the library, call it as the last thing before terminating your program."))))
      
      (subsection
       "Controlling Plots"
       (group
	(procedure
	 "(aqt:open-plot (id <exact>)) => <void>"
	 (p "Creates a new plot with an arbitrary identification number that can be used in calls to " (tt "aqt:select-plot") " to reference that plot.")
	 (p "Note that the plot is not displayed before you call " (tt "aqt:render-plot!")))
	(procedure
	 "(aqt:select-plot (id <exact>)) => <void>"
	 (p "Selects the plot identified by " (tt "id") " as the target for subsequent commands."))
	(procedure
	 "(aqt:set-plot-size! (width <number>) (height <float>)) => <void>"
	 (p "Defines the limits of the current plot area.")
	 (p "This function must be called before any drawing command following an " (tt "aqt:open-plot") " or " (tt "aqt:clear-plot!") " command, otherwise behaviour is undefined."))
	(procedure
	 "(aqt:set-plot-title! (title <string>)) => <void>"
	 (p "Sets a title for the current plot, which will be displayed in the plot window's titlebar and will be used as a default filename when saving the plot from AquaTerm."))
	(procedure
	 "(aqt:render-plot!) => <void>"
	 (p "Displays the current plot in an AquaTerm window rendering all drawing operations performed so far."))
	(procedure
	 "(aqt:clear-plot!) => <void>"
	 (p "Clears the current plot and resets all its attributes. Remeber to call " (tt "aqt:set-plot-size!") " again after using this function.")
	 (p "To clear the plot without resetting it, use the " (tt "aqt:erase-rect!") " procedure."))
	(procedure
	 "(aqt:close-plot!) => <void>"
	 (p "Closes the connection to the current plot and disables event handling.")
	 (p "Note that this function does not cause the plot window to disappear if it was shown before."))))

      (subsection
       "Clipping"
       (group
	(procedure
	 "(aqt:set-clip-rect! (x <number>) (y <number>) (width <number>) (height <number>)) => <void>"
	 (p "Set a rectangular clipping region to apply to all subsequent operations, until changed again by " (tt "aqt:set-clip-rect!") " or " (tt "aqt:set-default-clip-rect!")))
	(procedure
	 "(aqt:set-default-clip-rect!) => <void>"
	 (p "Reset the clipping region to the entire plot for all subsequent operations, until changed again by " (tt "aqt:set-clip-rect!") " or " (tt "aqt:set-default-clip-rect!")))))

      (subsection
       "Managing Colors"
       (group
	(procedure
	 "(aqt:set-color! (red <number>) (green <number>) (blue <number>)) => <void>"
	 (p "Set the drawing color in the active plot to the given " (tt "red") ", " (tt "green") " and " (tt "blue") " intensities between 0 and 1."))
	(procedure
	 "(aqt:set-background-color! (red <number>) (green <number>) (blue <number>)) => <void>"
	 (p "Set the background color in the active plot to the given " (tt "red") ", " (tt "green") " and " (tt "blue") " intensities between 0 and 1."))
	(procedure
	 "(aqt:get-color) => <number>, <number>, <number>"
	 (p "Retrieves the drawing color of the active plot and returns three values for its red, green and blue intensities between 0 and 1."))
	(procedure
	 "(aqt:get-background-color) => <number>, <number>, <number>"
	 (p "Retrieves the background color of the active plot and returns three values for its red, green and blue intensities between 0 and 1."))))

      (subsection
       "Managing the Colormap"
       (group
	(procedure
	 "(aqt:colormap-size) => <exact>"
	 (p "Returns the number of colormap entries available for the programmer."))
	(procedure
	 "(aqt:set-colormap-entry! (idx <exact>) (red <number>) (green <number>) (blue <number>)) => <void>"
	 (p "Set the entry at position " (tt "idx") " in the colormap to the given " (tt "red") ", " (tt "green") " and " (tt "blue") " intensities between 0 and 1."))
	(procedure
	 "(aqt:get-colormap-entry (idx <exact>)) => <number>, <number>, <number>"
	 (p "Retrieves the color at index " (tt "idx") " in the colormap and returns three values for its red, green and blue intensities between 0 and 1."))
	(procedure
	 "(aqt:take-color-from-colormap-entry! (idx <exact>)) => <void>"
	 (p "Set the drawing color in the active plot to the value of the colormap entry indicated by " (tt "idx") "."))
	(procedure
	 "(aqt:take-background-color-from-colormap-entry! (idx <exact>)) => <void>"
	 (p "Set the background color in the active plot to the value of the colormap entry indicated by " (tt "idx") "."))))

      (subsection
       "Drawing Text"
       (group
	(procedure
	 "(aqt:set-fontname! (name <string>)) => <void>"
	 (p "Sets the font to be used for future operations.")
	 (p "The default font is " (tt "\"Times-Roman\"") "."))
	(procedure
	 "(aqt:set-fontsize! (size <number>)) => <void>"
	 (p "Sets the font size in points for future operations.")
	 (p "The default font size are 14 pt."))
	(procedure
	 "(aqt:add-label! (text <string>) (x <number>) (y <number>) (angle <number>) #!optional ((h-align <symbol>) 'left) ((v-align <symbol>) 'baseline)) => <void>"
	 (p "Adds text at position " (tt "x, y") ", rotated by " (tt "angle") " degrees and aligned vertically and horizontally (with respect to position and rotation) according to " (tt "h-align") " and " (tt "v-align") ".")
	 (p "The following values are allowed for the alignment parameters:"
	    (table
	     (tr (th (tt "h-align") " -- Horizontal Alignment"))
	     (tr (td (tt "left")))
	     (tr (td (tt "center")))
	     (tr (td (tt "right"))))
	    (br)
	    (table
	     (tr (th (tt "v-align") " -- Vertical Alignment"))
	     (tr (td (tt "middle")))
	     (tr (td (tt "baseline")))
	     (tr (td (tt "bottom")))
	     (tr (td (tt "top"))))))
	(procedure
	 "(aqt:add-sheared-label! (text <string>) (x <number>) (y <number>) (angle <number>) (shear-angle <number>) (h-align <symbol>) (v-align <symbol>)) => <void>"
	 (p "Works like " (tt "aqt:add-label!") " but additionally shears the text by " (tt "shear-angle") " degrees in order to look right in 3D images for example."))))

      (subsection
       "Drawing Lines"
       (group
	(procedure
	 "(aqt:set-linewidth! (width <number>)) => <void>"
	 (p "Sets the current linewidth to " (tt "width") " points, used for all subsequent lines.")
	 (p "Any line currently being built by " (tt "aqt:move-to!") " and " (tt "aqt:add-line-to!") " will be considered finished since any coalesced sequence of line segments must share the same linewidth.")
	 (p "The default linewidth is 1 pt."))
	(procedure
	 "(aqt:set-linestyle-pattern! (phase <number>) . pattern) => <void>"
	 (p "Set the current line style to pattern style, used for all subsequent lines. The linestyle is specified as at most 8 numbers, where even positions in the list correspond to dash-lengths and odd positions correspond to gap-lengths.")
	 (p "To produce e.g. a dash-dotted line, use the command " (tt "(aqt:set-linestyle-pattern! 0 4 2 1 2)") "."))
	(procedure
	 "(aqt:set-linestyle-solid!) => <void>"
	 (p "Sets the current line style to solid, used for all subsequent lines.")
	 (p "This is the default setting."))
	(procedure
	 "(aqt:set-line-cap-style! (style <symbol>)) => <void>"
	 (p "Sets the current line cap style, used for all subsequent lines.")
	 (p "Any line currently being built by " (tt "aqt:move-to!") " and " (tt "aqt:add-line-to!") " will be considered finished since any coalesced sequence of line segments must share the same cap style.")
	 (p "The " (tt "style") " parameter can have the following values:"
	    (table
	     (tr (th "Style") (th "Meaning"))
	     (tr (td (tt "butt")) (td "Lines do not extend beyond their endpoint."))
	     (tr (td (tt "round")) (td "Lines extend into a half-circle beyond their endpoint."))
	     (tr (td (tt "square")) (td "Lines extend into a half-square beyond their endpoint."))))
	 (p "The default line cap style is " (tt "round") "."))
	(procedure
	 "(aqt:move-to! (x <number>) (y <number>)) => <void>"
	 (p "Moves the current point to " (tt "x, y") " in preparation for a new sequence of line segments."))
	(procedure
	 "(aqt:add-line-to! (x <number>) (y <number>)) => <void>"
	 (p "Adds a line segment from the current point (given by a previous " (tt "aqt:move-to!") " or " (tt "aqt:add-line-to!") ") to " (tt "x, y") " and sets the target position as the new current point."))
	(procedure
	 "(aqt:add-polyline! (points <list>)) => <void>"
	 (p "Adds a sequence of line segments specified by a list of start-, join-, and endpoint(s) in " (tt "points") ", a list of two number lists."))))

      (subsection
       "Drawing Rectangles and Polygons"
       (group
	(procedure
	 "(aqt:move-to-vertex! (x <number>) (y <number>)) => <void>"
	 (p "Moves the current point to " (tt "x, y") " in preparation for a new sequence of polygon edges."))
	(procedure
	 "(aqt:add-edge-to-vertex! (x <number>) (y <number>)) => <void>"
	 (p "Adds a polygon edge from the current point (given by a previous " (tt "aqt:move-to-vertex!") " or " (tt "aqt:add-edge-to-vertex!") ") to " (tt "x, y") " and sets the target position as the new current point."))
	(procedure
	 "(aqt:add-polygon! (points <list>)) => <void>"
	 (p "Adds a polygon specified by a list of vertices in " (tt "points") ", a list of two number lists."))
	(procedure
	 "(aqt:add-filled-rect! (x <number>) (y <number>) (width <number>) (height <number>)) => <void>"
	 (p "Adds a filled rectangle and attempts to remove any objects that will be covered by it."))
	(procedure
	 "(aqt:erase-rect! (x <number>) (y <number>) (width <number>) (height <number>)) => <void>"
	 (p "Removes any objects completely inside aRect. Does not force a redraw of the plot."))))

      (subsection
       "Drawing Bitmaps"
       (group
	(procedure
	 "(aqt:set-image-transform! (M-11 <number>) (M-12 <number>) (M-21 <number>) (M-22 <number>) (t-x <number>) (t-y <number>)) => <void>"
	 (p "Sets a transformation matrix for images added by " (tt "aqt:add-transformed-image-with-bitmap!") ", see the " (url "http://developer.apple.com/documentation/Cocoa/Conceptual/DrawBasic/Concepts/transforms.html#//apple_ref/doc/uid/20000887" "ADC Reference Documentation on Basic Drawing") " for more information how this works."))
	(procedure
	 "(aqt:reset-image-transform!) => <void>"
	 (p "Sets the transformation matrix to unity, i.e. no transform."))
	(procedure
	 "(aqt:add-image-with-bitmap! (data <string|byte-vector>) (data-width <exact>) (data-height <exact>) (x <number>) (y <number>) (width <number>) (height <number>)) => <void>"
	 (p "Adds a bitmap image of size " (tt "data-width * data-height") " pixels to the plot at position " (tt "x, y") ", scaling it to " (tt "width x height") " plot units.")
	 (p "The bitmap must be stored in " (tt "data") " as 24 bit per pixel, 8 bit per color channel raw RGB data.")
	 (p "Does not apply transform."))
	(procedure
	 "(aqt:add-transformed-image-with-bitmap! (data <string|byte-vector>) (data-width <exact>) (data-height <exact>) (x <number>) (y <number>) (width <number>) (height <number>)) => <void>"
	 (p "Adds a bitmap image of size " (tt "data-width * data-height") " pixels to the plot at position " (tt "x, y") ", scaling it to " (tt "width x height") " plot units and applying the stored transformation matrix to it.")
	 (p "The bitmap must be stored in " (tt "data") " as 24 bit per pixel, 8 bit per color channel raw RGB data."))))

      (subsection
       "Handling Events"
       (group
	(procedure
	 "(aqt:set-accepting-events! (yes <boolean>)) => <void>"
	 (p "Inform AquaTerm whether or not events should be passed from the currently selected plot. Deactivates event passing from any plot previously set to pass events."))
	(procedure
	 "(aqt:get-last-event) => <list|boolean>"
	 (p "Reads the last event logged by the viewer. Will always return " (tt "#f") " unless " (tt "aqt:set-accepting-events!") " was called with a " (tt "#t") " argument.")
	 (p "The event is returned by AquaTerm as a string but is decoded internally and passed back as follows:"
	    (table
	     (tr (th "Return value") (th "Meaning"))
	     (tr (td (tt "#f")) (td "No event was received."))
	     (tr (td (tt "('mouse (x y) button)")) (td "The mouse-button with the number " (tt "button") " was clicked at the position " (tt "x, y") " in plot coordinates."))
	     (tr (td (tt "('key (x y) key)")) (td "The key corresponding to the character " (tt "key") " was clicked while the mouse was at the position " (tt "x, y") " in plot coordinates."))))
	 (p "Should the event returned from the library encode an error, a continuable exception of the composite kind " (tt "(exn aquaterm)") " is thrown, which has an additional property " (tt "type") " holding either the symbol " (tt "server") " or " (tt "general") " depending on the source of the error."))
	(procedure
	 "(aqt:wait-next-event) => <list|boolean>"
	 (p "Works analogous to " (tt "aqt:get-last-event") " but blocks and waits for an event instead of returning immediately.")))))

      (examples
       (p "The following code is a free translation of the C API demo program shipped with AquaTerm. Most of the functionality of the library is demonstrated here.")
       ,(pull-aquaterm-demo-code-in))
      
      (license
       "Copyright (c) 2005, Thomas Chust <chust@web.de>.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

  Redistributions of source code must retain the above copyright notice,
  this list of conditions and the following disclaimer. Redistributions in
  binary form must reproduce the above copyright notice, this list of
  conditions and the following disclaimer in the documentation and/or
  other materials provided with the distribution. Neither the name of the
  author nor the names of its contributors may be used to endorse or
  promote products derived from this software without specific prior
  written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS
IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."))))

(eggdoc->html doc (eggdoc:make-stylesheet doc))