Github and POD

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)
    

=head2 SYNOPSIS

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>


=head2 INSTALLATION

To install this module, run the following commands:

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


=head2 DEPENDENCIES

This module requires these other modules and libraries:

	Carp


=head2 SUPPORT AND DOCUMENTATION

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

    perldoc Builder


=head2 COPYRIGHT AND LICENCE

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.

/I3az/

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