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.

/////////////////////////////////////////////////////////////////////////////
Notice here how:

	/** id:[SGML_PARSER_TREE]::
	 * ...
	 * ...
	 */

becomes:

	id:[SGML_PARSER_TREE]::
		...
		...

that is indented with a tab. The '::' combo is special this way.
/////////////////////////////////////////////////////////////////////////////

id:[SGML_PARSER_TREE]:: The first one is a DOM tree builder.

id:[SGML_PARSER_TREE]::
	The second 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.

enum:[sgml_parser_code]: (Error) codes for the SGML parser
----------------------------------------------------------

These enum values are used

/////////////////////////////////////////////////////////////////////////////
I don't know if this sort of little short version is possible

	SGML_PARSER_CODE_INCOMPLETE,	/*:: The parsing could not be completed */

becomes:

	id:[SGML_PARSER_CODE_INCOMPLETE]:: The parsing could not be completed

These oneliners makes some of it more readable.
/////////////////////////////////////////////////////////////////////////////

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

callback:[sgml_error_T]: SGML error callback
--------------------------------------------

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

If the return code is not ref:[SGML_PARSER_CODE_OK] the parsing will be
ended and that code will be returned.

struct:[sgml_parser]
--------------------

...

NOTE: ...

func:[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.

func:[done_sgml_parser]: Release an SGML parser
-----------------------------------------------

Deallocates all resources, _expect_ the root node.

parser::	The parser being released.