Debian Codegraph @

README

raw
1 NAME
2 HTML::HTML5::Outline - implementation of the HTML5 Outline algorithm
3
4 SYNOPSIS
5 use JSON;
6 use HTML::HTML5::Outline;
7
8 my $html = <<'HTML';
9 <!doctype html>
10 <h1>Hello</h1>
11 <h2>World</h2>
12 <h1>Good Morning</h1>
13 <h2>Vietnam</h2>
14 HTML
15
16 my $outline = HTML::HTML5::Outline->new($html);
17 print to_json($outline->to_hashref, {pretty=>1,canonical=>1});
18
19 DESCRIPTION
20 This is an implementation of the HTML5 Outline algorithm, as per
21 <http://www.w3.org/TR/html5/sections.html#outlines>.
22
23 The module can output a JSON-friendly hashref, or an RDF model.
24
25 Constructor
26 * "HTML::HTML5::Outline->new($html, %options)"
27
28 Construct a new outline. $html is the HTML to generate an outline
29 from, either as an HTML or XHTML string, or as an
30 XML::LibXML::Document object.
31
32 Options:
33
34 * default_language - default language to assume text is in when no
35 lang/xml:lang attribute is available. e.g. 'en-gb'.
36
37 * element_subjects - rather advanced feature that doesn't bear
38 explaining. See USE WITH RDF::RDFA::PARSER for an example.
39
40 * microformats - support "<ul class="xoxo">", "<ol class="xoxo">"
41 and "<whatever class="figure">" as sectioning elements (like
42 "<section>", "<figure>", etc). Boolean, defaults to false.
43
44 * parser - 'html' (default) or 'xml' - choose the parser to use
45 for XHTML/HTML. If the constructor is passed an
46 XML::LibXML::Document, this is ignored.
47
48 * suppress_collections - allows rdf:List stuff to be suppressed
49 from RDF output. RDF output - especially in Turtle format -
50 looks somewhat nicer without them, but if you care about the
51 order of headings and sections, then you'll want them. Boolean,
52 defaults to false.
53
54 * uri - the document URI for resolving relative URI references.
55 Only really used by the RDF output.
56
57 Object Methods
58 * "to_hashref"
59
60 Returns data as a nested hashref/arrayref structure. Dump it as JSON
61 and you'll figure out the format pretty easily.
62
63 * "to_rdf"
64
65 Returns data as a n RDF::Trine::Model. Requires RDF::Trine to be
66 installed. Otherwise this method won't exist.
67
68 * "primary_outlinee"
69
70 Returns a HTML::HTML5::Outline::Outlinee element representing the
71 outline for the page.
72
73 Class Methods
74 * "has_rdf"
75
76 Indicates whether the "to_rdf" object method exists.
77
78 USE WITH RDF::RDFA::PARSER
79 This module produces RDF data where many of the resources described are
80 HTML elements. RDFa data typically does not, but RDF::RDFa::Parser does
81 also support some extensions to RDFa which do (e.g. support for the
82 "cite" and "role" attributes). It's useful to combine the RDF data from
83 each, and RDF::RDFa::Parser 1.093 and upwards contains a few shims to
84 make this possible.
85
86 Without further ado...
87
88 use HTML::HTML5::Outline;
89 use RDF::RDFa::Parser 1.093;
90 use RDF::TrineShortcuts;
91
92 my $rdfa = RDF::RDFa::Parser->new(
93 $html_source,
94 $base_url,
95 RDF::RDFa::Parser::Config->new(
96 'html5', '1.1',
97 role_attr => 1,
98 cite_attr => 1,
99 longdesc_attr => 1,
100 ),
101 )->consume;
102
103 my $outline = HTML::HTML5::Outline->new(
104 $rdfa->dom,
105 uri => $rdfa->uri,
106 element_subjects => $rdfa->element_subjects,
107 );
108
109 # Merging two graphs is pretty complicated in RDF::Trine
110 # but a little easier with RDF::TrineShortcuts...
111 my $combined = rdf_parse();
112 rdf_parse($rdfa->graph, model => $combined);
113 rdf_parse($outline->to_rdf, model => $combined);
114
115 my $NS = {
116 dc => 'http://purl.org/dc/terms/',
117 o => 'http://ontologi.es/outline#',
118 type => 'http://purl.org/dc/dcmitype/',
119 xs => 'http://www.w3.org/2001/XMLSchema#',
120 xhv => 'http://www.w3.org/1999/xhtml/vocab#',
121 };
122
123 print rdf_string($combined => 'Turtle', namespaces => $NS);
124
125 SEE ALSO
126 HTML::HTML5::Outline::RDF, HTML::HTML5::Outline::Outlinee,
127 HTML::HTML5::Outline::Section.
128
129 HTML::HTML5::Parser, HTML::HTML5::Sanity.
130
131 AUTHOR
132 Toby Inkster, <[email protected]>
133
134 ACKNOWLEDGEMENTS
135 This module is a fork of the document structure parser from Swignition
136 <http://buzzword.org.uk/swignition/>.
137
138 That in turn includes the following credits: thanks to Ryan King and
139 Geoffrey Sneddon for pointing me towards [the HTML5] algorithm. I also
140 used Geoffrey's python implementation as a crib sheet to help me figure
141 out what was supposed to happen when the HTML5 spec was ambiguous.
142
143 COPYRIGHT AND LICENCE
144 Copyright (C) 2008-2011 by Toby Inkster
145
146 This library is free software; you can redistribute it and/or modify it
147 under the same terms as Perl itself.
148