Initial conversion from MediaWiki, 20170204

17 files changed, 1319 insertions, 0 deletions

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:
+<https://github.com/DNADNL/NetScript>
+
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]]
+
+<strong>Note:</strong>  
+<span style="text-indent:2em; display: inline-block;">Commands proceeded
+by \# should be done as root</span>  
+<span style="text-indent:2em; display: inline-block;">Commands proceeded
+by \$ should be done as your normal user</span>  
+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 <http://ci.netsurf-browser.org/builds/toolchains/>
+
+<strong>Note :</strong>  
+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
+<about:testament> 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
+
+    <nowiki>
+      <frameset rows="50%,50%">
+        <frameset cols="40,200">
+          <frame name="A" src="aaa">
+          <frame name="B" src="bbb">
+        </frameset>
+        <frameset cols="3*,*">
+          <frame name="C" src="ccc">
+          <frame name="D" src="ddd">
+        </frameset>
+      </frameset>
+    </nowiki>
+
+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' <aaa> (scrolling auto) border 0
+        (0 1): 0x608daeb0 (0 0) w200px h100% (margin w0 h0) 'B' <bbb> (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' <ccc> (scrolling auto) border 0
+        (0 1): 0x608d9b88 (0 0) w1* h100% (margin w0 h0) 'D' <ddd> (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
+<module>\_, 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
+<module>\_.
+
+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://www.w3.org/Protocols/rfc2616/rfc2616.html>
+-   <http://purl.org/NET/http-errata>
+-   <http://www.w3.org/Protocols/>|
+|HTTP Authentication|-   <http://www.cis.ohio-state.edu/cgi-bin/rfc/rfc2617.html>|
+|PNG|-   <http://www.w3.org/Graphics/PNG/>|
+|URI|-   <http://www.cis.ohio-state.edu/cgi-bin/rfc/rfc2396.html>
+-   <http://www.w3.org/Addressing/>|
+|Cookies|-   <http://wp.netscape.com/newsref/std/cookie_spec.html>
+-   <http://www.cis.ohio-state.edu/cgi-bin/rfc/rfc2109.html>|
+
+RISC OS
+-------
+
+|---|---|
+|Plugin|-   <http://www.ecs.soton.ac.uk/~jmb202/riscos/acorn/funcspec.html>
+-   <http://www.ecs.soton.ac.uk/~jmb202/riscos/acorn/browse-plugins.html>|
+|URI|-   <http://www.ecs.soton.ac.uk/~jmb202/riscos/acorn/uri.html>|
+|URL|-   <http://www.vigay.com/inet/inet_url.html>|
+|Nested WIMP|-   <http://www.ecs.soton.ac.uk/~jmb202/riscos/acorn/nested.html>|
+
+[[!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"]]
+