add initial javascript binding documentation

docs/jsbinding.md

@@ -0,0 +1,59 @@
+Javascript bindings
+===================
+
+In order for javascript programs to to interact with the page contents
+it must use the Document Object Model (DOM) and Cascading Style Sheet
+Object Model (CSSOM) API.
+
+These interfaces are described using web Interface Description
+Language (IDL) within the relevant specifications
+(e.g. https://dom.spec.whatwg.org/).
+
+Each interface described by the webIDL must be bound (connected) to
+the browsers internal representation for the DOM or CSS, etc. These
+bindings desciptions are processed together with the WebIDL by the
+nsgenbind tool to generate source code.
+
+A list of [DOM and CSSOM methods](unimplemented.html) is available
+outlining the remaining unimplemented API bindings.
+
+WebIDL
+------
+
+The WebIDL specification defines the interface description language used.
+
+These descriptions should be periodicaly updated to keep the browser
+interfaces current.
+
+There is a content/handlers/javascript/WebIDL/Makefile which attempts
+to automaticaly update the IDL files by scraping the web specs.
+
+This tool needs a great deal of hand holding, not least because many of the
+source documents list the IDL fragments multiple times, some even have
+appendicies with the entrire IDL repeated.
+
+Interface binding introduction
+------------------------------
+
+The binding files are processed by the nsgenbind tool to generate c
+source code which implements the interfaces within the javascript
+engine.
+
+The bindings are specific to a javascript engine, the DOM library, the
+CSS library and the browser. In this case that is the tuple of
+duktape, libdom, libcss and NetSurf.
+
+In principle other engines or libraries could be substituted
+(historicaly NetSurf unsucessfully tried to use spidermonkey) but the
+engineering to do so is formidable.
+
+The bindings are kept the sorce rpository within the duktape
+javascript handler content/handlers/javascript/duktape/
+
+The root binding which contains all the interfaces initroduced into
+the javascript programs initial execution context is nesurf.bnd this
+references all the WebIDL to be bound and includes all additional
+binding definitions to implement the interfaces.
+
+The bindings are a Domain Specific Language (DSL) which allows
+implementations to be added to each WebIDL method.

docs/mainpage.md

@@ -3,25 +3,123 @@ NetSurf web browser
 
 ![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1037/badge)[*](https://bestpractices.coreinfrastructure.org/projects/1037)
 
-The NetSurf code makes use of Doxygen for code documentation.
+# User Interface
 
-User Interface
+Netsurf is divided into a series of frontends which provide a user
---------------
+interface around common core functionality. Each frontend is a
+distinct implementation for a specific GUI toolkit.
 
-There are some basic user guides for the
+Because of this the user interface has different features in
-[framebuffer](docs/using-framebuffer.md) and
+each frontend allowing the browser to be a native application.
-[monkey](docs/using-monkey.md) frontends.
 
-The [core user options](docs/netsurf-options.md) of the browser are
+## Frontends
-documented which are augmented by each frontend in a specific manner.
 
-### Logging
+As GUI toolkits are often applicable to a single Operating
+System (OS) some frontends are named for their OS instead of the
+toolkit e.g. RISC OS WIMP frontend is named riscos and the Windows
+win32 frontend is named windows.
+
+### amiga
+
+Frontend specific to the amiga
+
+### atari
+
+Frontend specific to the atari
+
+### beos
+
+Frontend specific to the Haiku OS
+
+### framebuffer
+
+There is a basic user guide for the[framebuffer](docs/using-framebuffer.md)
+
+### gtk
+
+Frontend that uses the GTK+2 or GTK+3 toolkit
+
+### monkey
+
+This is the internal unit test frontend.
+
+There is a basic user guide [monkey](docs/using-monkey.md)
+
+### riscos
+
+Frontend for the RISC OS WIMP toolkit.
+
+### windows
+
+Frontend which uses the Microsodt win32 GDI toolkit.
+
+## User configuration
+
+The behaviour of the browser can be changed from the defaults with a
+configuration file. The [core user options](docs/netsurf-options.md)
+of the browser are common to all versions and are augmented by each
+frontend in a specific manner.
+
+
+# Development
+
+## Working with the team
+
+Generally it is sensible to check with the other developers if you are
+planning to make a change to NetSurf intended to be merged.
+
+We are often about on the IRC channel but failing that the developer
+mailing list is a good place to try.
+
+All the project sources are held in [public git repositories](http://source.netsurf-browser.org/)
+
+## Compilation environment
+
+Compiling a development edition of NetSurf requires a POSIX style
+environment. Typically this means a Linux based system although Free
+BSD, Open BSD, Mac OS X and Haiku all known to work.
+
+## Toolchains
+
+Compilation for non POSIX toolkits/frontends (e.g. RISC OS) generally
+relies upon a cross compilation environment which is generated using
+the makefiles found in our
+[toolchains](http://source.netsurf-browser.org/toolchains.git/)
+repository. These toolchains are built by the Continuous Integration
+(CI) system and the
+[results of the system](http://ci.netsurf-browser.org/builds/toolchains/)
+are published as a convenience.
+
+## Quick setup
+
+The [quick start guide](docs/quick-start.md) can be used to get a
+development environment setup quickly and uses the
+[env.sh](env_8sh_source.html) script the core team utilises.
+
+## Manual setup
+
+The Manual environment setup and compilation method is covered by the
+details in the [netsurf libraries](docs/netsurf-libraries.md) document
+for the core libraries and then one of the building documents for the
+specific frontend.
+
+- [Amiga Os cross](docs/building-AmigaCross.md) and [Amiga OS](docs/building-AmigaOS.md)
+- [Framebuffer](docs/building-Framebuffer.md)
+- [GTK](docs/building-GTK.md)
+- [Haiku (BeOS)](docs/building-Haiku.md)
+- [Windows Win32](docs/building-Windows.md)
+
+These documents are sometimes not completely up to
+date and the env.sh script should be considered canonical.
+
+## Logging
 
 The [logging](docs/logging.md) interface controls debug and error
 messages not output through the GUI.
 
-Documented API
+## Documented API
---------------
+
+The NetSurf code makes use of Doxygen for code documentation.
 
 There are several documents which detail specific aspects of the
 codebase and APIs.
@@ -39,60 +137,29 @@ provides a way for downloaded content to be kept on a persistent
 storage medium such as hard disc to make future retrieval of that
 content quickly.
 
-### Javascript
+## Javascript
 
-JavaScript is provided by integrating the duktape library. There are [instructions](docs/updating-duktape.md) on how to update the library.
+Javascript provision is split into four parts:
+- An engine that takes source code and executes it.
+- Interfaces between the program and the web page.
+- Browser support to retrive and manage the source code to be executed.
+- Browser support for the dispatch of events from user interface.
 
-A list of [unimplemented DOM and CSSOM methods](unimplemented.html)
+### Library
-is available outlining the remaining API that have to be implemented.
 
-Development
+JavaScript is provided by integrating the duktape library. There are
------------
+[instructions](docs/updating-duktape.md) on how to update the library.
 
-Compiling a development edition of NetSurf requires a POSIX style
+### Interface binding
-environment. Typically this means a Linux based system although Free
-BSD, Open BSD, Mac OS X and Haiku all known to work.
 
-### Working with the team
+In order for javascript programs to to interact with the page contents
+it must use the Document Object Model (DOM) and Cascading Style Sheet
+Object Model (CSSOM) API.
 
-Generally it is sensible to check with the other developers if you are
+These interfaces are described using web Interface Description
-planning to make a change to NetSurf intended to be merged.
+Language (IDL) within the relevant specifications
-
+(e.g. https://dom.spec.whatwg.org/).
-We are often about on the IRC channel but failing that the developer
-mailing list is a good place to try.
-
-All the project sources are held in [public git repositories](http://source.netsurf-browser.org/)
-
-### Toolchains
-
-Compilation for non POSIX toolkits/frontends (e.g. RISC OS) generally
-relies upon a cross compilation environment which is generated using
-the makefiles found in our
-[toolchains](http://source.netsurf-browser.org/toolchains.git/)
-repository. These toolchains are built by the Continuous Integration
-(CI) system and the
-[results of the system](http://ci.netsurf-browser.org/builds/toolchains/)
-are published as a convenience.
-
-### Quick setup
-
-The [quick start guide](docs/quick-start.md) can be used to get a
-development environment setup quickly and uses the
-[env.sh](env_8sh_source.html) script the core team utilises.
-
-### Manual setup
-
-The Manual environment setup and compilation method is covered by the
-details in the [netsurf libraries](docs/netsurf-libraries.md) document
-for the core libraries and then one of the building documents for the
-specific frontend.
-
-- [Amiga Os cross](docs/building-AmigaCross.md) and [Amiga OS](docs/building-AmigaOS.md)
-- [Framebuffer](docs/building-Framebuffer.md)
-- [GTK](docs/building-GTK.md)
-- [Haiku (BeOS)](docs/building-Haiku.md)
-- [Windows Win32](docs/building-Windows.md)
-
-These documents are sometimes not completely up to
-date and the env.sh script should be considered canonical.
 
+Each interface described by the webIDL must be bound (connected) to
+the browsers internal representation for the DOM or CSS, etc. The
+process of [writing bindings](docs/jsbinding.md) is ongoing.