}
1;
+
+__END__
+
+=head1 NAME
+
+HTML::String::Overload - Use constant overloading with L<HTML::String>
+
+=head1 SYNOPSIS
+
+ use HTML::String::Overload;
+
+ my $html = '<h1>'; # marked as HTML
+
+ no HTML::String::Overload;
+
+ my $text = '<h1>'; # not touched
+
+ my $html = do {
+ use HTML::String::Overload;
+
+ '<h1>'; # marked as HTML
+ };
+
+ my $text = '<h1>'; # not touched
+
+=head1 DESCRIPTION
+
+This module installs a constant overload for strings - see
+L<overload/Overloading constants> in overload.pm's docs for how that works.
+
+On import, we both set up the overload, and use L<B::Hooks::EndOfScope> to
+register a callback that will remove it again at the end of the block; you
+can remove it earlier by unimporting the module using C<no>.
+
+=head1 CAVEATS
+
+Due to a perl bug (L<https://rt.perl.org/rt3/Ticket/Display.html?id=49594>),
+you can't use backslash escapes in a string to be marked as HTML, so
+
+ use HTML::String::Overload;
+
+ my $html = "<h1>\n<div>foo</div>\n</h1>";
+
+will not be marked as HTML - instead you need to write
+
+ my $html = '<h1>'."\n".'<div>foo</div>'."\n".'</h1>';
+
+which is annoying, so consider just using L<HTML::String> and doing
+
+ my $html = html("<h1>\n<div>foo</div>\n</h1>");
+
+in that case.
+
+The import method we provide does actually take extra options for constructing
+your L<HTML::String::Value> objects but I'm not yet convinced that's a correct
+public API, so use that feature at your own risk (the only example of this is
+in L<HTML::String::TT::Directive>, which is definitely not user serviceable).
+
+=head1 AUTHORS
+
+See L<HTML::String> for authors.
+
+=head1 COPYRIGHT AND LICENSE
+
+See L<HTML::String> for the copyright and license.
+
+=cut