From 148639b70c3831693c08bb00d5ef372d59088840 Mon Sep 17 00:00:00 2001 From: Vincent Sanders Date: Thu, 2 May 2019 11:13:09 +0100 Subject: [PATCH] add initial javascript binding documentation --- docs/jsbinding.md | 59 +++++++++++++++ docs/mainpage.md | 189 +++++++++++++++++++++++++++++++--------------- 2 files changed, 187 insertions(+), 61 deletions(-) create mode 100644 docs/jsbinding.md 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,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 -[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. + +### 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) -is available outlining the remaining API that have to be implemented. +### Library -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 -environment. Typically this means a Linux based system although Free -BSD, Open BSD, Mac OS X and Haiku all known to work. +### Interface binding -### 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 -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/) - -### 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. +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.