From 50c03b09e4fc0c16fef522ec0a673a84d6a6d775 Mon Sep 17 00:00:00 2001 From: James Bursa Date: Fri, 1 Dec 2006 21:23:30 +0000 Subject: This documentation now in separate files. svn path=/trunk/netsurf/; revision=3089 --- Docs/developer | 215 --------------------------------------------------------- 1 file changed, 215 deletions(-) delete mode 100644 Docs/developer (limited to 'Docs') diff --git a/Docs/developer b/Docs/developer deleted file mode 100644 index fe0c2ed1d..000000000 --- a/Docs/developer +++ /dev/null @@ -1,215 +0,0 @@ -/** \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/) -- GTK specific code (gtk/) -- 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 re2c-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://re2c.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/ - (see also http://www.w3.org/MarkUp/) -- 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 - and errata http://purl.org/NET/http-errata - (see also 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 - (see also http://www.w3.org/Addressing/ and RFC 2616) -- Cookies http://wp.netscape.com/newsref/std/cookie_spec.html and - http://www.cis.ohio-state.edu/cgi-bin/rfc/rfc2109.html - -\section libs Libraries - -Get these compiled for RISC OS with headers from -http://netsurf.strcprstskrzkrk.co.uk/developer/ -- libxml (XML and HTML parser) http://www.xmlsoft.org/ -- libcurl (HTTP, FTP, etc) http://curl.haxx.se/libcurl/ -- OSLib (C interface to RISC OS SWIs) http://ro-oslib.sourceforge.net/ -- libmng (PNG, JNG, MNG support) http://www.libmng.com/ -- libjpeg (JPEG support) http://www.ijg.org/ -- zlib http://www.gzip.org/zlib/ -- OpenSSL (HTTPS support) http://www.openssl.org/ - -\section addcss Implementing a new CSS property - -In this section I go through adding a CSS property to NetSurf, using the -'white-space' property as an example. -- James Bursa - -1. Read and understand the description of the property in the CSS specification - (I have worked from CSS 2, but now 2.1 is probably better). - -These changes are required in the css directory: - -2. Add the property to css_enums. This file is used to generate css_enum.h - and css_enum.c: - \code css_white_space inherit normal nowrap pre \endcode - (I'm not doing pre-wrap and pre-line for now.) - -3. Add fields to struct ::css_style to represent the property: - \code css_white_space white_space; \endcode - -4. Add a parser function for the property to ruleset.c. Declare a new - function: - \code static void parse_white_space(struct css_style * const s, const struct css_node * const v); \endcode - and add it to ::property_table: - \code { "white-space", parse_white_space }, \endcode - This will cause the function to be called when the parser comes to a rule - giving a value for white-space. The function is passed a linked list of - struct ::css_node, each of which corresponds to a token in the CSS source, - and must update s to correspond to that rule. For white-space, the - implementation is simply: -\code -void parse_white_space(struct css_style * const s, const struct css_node * const v) -{ - css_white_space z; - if (v->type != CSS_NODE_IDENT || v->next != 0) - return; - z = css_white_space_parse(v->data, v->data_length); - if (z != CSS_WHITE_SPACE_UNKNOWN) - s->white_space = z; -} -\endcode - First we check that the value consists of exactly one identifier, as - described in the specification. If it is not, we ignore it, since it may be - some future CSS. The css_white_space_parse() function is generated in - css_enum.c, and converts a string giving a value to a constant. If the - conversion succeeds, the style s is updated. - -5. Add defaults for the style to ::css_base_style, ::css_empty_style, and - ::css_blank_style in css.c. The value in css_base_style should be the one - given as 'Initial' in the spec, and the value in css_empty_style should be - inherit. If 'Inherited' is yes in the spec, the value in css_blank_style - should be inherit, otherwise it should be the one given as 'Initial'. Thus - for white-space, which has "Initial: normal, Inherited: yes" in the spec, we - use CSS_WHITE_SPACE_NORMAL in css_base_style and CSS_WHITE_SPACE_INHERIT in - the other two. - -6. Edit css_cascade() and css_merge() in css.c to handle the property. In - both cases for white-space this looks like: - \code - if (apply->white_space != CSS_WHITE_SPACE_INHERIT) - style->white_space = apply->white_space; - \endcode - Add the property to css_dump_style() (not essential). - -Now the box, layout and / or redraw code needs to be changed to use the new -style property. This varies much more depending on the property. - -For white-space, convert_xml_to_box() was changed to split text at newlines if -white-space was pre, and to replace spaces with hard spaces for nowrap. -Additionally, calculate_inline_container_widths() was changed to give the -appropriate minimum width for pre and nowrap. - -\section errorhandling Error handling - -This section gives some suggestions for error handling in the code. - -The most common serious error is memory exhaustion. Previously we used xcalloc() -etc. instead of malloc(), so that no recovery code was required, and NetSurf -would just exit. We should no longer use this. 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 -\code -warn_user("NoMemory", 0); -\endcode - -The other common error is one returned by a RISC OS SWI. Always use "X" SWIs, -something like this: -\code -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; -} -\endcode - -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. - -*/ -- cgit v1.2.3