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)
    

=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

About these ads
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 ;-)

      /I3az/

Trackbacks

  1. Github | Most Popular Searches - webmastereye.net

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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 )

Google+ photo

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

Connecting to %s

Follow

Get every new post delivered to your Inbox.

%d bloggers like this: