NAME

Pod::PerlTricks - Perl 6 parser for PerlTricks pseudopod with to-HTML and to-JSON serializers

SYNOPSIS

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;

DESCRIPTION

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 filepath

The =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.

=include L<file://path/to/author.pod>

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

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

=tags accepts a horizontal whitespace-separated list of tags to be used as metadata

=tags programming perl io

image, cover-image

Both =image and =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

=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

And get

<pre><code>use Some::Lib;

my $foo = Bar.new();<code></pre>

terminal and data add a matching class attribute to the pre tag, e.g.

<pre class="terminal">...

chapter, title, subtitle, section

These are document metadata directives, e.g.:

=title 5 Ways to Optimize Your Code

For 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

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

=publish-date 2015-09-30T18:00:00

lang

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<data>, T<terminal>

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<github/repo>

G stands for GitHub. It builds a hyperlink to a Github repo or user page:

G<dnmfarrell/Pod-PerlTricks>

Becomes

<a href="https://github.com/dnmfarrell/Pod-PerlTricks">Pod-PerlTricks</a>

And

G<dnmfarrell>

Becomes

<a href="https://github.com/dnmfarrell">dnmfarrell</a>

#<hashtag>, @<handle>

# is for hashtag. This builds a hashtag search to Twitter. @ is for Twitter handle, and links to a particular user's Twitter feed.

N<note>

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>

Becomes

<p>Some important fact<sup><a href="#1">1</a></sup></p>

And later ...

<div class="footnotes">
  <ul>
    <li id="1">[1] Smith & Smith 2015 Oxford Press</li>
  </ul>
</div>

W<wikipedia entry>

W is for Wikipedia. The text should be replaced with a link to Wikipedia search for the content.

W<Perl>

Becomes

<a href="https://en.wikipedia.org/Perl">Perl</a>

AUTHOR

David Farrell © 2015

LICENSE

FreeBSD, see LICENSE