S26 in HTML

On http://perlcabal.org/syn/, Synopsis 26 is the only one without the HTML page. That’s of course due to the lack of Pod (Pod6) to HTML converter. Today there has been a breakthrough in this embarrasing situation :)
My Pod parser integrated into Rakudo is capable of parsing S26 completely, so this morning I wrote a Pod::To::HTML module for it. Parsing and generating HTML output from S26 takes about 4 minutes on my machine, but the outcoming document is not that bad. You can see some still NYI features, like the lack of formatting codes and correctly interpreting semantic blocks. The first one is a part of my GSoC work, the second one is not but I’ll probably do it anyway, just for the sake of having prettier S26 :)

My HTML-fu is a bit Less Than Awesome, so if anyone knows how to make it any better (and it won’t be cheating as Pod::To::HTML is not a part of my GSoC work), I’m willing to hand out commit bits to anyone interested.

Maybe it’s finally time to read this one. Have the appropriate amount of fun.

GSoC – The podparser branch has landed

Just a few minutes ago, with a total count of 28 files changed, 1627 insertions and 41 deletions, the podparser branch in which I’ve been doing my GSoC work has been merged into nom, the current development branch of Rakudo and the soon-to-be master. So, what do we get?

  • Pod is now parsed, not ignored. The whole parse tree is available in runtime in the $=POD variable
  • A basic support for documenting classes and subroutines with #= comments, and the .WHY method on each object returning the attached documentation
  • A –doc switch, a not-really-replacement for perldoc
  • A simple Pod::To::Text output generator
  • and more, of course :)
So, how does it look like in action?
All the Pod we have written in our code is now available in the $=POD variable. Example?
=begin pod
Some documentation
=end pod

say $=POD[0].content[0].content;
Results in

Some documentation

That’s not very useful per se, so how about this one:

=begin pod

=head1 NAME

A basic pod document

=head2 Running Perl programs

To run a Perl program from the Unix command line:

    perl progname.pl

=head2 Things on my desk

There are the following things on my desk right now:

=item A cup of tea
=item A couple of pens
=item A stereo
=item A couple of books
=item A laptop, obviously

=end pod

    use Pod::To::Text;
    say pod2text($=POD);

say "I'm just a simple program";

Now what’s the DOC INIT thing? Let’s see. How about we run the above program:

$ perl6 foo.pl
I'm just a simple program

No suprises. Let’s introduce the –doc switch then:

$ perl6 --doc foo.pl

A basic pod document

  Running Perl programs

To run a Perl program from the Unix command line:

    perl progname.pl

  Things on my desk

There are the following things on my desk right now:

 * A cup of tea
 * A couple of pens
 * A stereo
 * A couple of books
 * A laptop, obviously

That’s right. The DOC blocks are executed only when the –doc command line option has been given. At the moment you have to write them yourself, but maybe even in the nearest few days there will be a default DOC INIT block doing What You mean all by itself. There we go, a perldoc-alike built-in :)


That’s probably the biggest killer feature in the whole project. Although it’s not yet fully implemented in Rakudo (suprise segfaults here and there, don’t worry, they’re not permanent :)), it looks pretty much like this:

#= our zebra class
class Zebra {

say Zebra.WHY # prints: "our zebra class"

Yes yes, a documentation inspection in runtime. See the potential?

# what was that sub again?
&sort.WHY.say # get the documentation for the sort() builtin

That opens a way for lots of awesome userspace tools too.

So, what’s still not quite there?

  • .WHY (some cases)
  • Formatting Codes (C<code>, B<bold> etc)
  • DOC use (that can be written as DOC INIT { use … } for now)
  • Default DOC INIT (as mentioned above)
  • A Pod::Parser as a standalone module
With that done, my GSoC project will be finished, and I’ll hopefully have time to hit some things I was planning to poke in some spare time, for example:
  • HTML output generator
  • Extending the parser so Synopse 26 can be fully parsed
  • Other fancy userspace tools; I don’t want to spoil the suprise :)

What can I say? Pull it, compile it, play with it, report bugs and have the appopriate amount of fun :)

GSoC: First (easily) visible results

Yeah, of course I’m doing stuff for almost 2 months now. But all this was boooring. The goal was not for the parser outside the compiler, but the parser in the compiler itself, exposing Pod to runtime. After some funny and some frustrating moments (like self-duplicating bacon: worse than it sounds!) it finally happened: a $POD variable (should be $=POD one day), is visible in the code and contains sensemaking results. I also started moving tests to Rakudo tree, so ‘make test’ can be proud of the shiny new capabilites too. Exciting times. I feel excited and proud, one of the main goals is there, as it should be, not in some remote repo as a separate module. From now on, everything should be easier :)

The summary of the Community Bonding Period

Students get to know mentors, read documentation, get up to speed to begin working on their projects.

Or so says the GSoC timeline. That ends today, almost one month since the accepted students were announced.  I didn’t do much community bonding per se. I’ve been quite active in the Perl 6 community for almost a year now. I already knew Moritz and Carl (the latter one even in person), my mentors, so that part can be ticked as “done” as well. So what did I do, instead of  lying in the shade and drinking a fine tea? The Read Documentation part, but not only. I’ve done lots of discussions with my mentors, and received an excellent feedback. Almost every discussion I was afraid I may forgot about was scrupulously logged in the gsocmess repo. But not only the irc logs got there. I started scratching out how the Pod nodes of the example Pod documents will look like. I used the parts of S26, as they’re probably the best examples of Pod 6 out there. I didn’t spend the whole time parsing example documents myself though. Over the last two weekends I started the actual coding: what was to be done for week #1 and even #2. After some serious headscratching and a few wtf moments I ended up with a parser capable of parsing delimited, paragraph, and abbreviated blocks of Pod. 129 lines of code, 337 lines of tests. I also started moving the grammar rules into rakudo; I created a gsoc/podparser branch and started migrating the code there. It doesn’t bring any features, but it opens a way to fill in the action methods and actually produce the Pod node tree in parse time. At the moment of writing this, the branch fails on some of the spectests, which I plan fixing soon.

How will I fill the time that I got working in advance? Well, most of it will be lost^Wwasted^Wspent on the University work. My semester is still on, the exams finish on June the 30th, so it’s quite possible I won’t do any GSoC-related work in the upcoming weeks. On the other hand, I can’t imagine Physics or Signal Theory being more attractive than GSoC, so I’ll probably end up ruining my exam session and coding instead. But time will tell. Hopefully I’d be able to end up with the exams passed, and the GSoC on schedule.

TL;DR: Instead of community bonding, I started the actual coding and bit off most of week #1 and #2 of my schedule.


And so I’m accepted as a Perl Foundation GSoC student. Yay!

I don’t think there’s any particular blogging requirement, yet there’s already too much Perl on this blag, so a tiny bit more won’t make much difference. Plus I believe it’ll be so exciting I would have been blogging about it anyway :)

The coding starts in the last week of May I think, but due to somewhat unfortunate collision between the end of my semester and the beginning of the GSoC I may experience some lack of time. The reasonable solution is to start coding a bit earlier, to minimize the possibility of slips in the coding time. The gsocmess repo will keep all the thoughts and maybe some code I’ll write during the thinking time. Feel free to look into it from time to time (free code review \o/), and, as always, constructive criticism or your own thoughts will be more than appreciated.