summaryrefslogtreecommitdiff log msg author committer range
path: root/Docs/developer
blob: 8acaca65ac588c658a4da57521c120a3d794ba10 (plain)
 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100  /** \mainpage NetSurf Documentation for Developers This document contains an overview of the code for NetSurf, and any other information useful to developers. \section overview Source Code Overview The source is split at top level as follows: - \ref content - \ref css - \ref render - Non-platform specific front-end (desktop/) - RISC OS specific code (riscos/) - Unix debug build specific code (debug/) - Misc. useful functions (utils/) \section content Fetching, caching, and converting content (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. \section css CSS parser and interfaces (css/) 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/ \section render HTML processing and layout (render/) 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. \section links Other Documentation 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/ - CSS 2.1 http://www.w3.org/TR/CSS21/ - HTTP/1.1 http://www.w3.org/Protocols/rfc2616/rfc2616.html - PNG http://www.w3.org/Graphics/PNG/ \section libs 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/ */