Gitweb links: ...log http://git.netsurf-browser.org/netsurf.git/shortlog/bcc64cf263cd730ba8c13... ...commit http://git.netsurf-browser.org/netsurf.git/commit/bcc64cf263cd730ba8c13d3... ...tree http://git.netsurf-browser.org/netsurf.git/tree/bcc64cf263cd730ba8c13d318... The branch, master has been updated via bcc64cf263cd730ba8c13d31870528c160403e88 (commit) from fb4f1d28ba4d2b0935ac56a3d37ea9fa52c5de51 (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=bcc64cf263cd730ba8c... commit bcc64cf263cd730ba8c13d31870528c160403e88 Author: Vincent Sanders <vince(a)kyllikki.org&gt; Commit: Vincent Sanders <vince(a)kyllikki.org&gt; split up mainpage docs and add section on testing diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..773cf6b --- /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 0700137..de5de73 100644 --- a/docs/mainpage.md +++ b/docs/mainpage.md @@ -3,163 +3,6 @@ NetSurf web browser  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 0000000..7fa76d9 --- /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 deleted file mode 100644 index 49d82ed..0000000 --- a/docs/unit-testing +++ /dev/null @@ -1,166 +0,0 @@ -NetSurf Unit Testing -==================== - -Overview --------- - -NetSurf has unit tests integrated in the test directory. These tests -use the check unit test framework for C [1]. - -The tests are in a logical hierachy of "suite", "case" and individual -"test". Historicaly we have split suites of tests into separate test -programs although the framework does not madate this and some test -programs contain more than one suite. - - -Execution ---------- - -The test programs are executed by using the standard "test" target -from the top level make invocation. The "coverage" target additionally -generates code coverage reports allowing visibility on how much of a -code module is being exercised. - -The check library must be installed to run the tests and the CI system -automatically executes all enabled tests and generates coverage -reports for each commit. - -Adding tests ------------- - -The test/Makefile defines each indiviadual test program that should be -built and executed in the TESTS variable. - -The test program source files are defined in a xxx_SRCS variable and -the make rules will then ensure the target program is built and -executed. - -Each individual test program requires a main function which creates -one (or more) suites. The suites are added to a test runner and then -executed and the results reported. - -int main(int argc, char **argv) -{ - int number_failed; - SRunner *sr; - - sr = srunner_create(foo_suite_create()); - //srunner_add_suite(sr, bar_suite_create()); - - srunner_run_all(sr, CK_ENV); - - number_failed = srunner_ntests_failed(sr); - srunner_free(sr); - - return (number_failed == 0) ? EXIT_SUCCESS : EXIT_FAILURE; -} - -Suite creation is done with a sub function to logically split suite -code into sub modules. Each suite has test cases added to it. - -Suite *foo_suite_create(void) -{ - Suite *s; - s = suite_create("foo"); - - suite_add_tcase(s, baz_case_create()); - suite_add_tcase(s, qux_case_create()); - - return s; -} - -Test cases include the actual tests to be performed within each case. - -TCase *baz_case_create(void) -{ - TCase *tc; - tc = tcase_create("Baz"); - - tcase_add_test(tc, xxyz_test); - tcase_add_test(tc, zzyx_test); - - return tc; -} - -A test case may optionally have a fixture which is code that is -executed before and after each test case. Unchecked fixtures are -executed once before the test process forks for each test whereas -checked fixtures are executed for each and every test. - -static void fixture_setup(void) -{ -} - -static void fixture_teardown(void) -{ -} - -TCase *qux_case_create(void) -{ - TCase *tc; - - /* Matching entry tests */ - tc = tcase_create("Match"); - - tcase_add_checked_fixture(tc, - fixture_setup, - fixture_teardown); - - tcase_add_test(tc, zzz_test); - - return tc; -} - -Additionally test cases can contain tests executed in a loop. The test -recives a single integer as a parameter named _i which iterates -between values specified in the case setup. - -TCase *baz_case_create(void) -{ - TCase *tc; - tc = tcase_create("Baz"); - - tcase_add_loop_test(tc, looping_test, 0, 5); - - return tc; -} - -It is also possible to create tests which will generate a signal. The -most commonly used of these is to check asserts in API calls. - -TCase *baz_case_create(void) -{ - TCase *tc; - tc = tcase_create("Baz"); - - tcase_add_test_raise_signal(tc, assert_test, 6); - - return tc; -} - - -Actual test code is self contained in a function which uses the -ck_assert macros to test results. The check framework requires each -test to use the START_TEST and END_TEST macros when definig them. - -/** - * url access leaf test - */ -START_TEST(nsurl_access_leaf_test) -{ - nserror err; - nsurl *res_url; - const struct test_triplets *tst = &access_tests[_i]; - - /* not testing create, this should always succeed */ - err = nsurl_create(tst->test1, &res_url); - ck_assert(err == NSERROR_OK); - - ck_assert_str_eq(nsurl_access_leaf(res_url), tst->res); - - nsurl_unref(res_url); -} -END_TEST - - -[1] https://libcheck.github.io/check/ diff --git a/docs/unit-testing.md b/docs/unit-testing.md new file mode 100644 index 0000000..49d82ed --- /dev/null +++ b/docs/unit-testing.md @@ -0,0 +1,166 @@ +NetSurf Unit Testing +==================== + +Overview +-------- + +NetSurf has unit tests integrated in the test directory. These tests +use the check unit test framework for C [1]. + +The tests are in a logical hierachy of "suite", "case" and individual +"test". Historicaly we have split suites of tests into separate test +programs although the framework does not madate this and some test +programs contain more than one suite. + + +Execution +--------- + +The test programs are executed by using the standard "test" target +from the top level make invocation. The "coverage" target additionally +generates code coverage reports allowing visibility on how much of a +code module is being exercised. + +The check library must be installed to run the tests and the CI system +automatically executes all enabled tests and generates coverage +reports for each commit. + +Adding tests +------------ + +The test/Makefile defines each indiviadual test program that should be +built and executed in the TESTS variable. + +The test program source files are defined in a xxx_SRCS variable and +the make rules will then ensure the target program is built and +executed. + +Each individual test program requires a main function which creates +one (or more) suites. The suites are added to a test runner and then +executed and the results reported. + +int main(int argc, char **argv) +{ + int number_failed; + SRunner *sr; + + sr = srunner_create(foo_suite_create()); + //srunner_add_suite(sr, bar_suite_create()); + + srunner_run_all(sr, CK_ENV); + + number_failed = srunner_ntests_failed(sr); + srunner_free(sr); + + return (number_failed == 0) ? EXIT_SUCCESS : EXIT_FAILURE; +} + +Suite creation is done with a sub function to logically split suite +code into sub modules. Each suite has test cases added to it. + +Suite *foo_suite_create(void) +{ + Suite *s; + s = suite_create("foo"); + + suite_add_tcase(s, baz_case_create()); + suite_add_tcase(s, qux_case_create()); + + return s; +} + +Test cases include the actual tests to be performed within each case. + +TCase *baz_case_create(void) +{ + TCase *tc; + tc = tcase_create("Baz"); + + tcase_add_test(tc, xxyz_test); + tcase_add_test(tc, zzyx_test); + + return tc; +} + +A test case may optionally have a fixture which is code that is +executed before and after each test case. Unchecked fixtures are +executed once before the test process forks for each test whereas +checked fixtures are executed for each and every test. + +static void fixture_setup(void) +{ +} + +static void fixture_teardown(void) +{ +} + +TCase *qux_case_create(void) +{ + TCase *tc; + + /* Matching entry tests */ + tc = tcase_create("Match"); + + tcase_add_checked_fixture(tc, + fixture_setup, + fixture_teardown); + + tcase_add_test(tc, zzz_test); + + return tc; +} + +Additionally test cases can contain tests executed in a loop. The test +recives a single integer as a parameter named _i which iterates +between values specified in the case setup. + +TCase *baz_case_create(void) +{ + TCase *tc; + tc = tcase_create("Baz"); + + tcase_add_loop_test(tc, looping_test, 0, 5); + + return tc; +} + +It is also possible to create tests which will generate a signal. The +most commonly used of these is to check asserts in API calls. + +TCase *baz_case_create(void) +{ + TCase *tc; + tc = tcase_create("Baz"); + + tcase_add_test_raise_signal(tc, assert_test, 6); + + return tc; +} + + +Actual test code is self contained in a function which uses the +ck_assert macros to test results. The check framework requires each +test to use the START_TEST and END_TEST macros when definig them. + +/** + * url access leaf test + */ +START_TEST(nsurl_access_leaf_test) +{ + nserror err; + nsurl *res_url; + const struct test_triplets *tst = &access_tests[_i]; + + /* not testing create, this should always succeed */ + err = nsurl_create(tst->test1, &res_url); + ck_assert(err == NSERROR_OK); + + ck_assert_str_eq(nsurl_access_leaf(res_url), tst->res); + + nsurl_unref(res_url); +} +END_TEST + + +[1] https://libcheck.github.io/check/ diff --git a/docs/user-interface.md b/docs/user-interface.md new file mode 100644 index 0000000..5d7673f --- /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. + + ----------------------------------------------------------------------- Summary of changes: docs/{mainpage.md => development.md} | 136 ++++++++++++-------------- docs/mainpage.md | 163 +------------------------------- docs/project.md | 17 ++++ docs/{unit-testing => unit-testing.md} | 0 docs/user-interface.md | 59 ++++++++++++ 5 files changed, 141 insertions(+), 234 deletions(-) copy docs/{mainpage.md => development.md} (61%) create mode 100644 docs/project.md rename docs/{unit-testing => unit-testing.md} (100%) create mode 100644 docs/user-interface.md diff --git a/docs/mainpage.md b/docs/development.md similarity index 61% copy from docs/mainpage.md copy to docs/development.md index 0700137..773cf6b 100644 --- a/docs/mainpage.md +++ b/docs/development.md @@ -1,69 +1,7 @@ -NetSurf web browser -=================== +Development +=========== - 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 +# 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. @@ -73,7 +11,7 @@ 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 +# Compilation environment Compiling a development edition of NetSurf requires a POSIX style environment. Typically this means a Linux based system although Free @@ -112,45 +50,95 @@ specific frontend. These documents are sometimes not completely up to date and the env.sh script should be considered canonical. -## Logging +# Logging The [logging](docs/logging.md) interface controls debug and error messages not output through the GUI. -## Documented API +# 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 +## 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 +## 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 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 to retrieve and manage the source code to be executed. - Browser support for the dispatch of events from user interface. -### Library +## Library JavaScript is provided by integrating the duktape library. There are [instructions](docs/updating-duktape.md) on how to update the library. -### Interface binding +## 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 diff --git a/docs/mainpage.md b/docs/mainpage.md index 0700137..de5de73 100644 --- a/docs/mainpage.md +++ b/docs/mainpage.md @@ -3,163 +3,6 @@ NetSurf web browser  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 0000000..7fa76d9 --- /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 similarity index 100% rename from docs/unit-testing rename to docs/unit-testing.md diff --git a/docs/user-interface.md b/docs/user-interface.md new file mode 100644 index 0000000..5d7673f --- /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. + + -- NetSurf Browser