diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Doxyfile | 393 | ||||
| -rw-r--r-- | docs/PACKAGING-GTK | 22 | ||||
| -rw-r--r-- | docs/UnimplementedJavascript.md | 44 | ||||
| -rw-r--r-- | docs/building-GTK.md | 7 | ||||
| -rw-r--r-- | docs/core-window-interface.md | 2 | ||||
| -rw-r--r-- | docs/development.md | 123 | ||||
| -rw-r--r-- | docs/env.sh | 164 | ||||
| -rwxr-xr-x | docs/gource.sh | 4 | ||||
| -rw-r--r-- | docs/implementing-new-frontend.md | 413 | ||||
| -rw-r--r-- | docs/integration-testing.md | 542 | ||||
| -rw-r--r-- | docs/mainpage.md | 162 | ||||
| -rw-r--r-- | docs/netsurf-fb.1 | 15 | ||||
| -rw-r--r-- | docs/netsurf-gtk.1 | 10 | ||||
| -rw-r--r-- | docs/netsurf-options.md | 2 | ||||
| -rw-r--r-- | docs/project.md | 17 | ||||
| -rw-r--r-- | docs/quick-start.md | 17 | ||||
| -rw-r--r-- | docs/source-object-backing-store.md | 120 | ||||
| -rw-r--r-- | docs/unit-testing.md (renamed from docs/unit-testing) | 199 | ||||
| -rw-r--r-- | docs/user-interface.md | 61 | ||||
| -rw-r--r-- | docs/using-framebuffer.md | 58 |
20 files changed, 1788 insertions, 587 deletions
diff --git a/docs/Doxyfile b/docs/Doxyfile index 628bb81ac..974c5a728 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -1,4 +1,4 @@ -# Doxyfile 1.8.8 +# Doxyfile 1.8.13 # This file describes the settings to be used by the documentation system # doxygen (www.doxygen.org) for a project. @@ -32,7 +32,7 @@ DOXYFILE_ENCODING = UTF-8 # title of most generated pages and in a few other places. # The default value is: My Project. -PROJECT_NAME = NetSurf +PROJECT_NAME = "NetSurf" # The PROJECT_NUMBER tag can be used to enter a project or revision number. This # could be handy for archiving the generated documentation or if some version @@ -46,10 +46,10 @@ PROJECT_NUMBER = PROJECT_BRIEF = -# With the PROJECT_LOGO tag one can specify an logo or icon that is included in -# the documentation. The maximum height of the logo should not exceed 55 pixels -# and the maximum width should not exceed 200 pixels. Doxygen will copy the logo -# to the output directory. +# With the PROJECT_LOGO tag one can specify a logo or an icon that is included +# in the documentation. The maximum height of the logo should not exceed 55 +# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy +# the logo to the output directory. PROJECT_LOGO = @@ -60,7 +60,7 @@ PROJECT_LOGO = OUTPUT_DIRECTORY = -# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create 4096 sub- +# If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub- # directories (in 2 levels) under the output directory of each output format and # will distribute the generated files over these directories. Enabling this # option can be useful when feeding doxygen a huge amount of source files, where @@ -93,14 +93,14 @@ ALLOW_UNICODE_NAMES = NO OUTPUT_LANGUAGE = English -# If the BRIEF_MEMBER_DESC tag is set to YES doxygen will include brief member +# If the BRIEF_MEMBER_DESC tag is set to YES, doxygen will include brief member # descriptions after the members that are listed in the file and class # documentation (similar to Javadoc). Set to NO to disable this. # The default value is: YES. BRIEF_MEMBER_DESC = YES -# If the REPEAT_BRIEF tag is set to YES doxygen will prepend the brief +# If the REPEAT_BRIEF tag is set to YES, doxygen will prepend the brief # description of a member or function before the detailed description # # Note: If both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the @@ -118,7 +118,17 @@ REPEAT_BRIEF = YES # the entity):The $name class, The $name widget, The $name file, is, provides, # specifies, contains, represents, a, an and the. -ABBREVIATE_BRIEF = +ABBREVIATE_BRIEF = "The $name class" \ + "The $name widget" \ + "The $name file" \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the # If the ALWAYS_DETAILED_SEC and REPEAT_BRIEF tags are both set to YES then # doxygen will generate a detailed section even if there is only a brief @@ -135,7 +145,7 @@ ALWAYS_DETAILED_SEC = NO INLINE_INHERITED_MEMB = NO -# If the FULL_PATH_NAMES tag is set to YES doxygen will prepend the full path +# If the FULL_PATH_NAMES tag is set to YES, doxygen will prepend the full path # before files name in the file list and in the header files. If set to NO the # shortest path that makes the file name unique will be used # The default value is: YES. @@ -205,9 +215,9 @@ MULTILINE_CPP_IS_BRIEF = NO INHERIT_DOCS = YES -# If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce a -# new page for each member. If set to NO, the documentation of a member will be -# part of the file/class/namespace that contains it. +# If the SEPARATE_MEMBER_PAGES tag is set to YES then doxygen will produce a new +# page for each member. If set to NO, the documentation of a member will be part +# of the file/class/namespace that contains it. # The default value is: NO. SEPARATE_MEMBER_PAGES = NO @@ -276,7 +286,7 @@ OPTIMIZE_OUTPUT_VHDL = NO # instance to make doxygen treat .inc files as Fortran files (default is PHP), # and .f files as C (default is Fortran), use: inc=Fortran f=C. # -# Note For files without extension you can use no_extension as a placeholder. +# Note: For files without extension you can use no_extension as a placeholder. # # Note that for custom extensions you also need to set FILE_PATTERNS otherwise # the files are not read by doxygen. @@ -293,10 +303,19 @@ EXTENSION_MAPPING = MARKDOWN_SUPPORT = YES +# When the TOC_INCLUDE_HEADINGS tag is set to a non-zero value, all headings up +# to that level are automatically included in the table of contents, even if +# they do not have an id attribute. +# Note: This feature currently applies only to Markdown headings. +# Minimum value: 0, maximum value: 99, default value: 0. +# This tag requires that the tag MARKDOWN_SUPPORT is set to YES. + +TOC_INCLUDE_HEADINGS = 3 + # When enabled doxygen tries to link words that correspond to documented # classes, or namespaces to their corresponding documentation. Such a link can -# be prevented in individual cases by by putting a % sign in front of the word -# or globally by setting AUTOLINK_SUPPORT to NO. +# be prevented in individual cases by putting a % sign in front of the word or +# globally by setting AUTOLINK_SUPPORT to NO. # The default value is: YES. AUTOLINK_SUPPORT = YES @@ -336,13 +355,20 @@ SIP_SUPPORT = NO IDL_PROPERTY_SUPPORT = YES # If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC -# tag is set to YES, then doxygen will reuse the documentation of the first +# tag is set to YES then doxygen will reuse the documentation of the first # member in the group (if any) for the other members of the group. By default # all members of a group must be documented explicitly. # The default value is: NO. DISTRIBUTE_GROUP_DOC = NO +# If one adds a struct or class to a group and this option is enabled, then also +# any nested class or struct is added to the same group. By default this option +# is disabled and one has to add nested compounds explicitly via \ingroup. +# The default value is: NO. + +GROUP_NESTED_COMPOUNDS = NO + # Set the SUBGROUPING tag to YES to allow class member groups of the same type # (for instance a group of public functions) to be put as a subgroup of that # type (e.g. under the Public Functions section). Set it to NO to prevent @@ -401,7 +427,7 @@ LOOKUP_CACHE_SIZE = 0 # Build related configuration options #--------------------------------------------------------------------------- -# If the EXTRACT_ALL tag is set to YES doxygen will assume all entities in +# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in # documentation are documented, even if no documentation was available. Private # class members and static file members will be hidden unless the # EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES. @@ -411,35 +437,35 @@ LOOKUP_CACHE_SIZE = 0 EXTRACT_ALL = YES -# If the EXTRACT_PRIVATE tag is set to YES all private members of a class will +# If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will # be included in the documentation. # The default value is: NO. EXTRACT_PRIVATE = YES -# If the EXTRACT_PACKAGE tag is set to YES all members with package or internal +# If the EXTRACT_PACKAGE tag is set to YES, all members with package or internal # scope will be included in the documentation. # The default value is: NO. EXTRACT_PACKAGE = NO -# If the EXTRACT_STATIC tag is set to YES all static members of a file will be +# If the EXTRACT_STATIC tag is set to YES, all static members of a file will be # included in the documentation. # The default value is: NO. EXTRACT_STATIC = YES -# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) defined -# locally in source files will be included in the documentation. If set to NO +# If the EXTRACT_LOCAL_CLASSES tag is set to YES, classes (and structs) defined +# locally in source files will be included in the documentation. If set to NO, # only classes defined in header files are included. Does not have any effect # for Java sources. # The default value is: YES. EXTRACT_LOCAL_CLASSES = YES -# This flag is only useful for Objective-C code. When set to YES local methods, +# This flag is only useful for Objective-C code. If set to YES, local methods, # which are defined in the implementation section but not in the interface are -# included in the documentation. If set to NO only methods in the interface are +# included in the documentation. If set to NO, only methods in the interface are # included. # The default value is: NO. @@ -464,21 +490,21 @@ HIDE_UNDOC_MEMBERS = NO # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all # undocumented classes that are normally visible in the class hierarchy. If set -# to NO these classes will be included in the various overviews. This option has -# no effect if EXTRACT_ALL is enabled. +# to NO, these classes will be included in the various overviews. This option +# has no effect if EXTRACT_ALL is enabled. # The default value is: NO. HIDE_UNDOC_CLASSES = NO # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend -# (class|struct|union) declarations. If set to NO these declarations will be +# (class|struct|union) declarations. If set to NO, these declarations will be # included in the documentation. # The default value is: NO. HIDE_FRIEND_COMPOUNDS = NO # If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any -# documentation blocks found inside the body of a function. If set to NO these +# documentation blocks found inside the body of a function. If set to NO, these # blocks will be appended to the function's detailed documentation block. # The default value is: NO. @@ -492,7 +518,7 @@ HIDE_IN_BODY_DOCS = NO INTERNAL_DOCS = NO # If the CASE_SENSE_NAMES tag is set to NO then doxygen will only generate file -# names in lower-case letters. If set to YES upper-case letters are also +# names in lower-case letters. If set to YES, upper-case letters are also # allowed. This is useful if you have classes or files whose names only differ # in case and if your file system supports case sensitive file names. Windows # and Mac users are advised to set this option to NO. @@ -501,12 +527,19 @@ INTERNAL_DOCS = NO CASE_SENSE_NAMES = YES # If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with -# their full class and namespace scopes in the documentation. If set to YES the +# their full class and namespace scopes in the documentation. If set to YES, the # scope will be hidden. # The default value is: NO. HIDE_SCOPE_NAMES = NO +# If the HIDE_COMPOUND_REFERENCE tag is set to NO (default) then doxygen will +# append additional text to a page's title, such as Class Reference. If set to +# YES the compound reference will be hidden. +# The default value is: NO. + +HIDE_COMPOUND_REFERENCE= NO + # If the SHOW_INCLUDE_FILES tag is set to YES then doxygen will put a list of # the files that are included by a file in the documentation of that file. # The default value is: YES. @@ -534,14 +567,14 @@ INLINE_INFO = YES # If the SORT_MEMBER_DOCS tag is set to YES then doxygen will sort the # (detailed) documentation of file and class members alphabetically by member -# name. If set to NO the members will appear in declaration order. +# name. If set to NO, the members will appear in declaration order. # The default value is: YES. SORT_MEMBER_DOCS = YES # If the SORT_BRIEF_DOCS tag is set to YES then doxygen will sort the brief # descriptions of file, namespace and class members alphabetically by member -# name. If set to NO the members will appear in declaration order. Note that +# name. If set to NO, the members will appear in declaration order. Note that # this will also influence the order of the classes in the class list. # The default value is: NO. @@ -586,27 +619,25 @@ SORT_BY_SCOPE_NAME = NO STRICT_PROTO_MATCHING = NO -# The GENERATE_TODOLIST tag can be used to enable ( YES) or disable ( NO) the -# todo list. This list is created by putting \todo commands in the -# documentation. +# The GENERATE_TODOLIST tag can be used to enable (YES) or disable (NO) the todo +# list. This list is created by putting \todo commands in the documentation. # The default value is: YES. GENERATE_TODOLIST = YES -# The GENERATE_TESTLIST tag can be used to enable ( YES) or disable ( NO) the -# test list. This list is created by putting \test commands in the -# documentation. +# The GENERATE_TESTLIST tag can be used to enable (YES) or disable (NO) the test +# list. This list is created by putting \test commands in the documentation. # The default value is: YES. GENERATE_TESTLIST = YES -# The GENERATE_BUGLIST tag can be used to enable ( YES) or disable ( NO) the bug +# The GENERATE_BUGLIST tag can be used to enable (YES) or disable (NO) the bug # list. This list is created by putting \bug commands in the documentation. # The default value is: YES. GENERATE_BUGLIST = YES -# The GENERATE_DEPRECATEDLIST tag can be used to enable ( YES) or disable ( NO) +# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or disable (NO) # the deprecated list. This list is created by putting \deprecated commands in # the documentation. # The default value is: YES. @@ -631,8 +662,8 @@ ENABLED_SECTIONS = MAX_INITIALIZER_LINES = 30 # Set the SHOW_USED_FILES tag to NO to disable the list of files generated at -# the bottom of the documentation of classes and structs. If set to YES the list -# will mention the files that were used to generate the documentation. +# the bottom of the documentation of classes and structs. If set to YES, the +# list will mention the files that were used to generate the documentation. # The default value is: YES. SHOW_USED_FILES = YES @@ -696,7 +727,7 @@ CITE_BIB_FILES = QUIET = NO # The WARNINGS tag can be used to turn on/off the warning messages that are -# generated to standard error ( stderr) by doxygen. If WARNINGS is set to YES +# generated to standard error (stderr) by doxygen. If WARNINGS is set to YES # this implies that the warnings are on. # # Tip: Turn warnings on while writing the documentation. @@ -704,7 +735,7 @@ QUIET = NO WARNINGS = YES -# If the WARN_IF_UNDOCUMENTED tag is set to YES, then doxygen will generate +# If the WARN_IF_UNDOCUMENTED tag is set to YES then doxygen will generate # warnings for undocumented members. If EXTRACT_ALL is set to YES then this flag # will automatically be disabled. # The default value is: YES. @@ -721,12 +752,18 @@ WARN_IF_DOC_ERROR = YES # This WARN_NO_PARAMDOC option can be enabled to get warnings for functions that # are documented, but have no documentation for their parameters or return -# value. If set to NO doxygen will only warn about wrong or incomplete parameter -# documentation, but not about the absence of documentation. +# value. If set to NO, doxygen will only warn about wrong or incomplete +# parameter documentation, but not about the absence of documentation. # The default value is: NO. WARN_NO_PARAMDOC = YES +# If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when +# a warning is encountered. +# The default value is: NO. + +WARN_AS_ERROR = NO + # The WARN_FORMAT tag determines the format of the warning messages that doxygen # can produce. The string should contain the $file, $line, and $text tags, which # will be replaced by the file and line number from which the warning originated @@ -750,7 +787,7 @@ WARN_LOGFILE = # The INPUT tag is used to specify the files and/or directories that contain # documented source files. You may enter file names like myfile.cpp or # directories like /usr/src/myproject. Separate the files or directories with -# spaces. +# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. INPUT = docs \ @@ -776,6 +813,7 @@ INPUT = docs \ desktop \ content \ content/fetchers \ + content/fetchers/file \ content/handlers/image \ content/handlers/css \ content/handlers/javascript \ @@ -796,20 +834,62 @@ INPUT_ENCODING = UTF-8 # If the value of the INPUT tag contains directories, you can use the # FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and -# *.h) to filter out the source-files in the directories. If left blank the -# following patterns are tested:*.c, *.cc, *.cxx, *.cpp, *.c++, *.java, *.ii, -# *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, *.hh, *.hxx, *.hpp, -# *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, *.m, *.markdown, -# *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf, -# *.qsf, *.as and *.js. +# *.h) to filter out the source-files in the directories. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# read by doxygen. +# +# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp, +# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h, +# *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc, +# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f95, *.f03, *.f08, +# *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf and *.qsf. FILE_PATTERNS = *.c \ - *.h \ - *.y \ - *.l \ + *.cc \ + *.cxx \ *.cpp \ + *.c++ \ + *.java \ + *.ii \ + *.ixx \ + *.ipp \ + *.i++ \ + *.inl \ + *.idl \ + *.ddl \ + *.odl \ + *.h \ + *.hh \ + *.hxx \ + *.hpp \ + *.h++ \ + *.cs \ + *.d \ + *.php \ + *.php4 \ + *.php5 \ + *.phtml \ + *.inc \ *.m \ - *.md + *.markdown \ + *.md \ + *.mm \ + *.dox \ + *.py \ + *.pyw \ + *.f90 \ + *.f95 \ + *.f03 \ + *.f08 \ + *.f \ + *.for \ + *.tcl \ + *.vhd \ + *.vhdl \ + *.ucf \ + *.qsf # The RECURSIVE tag can be used to specify whether or not subdirectories should # be searched for input files as well. @@ -864,7 +944,7 @@ EXAMPLE_PATH = # *.h) to filter out the source-files in the directories. If left blank all # files are included. -EXAMPLE_PATTERNS = +EXAMPLE_PATTERNS = * # If the EXAMPLE_RECURSIVE tag is set to YES then subdirectories will be # searched for input files to be used with the \include or \dontinclude commands @@ -893,6 +973,10 @@ IMAGE_PATH = # Note that the filter must not add or remove lines; it is applied before the # code is scanned, but not when the output code is generated. If lines are added # or removed, the anchors will not be placed correctly. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. INPUT_FILTER = @@ -902,11 +986,15 @@ INPUT_FILTER = # (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how # filters are used. If the FILTER_PATTERNS tag is empty or if none of the # patterns match the file name, INPUT_FILTER is applied. +# +# Note that for custom extensions or not directly supported extensions you also +# need to set EXTENSION_MAPPING for the extension otherwise the files are not +# properly processed by doxygen. FILTER_PATTERNS = # If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using -# INPUT_FILTER ) will also be used to filter the input files that are used for +# INPUT_FILTER) will also be used to filter the input files that are used for # producing the source files to browse (i.e. when SOURCE_BROWSER is set to YES). # The default value is: NO. @@ -966,7 +1054,7 @@ REFERENCED_BY_RELATION = YES REFERENCES_RELATION = YES # If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set -# to YES, then the hyperlinks from functions in REFERENCES_RELATION and +# to YES then the hyperlinks from functions in REFERENCES_RELATION and # REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will # link to the documentation. # The default value is: YES. @@ -1013,13 +1101,13 @@ USE_HTAGS = NO VERBATIM_HEADERS = YES -# If the CLANG_ASSISTED_PARSING tag is set to YES, then doxygen will use the +# If the CLANG_ASSISTED_PARSING tag is set to YES then doxygen will use the # clang parser (see: http://clang.llvm.org/) for more accurate parsing at the # cost of reduced performance. This can be particularly helpful with template # rich C++ code for which doxygen's built-in parser lacks the necessary type # information. # Note: The availability of this option depends on whether or not doxygen was -# compiled with the --with-libclang option. +# generated with the -Duse-libclang=ON option for CMake. # The default value is: NO. CLANG_ASSISTED_PARSING = NO @@ -1062,7 +1150,7 @@ IGNORE_PREFIX = # Configuration options related to the HTML output #--------------------------------------------------------------------------- -# If the GENERATE_HTML tag is set to YES doxygen will generate HTML output +# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output # The default value is: YES. GENERATE_HTML = YES @@ -1128,10 +1216,10 @@ HTML_STYLESHEET = # cascading style sheets that are included after the standard style sheets # created by doxygen. Using this option one can overrule certain style aspects. # This is preferred over using HTML_STYLESHEET since it does not replace the -# standard style sheet and is therefor more robust against future updates. +# standard style sheet and is therefore more robust against future updates. # Doxygen will copy the style sheet files to the output directory. -# Note: The order of the extra stylesheet files is of importance (e.g. the last -# stylesheet in the list overrules the setting of the previous ones in the +# Note: The order of the extra style sheet files is of importance (e.g. the last +# style sheet in the list overrules the setting of the previous ones in the # list). For an example see the documentation. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1148,7 +1236,7 @@ HTML_EXTRA_STYLESHEET = HTML_EXTRA_FILES = # The HTML_COLORSTYLE_HUE tag controls the color of the HTML output. Doxygen -# will adjust the colors in the stylesheet and background images according to +# will adjust the colors in the style sheet and background images according to # this color. Hue is specified as an angle on a colorwheel, see # http://en.wikipedia.org/wiki/Hue for more information. For instance the value # 0 represents red, 60 is yellow, 120 is green, 180 is cyan, 240 is blue, 300 @@ -1179,8 +1267,9 @@ HTML_COLORSTYLE_GAMMA = 80 # If the HTML_TIMESTAMP tag is set to YES then the footer of each generated HTML # page will contain the date and time when the page was generated. Setting this -# to NO can help when comparing the output of multiple runs. -# The default value is: YES. +# to YES can help to show when doxygen was last run and thus if the +# documentation is up to date. +# The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. HTML_TIMESTAMP = YES @@ -1276,28 +1365,28 @@ GENERATE_HTMLHELP = NO CHM_FILE = # The HHC_LOCATION tag can be used to specify the location (absolute path -# including file name) of the HTML help compiler ( hhc.exe). If non-empty +# including file name) of the HTML help compiler (hhc.exe). If non-empty, # doxygen will try to run the HTML help compiler on the generated index.hhp. # The file has to be specified with full path. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. HHC_LOCATION = -# The GENERATE_CHI flag controls if a separate .chi index file is generated ( -# YES) or that it should be included in the master .chm file ( NO). +# The GENERATE_CHI flag controls if a separate .chi index file is generated +# (YES) or that it should be included in the master .chm file (NO). # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. GENERATE_CHI = NO -# The CHM_INDEX_ENCODING is used to encode HtmlHelp index ( hhk), content ( hhc) +# The CHM_INDEX_ENCODING is used to encode HtmlHelp index (hhk), content (hhc) # and project file content. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. CHM_INDEX_ENCODING = -# The BINARY_TOC flag controls whether a binary table of contents is generated ( -# YES) or a normal table of contents ( NO) in the .chm file. Furthermore it +# The BINARY_TOC flag controls whether a binary table of contents is generated +# (YES) or a normal table of contents (NO) in the .chm file. Furthermore it # enables the Previous and Next buttons. # The default value is: NO. # This tag requires that the tag GENERATE_HTMLHELP is set to YES. @@ -1411,7 +1500,7 @@ DISABLE_INDEX = NO # index structure (just like the one that is generated for HTML Help). For this # to work a browser that supports JavaScript, DHTML, CSS and frames is required # (i.e. any modern browser). Windows users are probably better off using the -# HTML help feature. Via custom stylesheets (see HTML_EXTRA_STYLESHEET) one can +# HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can # further fine-tune the look of the index. As an example, the default style # sheet generated by doxygen has an example that shows how to put an image at # the root of the tree instead of the PROJECT_NAME. Since the tree basically has @@ -1439,7 +1528,7 @@ ENUM_VALUES_PER_LINE = 4 TREEVIEW_WIDTH = 250 -# When the EXT_LINKS_IN_WINDOW option is set to YES doxygen will open links to +# If the EXT_LINKS_IN_WINDOW option is set to YES, doxygen will open links to # external symbols imported via tag files in a separate window. # The default value is: NO. # This tag requires that the tag GENERATE_HTML is set to YES. @@ -1468,7 +1557,7 @@ FORMULA_TRANSPARENT = YES # Enable the USE_MATHJAX option to render LaTeX formulas using MathJax (see # http://www.mathjax.org) which uses client side Javascript for the rendering -# instead of using prerendered bitmaps. Use this if you do not have LaTeX +# instead of using pre-rendered bitmaps. Use this if you do not have LaTeX # installed or if you want to formulas look prettier in the HTML output. When # enabled you may also need to install MathJax separately and configure the path # to it using the MATHJAX_RELPATH option. @@ -1554,7 +1643,7 @@ SERVER_BASED_SEARCH = NO # external search engine pointed to by the SEARCHENGINE_URL option to obtain the # search results. # -# Doxygen ships with an example indexer ( doxyindexer) and search engine +# Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library # Xapian (see: http://xapian.org/). # @@ -1567,7 +1656,7 @@ EXTERNAL_SEARCH = NO # The SEARCHENGINE_URL should point to a search engine hosted by a web server # which will return the search results when EXTERNAL_SEARCH is enabled. # -# Doxygen ships with an example indexer ( doxyindexer) and search engine +# Doxygen ships with an example indexer (doxyindexer) and search engine # (doxysearch.cgi) which are based on the open source search engine library # Xapian (see: http://xapian.org/). See the section "External Indexing and # Searching" for details. @@ -1605,7 +1694,7 @@ EXTRA_SEARCH_MAPPINGS = # Configuration options related to the LaTeX output #--------------------------------------------------------------------------- -# If the GENERATE_LATEX tag is set to YES doxygen will generate LaTeX output. +# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output. # The default value is: YES. GENERATE_LATEX = NO @@ -1636,7 +1725,7 @@ LATEX_CMD_NAME = latex MAKEINDEX_CMD_NAME = makeindex -# If the COMPACT_LATEX tag is set to YES doxygen generates more compact LaTeX +# If the COMPACT_LATEX tag is set to YES, doxygen generates more compact LaTeX # documents. This may be useful for small projects and may help to save some # trees in general. # The default value is: NO. @@ -1651,12 +1740,15 @@ COMPACT_LATEX = NO # The default value is: a4. # This tag requires that the tag GENERATE_LATEX is set to YES. -PAPER_TYPE = a4wide +PAPER_TYPE = a4 # The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names -# that should be included in the LaTeX output. To get the times font for -# instance you can specify -# EXTRA_PACKAGES=times +# that should be included in the LaTeX output. The package can be specified just +# by its name or with the correct syntax as to be used with the LaTeX +# \usepackage command. To get the times font for instance you can specify : +# EXTRA_PACKAGES=times or EXTRA_PACKAGES={times} +# To use the option intlimits with the amsmath package you can specify: +# EXTRA_PACKAGES=[intlimits]{amsmath} # If left blank no extra packages will be included. # This tag requires that the tag GENERATE_LATEX is set to YES. @@ -1671,9 +1763,9 @@ EXTRA_PACKAGES = # Note: Only use a user-defined header if you know what you are doing! The # following commands have a special meaning inside the header: $title, # $datetime, $date, $doxygenversion, $projectname, $projectnumber, -# $projectbrief, $projectlogo. Doxygen will replace $title with the empy string, -# for the replacement values of the other commands the user is refered to -# HTML_HEADER. +# $projectbrief, $projectlogo. Doxygen will replace $title with the empty +# string, for the replacement values of the other commands the user is referred +# to HTML_HEADER. # This tag requires that the tag GENERATE_LATEX is set to YES. LATEX_HEADER = @@ -1689,6 +1781,17 @@ LATEX_HEADER = LATEX_FOOTER = +# The LATEX_EXTRA_STYLESHEET tag can be used to specify additional user-defined +# LaTeX style sheets that are included after the standard style sheets created +# by doxygen. Using this option one can overrule certain style aspects. Doxygen +# will copy the style sheet files to the output directory. +# Note: The order of the extra style sheet files is of importance (e.g. the last +# style sheet in the list overrules the setting of the previous ones in the +# list). +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_EXTRA_STYLESHEET = + # The LATEX_EXTRA_FILES tag can be used to specify one or more extra images or # other source files which should be copied to the LATEX_OUTPUT output # directory. Note that the files will be copied as-is; there are no commands or @@ -1704,15 +1807,15 @@ LATEX_EXTRA_FILES = # The default value is: YES. # This tag requires that the tag GENERATE_LATEX is set to YES. -PDF_HYPERLINKS = NO +PDF_HYPERLINKS = YES # If the USE_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate -# the PDF file directly from the LaTeX files. Set this option to YES to get a +# the PDF file directly from the LaTeX files. Set this option to YES, to get a # higher quality PDF documentation. # The default value is: YES. # This tag requires that the tag GENERATE_LATEX is set to YES. -USE_PDFLATEX = NO +USE_PDFLATEX = YES # If the LATEX_BATCHMODE tag is set to YES, doxygen will add the \batchmode # command to the generated LaTeX files. This will instruct LaTeX to keep running @@ -1748,11 +1851,19 @@ LATEX_SOURCE_CODE = NO LATEX_BIB_STYLE = plain +# If the LATEX_TIMESTAMP tag is set to YES then the footer of each generated +# page will contain the date and time when the page was generated. Setting this +# to NO can help when comparing the output of multiple runs. +# The default value is: NO. +# This tag requires that the tag GENERATE_LATEX is set to YES. + +LATEX_TIMESTAMP = NO + #--------------------------------------------------------------------------- # Configuration options related to the RTF output #--------------------------------------------------------------------------- -# If the GENERATE_RTF tag is set to YES doxygen will generate RTF output. The +# If the GENERATE_RTF tag is set to YES, doxygen will generate RTF output. The # RTF output is optimized for Word 97 and may not look too pretty with other RTF # readers/editors. # The default value is: NO. @@ -1767,7 +1878,7 @@ GENERATE_RTF = NO RTF_OUTPUT = rtf -# If the COMPACT_RTF tag is set to YES doxygen generates more compact RTF +# If the COMPACT_RTF tag is set to YES, doxygen generates more compact RTF # documents. This may be useful for small projects and may help to save some # trees in general. # The default value is: NO. @@ -1804,11 +1915,21 @@ RTF_STYLESHEET_FILE = RTF_EXTENSIONS_FILE = +# If the RTF_SOURCE_CODE tag is set to YES then doxygen will include source code +# with syntax highlighting in the RTF output. +# +# Note that which sources are shown also depends on other settings such as +# SOURCE_BROWSER. +# The default value is: NO. +# This tag requires that the tag GENERATE_RTF is set to YES. + +RTF_SOURCE_CODE = NO + #--------------------------------------------------------------------------- # Configuration options related to the man page output #--------------------------------------------------------------------------- -# If the GENERATE_MAN tag is set to YES doxygen will generate man pages for +# If the GENERATE_MAN tag is set to YES, doxygen will generate man pages for # classes and files. # The default value is: NO. @@ -1852,7 +1973,7 @@ MAN_LINKS = NO # Configuration options related to the XML output #--------------------------------------------------------------------------- -# If the GENERATE_XML tag is set to YES doxygen will generate an XML file that +# If the GENERATE_XML tag is set to YES, doxygen will generate an XML file that # captures the structure of the code including all documentation. # The default value is: NO. @@ -1866,7 +1987,7 @@ GENERATE_XML = NO XML_OUTPUT = xml -# If the XML_PROGRAMLISTING tag is set to YES doxygen will dump the program +# If the XML_PROGRAMLISTING tag is set to YES, doxygen will dump the program # listings (including syntax highlighting and cross-referencing information) to # the XML output. Note that enabling this will significantly increase the size # of the XML output. @@ -1879,7 +2000,7 @@ XML_PROGRAMLISTING = YES # Configuration options related to the DOCBOOK output #--------------------------------------------------------------------------- -# If the GENERATE_DOCBOOK tag is set to YES doxygen will generate Docbook files +# If the GENERATE_DOCBOOK tag is set to YES, doxygen will generate Docbook files # that can be used to generate PDF. # The default value is: NO. @@ -1893,7 +2014,7 @@ GENERATE_DOCBOOK = NO DOCBOOK_OUTPUT = docbook -# If the DOCBOOK_PROGRAMLISTING tag is set to YES doxygen will include the +# If the DOCBOOK_PROGRAMLISTING tag is set to YES, doxygen will include the # program listings (including syntax highlighting and cross-referencing # information) to the DOCBOOK output. Note that enabling this will significantly # increase the size of the DOCBOOK output. @@ -1906,10 +2027,10 @@ DOCBOOK_PROGRAMLISTING = NO # Configuration options for the AutoGen Definitions output #--------------------------------------------------------------------------- -# If the GENERATE_AUTOGEN_DEF tag is set to YES doxygen will generate an AutoGen -# Definitions (see http://autogen.sf.net) file that captures the structure of -# the code including all documentation. Note that this feature is still -# experimental and incomplete at the moment. +# If the GENERATE_AUTOGEN_DEF tag is set to YES, doxygen will generate an +# AutoGen Definitions (see http://autogen.sf.net) file that captures the +# structure of the code including all documentation. Note that this feature is +# still experimental and incomplete at the moment. # The default value is: NO. GENERATE_AUTOGEN_DEF = NO @@ -1918,7 +2039,7 @@ GENERATE_AUTOGEN_DEF = NO # Configuration options related to the Perl module output #--------------------------------------------------------------------------- -# If the GENERATE_PERLMOD tag is set to YES doxygen will generate a Perl module +# If the GENERATE_PERLMOD tag is set to YES, doxygen will generate a Perl module # file that captures the structure of the code including all documentation. # # Note that this feature is still experimental and incomplete at the moment. @@ -1926,7 +2047,7 @@ GENERATE_AUTOGEN_DEF = NO GENERATE_PERLMOD = NO -# If the PERLMOD_LATEX tag is set to YES doxygen will generate the necessary +# If the PERLMOD_LATEX tag is set to YES, doxygen will generate the necessary # Makefile rules, Perl scripts and LaTeX code to be able to generate PDF and DVI # output from the Perl module output. # The default value is: NO. @@ -1934,9 +2055,9 @@ GENERATE_PERLMOD = NO PERLMOD_LATEX = NO -# If the PERLMOD_PRETTY tag is set to YES the Perl module output will be nicely +# If the PERLMOD_PRETTY tag is set to YES, the Perl module output will be nicely # formatted so it can be parsed by a human reader. This is useful if you want to -# understand what is going on. On the other hand, if this tag is set to NO the +# understand what is going on. On the other hand, if this tag is set to NO, the # size of the Perl module output will be much smaller and Perl will parse it # just the same. # The default value is: YES. @@ -1956,14 +2077,14 @@ PERLMOD_MAKEVAR_PREFIX = # Configuration options related to the preprocessor #--------------------------------------------------------------------------- -# If the ENABLE_PREPROCESSING tag is set to YES doxygen will evaluate all +# If the ENABLE_PREPROCESSING tag is set to YES, doxygen will evaluate all # C-preprocessor directives found in the sources and include files. # The default value is: YES. ENABLE_PREPROCESSING = YES -# If the MACRO_EXPANSION tag is set to YES doxygen will expand all macro names -# in the source code. If set to NO only conditional compilation will be +# If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names +# in the source code. If set to NO, only conditional compilation will be # performed. Macro expansion can be done in a controlled way by setting # EXPAND_ONLY_PREDEF to YES. # The default value is: NO. @@ -1979,7 +2100,7 @@ MACRO_EXPANSION = NO EXPAND_ONLY_PREDEF = NO -# If the SEARCH_INCLUDES tag is set to YES the includes files in the +# If the SEARCH_INCLUDES tag is set to YES, the include files in the # INCLUDE_PATH will be searched if a #include is found. # The default value is: YES. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. @@ -2056,20 +2177,21 @@ TAGFILES = GENERATE_TAGFILE = -# If the ALLEXTERNALS tag is set to YES all external class will be listed in the -# class index. If set to NO only the inherited external classes will be listed. +# If the ALLEXTERNALS tag is set to YES, all external class will be listed in +# the class index. If set to NO, only the inherited external classes will be +# listed. # The default value is: NO. ALLEXTERNALS = NO -# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed in -# the modules index. If set to NO, only the current project's groups will be +# If the EXTERNAL_GROUPS tag is set to YES, all external groups will be listed +# in the modules index. If set to NO, only the current project's groups will be # listed. # The default value is: YES. EXTERNAL_GROUPS = YES -# If the EXTERNAL_PAGES tag is set to YES all external pages will be listed in +# If the EXTERNAL_PAGES tag is set to YES, all external pages will be listed in # the related pages index. If set to NO, only the current project's pages will # be listed. # The default value is: YES. @@ -2086,7 +2208,7 @@ PERL_PATH = /usr/bin/perl # Configuration options related to the dot tool #--------------------------------------------------------------------------- -# If the CLASS_DIAGRAMS tag is set to YES doxygen will generate a class diagram +# If the CLASS_DIAGRAMS tag is set to YES, doxygen will generate a class diagram # (in HTML and LaTeX) for classes with base or super classes. Setting the tag to # NO turns the diagrams off. Note that this option also works with HAVE_DOT # disabled, but it is recommended to install and use dot, since it yields more @@ -2111,7 +2233,7 @@ MSCGEN_PATH = DIA_PATH = -# If set to YES, the inheritance and collaboration graphs will hide inheritance +# If set to YES the inheritance and collaboration graphs will hide inheritance # and usage relations if the target is undocumented or is not a class. # The default value is: YES. @@ -2184,7 +2306,7 @@ COLLABORATION_GRAPH = YES GROUP_GRAPHS = YES -# If the UML_LOOK tag is set to YES doxygen will generate inheritance and +# If the UML_LOOK tag is set to YES, doxygen will generate inheritance and # collaboration diagrams in a style similar to the OMG's Unified Modeling # Language. # The default value is: NO. @@ -2236,7 +2358,8 @@ INCLUDED_BY_GRAPH = YES # # Note that enabling this option will significantly increase the time of a run. # So in most cases it will be better to enable call graphs for selected -# functions only using the \callgraph command. +# functions only using the \callgraph command. Disabling a call graph can be +# accomplished by means of the command \hidecallgraph. # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2247,7 +2370,8 @@ CALL_GRAPH = YES # # Note that enabling this option will significantly increase the time of a run. # So in most cases it will be better to enable caller graphs for selected -# functions only using the \callergraph command. +# functions only using the \callergraph command. Disabling a caller graph can be +# accomplished by means of the command \hidecallergraph. # The default value is: NO. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2270,13 +2394,17 @@ GRAPHICAL_HIERARCHY = YES DIRECTORY_GRAPH = YES # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images -# generated by dot. +# generated by dot. For an explanation of the image formats see the section +# output formats in the documentation of the dot tool (Graphviz (see: +# http://www.graphviz.org/)). # Note: If you choose svg you need to set HTML_FILE_EXTENSION to xhtml in order # to make the SVG files visible in IE 9+ (other browsers do not have this # requirement). # Possible values are: png, png:cairo, png:cairo:cairo, png:cairo:gd, png:gd, # png:gd:gd, jpg, jpg:cairo, jpg:cairo:gd, jpg:gd, jpg:gd:gd, gif, gif:cairo, -# gif:cairo:gd, gif:gd, gif:gd:gd and svg. +# gif:cairo:gd, gif:gd, gif:gd:gd, svg, png:gd, png:gd:gd, png:cairo, +# png:cairo:gd, png:cairo:cairo, png:cairo:gdiplus, png:gdiplus and +# png:gdiplus:gdiplus. # The default value is: png. # This tag requires that the tag HAVE_DOT is set to YES. @@ -2324,10 +2452,19 @@ DIAFILE_DIRS = # PlantUML is not used or called during a preprocessing step. Doxygen will # generate a warning when it encounters a \startuml command in this case and # will not generate output for the diagram. -# This tag requires that the tag HAVE_DOT is set to YES. PLANTUML_JAR_PATH = +# When using plantuml, the PLANTUML_CFG_FILE tag can be used to specify a +# configuration file for plantuml. + +PLANTUML_CFG_FILE = + +# When using plantuml, the specified paths are searched for files specified by +# the !include statement in a plantuml block. + +PLANTUML_INCLUDE_PATH = + # The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of nodes # that will be shown in the graph. If the number of nodes in a graph becomes # larger than this value, doxygen will truncate the graph, which is visualized @@ -2364,7 +2501,7 @@ MAX_DOT_GRAPH_DEPTH = 0 DOT_TRANSPARENT = NO -# Set the DOT_MULTI_TARGETS tag to YES allow dot to generate multiple output +# Set the DOT_MULTI_TARGETS tag to YES to allow dot to generate multiple output # files in one run (i.e. multiple -o and -T options on the command line). This # makes dot run faster, but since only newer versions of dot (>1.8.10) support # this, this feature is disabled by default. @@ -2381,7 +2518,7 @@ DOT_MULTI_TARGETS = YES GENERATE_LEGEND = YES -# If the DOT_CLEANUP tag is set to YES doxygen will remove the intermediate dot +# If the DOT_CLEANUP tag is set to YES, doxygen will remove the intermediate dot # files that are used to generate the various graphs. # The default value is: YES. # This tag requires that the tag HAVE_DOT is set to YES. diff --git a/docs/PACKAGING-GTK b/docs/PACKAGING-GTK index 7436f238e..b81bc6162 100644 --- a/docs/PACKAGING-GTK +++ b/docs/PACKAGING-GTK @@ -29,11 +29,8 @@ checkouts smaller and making sure changes to one set of resources updates the other. - The binary that the build system produces is called "nsgtk". There is also - a shell script called "netsurf" that will set up the environment and launch - the nsgtk binary. Do not ship this shell script with your package. It is - included only as a convience for launching NetSurf from the build tree. - Instead, you should move nsgtk to /usr/bin/netsurf (or wherever your + The binary that the build system produces is called "nsgtk3". + You should install nsgtk3 to `/usr/bin/netsurf` (or wherever your distribution's packaging policy suggests) and copy the contents of gtk/res/ (dereferencing the symlinks, obviously) to /usr/share/netsurf (or wherever your packaging policy suggests). @@ -67,18 +64,19 @@ =================== You may also want to change NetSurf's user agent string to include the - name of your distribution. The user agent string is build by a function + name of your distribution. The user agent string is built by a function kept in utils/useragent.c - you'll want to change the macro called NETSURF_UA_FORMAT_STRING. It's processed via sprintf, so keep that in - mind when changing it. The first two printf parameters are major and minor - version numbers, the second two are OS name (uname -s) and architecture - (uname -m). You might want change this to something like: + mind when changing it. The first format parameter is the OS name (uname -s) + and the remainder are major and minor version numbers. You might want + to change this to something like: - "NetSurf/%d.%d (%s; %s; Debian GNU/Linux)" + "Mozilla/5.0 (%s; Debian GNU/Linux) NetSurf/%d.%d" - or similar. Please don't be tempted to mention Mozilla or similar - let's - let that lie die. + or similar. + Note that the "Mozilla/5.0" prefix is a requirement to enable modern + web standards on many websites. It should not be removed or modified. Home page URL =============== diff --git a/docs/UnimplementedJavascript.md b/docs/UnimplementedJavascript.md index 343c39950..0d21dc852 100644 --- a/docs/UnimplementedJavascript.md +++ b/docs/UnimplementedJavascript.md @@ -48,15 +48,7 @@ getter | UIEvent::view(user); getter | UIEvent::detail(long); method | CompositionEvent::initCompositionEvent(); getter | CompositionEvent::data(string); -method | KeyboardEvent::getModifierState(); method | KeyboardEvent::initKeyboardEvent(); -getter | KeyboardEvent::key(string); -getter | KeyboardEvent::code(string); -getter | KeyboardEvent::location(unsigned long); -getter | KeyboardEvent::ctrlKey(boolean); -getter | KeyboardEvent::shiftKey(boolean); -getter | KeyboardEvent::altKey(boolean); -getter | KeyboardEvent::metaKey(boolean); getter | KeyboardEvent::repeat(boolean); getter | KeyboardEvent::isComposing(boolean); getter | KeyboardEvent::charCode(unsigned long); @@ -178,10 +170,6 @@ getter | Element::namespaceURI(string); getter | Element::prefix(string); getter | Element::localName(string); getter | Element::tagName(string); -getter | Element::classList(user); -getter | Element::attributes(user); -getter | Element::innerHTML(string); -setter | Element::innerHTML(string); getter | Element::outerHTML(string); setter | Element::outerHTML(string); getter | Element::children(user); @@ -552,9 +540,6 @@ getter | DrawingStyle::textBaseline(string); setter | DrawingStyle::textBaseline(string); getter | DrawingStyle::direction(string); setter | DrawingStyle::direction(string); -getter | ImageData::width(unsigned long); -getter | ImageData::height(unsigned long); -getter | ImageData::data(user); getter | TextMetrics::width(double); getter | TextMetrics::actualBoundingBoxLeft(double); getter | TextMetrics::actualBoundingBoxRight(double); @@ -600,9 +585,6 @@ method | CanvasRenderingContext2D::drawImage(); method | CanvasRenderingContext2D::addHitRegion(); method | CanvasRenderingContext2D::removeHitRegion(); method | CanvasRenderingContext2D::clearHitRegions(); -method | CanvasRenderingContext2D::createImageData(); -method | CanvasRenderingContext2D::getImageData(); -method | CanvasRenderingContext2D::putImageData(); method | CanvasRenderingContext2D::setLineDash(); method | CanvasRenderingContext2D::getLineDash(); method | CanvasRenderingContext2D::closePath(); @@ -614,11 +596,6 @@ method | CanvasRenderingContext2D::arcTo(); method | CanvasRenderingContext2D::rect(); method | CanvasRenderingContext2D::arc(); method | CanvasRenderingContext2D::ellipse(); -getter | CanvasRenderingContext2D::canvas(user); -getter | CanvasRenderingContext2D::width(unsigned long); -setter | CanvasRenderingContext2D::width(unsigned long); -getter | CanvasRenderingContext2D::height(unsigned long); -setter | CanvasRenderingContext2D::height(unsigned long); getter | CanvasRenderingContext2D::currentTransform(user); setter | CanvasRenderingContext2D::currentTransform(user); getter | CanvasRenderingContext2D::globalAlpha(double); @@ -660,16 +637,11 @@ setter | CanvasRenderingContext2D::textBaseline(string); getter | CanvasRenderingContext2D::direction(string); setter | CanvasRenderingContext2D::direction(string); method | CanvasProxy::setContext(); -method | HTMLCanvasElement::getContext(); method | HTMLCanvasElement::probablySupportsContext(); method | HTMLCanvasElement::setContext(); method | HTMLCanvasElement::transferControlToProxy(); method | HTMLCanvasElement::toDataURL(); method | HTMLCanvasElement::toBlob(); -getter | HTMLCanvasElement::width(unsigned long); -setter | HTMLCanvasElement::width(unsigned long); -getter | HTMLCanvasElement::height(unsigned long); -setter | HTMLCanvasElement::height(unsigned long); getter | HTMLTemplateElement::content(user); getter | HTMLScriptElement::async(boolean); setter | HTMLScriptElement::async(boolean); @@ -1365,14 +1337,6 @@ method | HTMLAllCollection::namedItem(); getter | HTMLAllCollection::length(unsigned long); method | XMLSerializer::serializeToString(); method | DOMParser::parseFromString(); -method | DOMTokenList::item(); -method | DOMTokenList::contains(); -method | DOMTokenList::add(); -method | DOMTokenList::remove(); -method | DOMTokenList::toggle(); -getter | DOMTokenList::length(unsigned long); -getter | DOMSettableTokenList::value(string); -setter | DOMSettableTokenList::value(string); method | NodeFilter::acceptNode(); method | TreeWalker::parentNode(); method | TreeWalker::firstChild(); @@ -1451,17 +1415,13 @@ getter | Attr::textContent(string); setter | Attr::textContent(string); getter | Attr::ownerElement(user); getter | Attr::specified(boolean); -method | NamedNodeMap::item(); -method | NamedNodeMap::getNamedItem(); method | NamedNodeMap::getNamedItemNS(); method | NamedNodeMap::setNamedItem(); method | NamedNodeMap::setNamedItemNS(); method | NamedNodeMap::removeNamedItem(); method | NamedNodeMap::removeNamedItemNS(); -getter | NamedNodeMap::length(unsigned long); method | DOMImplementation::createDocumentType(); method | DOMImplementation::createDocument(); -method | DOMImplementation::createHTMLDocument(); method | DOMImplementation::hasFeature(); method | Document::getElementsByTagNameNS(); method | Document::getElementsByClassName(); @@ -1494,7 +1454,6 @@ method | Document::query(); method | Document::queryAll(); method | Document::querySelector(); method | Document::querySelectorAll(); -getter | Document::implementation(user); getter | Document::URL(string); getter | Document::documentURI(string); getter | Document::origin(string); @@ -1506,7 +1465,6 @@ getter | Document::doctype(user); getter | Document::domain(string); setter | Document::domain(string); getter | Document::referrer(string); -setter | Document::cookie(string); getter | Document::lastModified(string); getter | Document::readyState(user); getter | Document::title(string); @@ -1587,5 +1545,5 @@ method | EventListener::handleEvent(); method | CustomEvent::initCustomEvent(); getter | CustomEvent::detail(any); - 1581 unimplemented bindings + 1539 unimplemented bindings diff --git a/docs/building-GTK.md b/docs/building-GTK.md index dd1b7e2f3..aa898a04d 100644 --- a/docs/building-GTK.md +++ b/docs/building-GTK.md @@ -171,13 +171,10 @@ below. Or turn off the complaining features in a Makefile.config file. You may need to "make clean" before attempting to build after installing the dependencies. -Run NetSurf by executing the "test-nsgtk" shell script: +Run NetSurf by executing "nsgtk3": - $ ./test-nsgtk + $ ./nsgtk3 -This script makes it easy to run the nsgtk binary from the build tree. It -sets up some environment variables which enable NetSurf to find its -resources. ### Builtin resources diff --git a/docs/core-window-interface.md b/docs/core-window-interface.md index 8f6951f9f..1b389d916 100644 --- a/docs/core-window-interface.md +++ b/docs/core-window-interface.md @@ -10,7 +10,7 @@ The currently available user interfaces are: - Cookies - Global history - Hotlist - - SSL certificate view + - SSL certificate view (obsolete, but used as an example here) - local history Although not currently included in future additional user interfaces diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 000000000..3f08b5496 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,123 @@ +Development +=========== + +[TOC] + +# Working with the team + +Generally it is sensible to check with the other developers if you are +planning to make a change to NetSurf intended to be merged. + +We are often about on the IRC channel but failing that the developer +mailing list is a good place to try. + +All the project sources are held in [public git repositories](http://source.netsurf-browser.org/) + +# Compilation environment + +Compiling a development edition of NetSurf requires a POSIX style +environment. Typically this means a Linux based system although Free +BSD, Open BSD, Mac OS X and Haiku all known to work. + +## Toolchains + +Compilation for non POSIX toolkits/frontends (e.g. RISC OS) generally +relies upon a cross compilation environment which is generated using +the makefiles found in our +[toolchains](http://source.netsurf-browser.org/toolchains.git/) +repository. These toolchains are built by the Continuous Integration +(CI) system and the +[results of the system](http://ci.netsurf-browser.org/builds/toolchains/) +are published as a convenience. + +## Quick setup + +The [quick start guide](docs/quick-start.md) can be used to get a +development environment setup quickly and uses the +[env.sh](env_8sh_source.html) script the core team utilises. + +## Manual setup + +The Manual environment setup and compilation method is covered by the +details in the [netsurf libraries](docs/netsurf-libraries.md) document +for the core libraries and then one of the building documents for the +specific frontend. + +- [Amiga Os cross](docs/building-AmigaCross.md) and [Amiga OS](docs/building-AmigaOS.md) +- [Framebuffer](docs/building-Framebuffer.md) +- [GTK](docs/building-GTK.md) +- [Haiku (BeOS)](docs/building-Haiku.md) +- [Windows Win32](docs/building-Windows.md) + +These documents are sometimes not completely up to +date and the env.sh script should be considered canonical. + +# Logging + +The [logging](docs/logging.md) interface controls debug and error +messages not output through the GUI. + +# Unit testing + +NetSurf [unit tests](docs/unit-testing.md) provide basic test coverage +of many core parts of the browser code such as url parsing and utility +functions. + +# Integration testing + +NetSurf [integration tests](docs/integration-testing.md) use the +monkey frontend to operate the browser as a whole. These tests open +windows, navigate to websites and render contents as a user might. + +# New frontend development + +[Implementing a new frotend](docs/implementing-new-frontend.md) for a +toolkit can be challenging and this guide provides an overview and +worked example. + +# Documented API + +The NetSurf code makes use of Doxygen for code documentation. + +There are several documents which detail specific aspects of the +codebase and APIs. + +## Core window + +The [core window API](docs/core-window-interface.md) allows frontends +to use generic core code for user interface elements beyond the +browser render. + +## Source object caching + +The [source object caching](docs/source-object-backing-store.md) +provides a way for downloaded content to be kept on a persistent +storage medium such as hard disc to make future retrieval of that +content quickly. + +# Javascript + +Javascript provision is split into four parts: +- An engine that takes source code and executes it. +- Interfaces between the program and the web page. +- Browser support to retrieve and manage the source code to be executed. +- Browser support for the dispatch of events from user interface. + +## Library + +JavaScript is provided by integrating the duktape library. There are +[instructions](docs/updating-duktape.md) on how to update the library. + +## Interface binding + +In order for javascript programs to to interact with the page contents +it must use the Document Object Model (DOM) and Cascading Style Sheet +Object Model (CSSOM) API. + +These interfaces are described using web Interface Description +Language (IDL) within the relevant specifications +(e.g. https://dom.spec.whatwg.org/). + +Each interface described by the webIDL must be bound (connected) to +the browsers internal representation for the DOM or CSS, etc. The +process of [writing bindings](docs/jsbinding.md) is ongoing. diff --git a/docs/env.sh b/docs/env.sh index 3b0f24927..4cb056ec1 100644 --- a/docs/env.sh +++ b/docs/env.sh @@ -198,7 +198,7 @@ if [ "x${HOST}" = "x" ]; then HOST=${TARGET_ABI} fi else - HOST_CC_LIST="${HOST}-cc ${HOST}-gcc /opt/netsurf/${HOST}/cross/bin/${HOST}-cc /opt/netsurf/${HOST}/cross/bin/${HOST}-gcc" + HOST_CC_LIST="/opt/netsurf/${HOST}/cross/bin/${HOST}-cc /opt/netsurf/${HOST}/cross/bin/${HOST}-gcc ${HOST}-cc ${HOST}-gcc" for HOST_CC_V in $(echo ${HOST_CC_LIST});do HOST_CC=$(${WHICH_CMD} ${HOST_CC_V}) if [ "x${HOST_CC}" != "x" ];then @@ -213,9 +213,13 @@ else HOST_CC_MACHINE=$(${HOST_CC} -dumpmachine 2>/dev/null) if [ "${HOST_CC_MACHINE}" != "${HOST}" ];then - echo "Compiler dumpmachine differes from HOST setting" + echo "Compiler dumpmachine differs from HOST setting" return 2 fi + + NS_ENV_CC="${HOST_CC}" + export NS_ENV_CC + unset HOST_CC_LIST HOST_CC_V HOST_CC HOST_CC_MACHINE fi @@ -259,64 +263,81 @@ NS_GIT="git://git.netsurf-browser.org" # Buildsystem: everything depends on this NS_BUILDSYSTEM="buildsystem" -# internal libraries all frontends require (order is important) -NS_INTERNAL_LIBS="libwapcaplet libparserutils libhubbub libdom libcss libnsgif libnsbmp libutf8proc libnsutils libnspsl libnslog" +NS_TOOLS="" +NS_FRONTEND_LIBS="" -# The browser itself -NS_BROWSER="netsurf" +BUILD_TARGET="${TARGET:-netsurf}" - -# add target specific libraries -case "${HOST}" in - i586-pc-haiku) - # tools required to build the browser for haiku (beos) - NS_TOOLS="nsgenbind" - # libraries required for the haiku target abi - NS_FRONTEND_LIBS="libsvgtiny" - ;; - *arwin*) - # tools required to build the browser for OS X - NS_TOOLS="" - # libraries required for the Darwin target abi - NS_FRONTEND_LIBS="libsvgtiny libnsfb" - ;; - arm-unknown-riscos) - # tools required to build the browser for RISC OS - NS_TOOLS="nsgenbind" - # libraries required for the risc os target abi - NS_FRONTEND_LIBS="libsvgtiny librufl libpencil librosprite" - ;; - *-atari-mint) - # tools required to build the browser for atari - NS_TOOLS="" - # libraries required for the atari frontend - NS_FRONTEND_LIBS="" - ;; - ppc-amigaos) - # default tools required to build the browser - NS_TOOLS="nsgenbind" - # default additional internal libraries - NS_FRONTEND_LIBS="libsvgtiny" +case "$BUILD_TARGET" in + libhubbub) + NS_INTERNAL_LIBS="libparserutils" ;; - m68k-unknown-amigaos) - # default tools required to build the browser - NS_TOOLS="nsgenbind" - # default additional internal libraries - NS_FRONTEND_LIBS="libsvgtiny" + + libdom) + NS_INTERNAL_LIBS="libwapcaplet libparserutils libhubbub" ;; - *-unknown-freebsd*) - # tools required to build the browser for freebsd - NS_TOOLS="" - # libraries required for the freebsd frontend - NS_FRONTEND_LIBS="" - # select gnu make - MAKE=gmake + + libcss) + NS_INTERNAL_LIBS="libwapcaplet libparserutils" ;; - *) - # default tools required to build the browser - NS_TOOLS="nsgenbind" - # default additional internal libraries - NS_FRONTEND_LIBS="libsvgtiny libnsfb" + + netsurf) + # internal libraries all frontends require (order is important) + NS_INTERNAL_LIBS="libwapcaplet libparserutils libhubbub libdom libcss libnsgif libnsbmp libutf8proc libnsutils libnspsl libnslog" + + # add target specific libraries + case "${HOST}" in + i586-pc-haiku) + # tools required to build the browser for haiku (beos) + NS_TOOLS="nsgenbind" + # libraries required for the haiku target abi + NS_FRONTEND_LIBS="libsvgtiny" + ;; + *arwin*) + # tools required to build the browser for OS X + NS_TOOLS="" + # libraries required for the Darwin target abi + NS_FRONTEND_LIBS="libsvgtiny libnsfb" + ;; + arm-unknown-riscos|arm-riscos-gnueabi*) + # tools required to build the browser for RISC OS + NS_TOOLS="nsgenbind" + # libraries required for the risc os target abi + NS_FRONTEND_LIBS="libsvgtiny librufl libpencil librosprite" + ;; + *-atari-mint) + # tools required to build the browser for atari + NS_TOOLS="" + # libraries required for the atari frontend + NS_FRONTEND_LIBS="" + ;; + ppc-amigaos) + # default tools required to build the browser + NS_TOOLS="nsgenbind" + # default additional internal libraries + NS_FRONTEND_LIBS="libsvgtiny" + ;; + m68k-unknown-amigaos) + # default tools required to build the browser + NS_TOOLS="nsgenbind" + # default additional internal libraries + NS_FRONTEND_LIBS="libsvgtiny" + ;; + *-unknown-freebsd*) + # tools required to build the browser for freebsd + NS_TOOLS="" + # libraries required for the freebsd frontend + NS_FRONTEND_LIBS="" + # select gnu make + MAKE=gmake + ;; + *) + # default tools required to build the browser + NS_TOOLS="nsgenbind" + # default additional internal libraries + NS_FRONTEND_LIBS="libsvgtiny libnsfb" + ;; + esac ;; esac @@ -327,7 +348,7 @@ export MAKE # git pull in all repos parameters are passed to git pull ns-pull() { - for REPO in $(echo ${NS_BUILDSYSTEM} ${NS_INTERNAL_LIBS} ${NS_FRONTEND_LIBS} ${NS_TOOLS} ${NS_BROWSER}) ; do + for REPO in $(echo ${NS_BUILDSYSTEM} ${NS_INTERNAL_LIBS} ${NS_FRONTEND_LIBS} ${NS_TOOLS} ${BUILD_TARGET}) ; do echo -n " GIT: Pulling ${REPO}: " if [ -f "${TARGET_WORKSPACE}/${REPO}/.git/config" ]; then (cd ${TARGET_WORKSPACE}/${REPO} && git pull $*; ) @@ -340,19 +361,42 @@ ns-pull() # clone all repositories ns-clone() { + SHALLOW="" + SKIP="" + while [ $# -gt 0 ] + do + case "$1" in + -d | --deps-only) SKIP="${BUILD_TARGET}" + shift + ;; + -s | --shallow) SHALLOW="--depth 1" + shift + ;; + -*) echo "Error: Unknown option: $1" >&2 + exit 1 + ;; + *) # No more options + break + ;; + esac + done + mkdir -p ${TARGET_WORKSPACE} - for REPO in $(echo ${NS_BUILDSYSTEM} ${NS_INTERNAL_LIBS} ${NS_FRONTEND_LIBS} ${NS_RISCOS_LIBS} ${NS_TOOLS} ${NS_BROWSER}) ; do + for REPO in $(echo ${NS_BUILDSYSTEM} ${NS_INTERNAL_LIBS} ${NS_FRONTEND_LIBS} ${NS_RISCOS_LIBS} ${NS_TOOLS} ${BUILD_TARGET}) ; do + [ "x${REPO}" != "x${SKIP}" ] || continue echo -n " GIT: Cloning ${REPO}: " if [ -f ${TARGET_WORKSPACE}/${REPO}/.git/config ]; then echo "Repository already present" else - (cd ${TARGET_WORKSPACE} && git clone ${NS_GIT}/${REPO}.git; ) + (cd ${TARGET_WORKSPACE} && git clone ${SHALLOW} ${NS_GIT}/${REPO}.git; ) fi done # put current env.sh in place in workspace - if [ ! -f "${TARGET_WORKSPACE}/env.sh" -a -f ${TARGET_WORKSPACE}/${NS_BROWSER}/docs/env.sh ]; then - cp ${TARGET_WORKSPACE}/${NS_BROWSER}/docs/env.sh ${TARGET_WORKSPACE}/env.sh + if [ "x$NS_BROWSER" = "x" ]; then + if [ ! -f "${TARGET_WORKSPACE}/env.sh" -a -f ${TARGET_WORKSPACE}/${NS_BROWSER}/docs/env.sh ]; then + cp ${TARGET_WORKSPACE}/${NS_BROWSER}/docs/env.sh ${TARGET_WORKSPACE}/env.sh + fi fi } diff --git a/docs/gource.sh b/docs/gource.sh index a1fbcbe13..6f12b3ddb 100755 --- a/docs/gource.sh +++ b/docs/gource.sh @@ -23,7 +23,7 @@ OUTPUT_SIZE="1280x720" # HD widescreen 1080p #OUTPUT_SIZE="1280x1080" -TMP_DIR=/net/holly/srv/video/Unsorted/ +TMP_DIR=/home/video/gource/ ###################################################################### @@ -60,7 +60,7 @@ TMP_PPM=${TMP_DIR}/${TITLE}-gource-${TYPE}-${OUTPUT_SIZE}-${CMODE}.ppm FILENAME=${TITLE}-gource-${TYPE}-${OUTPUT_SIZE}-${CMODE}.mp4 # filter some directories which are not interesting -FILEFILTER="\!NetSurf/|riscos/distribution/|gtk/res/|framebuffer/res/|amiga/resources/|beos/res/|cocoa/res/|windows/res/|atari/res" +FILEFILTER="\!NetSurf/|riscos/distribution/|gtk/res/|framebuffer/res/|amiga/resources/|beos/res/|cocoa/res/|windows/res/|atari/res|riscos/appdir/" # generate gource --title "NetSurf Development" -${OUTPUT_SIZE} ${QPARAM} --max-files 10000 --bloom-multiplier 0.10 --bloom-intensity 0.5 --title ${TITLE} --highlight-all-users --output-framerate 25 --hide filenames --stop-at-end --date-format "%d %B %Y" --bloom-intensity 0.2 --file-filter "${FILEFILTER}" --key --camera-mode ${CMODE} --output-ppm-stream - > ${TMP_PPM} diff --git a/docs/implementing-new-frontend.md b/docs/implementing-new-frontend.md new file mode 100644 index 000000000..4bda47af0 --- /dev/null +++ b/docs/implementing-new-frontend.md @@ -0,0 +1,413 @@ +Implementing a new frontend +=========================== + +[TOC] + +# Introduction + +NetSurf is divided into a series of frontends which provide a user +interface around common core functionality. + +Each frontend is a distinct implementation for a specific GUI toolkit. + +The existing frontends are covered in the [user +interface](docs/user-interface.md) documentation. + +Note implementing a new frontend implies using a toolkit distinct from +one of those already implemented and is distinct from porting NetSurf +to a new operating system platform. + +It is recommend, in the strongest terms, that if the prospective +developer is porting to both a new platform and toolkit that they +*start* by getting the [monkey](docs/using-monkey.md) frontend +building and passing at least the basic integration tests on their +platform. + +Experience has shown that attempting to port to a platform and +implement a toolkit at the same time generally results in failure to +achieve either goal. + +NetSurf is built using GNU make and frontends are expected to +integrate with this buildsystem. + +Implementation languages have historically been limited to C, C++ and +objective C. However any language that can call C functions and +*importantly* be called back from C code ought to be usable. For +example there have been experiments with JAVA using JNI but no current +frontend is implemented using it. + +# Implementation complexity + +An absolutely minimal "proof of concept" frontend implementation (like +the FLTK frontend that will be used as an example) is around 1,000 +lines of C code. Basic functionality like the windows frontend is +around 7,000 lines. A complete fully functional frontend such as the +one for GTK is closer to 15,000 lines. + +It should be noted the majority of the minimal implementation can +simply be copied and the names changed as appropriate from an existing +example. The actual amount of new code that needs to be provided is +very small. + +NetSurf provides a great deal of generic functionality for things like +cookie, bookmark, history windows which require only minimal frontend +support with the [core window API](docs/core-window-interface.md). + +A frontend developer is free to implement any and all of this generic +functionality thelselves in a manner more integrated into a toolkit. + +# Implementation + +A frontend is generally named for the toolkit it is implementing (i.e +gtk for the GTK+ toolkit). It is advisable to be as specific as +possible e.g. the frontend for the windows operating system should +have been named win32 allowing for an impementation using a differnt +toolkit (e.g mfc) + +All the files needed for the frontend are contained in a single +sub-directory in the NetSurf source tree e.g. `frontends/fltk` + +The only file outside this directory that much be changed is the +`frontends/Makefile.hts` where a new entry must be added to the valid +targets list. + +## Build system + +A frontend must provide three GNU Makefile fragments (these will be +included from the core Makefile): + + - `Makefile` - This is used to extend CFLAGS, CXXFLAGS and LDFLAGS variables as required. The executable target is set with EXETARGET and the browser source files are listed in the SOURCES variable + - `Makefile.defaults` - allows setting frontend specific makefile variables and overriding of the default core build variables. + - `Makefile.tools` - allows setting up frontend specific build tooling (as a minimum a tool for the package configuration in PKG_CONFIG) + +Source code modules can be named as the devloper desires within the +frontend directory and should be added to the SOURCES variable as +desired. + +## Program entry + +Generally the entry point from the OS is the `main()` function and +several frontends have a `main.cpp` where some have used `gui.c`. + +The usual shape for the `main()` function is a six step process: + 1. The frontends operation tables are registered with NetSurf + 2. The toolkit specific initialisation is performed (which may involve calling NetSurf provided utility functions for support operations like logging, message translations etc.) + 3. Initialise the NetSurf core. After this point all browser functionality is available and registered operations can be called. + 4. Perform toolkiit setup, usually opening the initial browsing window (perhaps according to user preferences) + 5. Run the toolkits main loop while ensuring the Netsurf scheduled operations are also run at teh apropriate time. + 6. Finalisation on completion. + +## NetSurf operations tables + +The frontend will generally call netsurf interfaces to get a desired +behaviour e.g. `browser_window_create()` to create a new browsing +context (the `browser_window_` prefix is historical and does not +necessarily create a window e.g. on gtk it is more likely to open a +tab in an existing window). To achive the desired operation some +operations need to be performed by the frontend under control of +NetSurf, these operations are listed in tables. + +The operation tables should be registered with the NetSurf core as one +of the first operations of the frontend code. The functions in these +tables (and the tables themselves) must remain valid until +`netsurf_exit()` is called. + +There are (currently) twelve sets of operation tables held in separate +structures. Only five of these are mandantory (misc, window, fetch, +bitmap and layout). + +In this context mandantory means the tables must be non NULL and do +not have a suitable default. Each of the mandantory sets contain +function pointers to implement operations. + +### misc operation table + +The only mandantory operation in this table is schedule. + +When schedule is called the frontend must arrange for the passed +callback to be called with the context parameter after a number of +miliseconds. + +This callback is typicaly driven through the toolkits event loop and +it is important such callbacks are not attempted from an operation. + +### window operation table + +The window operations (poorly named as already mentioned) are where +the frontend is called to actually manipulate widgets in the +toolkit. This is mediated through a `gui_window` context pointer which +is typed as a structure. + +This context pointer is passed to all window operations and is +generally assumed to contain at least a reference to the underlying +`browser_window` which is provided in the initial create operation to +allow subsequent use of various core functionality. + +The mandantory window operations are: + - create - create a new browsing context widget in the frontend toolkit + - destroy - destoy a previously created `gui_window` + - invalidate - mark an area of the browsing context viewport as requiring redraw (note no redraw should be attempted from here) + - get_scroll - get the scroll offsets from the toolkit drawing widget + - set_scroll - set the scroll offsets on the toolkit drawing widget + - get_dimensions - get the dimensions of the toolkit drawing widget + - event - deal with various window events from netsurf which have no additional parameters + + +### fetch operation table + +The fetch operations allow the built in scheme fetchers (file, about, resource) to obtain additional information necessary to complete their operation. + +The two mandantory operations are: + - `filetype` - allows the file scheme to obtain a mime type from a file path e.g. `a.file.name.png` would result in `image/png` + - `get_resource_url` - maps resource scheme paths to URL e.g. `resource:default.css` to `file:///usr/share/netsurf/default.css` + +### bitmap operation table + +The bitmap table and all of its operations are mandantory only because +the empty defaults have not been included as it is assumed a browser +will want to display images. + +All operations may be provided by stubs that return the failure codes +until full implementations are made. + +### layout operation table + +The layout table is used to layout text. All operations are given +strings to manipulate encoded in UTF-8. There are three mandantory +operations: + - `width` - Calculate the width of a string. + - `position` - Find the position in a string where an x coordinate falls. + - `split` - Find where to split a string to make it fit a width. + +# Worked Example + +Rather than attempt to describe every aspect of an implementation we +will rather work from an actual minimal example for the FLTK toolkit. + +This is availble as a single commit (`git show 28ecbf82ed3024f51be4c87928fd91bacfc15cbc`) in the NetSurf source repository. Alternatively it can be [viewed in a web browser](https://git.netsurf-browser.org/netsurf.git/commit/?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc). + +This represents the absolute minimum implementation to get a browser +window on screen (and be able to click visible links). It is +implemented in C++ as that is the FLTK implementation language but an +equivalent implementation in other languages should be obvious. + +## Building + +The [frontends/Makefile.hts](https://git.netsurf-browser.org/netsurf.git/diff/frontends/Makefile.hts?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc) +had the fltk target added to the VLDTARGET variable. This allows +NetSurf to be built for this frontend with `make TARGET=fltk` + +As previously described the three GNU Make files are added: + +[Makefile](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/Makefile?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc) +this shows how the flags are extended to add the fltk headers and +library. Additionaly the list of sources are built here, as teh +comment suggests it is important the SOURCES variable is not expanded +here so the S_FRONTEND variable is used to allow expansion at teh +correct time in the build process. + +[Makefile.defaults](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/Makefile.defaults?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc) +has the default setting to control the build parameters and file locations. These can be overriden by the `Makefile.config` at compile time. + +[Makefile.tools](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/Makefile.tools?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc) +allows the configuration of additional tools necessary to build for the target as a minimum pkg-config is usually required to find libraries. + +## Program entry + +In our example program entry is the classical `main()` in the [main.cpp](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/main.cpp?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc) module. + +This implements the six stage process outlined previously. + +### Operations table registration + +The `netsurf_table` structure is initialised and passed to +`netsurf_register()`. It should be noted that the approach taken here +and in most frontends is to have a source module for each operation +table. The header for each module exposes just the pointer to the +indivial operation set, this allows for all the operation functions to +be static to their module and hence helps reduce global symbol usage. + +### Frontend specific initialisation + +Her it is implemented in `nsfltk_init()` this function performs all +the operations specific to the frontend which must be initialised +before netsurf itself. In some toolkits this would require calling the +toolkit initialisation (e.g. `gtk_init()`). + +It is nessesary to initialise netsurf logging and user options at this +point. A more fully featured implementation would also initialise the +message translation system here. + +### Netsurf initialisation + +This is simply the call to `netsurf_init()` from this point the +browser is fully operational and operations can and will be called. + +### Frontend specific startup + +Although the browser is running it has not yet been told to open a +window or navigate to a page. Here `nsfltk_start()` examines the +command line and environment to determine the initial page to navigate +to and calls `browser_window_create()` with the url, this will cause +the browser to open a new browsing context and start the navigation. + +A frontend may choose to implement more complex logic here but the +example here is a good start. + +### Toolkit run loop + +The function `nsfltk_run()` runs the toolkit event loop. In this case it is using the generic scheduleing in the [misc.cpp](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/misc.cpp?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc) module to ensure callbacks get made at the apropriate time. + +There is a `nsfltk_done` boolean global checked here so when all the +browser windows are closed the program will exit. + +A more fully featured port might use the toolkits scheduling rather +than open coding a solution with a linked list as is done +here. + +A futher optimisation would be to obtain the set of file descriptors +being used (with `fetch_fdset()`) for active fetches allowing for +activity based fetch progress instead of the fallback polling method. + +### finalisation + +This simply finalises the browser stopping all activity and cleaning +up any resource usage. After the call to `netsurf_exit()` no more +operation calls will be made and all caches used by the core will be +flushed. + +If user option chnages are to be made persistant `nsoption_finalise()` +should be called. + +The finalisation of logging will ensure that any output buffers are +flushed. + +## The window operation table + +Amongst all the boilerplate of the default implementation the only novel code is in the window operation table in the [window.cpp](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/window.cpp?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc) module. + +### `nsfltk_window_create` + +The create operation instansiates a new `NS_Window` object and +references it in the gui_window structure which it returns to the +caller. Technically we could simply return the `NS_Window` object as +the gui_window pointer but this implementation is avoiding the cast. + +Secondly `Fl_Double_Window` is subclassed as `NS_Widget`. The sublass +allows the close callback to be accessed so the global `nsfltk_done` +boolean can be set during the destructor method. + +The NS_Window creates an instance of `NS_Widget` in its constructor, a +more extensive implementation would add other window furniture here +(scroll bars, url bar, navigation elements, etc.) + +The implementation subclasses `Fl_Widget` implementing the draw +method to render the browsing context and the handle method to handle +mouse events to allow teh user to click. + +The `NS_Widget::handle()` method simply translates the mouse press +event from widget coordinates to netsurf canvas cooridinates and maps +teh mouse button state. The core is informed of these events using +`browser_window_mouse_click()` + +The `NS_Widget::draw` method similarly translates the fltk toolkits +clip rectangle, builds a plotting context and calls +`browser_window_redraw()` which will use the plotting operations in +the plotting context to render the browsing context within the area +specified. One thing to note here is the translation between the +coordinates of the render area and the internal page canvas given as +the second and third parameters to the draw call. When scrolling is +required this is achived by altering these offsets. + + +### `nsfltk_window_invalidate()` + +This simply calls the damage method on the `Fl_Widget` class with the +appropriate coordinate translation. + +### `nsfltk_window_get_dimensions()` + +This obtains the fltk widget width and height and returns them. + +## The plotting interface + +When the `NS_Widget::draw` method was discussed it was noted that a +plotting context is built containing an operation table. That table is +implemented in [plotters.cpp](https://git.netsurf-browser.org/netsurf.git/diff/frontends/fltk/plotters.cpp?h=vince/fltk&id=28ecbf82ed3024f51be4c87928fd91bacfc15cbc) + +The implementation here is as minimal as can be, only line, rectangle +and text have any implementation at all and even that simply sets a +colour and performs the appropriate fltk draw function (`fl_line`, +`fl_rect` and `fl_draw` respectively) + +# Worked Example next steps + +The previous section outlined the absolute minimum +implementation. Here we can exmaine some next steps taken to extend +the frontend. + +## Improving the user interface + +The example discussion is based on a commit (`git show bc546388ce428be5cfa37cecb174d549c7b30320`) in the NetSurf source repository. Alternatively it can be [viewed in a web browser](https://git.netsurf-browser.org/netsurf.git/commit/?h=vince/fltk&id=bc546388ce428be5cfa37cecb174d549c7b30320). + +This changes a single module `window.cpp` where the `NS_Window`, +`NS_Widget` and `NS_URLBar` classes are used to create a basic +browsing interface. + +The static window operation functions are moved inside the `NS_Window` +class and the `gui_window` structure is used to obtain an instance +allowing normal methods to be called to implement functionality. This +is purely to make the C++ code more idiomatic and obviously would be +handled differently in other languages. + +The `NS_Window` constructor builds additional widgets to just the +browser drawing widget. It creates: + - a URL bar widget containing some navigation buttons and a widget to show the current url + - a vertical scrollbar + - a horizontal scrollbar + - a status text widget + +The scrollbar widgets fltk callbacks (called when user interacts with +the scrollbar) call a method on the `NS_Widget` allowing it to track +the current scroll offsets which are subsequently used in the drawing +and user input handling methods. + +## Improving rendering + +Up to this point the rendering has been minimal and the text in a +single face and size with incorrect width measurement. There was no +proper handling of plotting styles and colours. + +## Implementing bitmap rendering + +There was no bitmap rendering so no pretty pictures. + +## Implementing the user messages API + +This immediately allows the browser to use the existing language +translations for many internal strings. + +## Implementing a user settings dialog + +Implementing a way for the user to change configuration options +without having to edit a configuration file greatly improves the +perceived functionality. + +## Implementing corewindow + +The [core window interface](docs/core-window-interface.md) allows a +frontend to use inbuilt rendering for several interfaces gaining a +great deal of functionality for very litte code. This one interface +set gives a cookie viewer,a local and global history viewer and a +hotlist(bookmarks) viewer. + +# Conclusion + +Hopefully this breif overview and worked example should give the +prospectinve frontend developer enough information to understand how +to get started implementing a new frontend toolkit for NetSurf. + +As can be seen there is actualy very little novel code necessary to +get started though I should mention that the move from "minimal" to +"full" implementation is a large undertaking and it would be wise to +talk with the NetSurf developers if undertaking such work. diff --git a/docs/integration-testing.md b/docs/integration-testing.md new file mode 100644 index 000000000..03b41308a --- /dev/null +++ b/docs/integration-testing.md @@ -0,0 +1,542 @@ +NetSurf Integration Testing +=========================== + +[TOC] + +# Overview + +The monkey frontend is used to perform complex tests involving +operating the browser as a user might (opening windows, navigating to +websites and rendering the contents etc.) + +A test is written as a set of operations in a yaml file. These files +are parsed and executed by the monkey driver script. + +There are very few tests within the NetSurf repository. The large +majority of integration tests are instead held within the +[netsurf-test](http://source.netsurf-browser.org/netsurf-test.git/) +repository. + +To allow more effective use of these tests additional infrastructure +has been constructed to allow groupings of tests to be run. This is +used extensively by the CI system to perform integration testing on +every commit. + +The infrastructure also provides for special CGI scripts which have +known behaviours such as delays or returning specific content to +extend test capabilities. + + +# Running a test + +An individual test can be run using the monkey_driver.py python script +from within the NetSurf repository + + $ make TARGET=monkey + $ ./test/monkey_driver.py -m ./nsmonkey -t test/monkey-tests/start-stop.yaml + +The command actually executed can be augmented using the wrapper +switch, this allows the test to be run under a debugger or profiler. + +For example to wrap execution under valgrind memory checker + + $ ./test/monkey_driver.py -m ./nsmonkey -w 'valgrind -v --track-origins=yes' -t test/monkey-tests/start-stop.yaml + + +# Running more than one test + +Each test is a member of a group and the tests within each group are +run together. Groups are listed within division index files. A group +of tests may occur within more than one division. + +To run the integration tests the monkey-see-monkey-do python script is +used. It downloads the test plan for a division from the NetSurf test +infrastructure and executes it. + + $ ./test/monkey-see-monkey-do + Fetching tests... + Parsing tests... + Running tests... + Start group: initial + [ Basic checks that the browser can start and stop ] + => Run test: start-stop-no-js.yaml + => Run test: basic-navigation.yaml + => Run test: start-stop.yaml + Start group: no-networking + [ Tests that require no networking ] + => Run test: resource-scheme.yaml + Start group: ecmascript + [ ECMAScript tests ] + PASS + +If no division is specified on the command line the "default" division +is used. Other divisions are specified with the d switch for example +to specify the "short-internet" division: + + $ ./test/monkey-see-monkey-do -d short-internet + +Additionally the g switch allows the limiting of tests within a single +group to be executed. + + $ ./test/monkey-see-monkey-do -g no-networking + Fetching tests... + Parsing tests... + Running tests... + Start group: no-networking + [ Tests that require no networking ] + => Run test: resource-scheme.yaml + PASS + +# Test files + +Each test is a individual [YAML](https://en.wikipedia.org/wiki/YAML) +file and consists of associative arrays (key/value pairs), lists and +comments. + +As a minimum a test must contain an associative array with keys for +`title`, `group` and `steps`. The `steps` key must contain a list of +test operations as a value. + +Each operation is an associative list and must, as a minimum, contain +an action key with a suitable value. + +A minimal test that simply starts the browser without JavaScript and +then quits it without ever opening a window to browse to a page + + title: start and stop browser without JS + group: initial + steps: + - action: launch + options: + - enable_javascript=0 + - action: quit + + +# Actions + +## launch + +Start a browser instance. A test will generally have a single launch +action paired with a quit action. + +Additional command line parameters may be set using the `launch-options` +key the value of which must be a list of command line arguments to be +passed to the browser (without their leading hyphens) + +The environment of the browser can be altered with the `environment` key +the value is an associative array of environment variables which will +be added to the browsers environment variables. + +User options may be set using the `options` key with a value containing +a list of options to set. These options allow operation with differing +user choices to be tested without a separate Choices file. + +The `language` key sets the LANGUAGE environment variable which controls +the browsers user interface language. Note this is distinct from the +language the browser requests from HTTP servers which is controlled +with the `accept_language` user option. + +The following launch action would start a browser: + * Passing `--verbose` on the commandline + * The `NETSURFRES` environment variable set to `/home/netsurf/resources` + * The user options `enable_javascript` and `send_referer` set to false. + * The `LANGUAGE` environment variable set to `en` + +``` +- action: launch + launch-options: + - verbose + environment: + NETSURFRES: /home/netsurf/resources + options: + - enable_javascript=0 + - send_referer=0 + language: en +``` + +## window-new + +Open a new browser window. The test may open as many browser windows +as necessary and they are usually paired with a `window-close` action + +The browser must have been previously launched or this action will +assert the test with a failure. + +The `tag` key *must* also be present with a value (unique for all +window-new actions). The value is used to identify subsequent +operations in this window. + +As an example this will open a new window which can subsequently be +referred to with the win1 identifier: + + - action: window-new + tag: win1 + + +## window-close + +Closes a previously opened window. The window is identified with the +`window` key, the value of this must be a previously created window +identifier or an assert will occur. + + - action: window-close + window: win1 + + +## navigate + +Cause a window to start navigating to a new URL. + +The window to be navigated is identified with the `window` key, the +value of this must be a previously created window identifier or an +assert will occur. + +The URL to navigate to navigate to is controlled either by the `url` +or `repeaturl` key. The `url` value is directly used as the address to +navigate to. + + - action: navigate + window: win1 + url: about:about + +The `repeaturl` value is used as a repeat action identifier allowing +navigation in a loop with different values. + + - action: repeat + values: + - https://www.google.com/ + - https://apple.com/ + - https://microsoft.com/ + tag: urls + - action: navigate + window: win1 + repeaturl: urls + + +## reload + +Cause a window to (re)navigate to the current URL + +The window to be navigated is identified with the `window` key, the +value of this must be a previously created window identifier or an +assert will occur. + + - action: reload + window: win1 + +## stop + +Cause a window to immediately stop any navigation. + +The window to be navigated is identified with the `window` key, the +value of this must be a previously created window identifier or an +assert will occur. + + - action: stop + window: win1 + +## sleep-ms + +Wait for time to pass before continuing to next action. + +The value of the `time` key is either the duration to wait for in +milliseconds or a `repeat` action identifier. + +The optional `conditions` key may contain a list of conditionals used +to terminate the delay early. If a `repeat` action identifier is in +use the loop is terminated if a condition is met. + +For example to wait 10 seconds: + + - action: sleep-ms + time: 10000 + +if a repeat action identifier is used the delay duration is the +current iteration value and the delay is timed from when the current +iteration started. + +The `sleep-ms` action here delays by 50 milliseconds more each +iteration until the window navigation is complete when the `sleep-ms` +action is delaying. + + - action: repeat + min: 0 + step: 50 + tag: sleepytimer + steps: + - action: launch + - action: window-new + tag: win1 + - action: navigate + window: win1 + url: about:about + - action: sleep-ms + time: sleepytimer + conditions: + - window: win1 + status: complete + - action: quit + + +## block + +Wait for conditions to be met before continuing. This is similar to +the `sleep-ms` action except that it will wait forever for the +conditions to be met. + +The `conditions` key must contain a list of conditionals used to +terminate the block. + + - action: block + conditions: + - window: win1 + status: complete + +valid `status` values are `complete` or `loading`. + +## repeat + +Repeat a set of actions. + +The identifier of the repeat action is set with the `tag` key and must +be present and unique among `repeat` action identifiers. + +The actions to be repeated are placed in the `steps` list which may +include any action and behaves just like the top level list. + +An iterator context is created for the repeat loop. The iterator can +either be configured as a numeric value or as a list of values. + +The numeric iterator is controlled with the `min` ,`step` and `max` +keys. All these keys are integer values and their presence is +optional. + +The `min` value is the initial value of the iterator which defaults +to 0. + +The `step` value controls how much the iterator is incremented +on every loop with default value of 1. + +The loop terminates if the `max` value is exceeded. If no `max` value +is specified the loop is infinite (i.e. no default) but may still be +terminated by the `sleep-ms` action + + - action: repeat + min: 0 + step: 50 + max: 100 + tag: loopvar + steps: + - action: launch + - action: quit + +A value iterator has a `values` key containing a list. On each +iteration of the loop a new value is available and can be used by the +`navigate` action. + +Note that `min` ,`step` and `max` are ignored if there is a `values` key + + - action: repeat + values: + - https://www.google.com/ + - https://www.blogger.com/ + - https://apple.com/ + - https://microsoft.com/ + tag: urls + steps: + - action: navigate + window: win1 + repeaturl: urls + - action: block + conditions: + - window: win1 + status: complete + + +## timer-start + +Start a timer. + +The identifier for the timer is set with the `timer` key. + + - action: timer-start + timer: timer1 + + +## timer-restart + +Re-start a timer + +The identifier for the timer is set with the `timer` key. + + - action: timer-restart + timer: timer1 + + +## timer-stop + +Stop a timer + +The identifier for the timer is set with the `timer` key. + + - action: timer-stop + timer: timer1 + + +## timer-check + +Check a timer meets a condition. + +The identifier for the timer is set with the `timer` key. + +The conditional is set with the `condition` key which must be present. + + +## plot-check + +Perform a plot of a previously navigated window. + +The window to be rendered is identified with the `window` key, the +value of this must be a previously created window identifier or an +assert will occur. + +The `area` key allows control of the area to be redraw. The parameters are on two forms: + + * A sequence of four numbers in the form `x0 y0 x1 y1` + * The keyword extent which attempt to plot the entire extent of the canvas + +An optional list of checks may be specified with the `checks` key. If +any check is not satisfied an assert will occur and the test will +fail. Multiple checks can be specified and all most pass successfully. + +The checks available are: + + * The key `text-contains` where the text must occur somewhere in the + plotted output. + * The key `text-not-contains` where the text must not occur in the + plotted output. + * The key `bitmap-count` which specifies the number of images that + must be present. + + + - action: plot-check + window: win1 + area: extent + checks: + - text-contains: NetSurf + - text-contains: Browser + - text-not-contains: Chrome + - bitmap-count: 1 + + +## click + +Perform a user mouse click on a specified window. + +The window to be clicked is identified with the `window` key, the +value of this must be a previously created window identifier or an +assert will occur. + +The `target` key contains an associative array which is used to select +the location of the mouse operation in the window. The key `text` can +be used to select text to be operated upon which matches the first +occurrence of the text. The key `bitmap` has an integer value to +select the index of the image to click. + +The optional `button` key selects which button is pressed it can take +the value `left` or `right`. The default if not specified is `left` + +The optional `kind` key selects which button operation to be performed +it can take the value `single`, `double` or `triple`. The default if +not specified is `single` + + - action: click + window: win1 + target: + text: "about:Choices" + + +## wait-loading + +Wait for the navigated page to start loading before moving to the next +action. + +The window to be waited upon is identified with the `window` key, the +value of this must be a previously created window identifier or an +assert will occur. + + - action: wait-loading + window: win1 + + +## add-auth + +Add basic authentication details for a navigation. + +The keys `url`, `realm`, `username` and `password` must be given. When +a basic authentication challenge occurs that matches the url and +realm parameters the associated username and password are returned to +answer the challenge. + + - action: add-auth + url: http://test.netsurf-browser.org/cgi-bin/auth.cgi?user=foo&pass=bar + realm: Fake Realm + username: foo + password: bar + + +## remove-auth + +Remove a previously added authentication details. + + - action: remove-auth + url: http://test.netsurf-browser.org/cgi-bin/auth.cgi?user=foo&pass=bar + realm: Fake Realm + username: foo + password: bar + + +## clear-log + +Clear log for a window. + +The window to be cleared is identified with the `window` key, the +value of this must be a previously created window identifier or an +assert will occur. + + +## wait-log + +Wait for string to appear in log output. + +The window to be waited upon is identified with the `window` key, the +value of this must be a previously created window identifier or an +assert will occur. + +The keys `source` `foldable` `level` and `substring` must be specified + +## js-exec + +Execute javascript in a window. + +The window to be execute within is identified with the `window` key, the +value of this must be a previously created window identifier or an +assert will occur. + +The `cmd` key contains the javascript to execute. + + +## page-info-state + +Check the page information status matches an expected value. + +The window to be checked is identified with the `window` key, the +value of this must be a previously created window identifier or an +assert will occur. + +The value of the `match` key is compared to the windows page +information status and an assert occurs if there is a mismatch. + +## quit + +This causes a previously launched browser instance to exit cleanly. diff --git a/docs/mainpage.md b/docs/mainpage.md index 0700137e6..afff4b65d 100644 --- a/docs/mainpage.md +++ b/docs/mainpage.md @@ -1,165 +1,13 @@ NetSurf web browser =================== -[*](https://bestpractices.coreinfrastructure.org/projects/1037) + -# User Interface +[CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1037) -Netsurf is divided into a series of frontends which provide a user -interface around common core functionality. Each frontend is a -distinct implementation for a specific GUI toolkit. -Because of this the user interface has different features in -each frontend allowing the browser to be a native application. +[Project](docs/project.md) -## Frontends +[User Interface](docs/user-interface.md) -As GUI toolkits are often applicable to a single Operating -System (OS) some frontends are named for their OS instead of the -toolkit e.g. RISC OS WIMP frontend is named riscos and the Windows -win32 frontend is named windows. - -### amiga - -Frontend specific to the amiga - -### atari - -Frontend specific to the atari - -### beos - -Frontend specific to the Haiku OS - -### framebuffer - -There is a basic user guide for the[framebuffer](docs/using-framebuffer.md) - -### gtk - -Frontend that uses the GTK+2 or GTK+3 toolkit - -### monkey - -This is the internal unit test frontend. - -There is a basic user guide [monkey](docs/using-monkey.md) - -### riscos - -Frontend for the RISC OS WIMP toolkit. - -### windows - -Frontend which uses the Microsodt win32 GDI toolkit. - -## User configuration - -The behaviour of the browser can be changed from the defaults with a -configuration file. The [core user options](docs/netsurf-options.md) -of the browser are common to all versions and are augmented by each -frontend in a specific manner. - - -# Development - -## Working with the team - -Generally it is sensible to check with the other developers if you are -planning to make a change to NetSurf intended to be merged. - -We are often about on the IRC channel but failing that the developer -mailing list is a good place to try. - -All the project sources are held in [public git repositories](http://source.netsurf-browser.org/) - -## Compilation environment - -Compiling a development edition of NetSurf requires a POSIX style -environment. Typically this means a Linux based system although Free -BSD, Open BSD, Mac OS X and Haiku all known to work. - -## Toolchains - -Compilation for non POSIX toolkits/frontends (e.g. RISC OS) generally -relies upon a cross compilation environment which is generated using -the makefiles found in our -[toolchains](http://source.netsurf-browser.org/toolchains.git/) -repository. These toolchains are built by the Continuous Integration -(CI) system and the -[results of the system](http://ci.netsurf-browser.org/builds/toolchains/) -are published as a convenience. - -## Quick setup - -The [quick start guide](docs/quick-start.md) can be used to get a -development environment setup quickly and uses the -[env.sh](env_8sh_source.html) script the core team utilises. - -## Manual setup - -The Manual environment setup and compilation method is covered by the -details in the [netsurf libraries](docs/netsurf-libraries.md) document -for the core libraries and then one of the building documents for the -specific frontend. - -- [Amiga Os cross](docs/building-AmigaCross.md) and [Amiga OS](docs/building-AmigaOS.md) -- [Framebuffer](docs/building-Framebuffer.md) -- [GTK](docs/building-GTK.md) -- [Haiku (BeOS)](docs/building-Haiku.md) -- [Windows Win32](docs/building-Windows.md) - -These documents are sometimes not completely up to -date and the env.sh script should be considered canonical. - -## Logging - -The [logging](docs/logging.md) interface controls debug and error -messages not output through the GUI. - -## Documented API - -The NetSurf code makes use of Doxygen for code documentation. - -There are several documents which detail specific aspects of the -codebase and APIs. - -### Core window - -The [core window API](docs/core-window-interface.md) allows frontends -to use generic core code for user interface elements beyond the -browser render. - -### Source object caching - -The [source object caching](docs/source-object-backing-store.md) -provides a way for downloaded content to be kept on a persistent -storage medium such as hard disc to make future retrieval of that -content quickly. - -## Javascript - -Javascript provision is split into four parts: -- An engine that takes source code and executes it. -- Interfaces between the program and the web page. -- Browser support to retrive and manage the source code to be executed. -- Browser support for the dispatch of events from user interface. - -### Library - -JavaScript is provided by integrating the duktape library. There are -[instructions](docs/updating-duktape.md) on how to update the library. - -### Interface binding - -In order for javascript programs to to interact with the page contents -it must use the Document Object Model (DOM) and Cascading Style Sheet -Object Model (CSSOM) API. - -These interfaces are described using web Interface Description -Language (IDL) within the relevant specifications -(e.g. https://dom.spec.whatwg.org/). - -Each interface described by the webIDL must be bound (connected) to -the browsers internal representation for the DOM or CSS, etc. The -process of [writing bindings](docs/jsbinding.md) is ongoing. +[Development](docs/development.md)
\ No newline at end of file diff --git a/docs/netsurf-fb.1 b/docs/netsurf-fb.1 index e4c310075..045c1fe1a 100644 --- a/docs/netsurf-fb.1 +++ b/docs/netsurf-fb.1 @@ -95,9 +95,6 @@ Maximum disc cache size. .B \-\-block_advertisements Boolean to enable ad blocking. .TP -.B \-\-minimum_gif_delay -Minimum time between gif frames -.TP .B \-\-send_referer Boolean controlling whether referer data should be sent .TP @@ -146,12 +143,6 @@ The width of the initial window. .B \-\-window_height The height of the initial window. .TP -.B \-\-window_screen_width -window screen width -.TP -.B \-\-window_screen_height -window screen height -.TP .B \-\-toolbar_status_size toolbar status size .TP @@ -308,9 +299,6 @@ Override CSS sys_colour_WindowFrame colour. .B \-\-sys_colour_WindowText Override CSS sys_colour_WindowText colour. .TP -.B \-\-render_resample -render resample -.TP .B \-\-downloads_clear downloads clear .TP @@ -332,9 +320,6 @@ button type .B \-\-disable_popups disable popups .TP -.B \-\-disable_plugins -disable plugins -.TP .B \-\-history_age history age .TP diff --git a/docs/netsurf-gtk.1 b/docs/netsurf-gtk.1 index 7b2f4f4f3..2ae61be84 100644 --- a/docs/netsurf-gtk.1 +++ b/docs/netsurf-gtk.1 @@ -67,8 +67,6 @@ Maximum memory cache size. Maximum disc cache size. .It Fl -block_advertisements Boolean to enable ad blocking. -.It Fl -minimum_gif_delay -Minimum time between gif frames .It Fl -send_referer Boolean controlling whether referrer data should be sent .It Fl -animate_images @@ -101,10 +99,6 @@ The Y co-ordinate of the initial window. The width of the initial window. .It Fl -window_height The height of the initial window. -.It Fl -window_screen_width -window screen width -.It Fl -window_screen_height -window screen height .It Fl -toolbar_status_size toolbar status size .It Fl -scale @@ -209,8 +203,6 @@ Override CSS sys_colour_Window colour. Override CSS sys_colour_WindowFrame colour. .It Fl -sys_colour_WindowText Override CSS sys_colour_WindowText colour. -.It Fl -render_resample -render resample .It Fl -downloads_clear downloads clear .It Fl -request_overwrite @@ -225,8 +217,6 @@ Force tabs to always be show. button type .It Fl -disable_popups disable popups -.It Fl -disable_plugins -disable plugins .It Fl -history_age history age .It Fl -hover_urls diff --git a/docs/netsurf-options.md b/docs/netsurf-options.md index 553813842..5a723c76b 100644 --- a/docs/netsurf-options.md +++ b/docs/netsurf-options.md @@ -42,9 +42,9 @@ General Options memory_cache_size | int | 12MiB | Preferred maximum size of memory cache in bytes. disc_cache_size | uint | 1GiB | Preferred expiry size of disc cache in bytes. disc_cache_age | int | 28 | Preferred expiry age of disc cache in days. + disc_cache_path | string | NULL | Path to disc cache, NULL means to use system path | block_advertisements | bool | false | Whether to block advertisements do_not_track | bool | false | Disable website tracking [1] - minimum_gif_delay | int | 10 | Minimum GIF animation delay send_referer | bool | true | Whether to send the referer HTTP header. foreground_images | bool | true | Whether to fetch foreground images background_images | bool | true | Whether to fetch background images diff --git a/docs/project.md b/docs/project.md new file mode 100644 index 000000000..7fa76d9ae --- /dev/null +++ b/docs/project.md @@ -0,0 +1,17 @@ +NetSurf Project +=============== + +The NetSurf project is developing a document browser for the World +Wide Web. It was started in 2002 on the RISC OS platform and has +support for numerous operating systems and graphical toolkits. + +NetSurf is very modular and built from many component libraries which +provide functionality from GIF image format decoding (libnsgif) to +HTML document object model handling (libdom). + +NetSurf browser is open source and is licensed under the GPLv2 (with +OpenSSL exception). Many of the supporting libraries are under a MIT +licence. + +The [main website](http://www.netsurf-browser.org/) contains links to +other resources and additional information. diff --git a/docs/quick-start.md b/docs/quick-start.md index 601269c96..449b956a3 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -1,10 +1,21 @@ Quick Build Steps for NetSurf ============================= -Last Updated: 15th December 2017 +Last Updated: 21st January 2020 This document provides steps for building NetSurf. +These instructions use a shell script to perform several operations. + This script has only been tested with the bash and zsh bourne style + shell interpreters. The latest version of this script should be + retrieved from the official NetSurf source repository. + +This shell script is used by the NetSurf Developers but you should + satisfy yourself that the script is not malicious. It should be noted + that building the browser will also be executing shell code and + requires a similar level of trust. + + Native build ============ @@ -66,13 +77,15 @@ To build the native front end (the GTK front end on Linux, BSDs, etc) you could do: $ make - $ ./nsgtk + $ ./nsgtk3 To build the framebuffer front end, you could do: $ make TARGET=framebuffer $ ./nsfb +More detailed documentation on using the [framebuffer](docs/using-framebuffer.md) + frontend are available. Cross Compiling =============== diff --git a/docs/source-object-backing-store.md b/docs/source-object-backing-store.md index 0fb3614d4..4fb662087 100644 --- a/docs/source-object-backing-store.md +++ b/docs/source-object-backing-store.md @@ -1,26 +1,36 @@ Source Object (low level) cache backing store ============================================= -Introduction ------------- +[TOC] -The source object cache provides a system to extend the life of source -objects (HTML files, images etc.) after they are no longer immediately -being used. +# Introduction -Only fetch types where we have well defined rules on caching are -considered, in practice this limits us to HTTP(S). The section in -RFC2616 [1] on caching specifies these rules. +The source object (referred to as low level in the code) content cache +provides a unified API for the rest of the browser to retrieve objects +(HTML files, images etc.) from a URL. + +The cache initialy always fufuls these requsts by using the fetcher +system to retrive data according to the URL scheme (network for HTTP, +disc for file etc.) and storing the result in memory. + +The cache also provides a system to extend the life of source objects +in memory when they are no longer immediately being used. Only fetch +types where there are well defined rules on caching are considered, in +practice this limits the cache to URLS with HTTP(S) schemes. The +section in RFC2616 [1] on caching specifies these rules. To further extend the objects lifetime they can be pushed into a backing store where the objects are available for reuse less quickly -than from RAM but faster than retrieving from the network again. +than from memory but faster than retrieving from the network again. The backing store implementation provides a key:value infrastructure with a simple store, retrieve and invalidate interface. -Generic filesystem backing store --------------------------------- +The key is the object URL which by definition is unique for a source +object. The value is the source object data *and* the associated +metadata + +# Generic filesystem backing store Although the backing store interface is fully pluggable a generic implementation based on storing objects on the filesystem in a @@ -34,13 +44,45 @@ As the backing store only holds cache data one should not expect a great deal of effort to be expended converting formats (i.e. the cache may simply be discarded). -Layout version 1.1 ------------------- +## Layout version 2.02 + +The version 2 layout stores cache entries in a hash map thus only uses +memory proportional to the number of entries present removing the need +for large fixed size indexes. + +The object identifier is generated from nsurl_hash() and data entries +are stored in either a fixed size disc blocks or in separate files on disc. + +The file path if stored on disc must conform to the limitations of all +the filesystems the cache can be placed upon. + +From http://en.wikipedia.org/wiki/Comparison_of_file_systems#Limits the relevant subset is: + - path elements no longer than 8 characters + - acceptable characters are A-Z, 0-9 + - short total path lengths (255 or less) + - no more than 77 entries per directory (6bits worth) + +The short total path lengths mean the encoding must represent as much +data as possible in the least number of characters. + +To achieve all these goals we use RFC4648 base32 encoding which packs +five bits into each character of the filename. By splitting the 32bit +identifier using six bits per directory level only five levels of +directory are required with a maximum of 64 entries per +directory. This requires a total path length of 22 bytes (including +directory separators) BA/BB/BC/BD/BE/ABCDEFG + +Files that are under 8KiB in size are stored in "small block files" +these are pre allocated 8 Megabyte files on disc in which remove the +need to have many, many small files stored on disc at the expensie of +a some amount of wasted space for files that are smaller than the 8K +block size. -An object has an identifier value generated from the URL (NetSurf -backing stores uses the URL as the unique key). The value used is -obtained using nsurl_hash() which is currently a 32 bit FNV so is -directly usable. +## Layout version 1.1 + +An object has an identifier value generated from the URL (the unique +key). The value used is obtained using nsurl_hash() which is currently +a 32 bit FNV so is directly usable. This identifier is adequate to ensure the collision rate for the hashed URL values (a collision for every 2^16 URLs added) is @@ -83,26 +125,23 @@ resulting in the data being stored in a file path of An address of 0x00040001 encodes to BAAB and a file path of "/store/prefix/m/B/A/A/BAABAAA" -Version 1.0 ------------ +## Layout Version 1.0 -The version 1 layout was identical to the 1.1 except base64url +The version 1.0 layout was identical to the 1.1 except base64url encoding was used, this proved problematic as some systems filesystems were case insensitive so upper and lower case letters collided. There is no upgrade provision from the previous version simply delete the cache directory. -Control files -~~~~~~~~~~~~~ +## Control files + +### control -control -+++++++ A control file is used to hold a list of values describing how the other files in the backing store should be used. -entries -+++++++ +### entries this file contains a table of entries describing the files held on the filesystem. @@ -110,26 +149,18 @@ filesystem. Each control file table entry is 28 bytes and consists of - signed 64 bit value for last use time - - 32bit full url hash allowing for index reconstruction and additional collision detection. Also the possibility of increasing the ADDRESS_LENGTH although this would require renaming all the existing files in the cache and is not currently implemented. - - unsigned 32bit length for data - - unsigned 32bit length for metadata - - unsigned 16bit value for number of times used. - - unsigned 16bit value for flags - - unsigned 16bit value for data block index (unused) - - unsigned 16bit value for metatdata block index (unused) -Address to entry index -~~~~~~~~~~~~~~~~~~~~~~ +### Address to entry index An entry index is held in RAM that allows looking up the address to map to an entry in the control file. @@ -137,14 +168,13 @@ map to an entry in the control file. The index is the only data structure whose size is directly dependant on the length of the hash specifically: -(2 ^ (ADDRESS_BITS - 3)) * ENTRY_BITS) in bytes + (2 ^ (ADDRESS_BITS - 3)) * ENTRY_BITS) in bytes where ADDRESS_BITS is how long the address is in bits and ENTRY_BITS is how many entries the control file (and hence the while cache) may hold. -RISCOS values -+++++++++++++ +## RISCOS values By limiting the ENTRY_BITS size to 14 (16,384 entries) the entries list is limited to 448kilobytes. @@ -159,8 +189,7 @@ address) to happen roughly for every 2 ^ (ADDRESS_BITS / 2) = 2 ^ 9 = 512 objects stored. This roughly translates to a cache miss due to collision every ten pages navigated to. -Larger systems -++++++++++++++ +## Larger systems In general ENTRY_BITS set to 16 as this limits the store to 65536 objects which given the average size of an object at 8 kilobytes @@ -170,11 +199,9 @@ For larger systems e.g. those using GTK frontend we would most likely select ADDRESS_BITS as 22 resulting in a collision every 2048 objects but the index using some 8 Megabytes -Typical values --------------- +## Typical values -Example 1 -~~~~~~~~~ +### Example 1 For a store with 1034 objects generated from a random navigation of pages linked from the about:welcome page. @@ -185,8 +212,7 @@ majority of the storage is used to hold the URLs and headers. Data total size is 9180475 bytes a mean of 8879 bytes 1648726 in the largest 10 entries which if excluded gives 7355 bytes average size -Example 2 -~~~~~~~~~ +### Example 2 355 pages navigated in 80 minutes from about:welcome page and a handful of additional sites (google image search and reddit) @@ -201,4 +227,4 @@ with one single 5,000,811 byte gif data totals without gif is 28,127,020 mean 13,945 -[1] http://tools.ietf.org/html/rfc2616#section-13
\ No newline at end of file +[1] http://tools.ietf.org/html/rfc2616#section-13 diff --git a/docs/unit-testing b/docs/unit-testing.md index 49d82ed81..f7adc82c7 100644 --- a/docs/unit-testing +++ b/docs/unit-testing.md @@ -1,8 +1,9 @@ NetSurf Unit Testing ==================== -Overview --------- +[TOC] + +# Overview NetSurf has unit tests integrated in the test directory. These tests use the check unit test framework for C [1]. @@ -13,8 +14,7 @@ programs although the framework does not madate this and some test programs contain more than one suite. -Execution ---------- +# Execution The test programs are executed by using the standard "test" target from the top level make invocation. The "coverage" target additionally @@ -25,8 +25,7 @@ The check library must be installed to run the tests and the CI system automatically executes all enabled tests and generates coverage reports for each commit. -Adding tests ------------- +# Adding tests The test/Makefile defines each indiviadual test program that should be built and executed in the TESTS variable. @@ -39,128 +38,128 @@ Each individual test program requires a main function which creates one (or more) suites. The suites are added to a test runner and then executed and the results reported. -int main(int argc, char **argv) -{ - int number_failed; - SRunner *sr; - - sr = srunner_create(foo_suite_create()); - //srunner_add_suite(sr, bar_suite_create()); - - srunner_run_all(sr, CK_ENV); - - number_failed = srunner_ntests_failed(sr); - srunner_free(sr); - - return (number_failed == 0) ? EXIT_SUCCESS : EXIT_FAILURE; -} + int main(int argc, char **argv) + { + int number_failed; + SRunner *sr; + + sr = srunner_create(foo_suite_create()); + //srunner_add_suite(sr, bar_suite_create()); + + srunner_run_all(sr, CK_ENV); + + number_failed = srunner_ntests_failed(sr); + srunner_free(sr); + + return (number_failed == 0) ? EXIT_SUCCESS : EXIT_FAILURE; + } Suite creation is done with a sub function to logically split suite code into sub modules. Each suite has test cases added to it. -Suite *foo_suite_create(void) -{ - Suite *s; - s = suite_create("foo"); - - suite_add_tcase(s, baz_case_create()); - suite_add_tcase(s, qux_case_create()); - - return s; -} + Suite *foo_suite_create(void) + { + Suite *s; + s = suite_create("foo"); + + suite_add_tcase(s, baz_case_create()); + suite_add_tcase(s, qux_case_create()); + + return s; + } Test cases include the actual tests to be performed within each case. -TCase *baz_case_create(void) -{ - TCase *tc; - tc = tcase_create("Baz"); - - tcase_add_test(tc, xxyz_test); - tcase_add_test(tc, zzyx_test); - - return tc; -} + TCase *baz_case_create(void) + { + TCase *tc; + tc = tcase_create("Baz"); + + tcase_add_test(tc, xxyz_test); + tcase_add_test(tc, zzyx_test); + + return tc; + } A test case may optionally have a fixture which is code that is executed before and after each test case. Unchecked fixtures are executed once before the test process forks for each test whereas checked fixtures are executed for each and every test. -static void fixture_setup(void) -{ -} - -static void fixture_teardown(void) -{ -} - -TCase *qux_case_create(void) -{ - TCase *tc; - - /* Matching entry tests */ - tc = tcase_create("Match"); - - tcase_add_checked_fixture(tc, - fixture_setup, - fixture_teardown); - - tcase_add_test(tc, zzz_test); - - return tc; -} + static void fixture_setup(void) + { + } + + static void fixture_teardown(void) + { + } + + TCase *qux_case_create(void) + { + TCase *tc; + + /* Matching entry tests */ + tc = tcase_create("Match"); + + tcase_add_checked_fixture(tc, + fixture_setup, + fixture_teardown); + + tcase_add_test(tc, zzz_test); + + return tc; + } Additionally test cases can contain tests executed in a loop. The test recives a single integer as a parameter named _i which iterates between values specified in the case setup. -TCase *baz_case_create(void) -{ - TCase *tc; - tc = tcase_create("Baz"); - - tcase_add_loop_test(tc, looping_test, 0, 5); - - return tc; -} + TCase *baz_case_create(void) + { + TCase *tc; + tc = tcase_create("Baz"); + + tcase_add_loop_test(tc, looping_test, 0, 5); + + return tc; + } It is also possible to create tests which will generate a signal. The most commonly used of these is to check asserts in API calls. -TCase *baz_case_create(void) -{ - TCase *tc; - tc = tcase_create("Baz"); - - tcase_add_test_raise_signal(tc, assert_test, 6); - - return tc; -} + TCase *baz_case_create(void) + { + TCase *tc; + tc = tcase_create("Baz"); + + tcase_add_test_raise_signal(tc, assert_test, 6); + + return tc; + } Actual test code is self contained in a function which uses the ck_assert macros to test results. The check framework requires each test to use the START_TEST and END_TEST macros when definig them. -/** - * url access leaf test - */ -START_TEST(nsurl_access_leaf_test) -{ - nserror err; - nsurl *res_url; - const struct test_triplets *tst = &access_tests[_i]; - - /* not testing create, this should always succeed */ - err = nsurl_create(tst->test1, &res_url); - ck_assert(err == NSERROR_OK); - - ck_assert_str_eq(nsurl_access_leaf(res_url), tst->res); - - nsurl_unref(res_url); -} -END_TEST + /** + * url access leaf test + */ + START_TEST(nsurl_access_leaf_test) + { + nserror err; + nsurl *res_url; + const struct test_triplets *tst = &access_tests[_i]; + + /* not testing create, this should always succeed */ + err = nsurl_create(tst->test1, &res_url); + ck_assert(err == NSERROR_OK); + + ck_assert_str_eq(nsurl_access_leaf(res_url), tst->res); + + nsurl_unref(res_url); + } + END_TEST [1] https://libcheck.github.io/check/ diff --git a/docs/user-interface.md b/docs/user-interface.md new file mode 100644 index 000000000..49ca7a1ed --- /dev/null +++ b/docs/user-interface.md @@ -0,0 +1,61 @@ +User Interface +============== + +[TOC] + +Netsurf is divided into a series of frontends which provide a user +interface around common core functionality. Each frontend is a +distinct implementation for a specific GUI toolkit. + +Because of this the user interface has different features in +each frontend allowing the browser to be a native application. + +# Frontends + +As GUI toolkits are often applicable to a single Operating +System (OS) some frontends are named for their OS instead of the +toolkit e.g. RISC OS WIMP frontend is named riscos and the Windows +win32 frontend is named windows. + +## amiga + +Frontend specific to the amiga + +## atari + +Frontend specific to the atari + +## beos + +Frontend specific to the Haiku OS + +## framebuffer + +There is a basic user guide for the [framebuffer](docs/using-framebuffer.md) + +## gtk + +Frontend that uses the GTK+2 or GTK+3 toolkit + +## monkey + +This is the internal unit test frontend. + +There is a basic user guide [monkey](docs/using-monkey.md) + +## riscos + +Frontend for the RISC OS WIMP toolkit. + +## windows + +Frontend which uses the Microsodt win32 GDI toolkit. + +# User configuration + +The behaviour of the browser can be changed from the defaults with a +configuration file. The [core user options](docs/netsurf-options.md) +of the browser are common to all versions and are augmented by each +frontend in a specific manner. + + diff --git a/docs/using-framebuffer.md b/docs/using-framebuffer.md index 3af8f983f..98a100a1f 100644 --- a/docs/using-framebuffer.md +++ b/docs/using-framebuffer.md @@ -62,6 +62,56 @@ Overview the GTK frontend is a vastly superior choice. The framebuffer frontend will appear exceptionally limited on such capable systems. +Running +======= + + The framebuffer frontend is executed with the nsfb command. This + command takes parameters to control the operation of the + browser. The 'Configuring' section describes the available options + in detail. + + The selection of the display surface is controlled with the -f + switch, the available display surfaces can be shown by passing '?' + as the parameter. + + $ ./nsfb -f ? + ./nsfb: Valid surface names are: + ./nsfb: ram + ./nsfb: sdl + ./nsfb: x + ./nsfb: vnc + ./nsfb: wld + + The avilable surfaces are dependant on what was compiled into the + nsfb library. + + Common issues + ------------- + + - The browser appears to "hang" with no output + + This is often cause by the unintentianal selection of the debug + "ram" surface. In this case the browser is in fact operating but + the output is being rendered to a memory buffer. the solution is + to explictly select the intended surface using the -f switch + + - The displayed browser interface has no visible icons + + This is generally because the necessary resources are not availale + on the resource search path. + + - There is no displayed text. + + The font configuration is incorrect either it has been compiled + wrongly or the configured freetype font is not available + + - The browser messages are "bad" + + If the browser messages are being emited as unrecognisable short + text symbols or in the wrong language it is likely the Messages + file could not be located. This can be confirmed by looking for + the text "Message translations failed to load" in the verbose log + output (run the browser with the -v switch) Configuring =========== @@ -72,11 +122,11 @@ Configuring for details. As with any NetSurf frontend run-time configuration is read from a - "Choices" file. This file is a simple key:value list and is located - in "${HOME}/.netsurf/Choices". + "Choices" file. This file is a simple key:value list and by default + is located in "${HOME}/.netsurf/Choices". - The standard values supported by the NetSurf core are documented in - the Options document. In addition to these there are a number of + The standard [core user options](docs/netsurf-options.md) are + available. In addition to the core options there are a number of values to control specific aspects of the framebuffer version. Toolkit Options |