Formatting complete up to the end of the first reference-guide section.

diff --git a/doc/mkws-developer.markdown b/doc/mkws-developer.markdown
index 0676509..036017f 100644 (file)
--- a/doc/mkws-developer.markdown
+++ b/doc/mkws-developer.markdown
@@ -3,8 +3,11 @@
 % 11 August 2014
 
 
 % 11 August 2014
 
 

-Introduction
-============
+Overview
+========
+
+Core concepts
+-------------

 
 Development with MKWS consists primarily of defining new types of
 widgets. These can interact with the core functionality is several
 
 Development with MKWS consists primarily of defining new types of
 widgets. These can interact with the core functionality is several

@@ -61,7 +64,7 @@ This simple widget illustrates several important points:
 
 
 Widget specialisation (inheritance)
 
 
 Widget specialisation (inheritance)

-===================================
+-----------------------------------

 
 Many widgets are simple specialisations of existing widgets. For
 example, the `Record` widget is the same as the `Records` widget
 
 Many widgets are simple specialisations of existing widgets. For
 example, the `Record` widget is the same as the `Records` widget

@@ -75,55 +78,65 @@ follows:
 
 Remember that when a promotion function is called, it's passed a base
 widget object that's not specialised for any particular task. To make
 
 Remember that when a promotion function is called, it's passed a base
 widget object that's not specialised for any particular task. To make

-a specialised widget, first promote that base widget into the type
-that you want to specialise from -- in this case, "Records" -- using
+a specialised widget, you first promote that base widget into the type
+that you want to specialise from -- in this case, `Records` -- using

 the promotion function that's been registered for that type.
 
 Once this has been done, the specialisations can be introduced. In
 the promotion function that's been registered for that type.
 
 Once this has been done, the specialisations can be introduced. In

-this case, it's a very simple matter of changing the "maxrecs"
+this case, it's a very simple matter of changing the `maxrecs`

 configuration setting to 1 unless it's already been given an explicit
 configuration setting to 1 unless it's already been given an explicit

-value. (That would occur if the HTML used an element like <div
-class="mkwsRecord" maxrecs="2">, though it's not obvious why anyone
+value. (That would occur if the HTML used an element like `<div
+class="mkwsRecord" maxrecs="2">`, though it's not obvious why anyone

 would do that.)
 
 
 would do that.)
 
 

-Widget Properties and Methods
-=============================
+Reference Guide
+===============
+
+
+Widget properties and methods
+-----------------------------
+
+The following properties and methods exist in the bare widget object
+that is passed into `registerWidgetType`'s callback function, and can
+be used by the derived widget.

 
 

-String this.type
+* `String this.type` --

        A string containing the type of the widget.
 
        A string containing the type of the widget.
 

-Team this.team
+* `Team this.team` --

        The team object to which this widget belongs. The team has
        several additional important properties and methods, described
        below.
 
        The team object to which this widget belongs. The team has
        several additional important properties and methods, described
        below.
 

-DOMElement this.node
+* `DOMElement this.node` --

        The DOM element of the widget
 
        The DOM element of the widget
 

-Hash this.config
+* `Hash this.config` --

        A table of configuration values for the widget. This table
        inherits missing values from the team's configuration, which
        in turn inherits from the top-level MKWS configuration, which
        inherits from the default configuration. Instances of widgets
        A table of configuration values for the widget. This table
        inherits missing values from the team's configuration, which
        in turn inherits from the top-level MKWS configuration, which
        inherits from the default configuration. Instances of widgets

-       in HTML can set configuration items as HTML attributes, as in
-       <div class="mkwsRecords" maxrecs="2">.
+       in HTML can set configuration items as HTML attributes: for
+       example, the HTML element
+       `<div class="mkwsRecords" maxrecs="10">`.
+       creates a widget for which `this.config.maxrecs` is set to 10.

 
 

-String this.toString()
+* `String this.toString()` --

        A function returning a string that briefly names this
        widget. Can be useful in logging.
 
        A function returning a string that briefly names this
        widget. Can be useful in logging.
 

-Void this.log(string)
+* `Void this.log(string)` --

        A function to log a string for debugging purposes. The string
        is written on the browser console, and also published to any
        A function to log a string for debugging purposes. The string
        is written on the browser console, and also published to any

-       "log" subcribers.
+       subcribers to the `log` event.

 
 

-String this.value()
+* `String this.value()` --

        A function returning the value of the widget's HTML element.
 
 
 Team methods
        A function returning the value of the widget's HTML element.
 
 
 Team methods

-============
+------------

 
 Since the team object is supposed to be opaque to widgets, all access
 is via the following API methods rather than direct access to
 
 Since the team object is supposed to be opaque to widgets, all access
 is via the following API methods rather than direct access to