HTML::...utline(3pm)

💖 HTML::...utline(3pm) 💖

okay bestie, this is the page for HTML::HTML5::Outline (the man page header lowkey abbreviates it to HTML::...utline(3pm) because ✨aesthetic✨, it lives in User Contributed Perl Documentation). buckle up, we're outlining HTML5 and it's gonna be iconic.

---

✨ NAME ✨

HTML::HTML5::Outline — literally just an implementation of the HTML5 Outline algorithm. that's it, that's the whole thing, and she ate 💅

---

🌸 SYNOPSIS 🌸

        use JSON;
        use HTML::HTML5::Outline;

        my $html = <<'HTML';
        <!doctype html>
        <h1>Hello</h1>
        <h2>World</h2>
        <h1>Good Morning</h1>
        <h2>Vietnam</h2>
        HTML

        my $outline = HTML::HTML5::Outline->new($html);
        print to_json($outline->to_hashref, {pretty=>1,canonical=>1});

no cap, that's the whole vibe right there 🦋

---

🎀 DESCRIPTION 🎀

so this module is an implementation of the HTML5 Outline algorithm, exactly as laid out over at <http://www.w3.org/TR/html5/sections.html#outlines>. go read the spec if you're feeling scholarly, i believe in you 🫶

and she can hand you back either a JSON-friendly hashref or an RDF model. versatile queen 👑

---

🧚 Constructor 🧚

• HTML::HTML5::Outline->new($html, %options) — bestie, this makes you a brand new outline. $html is the HTML you want an outline from, and it can be either an HTML or XHTML string, or an XML::LibXML::Document object. whatever's easiest for you, no judgement 💜

the options are:

• default_language — the language we just assume the text is in when there's no lang/xml:lang attribute anywhere to tell us. like, e.g. 'en-gb'. 🔥
• element_subjects — okay so this one is a rather advanced feature that honestly doesn't bear explaining. if you're curious, peek at USE WITH RDF::RDFA::PARSER below for an example. iykyk 🙈
• microformats — this one's a yes/no. when it's on, <ul class="xoxo">, <ol class="xoxo"> and <whatever class="figure"> get treated as sectioning elements, just like <section>, <figure>, etc. it's a boolean and it defaults to false. 🌸
• parser — pick your parser for XHTML/HTML: 'html' (that's the default) or 'xml'. heads up though — if the constructor gets handed an XML::LibXML::Document, this option is just ignored entirely. 💀
• suppress_collections — this lets you suppress the rdf:List stuff from the RDF output. and ngl, RDF output — especially in Turtle format — looks somewhat nicer without them. but if you actually care about the order of headings and sections, then bestie you want them. boolean, defaults to false. ✨
• uri — the document URI, used for resolving relative URI references. it's only really used by the RDF output, so don't stress about it otherwise. 💖

---

👑 Object Methods 👑

• to_hashref — hands you back the data as a nested hashref/arrayref structure. dump it as JSON and you'll figure out the format pretty easily, fr fr. 🌈
• to_rdf — hands you back the data as an RDF::Trine::Model. this one requires RDF::Trine to be installed. if it isn't, this method just... won't exist. that's it, that's the deal 🫶
• primary_outlinee — returns a HTML::HTML5::Outline::Outlinee element representing the outline for the page. main character energy tbh 👑

---

💅 Class Methods 💅

• has_rdf — tells you whether the to_rdf object method even exists. a little vibe check, if you will. ⭐

---

🦋 USE WITH RDF::RDFA::PARSER 🦋

okay so this module produces RDF data where lots of the resources described are HTML elements. RDFa data typically isn't like that, but RDF::RDFa::Parser does also support some extensions to RDFa that are (e.g. support for the cite and role attributes). so it's genuinely useful to combine the RDF data from each of them, and RDF::RDFa::Parser 1.093 and upwards contains a few shims to make that possible. iconic teamwork honestly 💖

without further ado... (bestie i love this part)

        use HTML::HTML5::Outline;
        use RDF::RDFa::Parser 1.093;
        use RDF::TrineShortcuts;

        my $rdfa = RDF::RDFa::Parser->new(
                $html_source,
                $base_url,
                RDF::RDFa::Parser::Config->new(
                        'html5', '1.1',
                        role_attr     => 1,
                        cite_attr     => 1,
                        longdesc_attr => 1,
                        ),
                )->consume;

        my $outline = HTML::HTML5::Outline->new(
                $rdfa->dom,
                uri              => $rdfa->uri,
                element_subjects => $rdfa->element_subjects,
                );

        # Merging two graphs is pretty complicated in RDF::Trine
        # but a little easier with RDF::TrineShortcuts...
        my $combined = rdf_parse();
        rdf_parse($rdfa->graph,     model => $combined);
        rdf_parse($outline->to_rdf, model => $combined);

        my $NS = {
                dc    => 'http://purl.org/dc/terms/',
                o     => 'http://ontologi.es/outline#',
                type  => 'http://purl.org/dc/dcmitype/',
                xs    => 'http://www.w3.org/2001/XMLSchema#',
                xhv   => 'http://www.w3.org/1999/xhtml/vocab#',
                };

        print rdf_string($combined => 'Turtle', namespaces => $NS);

slay 🌟

---

🌈 SEE ALSO 🌈

HTML::HTML5::Outline::RDF, HTML::HTML5::Outline::Outlinee, HTML::HTML5::Outline::Section.

HTML::HTML5::Parser, HTML::HTML5::Sanity.

(the whole friend group, obsessed 🫶)

---

💜 AUTHOR 💜

Toby Inkster, <tobyink@cpan.org>

---

🎀 ACKNOWLEDGEMENTS 🎀

this module is a fork of the document structure parser from Swignition <http://buzzword.org.uk/swignition/>. glow-up behavior ✨

and that in turn includes the following credits: thanks to Ryan King and Geoffrey Sneddon for pointing me towards [the HTML5] algorithm. i also used Geoffrey's python implementation as a crib sheet to help me figure out what was supposed to happen when the HTML5 spec was ambiguous. (the spec being ambiguous? shocking. never. 😭)

---

🌸 COPYRIGHT AND LICENCE 🌸

Copyright (C) 2008-2011 by Toby Inkster

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page bestie!! 💖 perl v5.36.0, dated 2022-11-19 — no cap, she's still serving. go forth and outline, you absolute legend 👑🎀🦋