01-blogpost

+++

title = "Peas in a Pod6"

date = 2020-09-09T07:55:24-04:00

+++

Maybe you already know this, but it took me way too long to realize it so I'm going to talk about it anyway: Pod is not Pod6.

<aside>

This post is entirely about the Pod6 documentation language. If you're not familiar with Pod6, it's a lightweight markup language that can be rendered to Markdown, HTML, plaintext, or a variety of other output formats; you can think of it a bit like a more powerful and flexible version of Markdown. It was originally designed to make inline Raku documentation as pleasant as possible to write, but you can use it anywhere you might want to generate HTML or another output format – in fact, I've started writing this blog in Pod6. There's even a dedicated editor for writing Pod6 and rendering realtime HTML output.</aside>

I want to be clear about what I'm not saying. My point isn't that Pod6 is not POD , aka Plain Ol' Documentation, the markup language used for Perl 5 documentation. That's true, of course – Pod6 and POD are not the same language – but I'm making a different point.

The point I'm making is that Pod6 and Pod aren't the same language any more that JSON and JavaScript objects are the same language. In fact, Pod6 and Pod have a relationship that is exactly analogous to JSON and JavaScript objects: like JSON, Pod6 is a notation for writing plaintext files that can be read both by humans and machines; like a JavaScript object, Pod is an in-memory representation of that content.

Put differently, Pod6 is a markup language, and Pod is a data format.

Here's an example of Pod6:

 =begin pod
 Hello, B<world>!
 =end pod

And here's some Raku code that reads that same Pod6, parses it into Pod, and then prints a textual representation of the Pod (not the Pod6).

Hello, B<world>!

And here's the output produced by running that code (or by, you know, running the tangled output of this post's source code ).

$[ Pod::Block::Named.new(
       name => "pod",
       config => {},
       contents => [ Pod::Block::Para.new(
                         config => {},
                         contents => [ "Hello, ",
                                       Pod::FormattingCode.new(
                                           type => "B",
                                           meta => [],
                                           config => {},
                                           contents => ["world"]),
                                       "!"])])]