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.

SGML_PARSER_STREAM: 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.
SGML_PARSER_TREE: 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.

The SGML parser has only little state.

sgml_parser_state.info: 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.
sgml_parser_state.end_token: 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.

SGML_PARSER_CODE_OK: The parsing was successful
SGML_PARSER_CODE_INCOMPLETE: The parsing could not be completed
SGML_PARSER_CODE_MEM_ALLOC: Failed to allocate memory
SGML_PARSER_CODE_ERROR: 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.

Note	The only variable the user should set is sgml_parser.error_func.

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.

Note	Line numbers are recorded in the scanner tokens.

1. enum sgml_parser_type: SGML parser type

2. enum sgml_parser_flag: SGML parser flags