diff options
Diffstat (limited to 'Docs/developer')
| -rw-r--r-- | Docs/developer | 109 |
1 files changed, 109 insertions, 0 deletions
diff --git a/Docs/developer b/Docs/developer new file mode 100644 index 000000000..a8c443cec --- /dev/null +++ b/Docs/developer @@ -0,0 +1,109 @@ +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 +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, except +for cache_free(). Instead use fetchcache(), which checks the cache for a url and +fetches, converts, and caches it if not present. + +________________________________________________________________________________ + +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 + +________________________________________________________________________________ + +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/ + +________________________________________________________________________________ |