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().
