From e7366bf41f68cfe07e9ea03fc4a398baecbae651 Mon Sep 17 00:00:00 2001 From: Daniel Silverstone Date: Sat, 4 Feb 2017 09:41:13 +0000 Subject: Initial conversion from MediaWiki, 20170204 --- documentation/buildingforamigaos.mdwn | 57 +++++ documentation/buildingforriscosquickstart.mdwn | 85 ++++++++ documentation/contents.mdwn | 148 +++++++++++++ documentation/directory_structure.mdwn | 45 ++++ documentation/errors.mdwn | 36 ++++ documentation/frames.mdwn | 64 ++++++ documentation/front_end_functions.mdwn | 81 +++++++ documentation/gettingcoding.mdwn | 155 ++++++++++++++ documentation/gitcheatsheet.mdwn | 278 +++++++++++++++++++++++++ documentation/gtk_interface.mdwn | 36 ++++ documentation/layout.mdwn | 70 +++++++ documentation/memory.mdwn | 26 +++ documentation/modular_coding_style.mdwn | 39 ++++ documentation/overview.mdwn | 9 + documentation/printing.mdwn | 65 ++++++ documentation/references.mdwn | 37 ++++ documentation/treeview.mdwn | 88 ++++++++ 17 files changed, 1319 insertions(+) create mode 100644 documentation/buildingforamigaos.mdwn create mode 100644 documentation/buildingforriscosquickstart.mdwn create mode 100644 documentation/contents.mdwn create mode 100644 documentation/directory_structure.mdwn create mode 100644 documentation/errors.mdwn create mode 100644 documentation/frames.mdwn create mode 100644 documentation/front_end_functions.mdwn create mode 100644 documentation/gettingcoding.mdwn create mode 100644 documentation/gitcheatsheet.mdwn create mode 100644 documentation/gtk_interface.mdwn create mode 100644 documentation/layout.mdwn create mode 100644 documentation/memory.mdwn create mode 100644 documentation/modular_coding_style.mdwn create mode 100644 documentation/overview.mdwn create mode 100644 documentation/printing.mdwn create mode 100644 documentation/references.mdwn create mode 100644 documentation/treeview.mdwn (limited to 'documentation') diff --git a/documentation/buildingforamigaos.mdwn b/documentation/buildingforamigaos.mdwn new file mode 100644 index 0000000..23fcb26 --- /dev/null +++ b/documentation/buildingforamigaos.mdwn @@ -0,0 +1,57 @@ +[[!meta title="Documentation/BuildingForAmigaOS"]] +[[!meta author="Chris"]] +[[!meta date="2016-06-27T19:13:10Z"]] + + +[[!toc]] + +Building NetSurf for AmigaOS 3.5+ (m68k-unknown-amigaos) +======================================================== + +Rough notes on how to build NetSurf for AmigaOS 3.5+. There may be an +easier way, but this works for me! + +Building for AmigaOS 4.x (ppc-amigaos) is similar. + +Toolchain +--------- + +Toolchain is built using something like this: + +`git clone `[`git://git.netsurf-browser.org/toolchains.git`](git://git.netsurf-browser.org/toolchains.git) +`cd ./toolchains/m68k-unknown-amigaos` +`sudo make` +`cd ../sdk` +`sudo GCCSDK_INSTALL_CROSSBIN=/opt/netsurf/m68k-unknown-amigaos/cross/bin GCCSDK_INSTALL_ENV=/opt/netsurf/m68k-unknown-amigaos/env make` + +Libraries +--------- + +Make/install buildsystem first! + +Clone and build the libraries with: + +`make HOST=m68k-unknown-amigaos` +`sudo make HOST=m68k-unknown-amigaos install` + +NetSurf +------- + +Build NetSurf with + +`make TARGET=amigaos3` + +Building under Cygwin +===================== + +Cygwin is a bit troublesome, as the toolchain setup is designed for +Debian 64-bit. Cygwin apparently works but there are two changes +required (I know nothing about these changes beyond what's here): + +- c-parse.in: I must replace two occurrences of YYLEX by yylex() +- collect2.c: I must add 0666 as parameter of the open for + redir\_handle. + +There is a script to build NetSurf for AmigaOS3 under Cygwin here: + + diff --git a/documentation/buildingforriscosquickstart.mdwn b/documentation/buildingforriscosquickstart.mdwn new file mode 100644 index 0000000..5a4d53a --- /dev/null +++ b/documentation/buildingforriscosquickstart.mdwn @@ -0,0 +1,85 @@ +[[!meta title="Documentation/BuildingForRISCOSQuickStart"]] +[[!meta author="Sprow"]] +[[!meta date="2015-08-11T21:40:32Z"]] + + +[[!toc]] + +Note: +Commands proceeded +by \# should be done as root +Commands proceeded +by \$ should be done as your normal user +Depending on how your system is configured you may need to log in as +root, or you may be able to use sudo. + +Building for the first time +--------------------------- + +### Install Debian or Ubuntu in a Virtual Machine, such as Virtual Box or kvm. + +Follow the rest of these instructions inside it. + +An example [guide for installing Debian in virtualbox on +windows](http://www.brianlinkletter.com/installing-debian-linux-in-a-virtualbox-virtual-machine/) +is linked here, however this is for Debian 6 but if followed current +Debian (version 8) should be installed. + +### Get a copy of env.sh, which manages a build environment for you, and have it install the dependencies. + +`$ wget `[`http://git.netsurf-browser.org/netsurf.git/plain/Docs/env.sh`](http://git.netsurf-browser.org/netsurf.git/plain/Docs/env.sh) +`# source env.sh` +`# ns-package-install` + +### Download and install the latest arm-unknown-riscos toolchain from + +Note : +The pre-compiled toolchains are for x86\_64 (64 bit x86 processors) and +therefore require the Virtual Machine be installed 64Bit + +`$ wget `[`http://ci.netsurf-browser.org/builds/toolchains/arm-unknown-riscos-2015-03-19_14-33-21.tar.xz`](http://ci.netsurf-browser.org/builds/toolchains/arm-unknown-riscos-2015-03-19_14-33-21.tar.xz) +`# tar xvf arm-unknown-riscos-2015-01-15_13-14-02.tar.xz -C /` + +### Clone all the NetSurf repositories. This creates a workspace for you to work in, /home/yourname/dev-netsurf/workspace + +`$ TARGET_ABI=arm-unknown-riscos source env.sh` +`$ ns-clone` + +### Build and install the libraries + +`$ ns-pull-install` + +### Switch to your newly created NetSurf workspace + +`$ rm env.sh` +`$ cd ~/dev-netsurf/workspace` +`$ TARGET_ABI=arm-unknown-riscos source env.sh` + +### Build NetSurf + +`$ cd netsurf` +`$ make TARGET=riscos` + +### Zip up the build for transfer to your RISC OS machine + +`$ make TARGET=riscos package` + +You can alternatively use Sunfish to access your VM via NFS and run your +build directly, but that is outside the scope of this document. + +To confirm you're running what you just build, you can visit + in NetSurf to view information about the build. + +Updating and building again +--------------------------- + +Next time you come to build NetSurf, remember to execute this before +working with the workspace: + +`$ TARGET_ABI=arm-unknown-riscos source env.sh` + +You can re-pull and re-install the libraries (to get the latest +versions) by simply reexecuting this: + +` $ ns-pull-install` + diff --git a/documentation/contents.mdwn b/documentation/contents.mdwn new file mode 100644 index 0000000..dea18da --- /dev/null +++ b/documentation/contents.mdwn @@ -0,0 +1,148 @@ +[[!meta title="Documentation/Contents"]] +[[!meta author="James Bursa"]] +[[!meta date="2010-03-01T02:56:11Z"]] + + +[[!toc]] The modules in the content +directory provide the infrastructure for fetching data, managing it in +memory, and converting it for display. + +Contents +-------- + +The data related to each URL used by NetSurf is stored in a 'struct +content' (known as a "content"). A content contains + +- a 'content type' which corresponds to the MIME type of the URL (for + example CONTENT\_HTML, CONTENT\_JPEG, or CONTENT\_OTHER) +- a status (for example LOADING, DONE, or ERROR) +- type independent data such as the URL and raw source bytes +- a union of structs for type dependent data (for example 'struct + content\_html\_data') + +Contents are stored in a global linked list 'content\_list', also known +as the "memory cache". + +The content\_\* functions provide a general interface for handling these +structures. They use a table of handlers to call type-specific code +('handler\_map'). For example, content\_redraw() may call html\_redraw() +or nsjpeg\_redraw() depending on the type of content. + +Each content has a list of users. A user is a callback function which is +sent a message (called) when something interesting happens to the +content (for example, it's ready to be displayed). Examples of users are +browser windows (of HTML contents) and HTML contents (of JPEG contents). + +Some content types may not be shared among users: an HTML content is +dependent on the width of the window, so sharing by two or more windows +wouldn't work. Thus there may be more than one content with the same URL +in memory. + +Content status +-------------- + +The status of a content follows a fixed order. Certain content functions +change the status, and each change of status results in a message to all +users of the content: + +- content\_create() creates a content in status TYPE\_UNKNOWN +- content\_set\_type() takes a content TYPE\_UNKNOWN to one of + - LOADING (sends optional MSG\_NEWPTR followed by MSG\_LOADING) + - ERROR (sends MSG\_ERROR) +- content\_process\_data() takes LOADING to one of + - LOADING (no message) + - ERROR (MSG\_ERROR) +- content\_convert() takes LOADING to one of + - READY (MSG\_READY) + - DONE (MSG\_READY, MSG\_DONE) + - ERROR (MSG\_ERROR) +- a content can move from READY to DONE by itself, for example HTML + contents become DONE when all images are fetched and the document is + reformatted (MSG\_DONE) +- content\_stop() aborts loading of a READY content and results in + status DONE (MSG\_DONE) + +Type functions +-------------- + +The type-specific functions for a content are as follows (where 'type' +is replaced by something): + +- type\_create():: called to initialise type-specific fields in the + content structure. Optional. +- type\_process\_data():: called when some data arrives. Optional. +- type\_convert():: called when data has finished arriving. The + content needs to be converted for display. Must set the status to + one of CONTENT\_STATUS\_READY or CONTENT\_STATUS\_DONE if no error + occurs. Optional, but probably required for non-trivial types. +- type\_reformat():: called when, for example, the window has been + resized, and the content needs reformatting for the new size. + Optional. +- type\_destroy():: called when the content is being destroyed. Free + all resources. Optional. +- type\_redraw():: called to plot the content to screen. +- type\_redraw\_tiled():: called to plot the content tiled across the + screen. Optional. +- type\_stop(): called when the user interrupts in status + CONTENT\_STATUS\_READY. Must stop any processing and set the status + to CONTENT\_STATUS\_DONE. Required iff the status can be + CONTENT\_STATUS\_READY. +- type\_open(): called when a window containing the content is opened. + Probably only makes sense if no\_share is set for the content type + in handler\_map. Optional. +- type\_close():: called when the window containing the content is + closed. Optional. + +If an error occurs in type\_create(), type\_process\_data(), +type\_convert(), CONTENT\_MSG\_ERROR must be broadcast and false +returned. The \_destroy function will be called soon after. + +Memory allocation +----------------- + +Each content structure is allocated using talloc, and all data related +to a content should be allocated as a child block of the content +structure using talloc. This will ensure that all memory used by a +content is freed. + +Contents must keep an estimate of non-talloc allocations in the +total\_size attribute. This is used to control the size of the memory +cache. + +Creating and fetching contents +------------------------------ + +A high-level interface to starting the process of fetching and +converting an URL is provided by the fetchcache functions, which check +the memory cache for a url and fetch, convert, and cache it if not +present. + +The fetch module provides a low-level URL fetching interface. + +Adding support for a new content type +------------------------------------- + +Addition of support for new content types is fairly simple and the +process is as follows: + +- Implement, or at least stub out, the new content type handler. See + the 'Type Functions' section above for details of the type handler + API. +- Add a type value to the 'content\_type' enumeration + (content\_type.h) +- Add an entry for the new type's private data in the 'data' union + within 'struct content' (content.h) +- Add appropriate mappings in the 'mime\_map' table from MIME type + strings to the 'content\_type' value created. (content.c) +- Add a textual name for the new content type to + 'content\_type\_name'. This array is indexed by 'content\_type'. + (content.c) +- Add an entry for the new content type's handler in the + 'handler\_map' array. This array is indexed by 'content\_type'. + (content.c) + +For examples of content type handlers, consult the image/ directory. The +JPEG handler is fairly self-explanatory. + +[[!inline raw=yes pages="Documentation"]] + diff --git a/documentation/directory_structure.mdwn b/documentation/directory_structure.mdwn new file mode 100644 index 0000000..e9d00a7 --- /dev/null +++ b/documentation/directory_structure.mdwn @@ -0,0 +1,45 @@ +[[!meta title="Documentation/Directory Structure"]] +[[!meta author="Tlsa"]] +[[!meta date="2012-10-23T10:53:54Z"]] + + +[[!toc]] NetSurf's code is broadly +split into two; core code, and front end code. All ports make use of the +core code and each port has its own front end code. + +Directory Structure +------------------- + +The source is split at top level as follows: + +### Core + +#### Content handling + +- **content** -- Generic content handling: Fetching, caching, + managing, etc +- **css** -- CSS content specific handling +- **image** -- Image content specific handling (conversion) +- **javascript** -- JavaScript content specific handling +- **render** -- HTML and Text content specific handling (processing, + layout, render) + +#### Other core components + +- **desktop** -- Non-platform specific front-end +- **utils** -- Misc reusable components + +### Front ends + +- **amiga** -- AmigaOS specific code +- **atari** -- Atari FreeMiNT code +- **beos** -- BeOS/Haiku specific code +- **cocoa** -- Mac OS X specific code +- **framebuffer** -- Framebuffer specific code +- **gtk** -- GTK specific code +- **monkey** -- Terminal based test engine specific code +- **riscos** -- RISC OS specific code +- **windows** -- Windows specific code + +[[!inline raw=yes pages="Documentation"]] + diff --git a/documentation/errors.mdwn b/documentation/errors.mdwn new file mode 100644 index 0000000..2e818ab --- /dev/null +++ b/documentation/errors.mdwn @@ -0,0 +1,36 @@ +[[!meta title="Documentation/Errors"]] +[[!meta author="James Bursa"]] +[[!meta date="2010-03-01T02:55:53Z"]] + + +[[!toc]] This section describes +error handling in the code. + +The most common serious error is memory exhaustion. If malloc(), +strdup(), etc. fails, clean up and free any partially complete +structures leaving data in a consistent state, and return a value which +indicates failure, eg. 0 for functions which return a pointer (document +the value in the function documentation). The caller should then +propagate the failure up in the same way. At some point, the error +should stop being passed up and be reported to the user using + + warn_user("NoMemory", 0); + +The other common error is one returned by a RISC OS SWI. Always use "X" +SWIs, something like this: + + os_error *error; + error = xwimp_get_pointer_info(&pointer); + if (error) { + LOG(("xwimp_get_pointer_info: 0x%x: %s\n", + error->errnum, error->errmess)); + warn_user("WimpError", error->errmess); + return false; + } + +If an error occurs during initialisation, in most cases exit immediately +using die(), since this indicates that there is already insufficient +memory, or a resource file is corrupted, etc. + +[[!inline raw=yes pages="Documentation"]] + diff --git a/documentation/frames.mdwn b/documentation/frames.mdwn new file mode 100644 index 0000000..236277f --- /dev/null +++ b/documentation/frames.mdwn @@ -0,0 +1,64 @@ +[[!meta title="Documentation/Frames"]] +[[!meta author="James Bursa"]] +[[!meta date="2010-03-01T02:56:32Z"]] + + +[[!toc]] Frames cut across many +parts of the browser. + +Representation in content +------------------------- + +During box-tree construction (box\_construct.c), frameset, frame, and +iframe elements are converted into structures in the 'struct content' +for the HTML document. + +Framesets and frames form a tree of 'struct content\_html\_frames' at +content-\>data.html.frameset. For example, the source + + + + + + + + + + + + + + +results in the tree + + 0x6099f2f4 (2 1) w0px h0px (margin w0 h0) (scrolling no) + (0 0): 0x608b730c (1 2) w100% h50% (margin w0 h0) (scrolling no) + (0 0): 0x608dae74 (0 0) w40px h100% (margin w0 h0) 'A' (scrolling auto) border 0 + (0 1): 0x608daeb0 (0 0) w200px h100% (margin w0 h0) 'B' (scrolling auto) border 0 + (1 0): 0x608b7348 (1 2) w100% h50% (margin w0 h0) (scrolling no) + (0 0): 0x608d9b4c (0 0) w3* h100% (margin w0 h0) 'C' (scrolling auto) border 0 + (0 1): 0x608d9b88 (0 0) w1* h100% (margin w0 h0) 'D' (scrolling auto) border 0 + +(output from html\_dump\_frameset()). + +Creation of browser windows +--------------------------- + +When a document containing frames is displayed in a browser window, +child windows are created for frames and iframes. This occurs when a +browser window receives a CONTENT\_MSG\_READY in +browser\_window\_callback(), which calls +browser\_window\_create\_frameset(). + +browser\_window\_create\_frameset() constructs a tree of 'struct +browser\_window' corresponding to the tree of 'struct +content\_html\_frames'. For each new browser\_window, it calls +gui\_create\_browser\_window() to create and open the actual +platform-specific window (represented by a 'struct gui\_window'). + +When this is completed it calls browser\_window\_recalculate\_frameset() +which calculates the positions of each frame in pixels and calls +gui\_window\_position\_frame() to position each one. + +[[!inline raw=yes pages="Documentation"]] + diff --git a/documentation/front_end_functions.mdwn b/documentation/front_end_functions.mdwn new file mode 100644 index 0000000..4e056f4 --- /dev/null +++ b/documentation/front_end_functions.mdwn @@ -0,0 +1,81 @@ +[[!meta title="Documentation/Front end functions"]] +[[!meta author="James Bursa"]] +[[!meta date="2011-11-26T22:20:01Z"]] + + +[[!toc]] This page documents the +functions that need to be implemented by each platform's front end. + +: *Note: in progress and incomplete* + +The prototypes for these functions are usually in gui/gui.h. The +implementations live in the platform code, for example **gui\_init()** +is implemented in each of amiga/gui.c, beos/beos\_gui.cpp, +framebuffer/gui.c, gtk/gtk\_gui.c, riscos/gui.c, and windows/gui.c. Of +course only one of those implementations is ever compiled into a binary +of NetSurf. + +Initialization and clean-up +--------------------------- + +### int main(int argc, char\*\* argv) + +This is the standard C entry point. It should do any critical very-early +initialization is required, and finish with + +`return netsurf_main(argc, argv);` + +The prototype may differ on some platforms. + +### void gui\_init(int argc, char\*\* argv) + +General initialization of platform stuff. Prepare the gui for use, but +don't yet open any windows. + +It should call: + +- hubbub\_initialise(), with the platform-specific path to the Aliases + file +- options\_read(), if saving and loading options is supported +- messages\_load(), with the platform-specific path to the Messages + file +- save\_complete\_init(), if save complete is used +- urldb\_load() and urldb\_load\_cookies() + +Should set default\_stylesheet\_url, quirks\_stylesheet\_url, and +adblock\_stylesheet\_url. + +(Called by netsurf\_init() in desktop/netsurf.c.) + +### void gui\_init2(int argc, char\*\* argv) + +Last-step of initialization. Can open window(s) by calling +browser\_window\_create() (e.g. depending on argv). + +(Called by netsurf\_init() in desktop/netsurf.c.) + +### void gui\_quit(void) + +Prepare for exit by doing whatever is needed by the platform. + +It should call: + +- urldb\_save\_cookies() and urldb\_save() +- hubbub\_finalise() + +(Called by netsurf\_exit() in desktop/netsurf.c.) + +Multitasking +------------ + +### void gui\_multitask(void) + +NetSurf's core will occasionally call this during long-running +operations. It should yield briefly to the OS if applicable, and handle +urgent gui events to keep NetSurf responsive. Then it should return +quickly. + +It **must not** call any function in the core or non-platform code. + +[[!inline raw=yes pages="Documentation"]] + diff --git a/documentation/gettingcoding.mdwn b/documentation/gettingcoding.mdwn new file mode 100644 index 0000000..d53fe33 --- /dev/null +++ b/documentation/gettingcoding.mdwn @@ -0,0 +1,155 @@ +[[!meta title="Documentation/GettingCoding"]] +[[!meta author="Tlsa"]] +[[!meta date="2014-03-15T12:02:06Z"]] + + +[[!toc]] + +Getting started with the NetSurf code base +========================================== + +NetSurf and its libraries are kept in the `git` revision control system. +This document guides though setting up an envronment to build and +develop NetSurf and the NetSurf project libraries from scratch.. + +You can see the `git` repositories at [The NetSurf +Gitweb](http://git.netsurf-browser.org/). + +There are two ways to go. You can use our +[env.sh](http://git.netsurf-browser.org/netsurf.git/plain/Docs/env.sh) +which will fetch the sources from git and build NetSurf and the +libraries with a few commands, or you can set up things manually. + +Easy way: Using NetSurf's env.sh and QUICK-START +------------------------------------------------ + +This makes it simple to git clone the sources for NetSurf and the +project libraries, build and install them. + +To use +[env.sh](http://git.netsurf-browser.org/netsurf.git/plain/Docs/env.sh), +follow the steps in our +[QUICK-START](http://git.netsurf-browser.org/netsurf.git/plain/Docs/QUICK-START) +document. + +Less easy: Manual setup +----------------------- + +If you need to do things manually, the rest of this section will take +you through the process. + +### Preparing your workspace + +NetSurf has a number of libraries which must be built in-order and +installed into your workspace. Each library depends on a core build +system which NetSurf projects use. This build system relies on the +presence of things like `pkg-config` to find libraries and also certain +environment variables in order to work correctly. Assuming you are +preparing a workspace in /home/netsurf/workspace then the following +sequence of commands will set you up. + +`# Make the workspace directory` +`mkdir -p ${HOME}/netsurf/workspace` +`# Change to it` +`cd ${HOME}/netsurf/workspace` +`# Make the temporary install space` +`mkdir inst` +`# Prepare environment script` +`cat > env.sh <<'EOF'` +`export PKG_CONFIG_PATH=${HOME}/netsurf/workspace/inst/lib/pkgconfig::` +`export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${HOME}/netsurf/workspace/inst/lib` +`export PREFIX=${HOME}/netsurf/workspace/inst` +`EOF` + +Whenever you wish to start development in a new shell, run the +following. + +`# Change to workspace` +`cd ${HOME}/netsurf/workspace` +`# Prepare shell environment` +`source env.sh` + +From here down, any commands in this document assume you have prepared +your shell environment and you are starting from the workspace +directory. + +### Checking the codebase out for the first time + +Now you can clone all of the core libraries and build them in turn. Some +may have additional dependencies outside of the NetSurf project's +codebase, and you should check the documentation in each library for +information about that. + +`# Acquire all the core libraries and NetSurf codebase` +`for REPO in buildsystem libwapcaplet libparserutils libcss libdom libhubbub libnsgif libnsbmp libsvgtiny librosprite libnsfb netsurf; do \` +`   git clone `[`git://git.netsurf-browser.org/`](git://git.netsurf-browser.org/)`${REPO}.git ; \` +`done` + +### Compiling the codebase + +Assuming you have done the above and checked out all of the code, the +following is the process of getting it all built. The assumption is +being made that you're on a GTK development system on Linux. Different +environments may require slightly different instructions. Refer to the +documentation in the codebase for more help. + +If you wish to run the tests for each of the libraries, then refer to +that library's documentation. Some of the libraries require additional +test harnesses to be installed. + +`# Install the shared build system` +`make -C buildsystem install` +`# Build the core libraries in turn (order matters due to dependencies)` +`make -C libwapcaplet install` +`make -C libparserutils install` +`make -C libcss install` +`make -C libhubbub install` +`make -C libdom install` +`# Build the core image decoders` +`make -C libnsbmp install` +`make -C libnsgif install` +`# Build the optional decoders` +`make -C librosprite install` +`make -C libsvgtiny install` +`# Build NetSurf` +`cd netsurf` +`make` +`# Try running NetSurf (GTK) from the build tree` +`./test-nsgtk` + +Configuring `git` for pushing changes +===================================== + +If you have push rights to the NetSurf repository, you need to ensure +you're pushing to the `ssh://` url rather than the `git://` one. + +The easiest way to do this is to run `git config --global -e` and ensure +that a section is inserted like the one below. + +`[url "`[`ssh://nsgit@git.netsurf-browser.org/`](ssh://nsgit@git.netsurf-browser.org/)`"]` +`    pushInsteadOf = `[`git://git.netsurf-browser.org/`](git://git.netsurf-browser.org/) + +This will cause `git` to automatically convert any `git://` url to the +NetSurf codebase to the corresponding `ssh://` one when pushing. Pulling +changes still happens over the more efficient and lighter weight +`git://` protocol. You can verify that this change is working correctly +by running `git remote -v` in any of your NetSurf code trees. It should +show something like the following. + +`origin `[`git://git.netsurf-browser.org/netsurf.git`](git://git.netsurf-browser.org/netsurf.git)` (fetch)` +`origin `[`ssh://nsgit@netsurf-browser.org/netsurf.git`](ssh://nsgit@netsurf-browser.org/netsurf.git)` (push)` + +Rules on branches +----------------- + +The `git` server (a [Gitano](http://www.gitano.org.uk/) instance on +[Pepperfish](http://www.pepperfish.net/)) has varying rules regarding +where you are allowed to push in terms of branch names. Usually core +developers may push to the `master` ref (equivalent of the trunk in +subversion) and anyone else must push to a ref named after their +username. + +All developers are encouraged to work in branches anyway, merging to +`master` only when changes are ready for others to use. See the +[[Git Cheat Sheet|documentation/gitcheatsheet]] for more help. + diff --git a/documentation/gitcheatsheet.mdwn b/documentation/gitcheatsheet.mdwn new file mode 100644 index 0000000..4a0e462 --- /dev/null +++ b/documentation/gitcheatsheet.mdwn @@ -0,0 +1,278 @@ +[[!meta title="Documentation/GitCheatSheet"]] +[[!meta author="Chris"]] +[[!meta date="2016-04-28T18:32:38Z"]] + + +[[!toc]] + +Git cheat sheet +=============== + +This document is here to help NetSurf developers who are more used to +non-distributed revision control systems, or to DVCSs which are not +`git`. It also contains a few helpful hints for people used to `git` so +it's worth a skim even to those who think they know it all already. + +`Git` is one of the least obvious, least intuitive distributed revision +control systems out there. However it is also very powerful and very +fast. `Git` appears to have won the DVCS race for the most part, and as +such, NetSurf uses it. + +Identify yourself +================= + +Every commit you make with `git` contains an identity. (Actually you can +differentiate between the identity of the author of a patch and the +person committing it to the repository if you want.) As such, you must +teach `git` who you are. + +`git config --global user.name "My Name"` +`git config --global user.email whoever@domain.name` + +Note that if you don't specify `--global` the name/email address will +only be local to the `git` tree you are inside when you run the command. + +The first time you make a commit, if you have not configured your +identity, `git` will give you a reminder. + +Useful bits and bobs +==================== + +It's well worth running: + +`git config --global push.default current` + +Since it tells git to only push the branch you're on. + +Repositories, Trees and Branches +================================ + +Each `git` repository is a project. As such, NetSurf has many +repositories. NetSurf's repositories reside on the NetSurf +[Gitano](http://www.gitano.org.uk/) instance. We will refer to this as +the *server* from now on. + +You acquire a copy of a repository by asking `git` to *clone* it. + +`git clone `[`git://git.netsurf-browser.org/buildsystem.git`](git://git.netsurf-browser.org/buildsystem.git) + +By default, `git` will create a directory named after the repository and +clone all the branches in that repository into it. + +When you have a local clone of a repository, we refer to that as a +*tree*. `Git` may also refer to it as a *working tree* and it is where +changes are made and commits are done. + +Each repository may have many branches. `Git` keeps them tucked away, +showing you only one at a time in your tree. You can list your local +branches with: + +`git branch` + +By default, a fresh clone will only contain one branch called `master` +which is the equivalent of Subversion's *trunk*. + +You can switch between local branches with: + +`git checkout branchname` + +Different bits of `git` documentation may also refer to *refs*. In `git` +branches, tags, etc are all represented by their commits. To give those +commits useful-to-a-human names, `git` has the concept of a *ref* which +is simply a name given to a commit. Refs in the namespace `refs/heads/` +are referred to as branches. + +Revisions and commits +===================== + +There are no traditional revision numbers in `git`. Instead each commit +is given a unique identifier. It is a long (40 character) hexadecimal +string but it is also commonly shortened to its first 7 characters. For +example, at the time of writing, the tip of the `master` branch in the +`NetSurf` repository was `00f76b5`. + +Remotes +======= + +Because your `git` tree is also a full local copy of the repository, +`git` keeps track of the server's copy of the repository in a data +structure called a *remote*. The default name for a remote is `origin` +and you will see that crop up in various places as we continue. + +You can update your local view of the server with the command: + +`git remote update` + +Or, assuming you're on `master` you may find *pull* to be of more use: + +`git pull` + +If you *pull* then `git` first updates its view of the remote, and then +attempts to merge in changes from the remote into your local branch. If +you've not made changes locally then this will be done by +*fast-forwarding* you to the server's revision. + +You can see the branches available on any remotes you have registered in +your tree with: + +`git branch -r` + +Making a branch to work on +========================== + +We recommend that everyone work on branches, merging to `master` only +when work is ready for others. In the past we've all worked on `trunk` +because it was such a pain in Subversion to merge work. However one of +`git`'s strengths is its merge functionality so this habit should end. + +Before making a new branch, it's customary to ensure that you've got +everything up-to-date from the server: + +`git remote update` + +Then you can create a new branch, from the server's idea of `master` +with: + +`git checkout -b username/branch origin/master` + +You should put your own username in for *username* (note it should be +the username which the server has for you. You can find that out by +running `ssh nsgit@netsurf-browser.org whoami`). + +For the branch name, give it something reasonably descriptive but not +too long. For example `fandango-experiment` is good, where +`experiment-with-new-layout-engine-idea` is probably too long. + +The `origin/master` is where you tell `git` that you want to track the +`master` branch of the `origin` remote. This not only gives you a +starting point for your branch, but also informs `git` where to get +changes from if you run `git pull` while you have that branch checked +out. + +To then inform the server of your new branch, run: + +`git push origin username/branch` + +When you wish to inform the server of new commits on your branch, you +can subsequently just run: + +`git push` + +Deleting a branch +================= + +To delete a branch from the server when it is no longer required: + +`git push origin :username/branch` + +Making changes and committing them +================================== + +You can make any amount of local changes before you commit, although we +recommend each commit be a reasonable self-contained "patch". Obviously +it is better to commit early and often; and `git` does contain a variety +of tools for helping you to turn a long line of small commits into a +neater set of commits ready for merging. We're not too bothered about +that with NetSurf for now; but if you want further reading on the +subject, go and search the web for *git rebase*. + +You can ask `git` about your working tree any time you like with: + +`git status` + +You can see changes in your working tree which you've not told `git` +about yet, with: + +`git diff` + +When you have edited the code and you are ready to commit, you should +run: + +`git add filename another/filename etc/etc/etc` + +You can run `git add` as many times as you like. Each time you do, +you're saying to `git` *I want you to remember this file just like it is +right now*. + +If you need to remove files then run: + +`git rm filename` + +You can see the diff which `git` has prepared for committing, with + +`git diff --cached` + +Once you're happy you've told git about any edited, new or deleted +files, you can run: + +`git commit` + +This will pop up an editor, telling you what will be committed and +encouraging you to write a change comment. The first line of the change +comment should be short (60 or so chars or less) and pithy. It will be +shown on the IRC channel as the commit message and also forms what `git` +refers to as the *short log message*. The rest of the message (ideally +separated from the first line by a blank) should explain what you did +and why. Normal good commit message etiquette applies here. + +You can see the log with: + +`git log` + +Don't forget to `git push` your commits to the server if you want anyone +else to see them. + +Merging branches +================ + +Since we're encouraging work on branches, we also need to know how to +merge those into the `master` branch. In order to keep things neat and +tidy, we ask that branches be merged in the following way: + +`# Switch to the master branch` +`git checkout master` +`# Ensure we're up-to-date relative to the server` +`git pull` +`# Merge the local branch in` +`git merge --no-commit --no-ff username/branch` +`# Review the changes here (git diff --cached)` +`# Commit the changes` +`git commit` + +Note that the commit will default to a message about the merge. That is +sufficient, although obviously any more useful message would be +appreciated. If the branch is not a local one, but one retrieved from +the server, then simply insert `origin/` in front of the branch name (so +it becomes `origin/username/branch`) to tell `git` the location of the +branch. + +Once the commit is done on `master` you can `git push` it to the server. + +The options to `git merge` are important. The `--no-commit` causes `git` +to leave the tree at the point that it has done the merge but hasn't +committed it to the branch. By default, `git` will commit merges which +had no conflicts. Since our code base is complex this is not always +sufficient, hence the review step above. The `--no-ff` causes `git` to +prepare a merge commit. Without it, if the `master` has not moved on +from where the branch was created, `git` will instead simply shunt the +commits onto the `master` branch. While not a bad thing in and of +itself, this would mean that when you did `git push` the `CIA.vc` bot +would announce every single commit from the branch. + +Merging changes from a 3rd party's repo +======================================= + +To merge from the "foo" branch of Somebody's github clone of the NetSurf +repo we can do this: + +`git remote add somebody `[`git://github.com/Somebody/netsurf`](git://github.com/Somebody/netsurf) +`git remote update somebody` +`git merge --no-ff --no-commit somebody/foo` +`git diff --cached` + +Check that the diff shows what we want to merge. If so, commit it. + +If you don't want to keep the remote around: + +`git remote rm somebody` + diff --git a/documentation/gtk_interface.mdwn b/documentation/gtk_interface.mdwn new file mode 100644 index 0000000..f480a52 --- /dev/null +++ b/documentation/gtk_interface.mdwn @@ -0,0 +1,36 @@ +[[!meta title="Documentation/GTK Interface"]] +[[!meta author="James Bursa"]] +[[!meta date="2010-04-07T17:05:44Z"]] + + +[[!toc]] This page describes the +GTK interface, which lives in the **gtk** directory. This interface is +used on Linux, BSD, and can be used on other platforms which have a port +of GTK. + +Windows and Scaffolding +----------------------- + +A "scaffolding" is a top-level main window, which contains a toolbar, +menu bar, and one or more tabs containing web pages. Each tab +corresponds to a gui\_window (and each frame if frames are present). + +All the UI designs for the main window are in netsurf.glade. +**wndBrowser** is a scaffolding. It contains a VBox containing a +MenuBar, Toolbar, Toolbar for search (normally hidden), and Notebook. + +The **tabContents** GtkTable (in tabContentsWindow) is used for each +tab. It contains a table with two rows and two columns, which contain +(line 1) a Layout, VScrollbar, (line 2) HPaned, and Statusbar (used for +resizing only). The HPaned contains the actual status bar (as a Label), +and a HScrollbar. + +Tab creation is implemented in gui\_create\_browser\_window() in +gtk/gtk\_window.c. The scrollbars are linked to the layout here. + +Frames are implemented as a ScrolledWindow containing a Layout, which is +then placed on the parent's Layout. This is also in +gui\_create\_browser\_window(). + +[[!inline raw=yes pages="Documentation"]] + diff --git a/documentation/layout.mdwn b/documentation/layout.mdwn new file mode 100644 index 0000000..414253f --- /dev/null +++ b/documentation/layout.mdwn @@ -0,0 +1,70 @@ +[[!meta title="Documentation/Layout"]] +[[!meta author="James Bursa"]] +[[!meta date="2011-11-26T22:20:06Z"]] + + +[[!toc]] The modules in the render +directory process and layout HTML pages. + +Overview +-------- + +This is the process to render an HTML document: + +First the HTML is parsed to a tree of xmlNodes using the HTML parser in +libxml. This happens simultaneously with the fetch +[html\_process\_data()]. + +Any stylesheets which the document depends on are fetched and parsed. + +The tree is converted to a 'box tree' by xml\_to\_box(). The box tree +contains a node for each block, inline element, table, etc. The aim of +this stage is to determine the 'display' or 'float' CSS property of each +element, and create the corresponding node in the box tree. At this +stage the style for each element is also calculated (from CSS rules and +element attributes). The tree is normalised so that each node only has +children of permitted types (eg. TABLE\_CELLs must be within +TABLE\_ROWs) by adding missing boxes. + +The box tree is passed to the layout engine [layout\_document()], which +finds the space required by each element and assigns coordinates to the +boxes, based on the style of each element and the available width. This +includes formatting inline elements into lines, laying out tables, and +positioning floats. The layout engine can be invoked again on a already +laid out box tree to reformat it to a new width. Coordinates in the box +tree are relative to the position of the parent node. + +The box tree can then be rendered using each node's coordinates. + +Lists +----- + +Lists are one or more elements with 'display: list-item' (which is set +for 'li' by the default CSS). A list-item is constructed as a BLOCK box +and a box for the marker attached at block-\>list\_marker. The marker +contains the bullet, number, or similar, depending on the +list-style-type. + +Layout of the block is as normal. A pass of layout after main layout +places list marker boxes to the left of their block (see +layout\_lists()). + +Absolute positioning +-------------------- + +Absolutely positioned boxes are constructed in the box tree in the same +place as if they were not absolutely positioned. Inline boxes are +created as INLINE\_BLOCK, tables as TABLE, and other boxes as BLOCK (see +box\_solve\_display()). + +During layout, absolutely positioned boxes in block context (BLOCK or +TABLE) are given a position in layout\_block\_context(), but treated as +having no height. In inline context (INLINE\_BLOCK), they are given a +position in layout\_line(), but treated as having no width or height. +This is done to determine the static position. + +An additional pass after main layout positions and layouts all +absolutely positioned boxes (see layout\_position\_absolute()). + +[[!inline raw=yes pages="Documentation"]] + diff --git a/documentation/memory.mdwn b/documentation/memory.mdwn new file mode 100644 index 0000000..f595e08 --- /dev/null +++ b/documentation/memory.mdwn @@ -0,0 +1,26 @@ +[[!meta title="Documentation/Memory"]] +[[!meta author="James Bursa"]] +[[!meta date="2010-03-01T02:56:01Z"]] + + +[[!toc]] This section describes +memory management. See Error handling for how memory exhaustion is +handled. + +Finding leaks on RISC OS +------------------------ + +Memory allocation can be traced and leaks can be found using dmalloc. + +Install dmalloc from the riscos.info autobuilder. Set the environment +variable TLINK\_MEMCHECK=dmalloc and re-link !RunImage. + +On RISC OS, + + *Set DMALLOC_OPTIONS debug=0x2,log=dmalloc_log + +set the working directory to a RAM disc, and run NetSurf. When it quits, +dmalloc\_log will contain a list of unfreed blocks. + +[[!inline raw=yes pages="Documentation"]] + diff --git a/documentation/modular_coding_style.mdwn b/documentation/modular_coding_style.mdwn new file mode 100644 index 0000000..da07a8a --- /dev/null +++ b/documentation/modular_coding_style.mdwn @@ -0,0 +1,39 @@ +[[!meta title="Documentation/Modular Coding Style"]] +[[!meta author="James Bursa"]] +[[!meta date="2011-11-26T22:20:15Z"]] + + +[[!toc]] + +Modules +------- + +NetSurf's source is organised in modules. A module usually consists of a +.c and .h file. For example the html module is in html.c and html.h. + +All functions (including static functions) in a module should start +\_, for example html\_create(), html\_process\_data(), etc. This +makes functions easy to find and names unique through the source, which +is helpful for backtraces, documentation, etc. + +Global variables in a module (including static) should also start +\_. + +Static functions should all be declared at the top. + +Put functions in a logical order, for example any init function first, +then functions it calls, then the next externally available function, +functions it calls, etc. + +Coding Style +------------ + +We use K&R (2nd edition ANSI C) style, tabs for indent, 80 characters +wide, lower\_case\_with\_underscores. + +See the [Style +Guide](http://www.netsurf-browser.org/developers/StyleGuide.pdf) for +further information and examples. + +[[!inline raw=yes pages="Documentation"]] + diff --git a/documentation/overview.mdwn b/documentation/overview.mdwn new file mode 100644 index 0000000..b742296 --- /dev/null +++ b/documentation/overview.mdwn @@ -0,0 +1,9 @@ +[[!meta title="Documentation/Overview"]] +[[!meta author="James Bursa"]] +[[!meta date="2010-03-01T02:41:51Z"]] + + +[[!toc]] + +1. REDIRECT [[Documentation/Directory Structure|documentation/directory_structure]] + diff --git a/documentation/printing.mdwn b/documentation/printing.mdwn new file mode 100644 index 0000000..a7f9ee2 --- /dev/null +++ b/documentation/printing.mdwn @@ -0,0 +1,65 @@ +[[!meta title="Documentation/Printing"]] +[[!meta author="James Bursa"]] +[[!meta date="2010-03-01T02:56:52Z"]] + + +[[!toc]] This document is supposed +to be a short guide of adding paged output to NetSurf. Currently the two +pieces of code using the print implementation are PDF export and GTK +printing. + +printer.h +--------- + +The first thing the new paged output has to do is implementing the +printer interface located in printer.h. It consists of four elements: + +- plotter. This are the plotters which will be used while redrawing + the content. +- print\_begin. This function is called right after the set up and + should manage all the remaining user-specific initialisation stuff. +- print\_next\_page. This function is called before the actual + printing of each page allowing to prepare the content to be printed. +- print\_end. This function is called right before the printing + routines clean after themselves and should be used for saving the + output to a file, freeing previously allocated memory, relesing + document handles etc. + +print.h +------- + +The provided print interface consists of a set of functions which can be +used seperately and one integrating them all making the print a matter +of one call. If it is enough you can just call print\_basic\_run and +wait for it to return. However, for the case you can't accompish the +printing task this way the print interface gives you the possiblity of +calling the print steps individually. + +Only if you are using print\_basic\_run you can omit specifying the +print settings. If this is the case the default ones will be used. + +As you will notice the functions correspond to those you had to +implement in the printer. The reason for this is adding some flexibility +to the system which occured necessary i.e in the GTK print +implementation. + +- print\_set\_up. This sets the printing system up and calls + print\_begin +- print\_draw\_next\_page. Here after calling print\_next\_page one + full page of the dimensions given in the print settings is plotted +- print\_cleanup. This function is responsible for freeing all used + resources right after calling print\_end + +Settings +-------- + +This is where the besic information about the print job is held. You can +use one of the predifined sets(DEFAULT and OPTIONS) or add your own. In +order to do that you have to follow this steps: + +- add your entry to the print\_configuration enum +- add handling of it to the switch in print\_make\_settings +- add the entry name to this document + +[[!inline raw=yes pages="Documentation"]] + diff --git a/documentation/references.mdwn b/documentation/references.mdwn new file mode 100644 index 0000000..ddbfe1e --- /dev/null +++ b/documentation/references.mdwn @@ -0,0 +1,37 @@ +[[!meta title="Documentation/References"]] +[[!meta author="James Bursa"]] +[[!meta date="2010-03-01T02:57:22Z"]] + + +[[!toc]] + +Web Specifications +------------------ + +|---|---| +|HTML|- [W3C HTML 4.01](http://www.w3.org/TR/html401/) +- [W3C Mark up](http://www.w3.org/MarkUp/)| +|XHTML 1.0|- [W3C XHTML 1.0](http://www.w3.org/TR/xhtml1/)| +|CSS|- [W3C CSS 2.1](http://www.w3.org/TR/CSS21/)| +|HTTP/1.1|- +- +- | +|HTTP Authentication|- | +|PNG|- | +|URI|- +- | +|Cookies|- +- | + +RISC OS +------- + +|---|---| +|Plugin|- +- | +|URI|- | +|URL|- | +|Nested WIMP|- | + +[[!inline raw=yes pages="Documentation"]] + diff --git a/documentation/treeview.mdwn b/documentation/treeview.mdwn new file mode 100644 index 0000000..3f6ecc9 --- /dev/null +++ b/documentation/treeview.mdwn @@ -0,0 +1,88 @@ +[[!meta title="Documentation/Treeview"]] +[[!meta author="James Bursa"]] +[[!meta date="2010-03-01T02:57:03Z"]] + + +[[!toc]] Using the treeview gadget +(together with core hotlist/history/cookies/sslcert) + +Providing front end specific bits +--------------------------------- + +Most of the treeview logic is located in core code but there still are +some functions that need implementing on the front end side. These +include: + +- Functions marked as front end specific ones and listed at the end of + +` tree_url_node.h.` + +- Functions in treeview\_table located in tree.h + +Additionally the option\_tree\_icons\_dir option should be set. It +should be pointing at the directory containing the frontend specific +icon set for the treeview. + +During GUI initialisation the following functions should be called: + +- cookies\_initialise +- history\_global\_initialise +- hotlist\_initialise +- sslcert\_init + +On GUI closure: + +- cookies\_cleanup +- history\_global\_cleanup +- hotlist\_cleanup +- no function for sslcert here! + +The sslcert tree is created and deleted each time the dialog gets +invoked. This is done with sslcert\_create\_tree and sslcert\_cleanup. +Make sure that closing the window with any other method will also +perform the cleanup. + +The remaining functions in the header files of +hotlist/history/cookies/sslcert have to be connected to the front end +specific buttons and menu or tool bars. + +The front end is responsible for creating the windows and toolbars as +well as empty core trees passed to the cookies/history/hotlist/sslcert +initialisation functions. Use the \*\_get\_tree\_flags functions to +obtain the flags with which the particular tree should be created. + +Using the treeview +------------------ + +### Creating and modifying the tree structure + +- Create an empty tree with tree\_create. +- Create the necessary folder/leave nodes. +- Fill the leave nodes with tree\_create\_node\_element and assign + content to the elements with tree\_update\_node\_element. +- Use tree\_link\_node to connect the created nodes in the required + structure. +- With tree\_set\_redraw set the redraw flag on the tree to true, any + further changes will result in tree redraws. The flag can be + set/unset multiple times. +- Call tree\_draw to draw the tree for the first time. + +### Client -\> Tree communication + +To make the tree respond to mouse action, all such has to be passed to +tree\_mouse\_action and tree\_drag\_end. The mouse coordinates have to +be given with respect to the tree origin. + +### Tree -\> Client communication + +Use tree\_set\_node\_user\_callback to provide a callback for any node +related events. At the moment it can be used for(default behavior for a +not handled event in brackets): + +- handling a node launch (no action) +- custom node element deletion (free text/bitmap) +- accepting/rejecting edited text (any text accepted) +- informing about edit end (no action) + +[[!inline raw=yes pages="Documentation"]] + -- cgit v1.2.3