Update of /project/cxml/cvsroot/closure-common
In directory clnet:/tmp/cvs-serv30482
Modified Files:
hax.lisp
Log Message:
HAX documentation
--- /project/cxml/cvsroot/closure-common/hax.lisp 2007/10/14 17:29:43 1.1
+++ /project/cxml/cvsroot/closure-common/hax.lisp 2007/10/21 14:11:28 1.2
@@ -129,3 +129,268 @@
(:method ((handler default-handler) data)
(declare (ignore data))
nil))
+
+
+;;;; documentation
+
+(setf (documentation (find-package :hax) t)
+ "An event protocol for HTML serialization, this package is similar
+ to the HAX protocol defined by cxml for XML serialization.
+
+ (Technically, this package should have been spelled SAH, but HAX
+ sounds better.)
+
+ Note that Closure HTML is not a streaming parser yet. Documents
+ are always parsed in full before the first HAX event is emitted.
+ In spite of this restriction, the HAX API is useful for HTML
+ serialization and transformation purposes, and for integration
+ with SAX.
+
+ @begin[HAX handlers]{section}
+ @aboutclass{abstract-handler}
+ @aboutclass{default-handler}
+ @end{section}
+ @begin[The attribute protocol]{section}
+ @aboutclass{standard-attribute}
+ @aboutfun{make-attribute}
+ @aboutfun{attribute-name}
+ @aboutfun{attribute-value}
+ @aboutfun{attribute-specified-p}
+ @end{section}
+ @begin[HAX events]{section}
+ @aboutfun{start-document}
+ @aboutfun{start-element}
+ @aboutfun{end-element}
+ @aboutfun{characters}
+ @aboutfun{comment}
+ @aboutfun{end-document}
+ @end{section}")
+
+(setf (documentation 'abstract-handler 'type)
+ "@short{The superclass of all HAX handlers.}
+
+ Direct subclasses have to implement all event methods, since
+ no default methods are defined on this class.
+
+ Note that it is permissible to use handlers that are not
+ instances of this class in some circumstances.
+
+ In particular,
+ @code{nil} is a valid HAX handler and ignores all events.
+
+ In addition,
+ @a[http://common-lisp.net/project/cxml/sax.html#sax]{SAX handlers}
+ are valid HAX handlers (and vice versa), even though
+ hax:abstract-handler and sax:abstract-handler do not
+ share a specific superclass. HAX events sent to SAX handlers are
+ automatically re-signalled as XHTML SAX events, and SAX events sent
+ to HAX handlers are re-signalled as namespace-less HAX events.
+
+ However, user code should define subclasses of the documented
+ superclasses to enable the HAX/SAX bridging described above.
+
+ @see{chtml:parse}
+ @see{chtml:serialize-lhtml}
+ @see{chtml:serialize-pt}
+ @see{start-document}
+ @see{end-document}
+ @see{start-element}
+ @see{end-element}
+ @see{characters}
+ @see{comment}")
+
+(setf (documentation 'default-handler 'type)
+ "@short{A no-op HAX handler.}
+
+ This class defines methods for all HAX events that do nothing.
+ It is useful as a superclass when implementing a HAX handler that
+ is interested in only some events and not others.
+
+ @see{chtml:parse}
+ @see{chtml:serialize-lhtml}
+ @see{chtml:serialize-pt}
+ @see{start-document}
+ @see{end-document}
+ @see{start-element}
+ @see{end-element}
+ @see{characters}
+ @see{comment}")
+
+(setf (documentation 'standard-attribute 'type)
+ "@short{An implementation of the HAX attribute protocol.}
+
+ A standard class implementing the generic functions for HAX
+ attributes. Instances of this class can be passed to
+ @fun{hax:start-element} in the list of attributes.
+
+ @see-slot{attribute-name}
+ @see-slot{attribute-value}
+ @see-slot{attribute-specified-p}
+ @see-constructor{make-instance}")
+
+(setf (documentation 'make-attribute 'function)
+ "@arg[name]{a string/rod}
+ @arg[value]{a string/rod}
+ @arg[specified-p]{a boolean, default is @code{t}}
+ @return{an instance of @class{standard-attribute}.}
+ @short{Creates a HAX attribute.}
+
+ Creates an instance that can be used with the generic functions
+ for HAX attributes. The result can be passed to
+ @fun{hax:start-element} in the list of attributes.
+
+ @see{attribute-name}
+ @see{attribute-value}
+ @see{attribute-specified-p}")
+
+(setf (documentation 'find-attribute 'function)
+ "@arg[name]{a string/rod}
+ @arg[attrs]{a list of attributes}
+ @return{an attribute, or nil}
+ @short{Searches for an attribute by name.}
+
+ Returns the first attribute in @var{attrs} with the specified name,
+ or @code{nil} if no such attribute was found.
+
+ @see{attribute-name}")
+
+(setf (documentation 'attribute-name 'function)
+ "@arg[instance]{any class implementing this function}
+ @return{a string/rod}
+ @short{Return an attribute's name.}
+
+ Instances of this classes implementing this function can be passed to
+ @fun{hax:start-element} in the list of attributes.
+
+ @see{attribute-value}
+ @see{attribute-specified-p}")
+
+(setf (documentation 'attribute-value 'function)
+ "@arg[instance]{any class implementing this function}
+ @return{a string/rod}
+ @short{Return an attribute's value.}
+
+ Instances of this classes implementing this function can be passed to
+ @fun{hax:start-element} in the list of attributes.
+
+ @see{attribute-name}
+ @see{attribute-specified-p}")
+
+(setf (documentation 'attribute-specified-p 'function)
+ "@arg[instance]{any class implementing this function}
+ @return{a string/rod}
+ @short{Return whether the attribute was contained the parsed document.}
+
+ Attributes return @code{nil} here if they resulted from a default
+ value declaration in a DTD.
+
+ Instances of this classes implementing this function can be passed to
+ @fun{hax:start-element} in the list of attributes.
+
+ @see{attribute-name}
+ @see{attribute-value}")
+
+(setf (documentation 'start-document 'function)
+ "@arg[handler]{a HAX/SAX handler
+ (see @class{abstract-handler} for details)}
+ @arg[name]{root element name, a rod/string}
+ @arg[public-id]{nil or the Public ID, a rod/string}
+ @arg[system-id]{nil or the System ID/URI, a rod/string}
+ @return{unspecified}
+ @short{Signals the beginning on an HTML document.}
+
+ This is the first event sent to any handler.
+
+ If @var{system-id} is non-nil, the document includes a doctype
+ declaration.
+
+ @see{start-element}
+ @see{end-element}
+ @see{characters}
+ @see{comment}
+ @see{end-document}")
+
+(setf (documentation 'start-element 'function)
+ "@arg[handler]{a HAX/SAX handler
+ (see @class{abstract-handler} for details)}
+ @arg[name]{root element name, a rod/string}
+ @arg[attributes]{a list of attributes}
+ @return{unspecified}
+ @short{Signals the beginning of an HTML element.}
+
+ This event corresponds to the opening tag of an element.
+
+ Elements of the attribute list can have any class, but must implement
+ the generic functions for attributes. See @class{standard-attribute}
+ for the built-in attribute implementation.
+
+ @see{find-attribute}
+ @see{start-document}
+ @see{end-element}
+ @see{characters}
+ @see{comment}
+ @see{end-document}")
+
+(setf (documentation 'end-element 'function)
+ "@arg[handler]{a HAX/SAX handler
+ (see @class{abstract-handler} for details)}
+ @arg[name]{root element name, a rod/string}
+ @return{unspecified}
+ @short{Signals the end of an HTML element.}
+
+ This event corresponds to the closing tag of an element.
+
+ @see{start-document}
+ @see{start-element}
+ @see{characters}
+ @see{comment}
+ @see{end-document}")
+
+(setf (documentation 'characters 'function)
+ "@arg[handler]{a HAX/SAX handler
+ (see @class{abstract-handler} for details)}
+ @arg[data]{rod/string}
+ @return{unspecified}
+ @short{Signals character data.}
+
+ This event represents character data in a document.
+
+ @see{start-document}
+ @see{start-element}
+ @see{end-element}
+ @see{comment}
+ @see{end-document}")
+
+(setf (documentation 'comment 'function)
+ "@arg[handler]{a HAX/SAX handler
+ (see @class{abstract-handler} for details)}
+ @arg[data]{rod/string}
+ @return{unspecified}
+ @short{Signals a comment.}
+
+ This event represents a comment.
+
+ @see{start-document}
+ @see{start-element}
+ @see{end-element}
+ @see{characters}
+ @see{end-document}")
+
+(setf (documentation 'end-document 'function)
+ "@arg[handler]{a HAX/SAX handler
+ (see @class{abstract-handler} for details)}
+ @return{The return value of this function depends on the handler class.}
+ @short{Signals the end on an HTML document.}
+
+ This is the last event sent to any handler, and signals the end of
+ serialization.
+
+ The return value of this function is usually returned to user code
+ by higher-level serialization functions and can be considered the
+ result of serialization and \"return value\" of the handler.
+
+ @see{start-document}
+ @see{start-element}
+ @see{end-element}
+ @see{characters}
+ @see{comment}")
