Gitweb links:
...log
http://git.netsurf-browser.org/netsurf.git/shortlog/148639b70c3831693c08bb00d5ef372d59088840
...commit
http://git.netsurf-browser.org/netsurf.git/commit/148639b70c3831693c08bb00d5ef372d59088840
...tree
http://git.netsurf-browser.org/netsurf.git/tree/148639b70c3831693c08bb00d5ef372d59088840
The branch, master has been updated
via 148639b70c3831693c08bb00d5ef372d59088840 (commit)
from ccb499b80057a8241829a3ba11e5f87013739c8d (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commitdiff
http://git.netsurf-browser.org/netsurf.git/commit/?id=148639b70c3831693c08bb00d5ef372d59088840
commit 148639b70c3831693c08bb00d5ef372d59088840
Author: Vincent Sanders <[email protected]>
Commit: Vincent Sanders <[email protected]>
add initial javascript binding documentation
diff --git a/docs/jsbinding.md b/docs/jsbinding.md
new file mode 100644
index 0000000..c258a67
--- /dev/null
+++ b/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.
diff --git a/docs/mainpage.md b/docs/mainpage.md
index fa72d14..0700137 100644
--- a/docs/mainpage.md
+++ b/docs/mainpage.md
@@ -3,57 +3,67 @@ NetSurf web browser
[*](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
-[framebuffer](docs/using-framebuffer.md) and
-[monkey](docs/using-monkey.md) frontends.
+Because of this the user interface has different features in
+each frontend allowing the browser to be a native application.
-The [core user options](docs/netsurf-options.md) of the browser are
-documented which are augmented by each frontend in a specific manner.
+## Frontends
-### 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.
-The [logging](docs/logging.md) interface controls debug and error
-messages not output through the GUI.
+### amiga
-Documented API
---------------
+Frontend specific to the amiga
-There are several documents which detail specific aspects of the
-codebase and APIs.
+### atari
-### Core window
+Frontend specific to the atari
-The [core window API](docs/core-window-interface.md) allows frontends
-to use generic core code for user interface elements beyond the
-browser render.
+### beos
-### Source object caching
+Frontend specific to the Haiku OS
-The [source object caching](docs/source-object-backing-store.md)
-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.
+### framebuffer
-### Javascript
+There is a basic user guide for the[framebuffer](docs/using-framebuffer.md)
-JavaScript is provided by integrating the duktape library. There are
[instructions](docs/updating-duktape.md) on how to update the library.
+### gtk
-A list of [unimplemented DOM and CSSOM methods](unimplemented.html)
-is available outlining the remaining API that have to be implemented.
+Frontend that uses the GTK+2 or GTK+3 toolkit
-Development
------------
+### monkey
-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.
+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.
-### Working with the team
+
+# 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.
@@ -63,7 +73,13 @@ 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 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
@@ -74,13 +90,13 @@ repository. These toolchains are built by the Continuous
Integration
[results of the system](http://ci.netsurf-browser.org/builds/toolchains/)
are published as a convenience.
-### Quick setup
+## 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
+## Manual setup
The Manual environment setup and compilation method is covered by the
details in the [netsurf libraries](docs/netsurf-libraries.md) document
@@ -96,3 +112,54 @@ specific frontend.
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
+
+The NetSurf code makes use of Doxygen for code documentation.
+
+There are several documents which detail specific aspects of the
+codebase and APIs.
+
+### Core window
+
+The [core window API](docs/core-window-interface.md) allows frontends
+to use generic core code for user interface elements beyond the
+browser render.
+
+### Source object caching
+
+The [source object caching](docs/source-object-backing-store.md)
+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 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.
+
+### Library
+
+JavaScript is provided by integrating the duktape library. There are
+[instructions](docs/updating-duktape.md) on how to update the library.
+
+### Interface binding
+
+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. The
+process of [writing bindings](docs/jsbinding.md) is ongoing.
-----------------------------------------------------------------------
Summary of changes:
docs/jsbinding.md | 59 ++++++++++++++++++++++
docs/mainpage.md | 141 +++++++++++++++++++++++++++++++++++++++--------------
2 files changed, 163 insertions(+), 37 deletions(-)
create mode 100644 docs/jsbinding.md
diff --git a/docs/jsbinding.md b/docs/jsbinding.md
new file mode 100644
index 0000000..c258a67
--- /dev/null
+++ b/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.
diff --git a/docs/mainpage.md b/docs/mainpage.md
index fa72d14..0700137 100644
--- a/docs/mainpage.md
+++ b/docs/mainpage.md
@@ -3,57 +3,67 @@ NetSurf web browser
[*](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
-[framebuffer](docs/using-framebuffer.md) and
-[monkey](docs/using-monkey.md) frontends.
+Because of this the user interface has different features in
+each frontend allowing the browser to be a native application.
-The [core user options](docs/netsurf-options.md) of the browser are
-documented which are augmented by each frontend in a specific manner.
+## Frontends
-### 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.
-The [logging](docs/logging.md) interface controls debug and error
-messages not output through the GUI.
+### amiga
-Documented API
---------------
+Frontend specific to the amiga
-There are several documents which detail specific aspects of the
-codebase and APIs.
+### atari
-### Core window
+Frontend specific to the atari
-The [core window API](docs/core-window-interface.md) allows frontends
-to use generic core code for user interface elements beyond the
-browser render.
+### beos
-### Source object caching
+Frontend specific to the Haiku OS
-The [source object caching](docs/source-object-backing-store.md)
-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.
+### framebuffer
-### Javascript
+There is a basic user guide for the[framebuffer](docs/using-framebuffer.md)
-JavaScript is provided by integrating the duktape library. There are
[instructions](docs/updating-duktape.md) on how to update the library.
+### gtk
-A list of [unimplemented DOM and CSSOM methods](unimplemented.html)
-is available outlining the remaining API that have to be implemented.
+Frontend that uses the GTK+2 or GTK+3 toolkit
-Development
------------
+### monkey
-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.
+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.
-### Working with the team
+
+# 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.
@@ -63,7 +73,13 @@ 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 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
@@ -74,13 +90,13 @@ repository. These toolchains are built by the Continuous
Integration
[results of the system](http://ci.netsurf-browser.org/builds/toolchains/)
are published as a convenience.
-### Quick setup
+## 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
+## Manual setup
The Manual environment setup and compilation method is covered by the
details in the [netsurf libraries](docs/netsurf-libraries.md) document
@@ -96,3 +112,54 @@ specific frontend.
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
+
+The NetSurf code makes use of Doxygen for code documentation.
+
+There are several documents which detail specific aspects of the
+codebase and APIs.
+
+### Core window
+
+The [core window API](docs/core-window-interface.md) allows frontends
+to use generic core code for user interface elements beyond the
+browser render.
+
+### Source object caching
+
+The [source object caching](docs/source-object-backing-store.md)
+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 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.
+
+### Library
+
+JavaScript is provided by integrating the duktape library. There are
+[instructions](docs/updating-duktape.md) on how to update the library.
+
+### Interface binding
+
+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. The
+process of [writing bindings](docs/jsbinding.md) is ongoing.
--
NetSurf Browser
_______________________________________________
netsurf-commits mailing list
[email protected]
http://listmaster.pepperfish.net/cgi-bin/mailman/listinfo/netsurf-commits-netsurf-browser.org
