X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=catagits%2FGitalist.git;a=blobdiff_plain;f=local-lib5%2Fman%2Fman3%2FXML%3A%3AParser.3pm;fp=local-lib5%2Fman%2Fman3%2FXML%3A%3AParser.3pm;h=6a22e1f94c498cce6bab4318f3c2e10a0da30908;hp=0000000000000000000000000000000000000000;hb=3fea05b9fbf95091f4522528b9980a33e0235603;hpb=af746827daa7a8feccee889e1d12ebc74cc9201e
diff --git a/local-lib5/man/man3/XML::Parser.3pm b/local-lib5/man/man3/XML::Parser.3pm
new file mode 100644
index 0000000..6a22e1f
--- /dev/null
+++ b/local-lib5/man/man3/XML::Parser.3pm
@@ -0,0 +1,594 @@
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. \*(C+ will
+.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.el \{\
+. de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "Parser 3"
+.TH Parser 3 "2007-11-20" "perl v5.8.7" "User Contributed Perl Documentation"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+XML::Parser \- A perl module for parsing XML documents
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+.Vb 1
+\& use XML::Parser;
+\&
+\& $p1 = new XML::Parser(Style => \*(AqDebug\*(Aq);
+\& $p1\->parsefile(\*(AqREC\-xml\-19980210.xml\*(Aq);
+\& $p1\->parse(\*(AqHello World\*(Aq);
+\&
+\& # Alternative
+\& $p2 = new XML::Parser(Handlers => {Start => \e&handle_start,
+\& End => \e&handle_end,
+\& Char => \e&handle_char});
+\& $p2\->parse($socket);
+\&
+\& # Another alternative
+\& $p3 = new XML::Parser(ErrorContext => 2);
+\&
+\& $p3\->setHandlers(Char => \e&text,
+\& Default => \e&other);
+\&
+\& open(FOO, \*(Aqxmlgenerator |\*(Aq);
+\& $p3\->parse(*FOO, ProtocolEncoding => \*(AqISO\-8859\-1\*(Aq);
+\& close(FOO);
+\&
+\& $p3\->parsefile(\*(Aqjunk.xml\*(Aq, ErrorContext => 3);
+.Ve
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+This module provides ways to parse \s-1XML\s0 documents. It is built on top of
+XML::Parser::Expat, which is a lower level interface to James Clark's
+expat library. Each call to one of the parsing methods creates a new
+instance of XML::Parser::Expat which is then used to parse the document.
+Expat options may be provided when the XML::Parser object is created.
+These options are then passed on to the Expat object on each parse call.
+They can also be given as extra arguments to the parse methods, in which
+case they override options given at XML::Parser creation time.
+.PP
+The behavior of the parser is controlled either by \f(CW"Style"\fR and/or
+\&\f(CW"Handlers"\fR options, or by \*(L"setHandlers\*(R" method. These all provide
+mechanisms for XML::Parser to set the handlers needed by XML::Parser::Expat.
+If neither \f(CW\*(C`Style\*(C'\fR nor \f(CW\*(C`Handlers\*(C'\fR are specified, then parsing just
+checks the document for being well-formed.
+.PP
+When underlying handlers get called, they receive as their first parameter
+the \fIExpat\fR object, not the Parser object.
+.SH "METHODS"
+.IX Header "METHODS"
+.IP "new" 4
+.IX Item "new"
+This is a class method, the constructor for XML::Parser. Options are passed
+as keyword value pairs. Recognized options are:
+.RS 4
+.IP "\(bu" 4
+Style
+.Sp
+This option provides an easy way to create a given style of parser. The
+built in styles are: \*(L"Debug\*(R", \*(L"Subs\*(R", \*(L"Tree\*(R", \*(L"Objects\*(R",
+and \*(L"Stream\*(R". These are all defined in separate packages under
+\&\f(CW\*(C`XML::Parser::Style::*\*(C'\fR, and you can find further documentation for
+each style both below, and in those packages.
+.Sp
+Custom styles can be provided by giving a full package name containing
+at least one '::'. This package should then have subs defined for each
+handler it wishes to have installed. See \*(L"\s-1STYLES\s0\*(R" below
+for a discussion of each built in style.
+.IP "\(bu" 4
+Handlers
+.Sp
+When provided, this option should be an anonymous hash containing as
+keys the type of handler and as values a sub reference to handle that
+type of event. All the handlers get passed as their 1st parameter the
+instance of expat that is parsing the document. Further details on
+handlers can be found in \*(L"\s-1HANDLERS\s0\*(R". Any handler set here
+overrides the corresponding handler set with the Style option.
+.IP "\(bu" 4
+Pkg
+.Sp
+Some styles will refer to subs defined in this package. If not provided,
+it defaults to the package which called the constructor.
+.IP "\(bu" 4
+ErrorContext
+.Sp
+This is an Expat option. When this option is defined, errors are reported
+in context. The value should be the number of lines to show on either side
+of the line in which the error occurred.
+.IP "\(bu" 4
+ProtocolEncoding
+.Sp
+This is an Expat option. This sets the protocol encoding name. It defaults
+to none. The built-in encodings are: \f(CW\*(C`UTF\-8\*(C'\fR, \f(CW\*(C`ISO\-8859\-1\*(C'\fR, \f(CW\*(C`UTF\-16\*(C'\fR, and
+\&\f(CW\*(C`US\-ASCII\*(C'\fR. Other encodings may be used if they have encoding maps in one
+of the directories in the \f(CW@Encoding_Path\fR list. Check \*(L"\s-1ENCODINGS\s0\*(R" for
+more information on encoding maps. Setting the protocol encoding overrides
+any encoding in the \s-1XML\s0 declaration.
+.IP "\(bu" 4
+Namespaces
+.Sp
+This is an Expat option. If this is set to a true value, then namespace
+processing is done during the parse. See \*(L"Namespaces\*(R" in XML::Parser::Expat
+for further discussion of namespace processing.
+.IP "\(bu" 4
+NoExpand
+.Sp
+This is an Expat option. Normally, the parser will try to expand references
+to entities defined in the internal subset. If this option is set to a true
+value, and a default handler is also set, then the default handler will be
+called when an entity reference is seen in text. This has no effect if a
+default handler has not been registered, and it has no effect on the expansion
+of entity references inside attribute values.
+.IP "\(bu" 4
+Stream_Delimiter
+.Sp
+This is an Expat option. It takes a string value. When this string is found
+alone on a line while parsing from a stream, then the parse is ended as if it
+saw an end of file. The intended use is with a stream of xml documents in a
+\&\s-1MIME\s0 multipart format. The string should not contain a trailing newline.
+.IP "\(bu" 4
+ParseParamEnt
+.Sp
+This is an Expat option. Unless standalone is set to \*(L"yes\*(R" in the \s-1XML\s0
+declaration, setting this to a true value allows the external \s-1DTD\s0 to be read,
+and parameter entities to be parsed and expanded.
+.IP "\(bu" 4
+NoLWP
+.Sp
+This option has no effect if the ExternEnt or ExternEntFin handlers are
+directly set. Otherwise, if true, it forces the use of a file based external
+entity handler.
+.IP "\(bu" 4
+Non-Expat-Options
+.Sp
+If provided, this should be an anonymous hash whose keys are options that
+shouldn't be passed to Expat. This should only be of concern to those
+subclassing XML::Parser.
+.RE
+.RS 4
+.RE
+.IP "setHandlers(\s-1TYPE\s0, \s-1HANDLER\s0 [, \s-1TYPE\s0, \s-1HANDLER\s0 [...]])" 4
+.IX Item "setHandlers(TYPE, HANDLER [, TYPE, HANDLER [...]])"
+This method registers handlers for various parser events. It overrides any
+previous handlers registered through the Style or Handler options or through
+earlier calls to setHandlers. By providing a false or undefined value as
+the handler, the existing handler can be unset.
+.Sp
+This method returns a list of type, handler pairs corresponding to the
+input. The handlers returned are the ones that were in effect prior to
+the call.
+.Sp
+See a description of the handler types in \*(L"\s-1HANDLERS\s0\*(R".
+.IP "parse(\s-1SOURCE\s0 [, \s-1OPT\s0 => \s-1OPT_VALUE\s0 [...]])" 4
+.IX Item "parse(SOURCE [, OPT => OPT_VALUE [...]])"
+The \s-1SOURCE\s0 parameter should either be a string containing the whole \s-1XML\s0
+document, or it should be an open IO::Handle. Constructor options to
+XML::Parser::Expat given as keyword-value pairs may follow the \s-1SOURCE\s0
+parameter. These override, for this call, any options or attributes passed
+through from the XML::Parser instance.
+.Sp
+A die call is thrown if a parse error occurs. Otherwise it will return 1
+or whatever is returned from the \fBFinal\fR handler, if one is installed.
+In other words, what parse may return depends on the style.
+.IP "parsestring" 4
+.IX Item "parsestring"
+This is just an alias for parse for backwards compatibility.
+.IP "parsefile(\s-1FILE\s0 [, \s-1OPT\s0 => \s-1OPT_VALUE\s0 [...]])" 4
+.IX Item "parsefile(FILE [, OPT => OPT_VALUE [...]])"
+Open \s-1FILE\s0 for reading, then call parse with the open handle. The file
+is closed no matter how parse returns. Returns what parse returns.
+.IP "parse_start([ \s-1OPT\s0 => \s-1OPT_VALUE\s0 [...]])" 4
+.IX Item "parse_start([ OPT => OPT_VALUE [...]])"
+Create and return a new instance of XML::Parser::ExpatNB. Constructor
+options may be provided. If an init handler has been provided, it is
+called before returning the ExpatNB object. Documents are parsed by
+making incremental calls to the parse_more method of this object, which
+takes a string. A single call to the parse_done method of this object,
+which takes no arguments, indicates that the document is finished.
+.Sp
+If there is a final handler installed, it is executed by the parse_done
+method before returning and the parse_done method returns whatever is
+returned by the final handler.
+.SH "HANDLERS"
+.IX Header "HANDLERS"
+Expat is an event based parser. As the parser recognizes parts of the
+document (say the start or end tag for an \s-1XML\s0 element), then any handlers
+registered for that type of an event are called with suitable parameters.
+All handlers receive an instance of XML::Parser::Expat as their first
+argument. See \*(L"\s-1METHODS\s0\*(R" in XML::Parser::Expat for a discussion of the
+methods that can be called on this object.
+.SS "Init (Expat)"
+.IX Subsection "Init (Expat)"
+This is called just before the parsing of the document starts.
+.SS "Final (Expat)"
+.IX Subsection "Final (Expat)"
+This is called just after parsing has finished, but only if no errors
+occurred during the parse. Parse returns what this returns.
+.SS "Start (Expat, Element [, Attr, Val [,...]])"
+.IX Subsection "Start (Expat, Element [, Attr, Val [,...]])"
+This event is generated when an \s-1XML\s0 start tag is recognized. Element is the
+name of the \s-1XML\s0 element type that is opened with the start tag. The Attr &
+Val pairs are generated for each attribute in the start tag.
+.SS "End (Expat, Element)"
+.IX Subsection "End (Expat, Element)"
+This event is generated when an \s-1XML\s0 end tag is recognized. Note that
+an \s-1XML\s0 empty tag () generates both a start and an end event.
+.SS "Char (Expat, String)"
+.IX Subsection "Char (Expat, String)"
+This event is generated when non-markup is recognized. The non-markup
+sequence of characters is in String. A single non-markup sequence of
+characters may generate multiple calls to this handler. Whatever the
+encoding of the string in the original document, this is given to the
+handler in \s-1UTF\-8\s0.
+.SS "Proc (Expat, Target, Data)"
+.IX Subsection "Proc (Expat, Target, Data)"
+This event is generated when a processing instruction is recognized.
+.SS "Comment (Expat, Data)"
+.IX Subsection "Comment (Expat, Data)"
+This event is generated when a comment is recognized.
+.SS "CdataStart (Expat)"
+.IX Subsection "CdataStart (Expat)"
+This is called at the start of a \s-1CDATA\s0 section.
+.SS "CdataEnd (Expat)"
+.IX Subsection "CdataEnd (Expat)"
+This is called at the end of a \s-1CDATA\s0 section.
+.SS "Default (Expat, String)"
+.IX Subsection "Default (Expat, String)"
+This is called for any characters that don't have a registered handler.
+This includes both characters that are part of markup for which no
+events are generated (markup declarations) and characters that
+could generate events, but for which no handler has been registered.
+.PP
+Whatever the encoding in the original document, the string is returned to
+the handler in \s-1UTF\-8\s0.
+.SS "Unparsed (Expat, Entity, Base, Sysid, Pubid, Notation)"
+.IX Subsection "Unparsed (Expat, Entity, Base, Sysid, Pubid, Notation)"
+This is called for a declaration of an unparsed entity. Entity is the name
+of the entity. Base is the base to be used for resolving a relative \s-1URI\s0.
+Sysid is the system id. Pubid is the public id. Notation is the notation
+name. Base and Pubid may be undefined.
+.SS "Notation (Expat, Notation, Base, Sysid, Pubid)"
+.IX Subsection "Notation (Expat, Notation, Base, Sysid, Pubid)"
+This is called for a declaration of notation. Notation is the notation name.
+Base is the base to be used for resolving a relative \s-1URI\s0. Sysid is the system
+id. Pubid is the public id. Base, Sysid, and Pubid may all be undefined.
+.SS "ExternEnt (Expat, Base, Sysid, Pubid)"
+.IX Subsection "ExternEnt (Expat, Base, Sysid, Pubid)"
+This is called when an external entity is referenced. Base is the base to be
+used for resolving a relative \s-1URI\s0. Sysid is the system id. Pubid is the public
+id. Base, and Pubid may be undefined.
+.PP
+This handler should either return a string, which represents the contents of
+the external entity, or return an open filehandle that can be read to obtain
+the contents of the external entity, or return undef, which indicates the
+external entity couldn't be found and will generate a parse error.
+.PP
+If an open filehandle is returned, it must be returned as either a glob
+(*FOO) or as a reference to a glob (e.g. an instance of IO::Handle).
+.PP
+A default handler is installed for this event. The default handler is
+XML::Parser::lwp_ext_ent_handler unless the NoLWP option was provided with
+a true value, otherwise XML::Parser::file_ext_ent_handler is the default
+handler for external entities. Even without the NoLWP option, if the
+\&\s-1URI\s0 or \s-1LWP\s0 modules are missing, the file based handler ends up being used
+after giving a warning on the first external entity reference.
+.PP
+The \s-1LWP\s0 external entity handler will use proxies defined in the environment
+(http_proxy, ftp_proxy, etc.).
+.PP
+Please note that the \s-1LWP\s0 external entity handler reads the entire
+entity into a string and returns it, where as the file handler opens a
+filehandle.
+.PP
+Also note that the file external entity handler will likely choke on
+absolute URIs or file names that don't fit the conventions of the local
+operating system.
+.PP
+The expat base method can be used to set a basename for
+relative pathnames. If no basename is given, or if the basename is itself
+a relative name, then it is relative to the current working directory.
+.SS "ExternEntFin (Expat)"
+.IX Subsection "ExternEntFin (Expat)"
+This is called after parsing an external entity. It's not called unless
+an ExternEnt handler is also set. There is a default handler installed
+that pairs with the default ExternEnt handler.
+.PP
+If you're going to install your own ExternEnt handler, then you should
+set (or unset) this handler too.
+.SS "Entity (Expat, Name, Val, Sysid, Pubid, Ndata, IsParam)"
+.IX Subsection "Entity (Expat, Name, Val, Sysid, Pubid, Ndata, IsParam)"
+This is called when an entity is declared. For internal entities, the Val
+parameter will contain the value and the remaining three parameters will be
+undefined. For external entities, the Val parameter will be undefined, the
+Sysid parameter will have the system id, the Pubid parameter will have the
+public id if it was provided (it will be undefined otherwise), the Ndata
+parameter will contain the notation for unparsed entities. If this is a
+parameter entity declaration, then the IsParam parameter is true.
+.PP
+Note that this handler and the Unparsed handler above overlap. If both are
+set, then this handler will not be called for unparsed entities.
+.SS "Element (Expat, Name, Model)"
+.IX Subsection "Element (Expat, Name, Model)"
+The element handler is called when an element declaration is found. Name
+is the element name, and Model is the content model as an XML::Parser::Content
+object. See \*(L"XML::Parser::ContentModel Methods\*(R" in XML::Parser::Expat
+for methods available for this class.
+.SS "Attlist (Expat, Elname, Attname, Type, Default, Fixed)"
+.IX Subsection "Attlist (Expat, Elname, Attname, Type, Default, Fixed)"
+This handler is called for each attribute in an \s-1ATTLIST\s0 declaration.
+So an \s-1ATTLIST\s0 declaration that has multiple attributes will generate multiple
+calls to this handler. The Elname parameter is the name of the element with
+which the attribute is being associated. The Attname parameter is the name
+of the attribute. Type is the attribute type, given as a string. Default is
+the default value, which will either be \*(L"#REQUIRED\*(R", \*(L"#IMPLIED\*(R" or a quoted
+string (i.e. the returned string will begin and end with a quote character).
+If Fixed is true, then this is a fixed attribute.
+.SS "Doctype (Expat, Name, Sysid, Pubid, Internal)"
+.IX Subsection "Doctype (Expat, Name, Sysid, Pubid, Internal)"
+This handler is called for \s-1DOCTYPE\s0 declarations. Name is the document type
+name. Sysid is the system id of the document type, if it was provided,
+otherwise it's undefined. Pubid is the public id of the document type,
+which will be undefined if no public id was given. Internal is the internal
+subset, given as a string. If there was no internal subset, it will be
+undefined. Internal will contain all whitespace, comments, processing
+instructions, and declarations seen in the internal subset. The declarations
+will be there whether or not they have been processed by another handler
+(except for unparsed entities processed by the Unparsed handler). However,
+comments and processing instructions will not appear if they've been processed
+by their respective handlers.
+.SS "* DoctypeFin (Parser)"
+.IX Subsection "* DoctypeFin (Parser)"
+This handler is called after parsing of the \s-1DOCTYPE\s0 declaration has finished,
+including any internal or external \s-1DTD\s0 declarations.
+.SS "XMLDecl (Expat, Version, Encoding, Standalone)"
+.IX Subsection "XMLDecl (Expat, Version, Encoding, Standalone)"
+This handler is called for xml declarations. Version is a string containg
+the version. Encoding is either undefined or contains an encoding string.
+Standalone will be either true, false, or undefined if the standalone attribute
+is yes, no, or not made respectively.
+.SH "STYLES"
+.IX Header "STYLES"
+.SS "Debug"
+.IX Subsection "Debug"
+This just prints out the document in outline form. Nothing special is
+returned by parse.
+.SS "Subs"
+.IX Subsection "Subs"
+Each time an element starts, a sub by that name in the package specified
+by the Pkg option is called with the same parameters that the Start
+handler gets called with.
+.PP
+Each time an element ends, a sub with that name appended with an underscore
+(\*(L"_\*(R"), is called with the same parameters that the End handler gets called
+with.
+.PP
+Nothing special is returned by parse.
+.SS "Tree"
+.IX Subsection "Tree"
+Parse will return a parse tree for the document. Each node in the tree
+takes the form of a tag, content pair. Text nodes are represented with
+a pseudo-tag of \*(L"0\*(R" and the string that is their content. For elements,
+the content is an array reference. The first item in the array is a
+(possibly empty) hash reference containing attributes. The remainder of
+the array is a sequence of tag-content pairs representing the content
+of the element.
+.PP
+So for example the result of parsing:
+.PP
+.Vb 1
+\& Hello thereHowdy