summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorVincent Sanders <vince@kyllikki.org>2019-12-31 19:30:26 +0000
committerVincent Sanders <vince@kyllikki.org>2019-12-31 19:30:26 +0000
commitbcc64cf263cd730ba8c13d31870528c160403e88 (patch)
treea6ec38a2d956fa76f20cd780eb3961f3667ac480
parentfb4f1d28ba4d2b0935ac56a3d37ea9fa52c5de51 (diff)
downloadnetsurf-bcc64cf263cd730ba8c13d31870528c160403e88.tar.gz
netsurf-bcc64cf263cd730ba8c13d31870528c160403e88.tar.bz2
split up mainpage docs and add section on testing
-rw-r--r--docs/development.md153
-rw-r--r--docs/mainpage.md163
-rw-r--r--docs/project.md17
-rw-r--r--docs/unit-testing.md (renamed from docs/unit-testing)0
-rw-r--r--docs/user-interface.md59
5 files changed, 232 insertions, 160 deletions
diff --git a/docs/development.md b/docs/development.md
new file mode 100644
index 000000000..773cf6b8f
--- /dev/null
+++ b/docs/development.md
@@ -0,0 +1,153 @@
+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.
+
+# Unit testing
+
+NetSurf [unit tests](docs/unit-testing.md) provide basic test coverage
+of many core parts of the browser code such as url parsing and utility
+functions.
+
+# Integration testing
+
+The monkey frontend is used to perform complex tests involving
+operating the browser as a user might (opening windows, navigating to
+websites and rendering the contents etc.)
+
+A test is written as a set of operations in a yaml file. A test can be
+run using the monkey_driver.py python script
+
+ $ ./test/monkey_driver.py -m ./nsmonkey -t test/monkey-tests/start-stop.yaml
+
+There are very few tests within the netsurf repository. The large
+majority of integration tests are held within the
+[netsurf-test](http://source.netsurf-browser.org/netsurf-test.git/)
+repository.
+
+To allow more effective use of these tests additional infrastructure
+has been constructed to allow groupings of tests to be run. This is
+used extensively by the CI system to perform integration testing on
+every commit.
+
+Each test is a member of a group and the tests within each group are
+run together. Groups are listed within division index files. To run
+the integration tests the monkey-see-monkey-do python script is
+used. It downloads the test plan for a division from the netsurf test
+infrastructrure and executes it.
+
+ $ ./test/monkey-see-monkey-do
+ Fetching tests...
+ Parsing tests...
+ Running tests...
+ Start group: initial
+ [ Basic checks that the browser can start and stop ]
+ => Run test: start-stop-no-js.yaml
+ => Run test: basic-navigation.yaml
+ => Run test: start-stop.yaml
+ Start group: no-networking
+ [ Tests that require no networking ]
+ => Run test: resource-scheme.yaml
+ Start group: ecmascript
+ [ ECMAScript tests ]
+ PASS
+
+
+# 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 retrieve 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.
diff --git a/docs/mainpage.md b/docs/mainpage.md
index 0700137e6..de5de7331 100644
--- a/docs/mainpage.md
+++ b/docs/mainpage.md
@@ -3,163 +3,6 @@ NetSurf web browser
![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1037/badge)[*](https://bestpractices.coreinfrastructure.org/projects/1037)
-# 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.
-
-Because of this the user interface has different features in
-each frontend allowing the browser to be a native application.
-
-## Frontends
-
-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
-
-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.
+# [Project](docs/project.md)
+# [User Interface](docs/user-interface.md)
+# [Development](docs/development.md)
diff --git a/docs/project.md b/docs/project.md
new file mode 100644
index 000000000..7fa76d9ae
--- /dev/null
+++ b/docs/project.md
@@ -0,0 +1,17 @@
+NetSurf Project
+===============
+
+The NetSurf project is developing a document browser for the World
+Wide Web. It was started in 2002 on the RISC OS platform and has
+support for numerous operating systems and graphical toolkits.
+
+NetSurf is very modular and built from many component libraries which
+provide functionality from GIF image format decoding (libnsgif) to
+HTML document object model handling (libdom).
+
+NetSurf browser is open source and is licensed under the GPLv2 (with
+OpenSSL exception). Many of the supporting libraries are under a MIT
+licence.
+
+The [main website](http://www.netsurf-browser.org/) contains links to
+other resources and additional information.
diff --git a/docs/unit-testing b/docs/unit-testing.md
index 49d82ed81..49d82ed81 100644
--- a/docs/unit-testing
+++ b/docs/unit-testing.md
diff --git a/docs/user-interface.md b/docs/user-interface.md
new file mode 100644
index 000000000..5d7673f71
--- /dev/null
+++ b/docs/user-interface.md
@@ -0,0 +1,59 @@
+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.
+
+Because of this the user interface has different features in
+each frontend allowing the browser to be a native application.
+
+# Frontends
+
+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.
+
+