view release on metacpan or  search on metacpan

html/pod/HTML.pod  view on Meta::CPAN

=for Marpa::R2::Display::End

Here is what C<$result> would contain after the above code was run:

=for Marpa::R2::Display
name: 'HTML Pod: Handler Precedence Result'
normalize-whitespace: 1

    ".high" handler: High Span
    wildcard handler: Low Span
    "div.high" handler: High Div
    "div" handler: Low Div
    ".oddball" handler: Oddball Div

=for Marpa::R2::Display::End

=head2 Details of the Specifier Syntax

For elements and class names only alphanumerics, hyphens and underscores are supported.
Elements must be specified in lowercase, but they will match tagnames in the original
document on a case-insensitive basis.

Forcing element names to be lowercase follows the default behavior of
L<HTML::Parser>, which coerces all tagnames to lowercase.
This is consistent with the HTML standards.
It is B<not> consistent with the XML standards,
and an option to configure this behavior may be added in
the future.

Pseudoclass names special to
L<Marpa::R2::HTML> are case-sensitive, and must be all uppercase.
Lowercase is reserved for CSS pseudoclasses.
The CSS standard specifies that its pseudoclass names are case-indifferent.
No CSS pseudoclasses are supported at this writing.

=head1 PSEUDOCLASSES

L<Marpa::R2::HTML> uses
L<HTML::Parser> to do its low-level parsing.
L<HTML::Parser> "events"
become the terminals for L<Marpa::R2::HTML>.

Besides terminals and elements,
three other HTML components are recognized:
the SGML prolog (C<:PROLOG>),
the SGML trailer (C<:TRAILER>),
and the HTML document as a whole (C<:TOP>).

=head2 :CDATA

The C<:CDATA> pseudoclass specifies the action for
CDATA terminals.
Its action is called once for each non-whitespace raw C<text> event
that is not reclassed as cruft.
(B<Raw text>
is text in which any markup and entities should be left as is.)

More precisely,
a C<:CDATA> terminal is created from any
L<HTML::Parser> C<text> event that has the C<is_cdata> flag on;
that contains a non-whitespace character
as defined in the HTML 4.01 specification
(L<http://www.w3.org/TR/html4/struct/text.html#h-9.1>);
and that is not reclassed as cruft.

=head2 :COMMENT

The C<:COMMENT> pseudoclass specifies the action for HTML comments.
Its action is called once for every C<HTML::Parser> C<comment> event that
is not reclassed as cruft.

=head2 :CRUFT

The C<:CRUFT> pseudoclass specifies the action for cruft.
Its action is called once for every C<HTML::Parser> event that
L<Marpa::R2::HTML> reclasses as cruft.

L<Marpa::R2::HTML> reclasses terminals as cruft when
they do not fit the structure of an HTML document.
One example of a terminal that
L<Marpa::R2::HTML> would reclass as cruft is a
C<< </head> >> end tag in the HTML body.

Reclassing terminals as cruft is only done as the last resort.
When it can,
L<HTML::Parser> forgives
violations of the HTML standards and accepts terminals as non-cruft.

Cruft is treated in much the same way as comments.
It is preserved, untouched, in the original text view.

=head2 :DECL

The C<:DECL> pseudoclass specifies the action for SGML declarations.
Its action is called once for every C<HTML::Parser> C<declaration> event that
is not reclassed as cruft.

=head2 :PCDATA

The C<:PCDATA> pseudoclass specifies the action for
PCDATA terminals.
Its action is called once for each non-whitespace non-raw C<text> event
that is not reclassed as cruft.

More precisely,
a C<:PCDATA> terminal is created from any
L<HTML::Parser> C<text> event that has the C<is_cdata> flag B<off>;
that contains a non-whitespace character
as defined in the HTML 4.01 specification
(L<http://www.w3.org/TR/html4/struct/text.html#h-9.1>);
and that is not reclassed as cruft.

Markup and entities in
C<:PCDATA> text
are expected to be interpreted eventually,
but it can be counter-productive to do this
during parsing.
An application may, for example,
be rewriting a document for display on the web.
In that case it will often
want to leave markup and entities for the client's browser
to interpret.

L<Marpa::R2::HTML> leaves interpretation of markup and entities entirely to
the application.
An application which chooses to do the interpretation itself
may do it in the actions,
or deal with it in post-processing.
CPAN has excellent tools for this,
some of which are part of L<HTML::Parser>.

=head2 :PI

The C<:PI> pseudoclass specifies the action for SGML processing instructions.
Its action is called once for every L<HTML::Parser> C<process> event that
is not reclassed as cruft.

=head2 :PROLOG

The C<:PROLOG> pseudoclass specifies the action for SGML prolog.
This is the part of the HTML document which precedes the HTML root element.
Components valid in the
prolog include SGML comments, processing instructions and whitespace.

=head2 :TOP

The action specified for the C<:TOP> pseudoclass will be called
once and only once in every parse,
and will be the last action called in every parse.
The C<:TOP> component is the entire
physical document, including
the SGML prolog,
the root element,
and the SGML trailer.
All the other HTML components in a document
will be descendants of the C<:TOP> component.

The C<:TOP> action is unique, in that there is always an action
for it, even if one is not specified.
The C<html> method returns the value
returned by the C<:TOP> action.
The default C<:TOP> action returns a B<reference> to a string
with the literal text value of all
of its descendants.

=head2 :TRAILER