Commits

Toby Inkster committed 78ad82e

blog post

  • Participants
  • Parent commits 806918f

Comments (0)

Files changed (2)

devel.docs/blog/2013-02-26.html

+<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml">
+	<head>
+		<title></title>
+		<meta charset="utf-8" />
+	</head>
+	<body class="pod">
+		<span id="___top"></span>
+		<p>OK, so there were already <a class="podlinkurl" href="https://metacpan.org/search?q=pod+html">a thousand solutions</a> for converting pod to HTML, but I wasn't especially happy with any of them. Things I wanted were:</p>
+		<ul>
+			<li>Clean-looking XHTML and/or HTML5 output.</li>
+			<li>Unicode support. ☻</li>
+			<li>Good syntax highlighting for Perl code samples within the pod.</li>
+			<li>Links to <a class="podlinkurl" href="https://metacpan.org/">metacpan.org</a> by default rather than <a class="podlinkurl" href="http://search.cpan.org/">search.cpan.org</a>.</li>
+		</ul>
+		<p>And so I've cobbled together a solution using <a class="podlinkpod" href="https://metacpan.org/module/Pod%3A%3ASimple">Pod::Simple</a>, <a class="podlinkpod" href="https://metacpan.org/module/PPI%3A%3AHTML">PPI::HTML</a>, <a class="podlinkpod" href="https://metacpan.org/module/HTML%3A%3AHTML5%3A%3AParser">HTML::HTML5::Parser</a>, <a class="podlinkpod" href="https://metacpan.org/module/HTML%3A%3AHTML5%3A%3AWriter">HTML::HTML5::Writer</a>, <a class="podlinkpod" href="https://metacpan.org/module/XML%3A%3ALibXML%3A%3APrettyPrint">XML::LibXML::PrettyPrint</a> and <a class="podlinkpod" href="https://metacpan.org/module/Moo">Moo</a>, and released it as <a class="podlinkpod" href="https://metacpan.org/module/TOBYINK%3A%3APod%3A%3AHTML">TOBYINK::Pod::HTML</a>.</p>
+		<p>Here's the example from the synopsis section:</p>
+		<pre><span class="line_number" style="color:#666"> 1: </span><span class="comment" style="color:#060;font-style:italic">    #!/usr/bin/perl
+</span><span class="line_number" style="color:#666"> 2: </span>    
+<span class="line_number" style="color:#666"> 3: </span>    <span class="keyword" style="color:#009;font-weight:bold">use</span> <span class="pragma" style="color:#009">strict</span><span class="structure">;</span>
+<span class="line_number" style="color:#666"> 4: </span>    <span class="keyword" style="color:#009;font-weight:bold">use</span> <span class="pragma" style="color:#009">warnings</span><span class="structure">;</span>
+<span class="line_number" style="color:#666"> 5: </span>    <span class="keyword" style="color:#009;font-weight:bold">use</span> <span class="word">TOBYINK::Pod::HTML</span><span class="structure">;</span>
+<span class="line_number" style="color:#666"> 6: </span>    
+<span class="line_number" style="color:#666"> 7: </span>    <span class="keyword" style="color:#009;font-weight:bold">my</span> <span class="symbol">$pod2html</span> <span class="operator" style="color:#000;font-weight:bold">=</span> <span class="double" style="color:#909">"TOBYINK::Pod::HTML"</span><span class="operator" style="color:#000;font-weight:bold">-&gt;</span><span class="word">new</span><span class="structure">(</span>
+<span class="line_number" style="color:#666"> 8: </span>        <span class="word">pretty</span>             <span class="operator" style="color:#000;font-weight:bold">=&gt;</span> <span class="number" style="color:#39C">1</span><span class="operator" style="color:#000;font-weight:bold">,</span>       <span class="comment" style="color:#060;font-style:italic"># nicely indented HTML</span>
+<span class="line_number" style="color:#666"> 9: </span>        <span class="word">code_highlighting</span>  <span class="operator" style="color:#000;font-weight:bold">=&gt;</span> <span class="number" style="color:#39C">1</span><span class="operator" style="color:#000;font-weight:bold">,</span>       <span class="comment" style="color:#060;font-style:italic"># use PPI::HTML</span>
+<span class="line_number" style="color:#666">10: </span>        <span class="word">code_line_numbers</span>  <span class="operator" style="color:#000;font-weight:bold">=&gt;</span> <span class="core" style="color:#009;font-weight:bold">undef</span><span class="operator" style="color:#000;font-weight:bold">,</span>
+<span class="line_number" style="color:#666">11: </span>        <span class="word">code_styles</span>        <span class="operator" style="color:#000;font-weight:bold">=&gt;</span> <span class="structure">{</span>        <span class="comment" style="color:#060;font-style:italic"># some CSS</span>
+<span class="line_number" style="color:#666">12: </span>            <span class="word">comment</span>   <span class="operator" style="color:#000;font-weight:bold">=&gt;</span> <span class="single" style="color:#909">'color:green'</span><span class="operator" style="color:#000;font-weight:bold">,</span>
+<span class="line_number" style="color:#666">13: </span>            <span class="word">keyword</span>   <span class="operator" style="color:#000;font-weight:bold">=&gt;</span> <span class="single" style="color:#909">'font-weight:bold'</span><span class="operator" style="color:#000;font-weight:bold">,</span>
+<span class="line_number" style="color:#666">14: </span>        <span class="structure">}</span>
+<span class="line_number" style="color:#666">15: </span>    <span class="structure">);</span>
+<span class="line_number" style="color:#666">16: </span>    
+<span class="line_number" style="color:#666">17: </span>    <span class="word">print</span> <span class="symbol">$pod2html</span><span class="operator" style="color:#000;font-weight:bold">-&gt;</span><span class="word">file_to_html</span><span class="structure">(</span><span class="word">__FILE__</span><span class="structure">);</span></pre>
+		<p>There's a basic command-line script <code>pod2html-tobyink</code> supplied with it.</p>
+		<p>Oh, and this blog post was <a class="podlinkurl" href="https://bitbucket.org/tobyink/p5-tobyink-pod-html/src/tip/devel.docs/blog/2013-02-26.pod">written as pod</a> and <a class="podlinkurl" href="https://bitbucket.org/tobyink/p5-tobyink-pod-html/src/tip/devel.docs/blog/2013-02-26.html">converted to HTML</a>.</p>
+	</body>
+</html>

devel.docs/blog/2013-02-26.pod

+#!/usr/bin/perl
+
+use strict;
+use warnings;
+use TOBYINK::Pod::HTML;
+
+my $pod2html = "TOBYINK::Pod::HTML"->new(
+	pretty             => 1,       # nicely indented HTML
+	code_highlighting  => 1,       # use PPI::HTML
+	code_line_numbers  => undef,
+);
+
+print $pod2html->file_to_html(__FILE__);
+
+__END__
+
+=pod
+
+=encoding utf-8
+
+OK, so there were already
+L<a thousand solutions|https://metacpan.org/search?q=pod+html> for
+converting pod to HTML, but I wasn't especially happy with any of
+them. Things I wanted were:
+
+=over
+
+=item *
+
+Clean-looking XHTML and/or HTML5 output.
+
+=item *
+
+Unicode support. ☻
+
+=item *
+
+Good syntax highlighting for Perl code samples within the pod.
+
+=item *
+
+Links to L<metacpan.org|https://metacpan.org/> by default rather than
+L<search.cpan.org|http://search.cpan.org/>.
+
+=back
+
+And so I've cobbled together a solution using L<Pod::Simple>, L<PPI::HTML>,
+L<HTML::HTML5::Parser>, L<HTML::HTML5::Writer>, L<XML::LibXML::PrettyPrint>
+and L<Moo>, and released it as L<TOBYINK::Pod::HTML>.
+
+Here's the example from the synopsis section:
+
+    #!/usr/bin/perl
+    
+    use strict;
+    use warnings;
+    use TOBYINK::Pod::HTML;
+    
+    my $pod2html = "TOBYINK::Pod::HTML"->new(
+        pretty             => 1,       # nicely indented HTML
+        code_highlighting  => 1,       # use PPI::HTML
+        code_line_numbers  => undef,
+        code_styles        => {        # some CSS
+            comment   => 'color:green',
+            keyword   => 'font-weight:bold',
+        }
+    );
+    
+    print $pod2html->file_to_html(__FILE__);
+
+There's a basic command-line script C<pod2html-tobyink> supplied with it.
+
+Oh, and this blog post was
+L<written as pod|https://bitbucket.org/tobyink/p5-tobyink-pod-html/src/tip/devel.docs/blog/2013-02-26.pod>
+and
+L<converted to HTML|https://bitbucket.org/tobyink/p5-tobyink-pod-html/src/tip/devel.docs/blog/2013-02-26.html>.