Pod::PerlTricks - Perl 6 parser for PerlTricks pseudopod with to-HTML and to-JSON serializers
use Pod::PerlTricks::Grammar; use Pod::PerlTricks::ToHTML; my $actions = Pod::PerlTricks::ToHTML.new; my $match = Pod::PerlTricks::Grammar.parsefile('example.pod', :$actions); my $html = $match.made; my $html_head = $actions.head; my $html_body = $actions.body;
Pod::PerlTricks extends ordinary pod with new syntax for blogging / publishing.
Pod::PerlTricks::Grammar supports all of regular pod, plus new directives. It comes with action classes for converting PerlTricks pod to HTML (
Pod::PerlTricks::ToHTML) and to JSON (
Pod::PerlTricks::ToJSON) with the document body serialized as HTML and the meta attributes in key value pairs (mostly for use with AngularJS).
If you're just interested in parsing normal pod syntax, take a look at Pod::Perl5. It can translate pod into both HTML and Markdown.
new command blocks
=include directive takes a filepath to one or more pod files. When an action class parses
=include it will open and parse each referenced pod file. The files can contain inline pod too.
This is useful if you have boilerplate text you want t include in every pod file, (like author details) but don't want to type out every time.
Or maybe you want to make a manifest of pod files:
=include L<file://chapter1.pod> L<file://chapter2.pod> L<file://chapter3.pod> L<file://chapter4.pod> L<file://chapter5.pod> L<file://chapter6.pod> L<file://chapter7.pod> L<file://chapter8.pod> L<file://index.pod>
This file will be processed into a single match object containing all of the pod content from the files. The links can be separated by vertical or horizontal whitespace.
=author-name, author-bio, author-image
=author-* command directives are to represent author details.
=author-name Jane Smith =author-bio Jane Smith is a professional programmer with 12 years of experience, specializing in acme code ... =author-image path/to/j_smith.jpg
=tags accepts a horizontal whitespace-separated list of tags to be used as metadata
=tags programming perl io
=cover-image are intended to include images, the only difference between them is
=cover-image is supposed to denote the primary image for the article, whereas
=image represents an image inline in the article.
=image L<Image caption|/path/to/image.png> =cover-image L</path/to/image.png>
=table indicates the start of a pipe-separated table. The directive must be followed by a blank line, and then the table itself. The first row is the header row. The table is terminted by a blank line.
=table | Team | Score | | The Farmers | 54 | | Timeout United | 21 |
The whitespace around the pipes is optional and will not be associated with the text in the cell.
begin data, terminal & code
Pod::PerlTricks supports 3 new types of begin/end blocks:
data - this is meant to represent data
terminal - for terminal output, commands etc
code - for programming code
So you can do:
=begin code use Some::Lib; my $foo = Bar.new(); =end code
<pre><code>use Some::Lib; my $foo = Bar.new();<code></pre>
data add a matching class attribute to the
pre tag, e.g.
chapter, title, subtitle, section
These are document metadata directives, e.g.:
=title 5 Ways to Optimize Your Code
Pod::PerlTricks::ToHTML This will be rendered in a div node with the class attribute
title, and added to the head node. For
Pod::PerlTricks::ToJSON article metadata directives are included as a key/pair value in the head key, but not rendered in the body. There is nothing special about these directives except
=chapter increments the chapter count, and flushes the footnotes cache.
=publish-date takes an ISO8601 datetime, with an optional timezone component. This can be used to determine when an article "goes live" on a blog site, and is also just useful metadata.
Specify the language that the article is written in. In
Pod::PerlTricks::ToHTML this is added to the root HTML node.
New formatting codes
D stands for data, and T for terminal to complement the C<> formatting code. These should be styled accordingly (monospaced font, possibly colored background).
G stands for GitHub. It builds a hyperlink to a Github repo or user page:
# is for hashtag. This builds a hashtag search to Twitter. @ is for Twitter handle, and links to a particular user's Twitter feed.
N is for footnote or notation. The text inside the angle brackets should be formatted as a footnote in the article, with a link to the footnote created inplace of the formatting code. Footnotes are per chapter - if there are none / one
=chapter directives, all footnotes will appear at the bottom of the document.
Some important fact N<Smith & Smith 2015 Oxford Press>
<p>Some important fact<sup><a href="#1">1</a></sup></p>
And later ...
<div class="footnotes"> <ul> <li id="1"> Smith & Smith 2015 Oxford Press</li> </ul> </div>
W is for Wikipedia. The text should be replaced with a link to Wikipedia search for the content.
David Farrell © 2015
FreeBSD, see LICENSE