File: parser.html

package info (click to toggle)
xmhtml 1.1.7-7
links: PTS
area: main
in suites: woody
size: 6,104 kB
ctags: 8,347
sloc: ansic: 68,063; makefile: 496; sh: 161; perl: 36
file content (715 lines) | stat: -rw-r--r-- 14,997 bytes
parent folder | download | duplicates (10)
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
	<TITLE>XmHTML Parser Description</TITLE>
	<META HTTP-EQUIV="Keywords" CONTENT="XmHTML, HTML, Motif, Widget, eXode, XntHelp, Linux">
	<META HTTP-EQUIV="Reply-to" CONTENT="ripley@xs4all.nl">
	<META HTTP-EQUIV="Description" CONTENT="This document describes 
the XmHTML html parser.">
	<META NAME="Author" CONTENT="Koen D'Hondt">
	<META NAME="Copyright" content="1995-1997 by Ripley Software Development">
	<META NAME="Source" content="$Source$">
	<META NAME="Revision" content="$Revision$">
	<link rel="TOC" href="XmHTML.html#toc">
	<link rel="copyright" href="copyrights.html">
</HEAD>

<BODY BGCOLOR="#FFFFFF" text="#000000">

<h1><a name="top">XmHTML Parser Description</a></h1>

<ul>
<li><a href="#overview">Overview</a>
<li><a href="#tree">Parser Tree</a>
<li><a href="#verification">Document Verification</a>
<li><a href="#repair">Document Repair</a>
<li><a href="#parserCallback">XmNparserCallback</a>
<li><a href="#documentCallback">XmNdocumentCallback</a>
<li><a href="#privateFuncs">Private functions</a>
<li><a href="#htmlEnum">XmHTML Element Identifiers</a>
</ul>
<p>

<p>
<a name="overview"><IMG SRC="../Images/wood/bar.gif" width=508 height=15></a>
<p>
<h2>Overview</h2>
This document describes XmHTML's HTML parser in detail and provides background
information on the how and why of document verification and repair. It is 
targetted towards programmers that want to make full use of the parser and
document callback resources as well as programmers that want to use the
generated parser tree for different purposes.
<p>

XmHTML's HTML parser is fairly powerfull in that it is capable of repairing
even the most terrible HTML documents as well as converting a non HTML 3.2
conforming document to a HTML 3.2 conforming one. The only reason for the
existance of these document verification and repair capabilities is that
XmHTML only works with fully balanced HTML documents. A balanced HTML document
is a document in which each terminated HTML element has its opening and
closing members at the same level.
<p>

<p>
<a name="tree"><IMG SRC="../Images/wood/bar.gif" width=508 height=15></a>
<p>
<h2>Parser Tree</h2>
When a document is loaded into XmHTML, the parser translates this document to
a doubly linked list of objects (referred to as the <i>Parser Tree</i>).
Each object contains either a HTML element (and its attributes) or plain text.

<a name="object"></a>
<pre>
typedef struct _XmHTMLObject{
	htmlEnum id;		/* ID for this element */
	String element;		/* element text */
	String attributes;	/* attributes for this element, if any */
	Boolean is_end;		/* true when this is a closing element */
	Boolean terminated;	/* true when element has a closing counterpart */
	int line;		/* line number for this element */
	struct _XmHTMLObject *next;
	struct _XmHTMLObject *prev;
}XmHTMLObject;
</pre>

The <i>id</i> field of this structure describes the type of element. 
The <a href="#htmlEnum">table</a> at the end of this document lists all
elements that XmHTML knows of.
<p>

When <i>id</i> is HT_ZTEXT, the <i>element</i> field contains plain text
as read from the document (character escape sequences <b>not</b> expanded).
The <i>attributes, is_end</i> and <i>terminated</i> elements are meaningless.
<p>

In all other cases, the <i>element</i> field contains the element name and the
<i>attributes</i> field contains possible attributes for this element. When
an element is terminated (that is, has a closing counterpart), the 
<i>terminated</i> field will be <b>True</b>, and the <i>is_end</i> field 
indicates whether the current element is an opening or a closing one.
Only unterminated or opening elements can have attributes.
<p>

The <i>element</i> and <i>attributes</i> fields are contained in the same
memory buffer, where the latter is separated from the former by a NULL
character. When freeing an object, freeing the <i>element</i> field will
also free the <i>attribute</i> field.
<p>

The <i>line</i> field contains the line number in the source document where
the element is located.
<p>

The <i>objects</i> field in the
<a href="#documentCallbackStruct">XmHTMLDocumentCallbackStruct</a> contains the
starting point of the parser tree.
<p>

Programmers that want to use the generated parser tree for different purposes
might be interested in some of the
<a href="#privateFuncs">XmHTML private functions</a> for extracting
attribute values and character escape sequence expansion.

<p>
<a name="verification"><IMG SRC="../Images/wood/bar.gif" width=508 height=15></a>
<p>

<h2>Document Verification</h2>

<p>
<a name="repair"><IMG SRC="../Images/wood/bar.gif" width=508 height=15></a>
<p>

<h2>Document Repair</h2>

<p>
<a name="parserCallback"><IMG SRC="../Images/wood/bar.gif" width=508 height=15></a>
<p>

<h2>XmNparserCallback</h2>

<pre>
typedef struct
{
	int reason;		/* the reason the callback was called */
	XEvent *event;		/* always NULL for XmNparserCallback */
	int no;			/* total error count uptil now */
	int line_no;		/* input line number where error was detected */
	int start_pos;		/* absolute index where error starts */
	int end_pos;		/* absolute index where error ends */
	parserError error;	/* type of error */
	int action;		/* suggested correction action */
	String err_msg;		/* error message */
}XmHTMLParserCallbackStruct, *XmHTMLParserCallbackStructPtr;
</pre>

This table lists all possible values for the <i>action</i> field, together
with a short description of what the parser response will be.
<p>

<table cols=2 border=1>
<tr>
	<th>Action
	<th>Description
<tr>
	<td>XmHTML_REMOVE
	<td>offending element will be removed
<tr>
	<td>XmHTML_INSERT
	<td>insert missing element
<tr>
	<td>XmHTML_SWITCH
	<td>switch offending and expected element
<tr>
	<td>XmHTML_KEEP
	<td>keep offending element
<tr>
	<td>XmHTML_IGNORE
	<td>ignore, proceed as if nothing happened
<tr>
	<td>XmHTML_TERMINATE
	<td>terminate parser
<tr>
</table>
<p>

Shown below are all possible values for the <i>error</i> field (default
action is displayed in <b>bold</b>), allowed actions and the value of the
<i>err_msg</i> field. When the <i>action</i> field is set to an action that
is not allowed for an error, XmHTML will use the default action.
<p>

<table cols=2 border=0>
	<tr valign="top" align="left">
	<th>error:
	<td>HTML_UNKNOWN_ELEMENT
	<tr valign="top" align="left">
	<th>actions:
	<td><b>XmHTML_REMOVE</b>, XmHTML_TERMINATE
	<tr valign="top" align="left">
	<th>err_msg:
	<td><tt>%s: unknown HTML identifier</tt>
</table>
<p>

<table cols=2 border=0>
	<tr valign="top" align="left">
	<td>error:
	<td>HTML_UNKNOWN_ESCAPE
	<tr valign="top" align="left">
	<td>actions:
	<td><b>XmHTML_REMOVE</b>, XmHTML_TERMINATE
	<tr valign="top" align="left">
	<td>err_msg:
	<td><tt>%s: unknown character escape sequence</tt>
</table>
<p>

<table cols=2 border=0>
	<tr valign="top" align="left">
	<td>error:
	<td>HTML_BAD
	<tr valign="top" align="left">
	<td>actions:
	<td><b>XmHTML_REMOVE</b>, XmHTML_IGNORE, XmHTML_TERMINATE
	<tr valign="top" align="left">
	<td>err_msg:
	<td><tt>Terrible HTML! element %s completely out of balance.</tt>
</table>
<p>

<table cols=2 border=0>
	<tr valign="top" align="left">
	<td>error:
	<td>HTML_OPEN_BLOCK
	<tr valign="top" align="left">
	<td>actions:
	<td><b>XmHTML_INSERT</b>, XmHTML_REMOVE, XmHTML_KEEP
	<tr valign="top" align="left">
	<td>err_msg:
	<td><tt>A new block level element (%s) was encountered while %s is
		still open.</tt>
	</table>
<p>

<table cols=2 border=0>
	<tr valign="top" align="left">
	<td>error:
	<td>HTML_CLOSE_BLOCK
	<tr valign="top" align="left">
	<td>actions:
	<td><b>XmHTML_REMOVE</b>, XmHTML_INSERT, XmHTML_KEEP, XmHTML_TERMINATE
	<tr valign="top" align="left">
	<td>err_msg:
	<td><tt>A closing block level element (%s) was encountered while it "
		was never opened.</tt>
	</table>
<p>

<table cols=2 border=0>
	<tr valign="top" align="left">
	<td>error:
	<td>HTML_OPEN_ELEMENT
	<tr valign="top" align="left">
	<td>actions:
	<td><b>XmHTML_REMOVE</b>, XmHTML_SWITCH, XmHTML_TERMINATE
	<tr valign="top" align="left">
	<td>err_msg:
	<td><tt>Unbalanced terminator: got %s while %s is required.</tt>
	</table>
<p>

<table cols=2 border=0>
	<tr valign="top" align="left">
	<td>error:
	<td>HTML_VIOLATION
	<tr valign="top" align="left">
	<td>actions:
	<td>XmHTML_REMOVE, XmHTML_KEEP, XmHTML_TERMINATE
	<tr valign="top" align="left">
	<td>err_msg:
	<td><tt>%s may not occur inside %s</tt>
</table>
<p>

<table cols=2 border=0>
	<tr valign="top" align="left">
	<td>error:
	<td>HTML_INTERNAL
	<tr valign="top" align="left">
	<td>actions:
	<td><b>XmHTML_TERMINATE</b>, XmHTML_IGNORE
	<tr valign="top" align="left">
	<td>err_msg:
	<td><tt>Internal parser error</tt>
</table>
<p>

<p>
<a name="documentCallback"><IMG SRC="../Images/wood/bar.gif" width=508 height=15></a>
<p>

<h2>XmNdocumentCallback</h2>

<a name="documentCallbackStruct"></a>
<pre>
typedef struct
{
	int reason;		/* the reason the callback was called */
	XEvent *event;		/* always NULL for XmNdocumentCallback */
	Boolean html32;		/* True when document was HTML 3.2 conforming */
	Boolean verified;	/* True when document has been verified */
	Boolean balanced;	/* True when parser tree is balanced */
	int pass_level;		/* current parser level count. Starts at 0 */
	Boolean redo;		/* See below */
	XmHTMLObject *objects;	/* parser tree starting point */
}XmHTMLDocumentCallbackStruct;
</pre>

<p>
<a name="privateFuncs"><IMG SRC="../Images/wood/bar.gif" width=508 height=15></a>
<p>

<h2>Private Functions</h2>
XmHTML uses a number of functions to extract values from the attributes
field of the <a href="#object">XmHTMLObject</a> structures. This section gives
a brief overview of these functions, along with the prototypes. The functions
themselves are defined in the header file <i>XmHTMLfuncs.h</i>.


<pre>
extern Boolean _XmHTMLTagCheck(char *attributes, char *tag);
</pre>

<dl>
<dd>Returns <b>True</b> when <tt>tag</tt> is present in the given attributes.
</dl>
<p>

<pre>
extern Boolean _XmHTMLTagCheckValue(char *attributes, char *tag, char *check);
</pre>

<dl>
<dd>Returns <b>True</b> when <tt>tag</tt> has the specified value
	<tt>check</tt> and <b>False</b> if not.
</dl>
<p>

<pre>
extern char *_XmHTMLTagGetValue(char *attributes, char *tag);
</pre>
<dl>
<dd>Returns the value of <tt>tag</tt> if found in the given attributes, NULL
	otherwise. The return value must be freed by the caller.
</dl>
<p>

<pre>
extern int _XmHTMLTagGetNumber(char *attributes, char *tag, int def);
</pre>
<dl>
<dd>Returns the numerical value of <tt>tag</tt> if found in the given
	attributes. <tt>def</tt> specifies the return value if <tt>tag</tt>
	is not found.
</dl>
<p>

The following function searches and expands any character escape sequences
in the given string:
<pre>
extern void _XmHTMLExpandEscapes(char *string);
</pre>
This function recognizes all escape sequences from the <tt>ISO 8895-1</tt>
character set, as well as all <tt>&amp;#</tt> character escapes below 160.
Escape sequences are not required to have a terminating semi-colon.
<p>

<p>
<a name="htmlEnum"><IMG SRC="../Images/wood/bar.gif" width=508 height=15></a>
<p>

<h2>XmHTML Element Identifiers</h2>

This table lists the internal identifiers, the name of the corresponding
HTML element and whether an element is terminated or not.
It includes the complete set of HTML 3.2 elements, as well as a small number
of extensions.

<table cols=6 border=1>
<caption align="top">XmHTML Element Identifiers</caption>
<tr>
	<td>id
	<td>Element
	<td>Terminated

	<td>id
	<td>Element
	<td>Terminated
<tr>

	<td>HT_DOCTYPE
	<td>!doctype
	<td>False

	<td>HT_A
	<td>a
	<td>True
<tr>
	<td>HT_ADDRESS
	<td>address
	<td>True

	<td>HT_APPLET
	<td>applet
	<td>True
<tr>
	<td>HT_AREA
	<td>area
	<td>False

	<td>HT_B
	<td>b
	<td>True
<tr>
	<td>HT_BASE
	<td>base
	<td>False

	<td>HT_BASEFONT
	<td>basefont
	<td>False
<tr>
	<td>HT_BIG
	<td>big
	<td>True

	<td>HT_BLOCKQUOTE
	<td>blockquote
	<td>True
<tr>
	<td>HT_BODY
	<td>body
	<td>True

	<td>HT_BR
	<td>br
	<td>False
<tr>
	<td>HT_CAPTION
	<td>caption
	<td>True

	<td>HT_CENTER
	<td>center
	<td>True
<tr>
	<td>HT_CITE
	<td>cite
	<td>True

	<td>HT_CODE,
	<td>code
	<td>True
<tr>
	<td>HT_DD
	<td>dd
	<td>True

	<td>HT_DFN
	<td>dfn
	<td>True
<tr>
	<td>HT_DIR
	<td>dir
	<td>True

	<td>HT_DIV
	<td>div
	<td>True
<tr>
	<td>HT_DL
	<td>dl
	<td>True

	<td>HT_DT
	<td>dt
	<td>True
<tr>
	<td>HT_EM
	<td>em
	<td>True

	<td>HT_FONT
	<td>font
	<td>True
<tr>
	<td>HT_FORM
	<td>form
	<td>True

	<td>HT_FRAME
	<td>frame
	<td>True
<tr>
	<td>HT_FRAMESET
	<td>frameset
	<td>True

	<td>HT_H1
	<td>h2
	<td>True
<tr>
	<td>HT_H2
	<td>h2
	<td>True

	<td>HT_H3
	<td>h3
	<td>True
<tr>
	<td>HT_H4
	<td>h4
	<td>True

	<td>HT_H5
	<td>h5
	<td>True
<tr>
	<td>HT_H6
	<td>h6
	<td>True

	<td>HT_HEAD
	<td>head
	<td>True
<tr>
	<td>HT_HR
	<td>hr
	<td>False

	<td>HT_HTML
	<td>html
	<td>True
<tr>
	<td>HT_I
	<td>i
	<td>True

	<td>HT_IMG
	<td>img
	<td>False
<tr>
	<td>HT_INPUT
	<td>input
	<td>False

	<td>HT_ISINDEX
	<td>isindex
	<td>False
<tr>
	<td>HT_KBD
	<td>kbd
	<td>True

	<td>HT_LI
	<td>li
	<td>True
<tr>
	<td>HT_LINK
	<td>link
	<td>False

	<td>HT_MAP
	<td>map
	<td>True
<tr>
	<td>HT_MENU,
	<td>menu
	<td>True

	<td>HT_META
	<td>meta
	<td>False
<tr>
	<td>HT_NOFRAMES
	<td>noframes
	<td>True

	<td>HT_OL
	<td>ol
	<td>True
<tr>
	<td>HT_OPTION
	<td>option
	<td>True

	<td>HT_P
	<td>p
	<td>True
<tr>
	<td>HT_PARAM
	<td>param
	<td>False

	<td>HT_PRE
	<td>pre
	<td>True
<tr>
	<td>HT_SAMP
	<td>samp
	<td>True

	<td>HT_SCRIPT
	<td>script
	<td>True
<tr>
	<td>HT_SELECT
	<td>select
	<td>True

	<td>HT_SMALL
	<td>small
	<td>True
<tr>
	<td>HT_STRIKE
	<td>strike
	<td>True

	<td>HT_STRONG
	<td>strong
	<td>True
<tr>
	<td>HT_STYLE
	<td>style
	<td>True

	<td>HT_SUB
	<td>sub
	<td>True
<tr>
	<td>HT_SUP
	<td>sup
	<td>True

	<td>HT_TAB
	<td>tab
	<td>False
<tr>
	<td>HT_TABLE
	<td>table
	<td>True

	<td>HT_TD
	<td>td
	<td>True
<tr>
	<td>HT_TEXTAREA
	<td>textarea
	<td>True

	<td>HT_TH
	<td>th
	<td>True
<tr>
	<td>HT_TITLE,
	<td>title
	<td>True

	<td>HT_TR
	<td>tr
	<td>True
<tr>
	<td>HT_TT
	<td>tt
	<td>True

	<td>HT_U
	<td>u
	<td>True
<tr>
	<td>HT_UL
	<td>ul
	<td>True

	<td>HT_VAR
	<td>var
	<td>True
<tr>
	<td>HT_ZTEXT
	<td>plain text
	<td>False

	<td>&nbsp;
	<td>&nbsp;
	<td>&nbsp;
</table>

<p>
<IMG SRC="../Images/wood/bar.gif" width=508 height=15>
<br>

<img ismap usemap=#back src="../Images/wood/back.gif" border=0>
<map name=back>
	<area href="XmHTML.html" shape=rect coords=0,0,83,33>
</map>

<img ismap usemap=#index_map src="../Images/wood/home.gif" border=0>
<map name=index_map>
	<area href="../index.html#toc" shape=rect coords=0,0,83,33>
</map>
<img ismap usemap=#email_map src="../Images/wood/email.gif" border=0>
<map name=email_map>
	<area href="mailto:ripley@xs4all.nl" shape=rect coords=0,0,83,33>
</map>

<br>
<IMG SRC="../Images/wood/bar.gif" width=508 height=15>
<br>

<i><font size="-1">
&copy;Copyright 1996-1997 by Ripley Software Development<br>
Last update: September 19, 1997 by Koen
</font></i>
</BODY>
</HTML>