Skip to content

Github and POD

December 3, 2009
tags: , ,

If you look at the Github README formatting guide you will notice a feature request for POD that yours truly left there 10 months ago.

Recently I noticed that POD’s on Github were being rendered now (which may have been the case for quite a while and simply passed me by!). For eg. chromatic’s Modern Perl Book outline.pod.

So I added a README.pod to my Builder repo on Github and it works taking precedence over the plain README when rendering the repo landing page.

So no need to resort to using Markdown or Textile… its POD all the way! Hats off to Github for adding POD.

This is the README.pod I ended up with after a few trial attempts:

=head1 Builder

Build XML, HTML and (eventually!) other outputs in blocks

=head2 VERSION

version 0.04

This distribution includes the following modules:

    Builder             (0.04)
    Builder::Utils      (0.02)
    Builder::XML        (0.02)
    Builder::XML::Utils (0.02)


Using building blocks to render XML, CSS, HTML and other outputs.

    use Builder;
    my $builder = Builder->new;
    my $xm      = $builder->block( 'Builder::XML' );
    # example 1
    $xm->parent( { isa => 'Mother' }, $xm->child( 'Hi Mum!' ) );
    say $builder->render;
    # <parent isa="Mother"><child>Hi Mum!</child></parent>
    # example 2
    $xm->parent( sub {
        for my $say qw/Mum Dad/ {
            $xm->child( "Hi $say" );
    say $builder->render;
    # <parent><child>Hi Mum</child><child>Hi Dad</child></parent>


To install this module, run the following commands:

	perl Build.PL
	./Build test
	./Build install


This module requires these other modules and libraries:



After installing, you can find documentation for this module with the
perldoc command.

    perldoc Builder


Copyright (C) 2008,2009 Barry Walsh (Draegtun Systems Ltd)

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.


Update 08-Dec-2009: I’ve now amended the GitHub README formatting guide wiki to show that POD is now a supported format

3 Comments leave one →
  1. John permalink
    December 3, 2009 9:07 pm

    POD is pretty easy to write, but I don’t like reading it in my text editor (that is, while I’m editing it). Much happier with Markdown (plus Pandoc-enhancements (tables, for example)).

    • December 4, 2009 4:45 pm

      Hi John,

      Yes I know what you mean. However when I’m writing a Perl module I prefer to stick to just POD for all docs and not get my little brain in any extra knots 😉



  1. Github | Most Popular Searches -

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: