From 148639b70c3831693c08bb00d5ef372d59088840 Mon Sep 17 00:00:00 2001 From: Vincent Sanders Date: Thu, 2 May 2019 11:13:09 +0100 Subject: add initial javascript binding documentation --- docs/jsbinding.md | 59 +++++++++++++++++++++++ docs/mainpage.md | 141 ++++++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 163 insertions(+), 37 deletions(-) create mode 100644 docs/jsbinding.md (limited to 'docs') diff --git a/docs/jsbinding.md b/docs/jsbinding.md new file mode 100644 index 000000000..c258a678d --- /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 fa72d1464..0700137e6 100644 --- a/docs/mainpage.md +++ b/docs/mainpage.md @@ -3,57 +3,67 @@ 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 -[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. -- cgit v1.2.3