| 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 |
|