Parser for PerlTricks pseudopod
Other HTML Perl
Switch branches/tags
Nothing to show
Latest commit b9318e7 Feb 23, 2017 @dnmfarrell committed on GitHub Merge pull request #2 from zoffixznet/patch-1
Add mandatory "perl" META field
Permalink
Failed to load latest commit information.
lib/Pod/PerlTricks append newlines when adding to HTML body Oct 12, 2015
t include accepts an array of filepaths Oct 12, 2015
test-corpus append newlines when adding to HTML body Oct 12, 2015
.gitignore test new formatting codes Oct 10, 2015
.travis.yml
LICENSE initial draft Sep 28, 2015
META.info Add mandatory "perl" META field Oct 26, 2016
README.pod clarified relationship to Pod::Perl5 Oct 13, 2015

README.pod

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