I really like POD and I like the changes in the upcoming Perl 6 Pod.

Have you ever heard of literate programing? (see Wikipedia). I think it would be neat if Pod could do literate programing. It is already very close. For reference, please see this article:

For reference, please see this page:

In brief, the only thing that Pod is missing is allowing you to write code sections in whatever order is best for people to understand, and have them be re-ordered when we run the program.

I would like to suggest a "=ref" block type (for "reference") as well as the :ref() configuration option for =head* and =code, such that:

---- start myshell.pl -----
=begin pod
=head1 Intro

This program is an infinite loop. On each iteration we
read user input and do something with it.

=begin code
while 1 {
=ref handle_input
=end code

=head1 Handling user input :ref(handle_input)

To handle user input we simply give the input to
Perl's built-in eval() function.

=begin code :ref(handle_input)
print "Prompt> ";
=end code
=end pod
---- end myshell.pl -----

1) When you run "perl myshell.pl", Perl would grab the second code block, move to where "=ref" is, and run the program normally.

2) When you run (say) "pod2html myshell.pl", the code block would remain where it is, but the "=ref" would be replaced by a hyperlink to the second "=head1".

In this way, a relatively simple change makes Perl 6 Pod able to do literate programing for anyone who is interested.

What do you think?

Reply via email to