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

“you learn something new every day”

My last upload of MooseX::SingletonMethod produced a funny in the module documentation (POD) on CPAN. It was showing the same POD in both modules (MX::SM & MX::SM::Role).

And not only was it showing MX::SM::Role POD in both but when you selected source you would only see code for MX::SM!?

How very odd?? (and u can still see this when u click above 0.02 link).

Here is an important snippet of how the modules / POD looked… first for MooseX::SingletonMethod:

package MooseX::SingletonMethod;

...

1;

__END__

=head1 NAME

MooseX::SingletonMethod - Moose with Singleton Method facility.

...

and for MooseX::SingletonMethod::Role

package MooseX::SingletonMethod::Role;
...
  
1;

__END__

=head1 NAME

MooseX::SingletonMethod - Role providing Singleton Method option

...

Spot the mistake?

The last line shown in above module should be….

MooseX::SingletonMethod::Role - Role providing Singleton Method option

Opps… missed off the ::Role part

I thought the CPAN docs were picked up from and assigned via package declaration… obviously not! Also the POD coverage tests didn’t spot anything either (perhaps it might have done if I completely foobar the POD name! )

Anyway… all’s well that ends well

/I3az/