1. enum sgml_parser_type: SGML parser type

There are two kinds of parser types: One that optimises one-time access to the DOM tree and one that creates a persistent DOM tree.

The first one will simply push nodes on the stack, not building a DOM tree. This interface is similar to that of SAX (Simple API for XML) where events are fired when nodes are entered and exited. It is useful when you are not actually interested in the DOM tree, but can do all processing in a stream-like manner, such as when highlighting HTML code.
The second one is a DOM tree builder, that builds a persistent DOM tree. When using this type, it is possible to do even more (pre)processing than for parser streams. For example you can sort element child nodes, or purge various node such as text nodes that only contain space characters.

2. enum sgml_parser_flag: SGML parser flags

These flags control how the parser behaves.

Make line numbers available.
Used internally when incremental.
Parse chunks of input.
Report errors.

3. struct sgml_parser_state: SGML parser state

The SGML parser has only little state.

Info about the properties of the node contained by state. This is only meaningful to element and attribute nodes. For unknown nodes it points to the common unknown node info.
This is used by the DOM source renderer for highlighting the end-tag of an element.

4. enum sgml_parser_code: (Error) codes for the SGML parser

These enum values are used for return codes.

The parsing was successful
The parsing could not be completed
Failed to allocate memory
FIXME: For when we will add support for requiring stricter parsing or even a validator.

5. callback sgml_error_T: SGML error callback

Called by the SGML parser when a parsing error has occurred.

If the return code is not SGML_PARSER_CODE_OK the parsing will be ended and that code will be returned.

6. struct sgml_parser: The SGML parser

This struct hold info used while parsing SGML data.

The only variable the user should set is sgml_parser.error_func.
Stream or tree
Flags that control the behaviour
Backend dependent info
The URI of the DOM document
The document root node
Called for detected errors
A stack for tracking parsed nodes
Used for tracking parsing states

7. init_sgml_parser(): Initialise an SGML parser

Initialise an SGML parser with the given properties.

type Stream or tree; one-time or persistant.
doctype The document type, this affects what sub type nodes are given.
uri The URI of the document root.
flags Flags controlling the behaviour of the parser.

Returns the created parser or NULL.

8. done_sgml_parser(): Release an SGML parser

Deallocates all resources, _expect_ the root node.

parser The parser being released.

9. parse_sgml(): Parse a chunk of SGML source

Parses the given buffer. For incremental rendering the last buffer can be signals through the complete parameter.

parser A parser created with init_sgml_parser.
buffer A string containing the chunk to parse.
complete Whether this is the last chunk to parse.

The returned code is SGML_PARSER_CODE_OK if the buffer was successfully parserd, else a code hinting at the error.

10. get_sgml_parser_line_number(): Get the line position in the source

Returns what line number the parser is currently at or zero if there has been no parsing yet.

Line numbers are recorded in the scanner tokens.