Index: doc-rnd/gpmi/packages/dialogs.html
===================================================================
--- doc-rnd/gpmi/packages/dialogs.html	(revision 623)
+++ doc-rnd/gpmi/packages/dialogs.html	(revision 624)
@@ -7,13 +7,38 @@
 	on stderr. Note: message arguments usually may contain newline (\n) characters
 	to split the message.
 
-	<H2> function void dialog_log(const char *msg) </H2>
+	<H2> Common conventions </H2>
+	Dialog boxes are blocking calls to the GUI HID: when the script
+	calls a dialog box, the script is suspended until the dialog box
+	is closed by the user. In other words, dialog boxes behave
+	as regular function calls from the scripts: when they return,
+	the dialog is over and the result is known.
+	<p>
+	The only exception is <i>dialog_progress()</i>, which opens or
+	updates or closes the already open progress dialog box, and 
+	returns immediately (even when the box is left open).
+
+	<H2> Simple dialogs vs. custom dialogs </H2>
+	Most of the calls will pop up a static dialog box. Static means
+	that widgets are predefined by the GUI HID. The script
+	is free to fill in data, but can not change the basic structure of
+	the dialog box. For example <i>dialog_confirm(), dialog_prompt(),
+	dialog_fileselect()</i> are static.
+	<p>
+	When the script needs a custom, dynamic dialog box, it needs to
+	create an <i>attribute dialog</i>. The script sets up a HID
+	structure using the hid package, builds up all the input fields
+	then calls <i>dialog_attribute()</i> with the hid.
+
+	<H2> API reference </H2>
+
+	<H3> function void dialog_log(const char *msg) </H3>
 		Append a message to the log (log window and/or stderr). Arguments:
 		<OL>
 			<LI> const char *msg: the message
 		</OL>
 
-	<H2> function int dialog_confirm(const char *msg, const char *ok, const char *cancel) </H2>
+	<H3> function int dialog_confirm(const char *msg, const char *ok, const char *cancel) </H3>
 		Ask the user for confirmation. Returns 0 for cancel and 1 for ok. Arguments:
 		<OL>
 			<LI> const char *msg: message to the user
@@ -24,7 +49,7 @@
 		case the GUI will use the default (perhaps localized) labels for
 		those buttons.
 
-	<H2>function void dialog_report(const char *title, const char *msg) </H2>
+	<H3>function void dialog_report(const char *title, const char *msg) </H3>
 		Pop up a report dialog. Arguments:
 		<OL>
 			<LI> const char *title: title of the window
@@ -32,7 +57,7 @@
 		</OL>
 		No return value.
 
-	<H2> function char *dialog_prompt(const char *msg, const char *default_) </H2>
+	<H3> function char *dialog_prompt(const char *msg, const char *default_) </H3>
 		Prompt the user for a single line textual data. Arguments:
 		<OL>
 			<LI> const char *msg: message or question to the user
@@ -40,10 +65,10 @@
 		</OL>
 		Returns what the user typed or NULL (empty) if the user choosed to cancel.
 
-	<H2> function void dialog_beep(void) </H2>
+	<H3> function void dialog_beep(void) </H3>
 		Beeps. No argument, no return value.
 
-	<H2> function int dialog_progress(int so_far, int total, const char *message) </H2>
+	<H3> function int dialog_progress(int so_far, int total, const char *message) </H3>
 		Request the GUI hid to draw a progress bar. Arguments:
 		<OL>
 			<LI> int so_far: achieved state
@@ -58,7 +83,7 @@
 		break the loop on cancel. After the loop a call with so_far=total+1
 		should be made to make sure the window is closed.
 
-	<H2> function int dialog_attribute(hid_t *hid, const char *title, const char *descr) </H2>
+	<H3> function int dialog_attribute(hid_t *hid, const char *title, const char *descr) </H3>
 		Presents the user a custom dialog box, similar to those used by
 		the exporters.
 		<OL>
@@ -69,7 +94,7 @@
 		Return value: !!!TODO!!!. Values selected by the user are accessed
 		using <a href="!!!TODO!!!">hid_get_attribute</a>.
 
-	<H2> function char *dialog_fileselect(const char *title, const char *descr, char *default_file_, char *default_ext, const char *history_tag, multiple dialog_fileselect_t flags)</H2>
+	<H3> function char *dialog_fileselect(const char *title, const char *descr, char *default_file_, char *default_ext, const char *history_tag, multiple dialog_fileselect_t flags)</H3>
 		Pops up a file selection dialog.
 		<OL>
 			<LI> const char *title: window title
Index: doc-rnd/gpmi/packages/event_id.html
===================================================================
--- doc-rnd/gpmi/packages/event_id.html	(revision 623)
+++ doc-rnd/gpmi/packages/event_id.html	(revision 624)
@@ -11,8 +11,9 @@
 
 <P>
 
-The above described case (dispatcher event handler) is rare - most users
-can safely ignore this argument, but it must present as the first argument
+The case described above (dispatcher in the event handler) is rare.
+Most users will bind one event to one function and can safely ignore this
+argument. Nevertheless it must present as the first argument
 on the event handler's argument list.
 
 </BODY>
Index: doc-rnd/gpmi/packages/hid.html
===================================================================
--- doc-rnd/gpmi/packages/hid.html	(revision 623)
+++ doc-rnd/gpmi/packages/hid.html	(revision 624)
@@ -4,18 +4,18 @@
 
 The hid package has two purposes:
 <UL>
-	<LI> it is glue layer for exporter dialog boxes and attribute dialog boxes;
+	<LI> it is glue layer for exporter dialog boxes and <i>attribute dialog boxes</i>;
 	<LI> it can register exporter HIDs in PCB
 </UL>
 
-<H1> hid package - attribute dialog boxes</H1>
-	<H2>function hid_t *hid_create(char *hid_name, char *description); </H2>
+<H2> API reference - attribute dialog boxes</H1>
+	<H3>function hid_t *hid_create(char *hid_name, char *description); </H3>
 		Creates a new hid context. Name and description matters only
 		if the hid is registered as an exporter later. hid_t is an opaq
 		structure for the package that is used to describe attributes
 		of an attribute dialog or an exporter hid.
 
-	<H2>function int hid_add_attribute(hid_t *hid, char *attr_name, char *help, hid_attr_type_t type, int min, int max, char *default_val) </H2>
+	<H3>function int hid_add_attribute(hid_t *hid, char *attr_name, char *help, hid_attr_type_t type, int min, int max, char *default_val) </H3>
 		Append an attribute in a hid previously created using hid_create().
 		Arguments:
 		<OL>
@@ -43,7 +43,7 @@
 			<LI>HIDA_Path: path to a file or directory
 		</UL>
 
-	<H2>function char *hid_get_attribute(hid_t *hid, int attr_id) </H2>
+	<H3>function char *hid_get_attribute(hid_t *hid, int attr_id) </H3>
 		Query an attribute from the hid after dialog_attributes() returned.
 		<OL>
 			<LI> hid: hid_t previously created using hid_create()
@@ -51,8 +51,8 @@
 		</OL>
 		Returns the value set by the user.
 
-<H1> hid package - register an exporter</H1>
-	<H2> function int hid_register(hid_t *hid) </H2>
+<H2> API reference - register an exporter</H2>
+	<H3> function int hid_register(hid_t *hid) </H3>
 		Register the hid as an exporter. Should be called after all attributes have been
 		added using hid_add_atrtibute(). The export is coordinated by pcb core;
 		when the user request an export using the
@@ -63,7 +63,7 @@
 			<li> an envelope event to finish exporting
 		</ol>
 
-	<H2> Envelope: events generated before or after exporting </H2>
+	<H3> Envelope: events generated before or after exporting </H3>
 		<UL>
 			<LI>HIDE_get_export_options(void *hid): TODO Generated before get_exporter_options returns the option list to the GUI hid
 			<LI>HIDE_do_export_start(void *hid): Generated before export redraw starts
@@ -70,7 +70,7 @@
 			<LI>HIDE_do_export_finish(void *hid): Generated after export redraw finihsed
 		</UL>
 
-	<H2> Drawing: events generated during exporting </H2>
+	<H3> Drawing: events generated during exporting </H3>
 		Note: there may be multiple <I>gc</I>s (graphic contexts), each having its own color, line
 		properties, xor drawing and faded state. Graphic contexts are created
 		and destroyed by the following events:
Index: doc-rnd/gpmi/packages/layout.html
===================================================================
--- doc-rnd/gpmi/packages/layout.html	(revision 623)
+++ doc-rnd/gpmi/packages/layout.html	(revision 624)
@@ -3,9 +3,9 @@
 <H1> layout package </H1>
 
 Layout package searches and manipulates the current layout. Dimension units
-are in 1/100 mil TODO unless otherwise mentioned.
+are in nanometer unless otherwise mentioned.
 
-<H1> layout package - page </H1>
+<H2> layout package - page </H2>
 	Functions used to query or set width and height of the drawing:
 	<UL>
 		<LI>int layout_get_page_width();
@@ -13,7 +13,7 @@
 		<LI>void layout_set_page_size(int width, int height);
 	</UL>
 
-<H1> layout package - layer manipulation </H1>
+<H2> layer manipulation </H2>
 Most functions perform operations similar to user commands affecting
 the current layer.
 The following few calls can change the current layer. Warning: this is the
@@ -25,7 +25,7 @@
 		<LI>void layout_switch_to_layer(int layer): switch to layer (further actions will take place there)
 	</UL>
 
-<H1> layout package - search layer(s) for objects </H1>
+<H2> API reference - search layer(s) for objects </H2>
 	Search results are collected on lists identified by their name (search_ID).
 	If a new search is done with the same name, old search results for that
 	name are discarded.
@@ -39,7 +39,7 @@
 	<P>
 	[todo] lists can be merged or copied. [todo]
 
-	<H2> function int layout_search_box(const char *search_ID, multiple layout_object_mask_t obj_types, int x1, int y1, int x2, int y2); </H2>
+	<H3> function int layout_search_box(const char *search_ID, multiple layout_object_mask_t obj_types, int x1, int y1, int x2, int y2); </H3>
 		Creates a new search and adds all objects that matches obj_types mask within the given rectangle on the current layer.
 		Arguments:
 		<OL>
@@ -58,7 +58,7 @@
 			<LI> OM_PIN
 		</UL>
 
-	<H2> function int layout_search_selected(const char *search_ID, multiple layout_object_mask_t obj_types) </H2>
+	<H3> function int layout_search_selected(const char *search_ID, multiple layout_object_mask_t obj_types) </H3>
 		Creates a new search and adds all selected objects.
 		Arguments:
 		<OL>
@@ -66,7 +66,7 @@
 			<LI> obj_types: on or more object types or'd
 		</OL>
 
-	<H2> function int layout_search_found(const char *search_ID, multiple layout_object_mask_t obj_types) </H2>
+	<H3> function int layout_search_found(const char *search_ID, multiple layout_object_mask_t obj_types) </H3>
 		Creates a new search and adds all "found" objects (found objects are highlighted in green on the GUI).
 		Arguments:
 		<OL>
@@ -74,7 +74,7 @@
 			<LI> obj_types: on or more object types or'd
 		</OL>
 
-	<H2> function layout_object_t *layout_search_get(const char *search_ID, int n); </H2>
+	<H3> function layout_object_t *layout_search_get(const char *search_ID, int n); </H3>
 		Returns the nth object of a search.
 		Arguments:
 		<OL>
@@ -85,7 +85,7 @@
 		Fields of the object structure can be accessed using the object
 		accessors (see below).
 
-	<H2> int layout_search_free(const char *search_ID) </H2>
+	<H3> int layout_search_free(const char *search_ID) </H3>
 		Frees all memory related to a search. Returns 0 on success.
 		Argument:
 		<OL>
@@ -92,12 +92,12 @@
 			<LI> search_ID: unique name of the search (requires an existing search)
 		</OL>
 
-<H1> layout package - object accessors </H1>
+<H2> API reference - object accessors </H2>
 	The following functions may be used by the script to access fields of
 	an object structure. The object structure is most often obtained by
 	calling layout_search_get().
 
-	<H2> int layout_obj_coord(layout_object_t *obj, layout_object_coord_t coord) </H2>
+	<H3> int layout_obj_coord(layout_object_t *obj, layout_object_coord_t coord) </H3>
 		Return the requested coord of an object.
 		Arguments:
 		<OL>
@@ -123,10 +123,10 @@
 		Point 1 and point 2 are usually endpoints of the object (line, arc), "the whole object" 
 		coordinate is a central point (TODO: what's this?).
 
-	<H2> layout_object_mask_t layout_obj_type(layout_object_t *obj) </H2>
+	<H3> layout_object_mask_t layout_obj_type(layout_object_t *obj) </H3>
 		Return the type of an object (always a single value of layout_object_mask_t).
 
-	<H2> int layout_obj_move(layout_object_t *obj, layout_object_coord_t coord, int dx, int dy) </H2>
+	<H3> int layout_obj_move(layout_object_t *obj, layout_object_coord_t coord, int dx, int dy) </H3>
 		Change location of an object or parts of the object (like move endpoint
 		of a line); returns 0 on success.
 		Arguments:
@@ -137,14 +137,14 @@
 		</OL>
 
 
-	<H2> int layout_arc_angles(layout_object_t *obj, int relative, int start, int delta) </H2>
+	<H3> int layout_arc_angles(layout_object_t *obj, int relative, int start, int delta) </H3>
 		Change angles of an arc; start and delta are relative if <I>relative</I> is non-zero;
 		returns 0 on success.
 
 
-<H1> layout package - create new objects </H1>
+<H2> API reference - create new objects </H2>
 	These calls are used to create new objects on the current layer.
-	<H2>int layout_create_line(int x1, int y1, int x2, int y2, int thickness, int clearance, multiple layout_flag_t flags)</H2>
+	<H3>int layout_create_line(int x1, int y1, int x2, int y2, int thickness, int clearance, multiple layout_flag_t flags)</H3>
 		Creates a line.
 		Arguments:
 		<OL>
@@ -186,7 +186,7 @@
 			<LI> FL_THERMALSTYLE5 
 		</UL>
 
-	<H2> int layout_create_via(int x, int y, int thickness, int clearance, int mask, int hole, const char *name, multiple layout_flag_t flags) </H2>
+	<H3> int layout_create_via(int x, int y, int thickness, int clearance, int mask, int hole, const char *name, multiple layout_flag_t flags) </H3>
 		Create a named via.
 		Arguments:
 		<OL>
@@ -199,7 +199,7 @@
 		</OL>
 
 
-	<H2> int layout_create_arc(int x, int y, int width, int height, int sa, int dir, int thickness, int clearance, multiple layout_flag_t flags); </H2>
+	<H3> int layout_create_arc(int x, int y, int width, int height, int sa, int dir, int thickness, int clearance, multiple layout_flag_t flags); </H3>
 		Create a new arc.
 		Arguments:
 		<OL>
@@ -212,5 +212,11 @@
 			<LI> flags: one or more of layout flags
 		</OL>
 
+<H2> API reference - page, untis and coordinates </H2>
+TODO
+
+<H2> API reference - debug draw </H2>
+TODO
+
 </BODY>
 </HTML>