Hubbub -- an HTML parser
========================

Overview
--------

  Hubbub is a flexible HTML parser. It aims to comply with the HTML5
  specification.

Requirements
------------

  Hubbub requires the following tools:

    + A C99 capable C compiler
    + GNU make or compatible
    + Perl (for the testcases)
    + Pkg-config (for the testcases)
    + xsltproc (for the entity fetcher)
    + wget (for the entity fetcher)
    + doxygen (for the API documentation)

  Hubbub also requires the following libraries to be installed:

    + An iconv implementation (e.g. libiconv)
    + LibParserUtils -- see below for further information
    + JSON-C (for the testcases) -- see below for further information

  Hubbub can make use of the following, for debugging and testing purposes:

    + gcov and lcov, for test coverage data

LibParserUtils
--------------

  To compile Hubbub, you will need LibParserUtils.  This can be
  obtained from SVN:
  		$ svn co svn://svn.netsurf-browser.org/trunk/libparserutils/

  Follow the instructions in LibParserUtils' README file to build and 
  install it.

  Note: By default, libparserutils only supports a few character sets. It may, 
        however, be configured to use iconv() to provide charset conversion.
        See LibParserUtils' README for further information.

JSON-C
------

  To run tests, you will need JSON-C.  You can obtain the version
  that Hubbub needs from SVN:
  		$ svn co svn://svn.netsurf-browser.org/trunk/json-c/json-c/

  Build and install JSON-C as follows:

		$ sh autogen.sh
		$ make install

Compilation
-----------

  The exact type of build may be configured by passing parameters to make.
  Common usage is described below.

  For a static library:

  		$ make

  For a shared library:

		$ make COMPONENT_TYPE=lib-shared

  For a static library with debug enabled:

		$ make BUILD=debug

  To cross-compile a static library:

		$ make TARGET=<target-platform>

Verification
------------

  The library's functionality may be verified, thus:
  
  		$ make test

  If you wish to see test coverage statistics, run:

  		$ make coverage

  Then open build/coverage/index.html in a web browser.

  In both cases, ensure that the same parameters to make are passed as when 
  building the library.

(Un)installation
----------------

  To install the library:

		$ make install

  Ensure that the same parameters to make are passed as when building the
  library.

  To specify the installation prefix:

		$ make install PREFIX=/path/to/prefix

  To specify a staging directory for packaging:

		$ make install DESTDIR=/path/to/directory

  Items will be installed to $(DESTDIR)$(PREFIX)/

  To uninstall:

		$ make uninstall

API documentation
-----------------

  Use doxygen to auto-generate API documentation, thus:

  		$ make docs

  Then open build/docs/html/index.html in a web browser.

  The "examples" directory contains commented examples of how to use Hubbub.
  The test driver code in test/ may also provide some useful pointers.

A note on character set aliases
-------------------------------

  Hubbub uses an external mapping file to encode relationships between 
  character set names. This is the "Aliases" file. A copy may be found at
  test/data/Aliases. The path to this file is required when calling 
  hubbub_initialise().