mirror of
https://github.com/netsurf-browser/netsurf
synced 2024-11-29 01:33:16 +03:00
123 lines
4.8 KiB
Plaintext
123 lines
4.8 KiB
Plaintext
Documentation for Developers
|
|
|
|
This document contains an overview of the code for NetSurf, and any other
|
|
information useful to developers.
|
|
|
|
________________________________________________________________________________
|
|
|
|
Source Code Overview
|
|
|
|
The source is split at top level as follows:
|
|
|
|
content -- fetching, caching, and converting content
|
|
css -- CSS parser and interfaces
|
|
debug -- defines functions which allow debugging under *nix
|
|
desktop -- non-platform specific front-end
|
|
render -- HTML processing and layout
|
|
riscos -- RISC OS specific code
|
|
utils -- misc. useful functions
|
|
|
|
________________________________________________________________________________
|
|
|
|
content -- fetching, caching, and converting content
|
|
|
|
Each URL is stored in a struct content. This structure contains a union with
|
|
fields for each type of data (HTML, CSS, images).
|
|
|
|
The content_* functions provide a general interface for handling these
|
|
structures. A content of a specified type is created using content_create(),
|
|
data is fed to it using content_process_data(), terminated by a call to
|
|
content_convert(), which converts the content into a structure which can be
|
|
displayed easily.
|
|
|
|
The cache stores this converted content. When content is retrieved from the
|
|
cache, content_revive() should result in content which can be displayed (eg. by
|
|
loading any images and styles required and updating pointers to them).
|
|
|
|
Code should not usually use the fetch_* and cache_* functions directly.
|
|
Instead use fetchcache(), which checks the cache for a url and
|
|
fetches, converts, and caches it if not present.
|
|
|
|
See content/overview for more information.
|
|
|
|
________________________________________________________________________________
|
|
|
|
css -- CSS parser and interfaces
|
|
|
|
CSS is tokenised by a flex-generated scanner (scanner.l), and then parsed into a
|
|
memory representation by a lemon-generated parser (parser.y, ruleset.c).
|
|
|
|
Styles are retrieved using css_get_style(). They can be cascaded by
|
|
css_cascade().
|
|
|
|
http://lex.sourceforge.net/
|
|
http://www.hwaci.com/sw/lemon/
|
|
|
|
________________________________________________________________________________
|
|
|
|
render -- HTML processing and layout
|
|
|
|
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.
|
|
|
|
box.[ch] -- definition of the box tree, conversion from xml tree, normalising
|
|
html.[ch] -- interface to HTML processing
|
|
layout.[ch] -- layout engine
|
|
|
|
________________________________________________________________________________
|
|
|
|
RISC OS specific protocols
|
|
|
|
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
|
|
|
|
________________________________________________________________________________
|
|
|
|
Specifications
|
|
|
|
HTML 4.01 http://www.w3.org/TR/html401/
|
|
XHTML 1.0 http://www.w3.org/TR/xhtml1/
|
|
CSS2 http://www.w3.org/TR/REC-CSS2/
|
|
HTTP/1.1 http://www.w3.org/Protocols/rfc2616/rfc2616.html
|
|
PNG http://www.w3.org/Graphics/PNG/
|
|
|
|
________________________________________________________________________________
|
|
|
|
Libraries
|
|
|
|
Get these compiled for RISC OS with headers from
|
|
http://netsurf.strcprstskrzkrk.co.uk/developer/
|
|
|
|
libxml (XML and HTML parser) http://xmlsoft.org/
|
|
libcurl (HTTP, FTP, etc) http://curl.haxx.se/libcurl/
|
|
OSLib (C interface to RISC OS SWIs) http://ro-oslib.sourceforge.net/
|
|
libpng (PNG support) http://www.libpng.org/pub/png/libpng.html
|
|
zlib http://www.gzip.org/zlib/
|
|
|
|
________________________________________________________________________________
|